Welcome to Silk Performer 21.0

Published on 2020-10-21

Welcome to Silk Performer 21.0

  • Silk Performer 21.0
  • Tour of the UI
  • Upgrade and licensing information
  • Getting Started

What's New

  • What's New in Silk Performer 21.0

Featured Sections

  • .NET testing support
  • Java testing support
  • TrueLog Explorer
  • Performance Explorer

Tutorials and Demonstrations

  • Testing Web 2.0 applications (protocol-level)
  • Testing Web 2.0 applications (browser-driven)
  • Testing Web applications for mobile devices
  • Testing in the cloud
  • Testing Citrix applications
  • Testing Oracle Forms / Oracle Applications
  • Testing terminal emulation applications

Code Samples

  • Benchmark Description Language (BDL) Reference

Online Resources

  • Micro Focus Website
  • Silk Performer Youtube Videos
  • Silk Performer Online Documentation
  • Silk Performer On-Demand Training
  • Silk Performer Support & Services
  • Silk Performer Product Updates
  • Silk Performer Community
  • Silk Performer Blog
  • Silk Performer Knowledge Base

Provide Feedback

  • Contacting Micro Focus
  • Email us feedback regarding this Help


Installation Guide

  • Introduction
    Introduces the Silk Performer Installation Guide.
  • Silk Performer Licensing
    Describes the Silk Performer licensing policy, the two licensing models, and the types of VUsers. Also, the topic lists all application types each VUser type comprises.
  • Installing Silk Performer
    Provides an overview of the Silk Performer installation process.
  • Installing Optional Components
  • Installing Agent Software on Remote Computers
    Describes the process of setting up Silk Performer Agent software on remote computers.


Introduction

This Help provides all the information you need to install and uninstall Silk Performer and to prepare the load testing environment. It suggests hardware, software, and operating system requirements and offers alternative installation options.

During the installation, the setup wizard confirms that all the software you need for installation and use of Silk Performer is available on your computer. If this is not the case, the setup wizard provides options for installing the missing software.

  • System Requirements
    Identifies the system requirements and prerequisites for Silk Performer.
  • Performance and Scalability Matrix
    Provides guidance for calculating the recommended maximum number of virtual users per agent.
Parent topic: Installation Guide


System Requirements

The following sections describe the system requirements for installing and running Silk Performer.

To run the Silk Performer agent software, or both controller and agent software, and to use the full potential of Silk Performer to run large-scale load tests, your system must meet the following minimum requirements:

Hardware Requirements

System Area | Requirement
Processor | Intel Core 2 Duo or equivalent CPU
RAM | 4 GB
Hard disk space | 2.5 GB for controller software installation 1 GB for agent-only installation Depending on the size of your load tests, make sure you have enough space on your hard disk for result files.
Network | Network connectivity to the system under test and to all Silk Performer agent computers.

Operating System Requirements

  • Both the Silk Performer controller and the Silk Performer agent can be installed on Microsoft Windows 8.1 or newer, or Microsoft Windows Server 2012 or newer.
  • Installing the network emulation driver is currently not supported for Microsoft Windows 10 and Microsoft Windows Server 2016 and 2019.

Software Requirements

To install and run Silk Performer, your system requires a minimum set of software components.

The required components vary based on installation type. For example, to run Silk Performer Java Explorer, your system must be equipped with the appropriate Java Development Kit. Download components from the respective websites.
  • Internet Explorer 11, Google Chrome, Mozilla Firefox, Microsoft Edge, or Opera for browser-driven load testing.

  • PDF viewer to view documentation .

  • Citrix Receiver for Microsoft Windows 4.9.7 (LTSR) or later to test Citrix applications.
  • Java Runtime Environment (JRE): Both 32- and 64-bit versions are required on 64-bit operating systems.
  • Java Development Kit 7, 8 (32-bit) to test Java applications with Java Explorer.
  • Visual Studio 2015, 2017, or 2019 for Visual Studio extension.

Working with Silk Performer on a multi-user system

Silk Performer can be installed on a machine with terminal services enabled for multi-user access. In general, it is not recommended to work in multiple sessions simultaneously. If you want to do so nevertheless, keep the following in mind:

  • Recording: The Silk Performer Recorder uses a system-wide hooking mechanism. If one user starts the Recorder, the traffic of all other users might be recorded as well.
  • Workbench: Multiple users can work on different projects simultaneously. Working on the same project is not recommended. The project will be opened in read-only mode for the second and all further users.
  • Executing tests: Multiple users can execute tests simultaneously from one machine. However, multiple simultaneously running tests will influence each other as they share the same resources (CPU, memory, network bandwidth).
  • Monitoring tests: Performance Explorer does not differentiate between test metrics of multiple running tests. Therefore, real-time values of the wrong test might be displayed.
Parent topic: Introduction


Performance and Scalability Matrix

Maximum VUsers per Agent Computer

The following table shows the recommended maximum number of virtual users per agent computer based on the hardware resources of the agent computer and the type of tested web application.

Note: Testing of applications utilizing SSL reduces VUser capacity by 35%. Testing with TrueLog on Error enabled reduces VUser capacity by 30%. Testing a web application using low-level APIs (Web Low Level) increases VUser capacity by 20%.
System | OS | Web Business App | Web Business App with SSL (-35%) | TrueLog on Error (-30%) | TrueLog on Error with SSL | Web Low Level (+20%)
Intel Xeon Quadcore 3 GHz, 16 GB RAM | Windows Server 2008 R2 | 6500 | 4225 | 4550 | 2958 | 7800
Intel Core i7 Quadcore 2.8 GHz, 8 GB RAM | Windows 8.1 | 6500 | 4225 | 4550 | 2958 | 7800
Intel Core2 Duo 3 GHz, 4 GB RAM | Windows 7 Enterprise | 4700 | 3055 | 3290 | 2139 | 5640
Note: Web Business App uses page-level APIs (HTML/HTTP). Web Low Level uses low-level APIs (HTTP).

VUsers per Cloud Agent

Note: The maximum number of VUsers per cloud-based agent is 1,000 regardless of the type of the tested application.

The following table shows the number of VUsers that can typically be supported per cloud-based agent, based on the type of the tested application.

Application Under Test | Supported VUsers per Cloud-Based Agent
Browser-Driven Load Testing | 5
Java/.NET | 250
Secure Web (SSL) | 600
Web | 800

Test Parameters

The numbers in the previous tables were determined by using a realistic workload with the following characteristics:

  • The page structure of all requested web pages corresponds to popular public web pages.
  • The average think time between page views for virtual users was 32 seconds.
  • A single virtual user was emulated with four concurrent connections.

As a result, the number of simulated virtual users corresponds to a realistic number of concurrent users accessing a popular web site, providing the following information:

  • Average hits per page: 39
  • Average page size: 130 KB
  • Average think time between pages: 32 sec

Agent Capacity for Web Protocol Virtual Users

Silk Performer determines the capacity of a machine by using a formula that takes the following parameters into consideration:
  • Number of CPUs
  • Number of cores per CPU
  • CPU speed
  • Memory size

The result is the number of virtual users that can execute a web protocol script on an agent machine with the corresponding parameters.

Agent Capacity for Other Virtual User Types

To determine the number of virtual users that can run on a particular agent machine, the number of web protocol virtual users is weighted by a particular factor that depends on the used technology.
Note: For some technologies there is a maximum number of virtual users defined per machine, merely due to OS limitations rather than CPU or memory constraints.
Parent topic: Introduction
Parent topic: Getting Started


Silk Performer Licensing

The Silk Performer licensing model is based on virtual users (VUsers).

Starting and using the Silk Performer Workbench does not require a license. You can model and customize scripts as well as adjust many other load test settings without a license. Also, executions that are performed with only one virtual user (like try script or baseline executions) do not require a license.

Starting a load test run requires licenses for the virtual users employed in the execution.

Silk Performer offers two licensing models:

  • on-premise licensing
  • online licensing

When you upgrade from an older Silk Performer version, new licenses are required for executing load tests with the new version. During the upgrade process, you can keep the old licenses for a period of 90 days.

Silk Performer works with three types of VUsers. Each type allows to simulate different application types:

  • Web
  • Standard
  • Premium
VUser Type | Application Type
Web | Web Browser-Driven GUI-level testing in single session mode with selected web browsers HTTP(S) (Web browser low level) HTTP(S)/HTML (Web browser high level) HTTP(S)/XML (Web services, SOAP) HTTP Live Streaming (HLS) Silverlight Mobile SAP NetWeaver WebDAV (MS Outlook Web Access) Email (SMTP/POP) FTP TCP/IP UDP AMF0/AMF3/FLEX Java over HTTP DLL Interface
Standard | All of Web, plus: Visual Studio Extension Java Add-On DB2-CLI Add-On OCI Add-On ODBC Add-On Visual Basic Add-On (Framework) Directory server (LDAP) CORBA Add-On
Premium | All of Standard, plus: GUI Level Testing (UFT Developer (Silk4J), UFT Developer (Silk4NET), Silk Test Classic) Remedy Web ARS SAPGUI Add-On for Silk Performer Oracle Applications/Forms Add-On PeopleSoft Add-On Siebel Add-On Citrix Add-On Terminal Emulation (Green-Screen) Add-On Tuxedo/ATMI Add-On
  • On-Premise Licensing
    Lists the two types of on-premise licenses and provides basic information around floating licenses and license servers.
  • Online Licensing
    Explains what online licensing is, how to acquire licenses using online licensing, and how to use both online and on-premise licenses.
  • Silk Performer SOA Edition Licensing
    Describes what the SOA edition is, how the SOA edition licensing works, and lists what can be tested using the SOA edition.
Parent topic: Installation Guide
Related tasks
Installing Silk Meter on Your License Server


On-Premise Licensing

For on-premise licensing, Silk Performer provides two types of licenses:

  • standalone licenses
  • floating licenses

The concept of floating licenses allows license sharing among users by installing the licenses on a license server. Standalone licenses are bound to a particular machine. Each Silk product supports both licensing technologies, Silk Meter and Micro Focus AutoPass. Silk Meter is considered the native license technology and supports standalone as well as floating licenses. With AutoPass, currently only floating licensing is supported. However, AutoPass provides better usage reporting capabilities.

Note the following:

  • If you have multiple license servers, you need multiple license files, each one tied to a particular license server.
  • If you have received a Silk Performer license file, install the file on your license server.
  • If you have not received a license file, generate one with the online license generator.
  • Generating a Silk Performer License
    Describes how to generate a Silk Performer license.
  • Finding the Host ID
    Find the host ID of the computer, on which you want to install the licenses. You need the host ID to obtain a Silk Performer license file.
  • Silk Meter Installation
    Explains what you need to know before you install the Silk Meter license server software.
  • Modifying Your License Configuration
    Modify your license server configuration if the host name or port of your Silk Meter license server changes.
Parent topic: Silk Performer Licensing


Generating a Silk Performer License

To run load tests with Silk Performer, you need a valid license. If you have purchased Silk Performer, you can use our online license generator to generate a license file. The online license generator requires an SSL-capable browser, such as Firefox or Chrome. You will receive an email with instructions on how to generate your license file. If you did not receive these instructions, contact customer care at http://support.microfocus.com.

Parent topic: On-Premise Licensing
Related concepts
Installing Silk Performer
Related tasks
Installing Silk Meter on Your License Server


Finding the Host ID

A license must be bound to a particular machine, either the license server for floating licenses or the Silk Performer controller machine for standalone licenses. To bind a license, a so-called host ID is required. In case of Silk Meter, the host ID is the MAC address of a LAN card, which can be obtained as follows:

  1. On the machine you want to generate the license for, open a command prompt and enter the command ipconfig/all. The network adapters and additional information is listed.
  2. Note the host ID, which is the MAC Address or Physical Address of your LAN card, for example 00-BF-00-1C-D3-3D.
    Tip: Depending on your system setup, including virtual machines and VPN connections, your computer might have several network adapters with different MAC addresses. Be sure to note the host ID of your physical LAN card.
In case of the AutoPass license server the host ID is called lock code and is displayed under LICENSE menu in the INSTALL tab. For further details about AutoPass license server installation and usage refer to the corresponding product page on the Micro Focus Marketplace.
Parent topic: On-Premise Licensing


Silk Meter Installation

If you already have a Silk Performer license file, you can install it when you install Silk Meter. If you do not have a valid Silk Performer license, access the online License Generator to generate a license file.

To install and run Silk Meter on your license server, no license file is required. However, you must import a license file before you can run load tests with Silk Performer. You can import a license file using the Silk Meter Policy Administrator.

If you have multiple license servers, you need multiple license files, each one containing licenses tied to a particular license server. A single Silk Meter license server can administer licenses for multiple products.

Silk Meter License Server Requirements

Before installing Silk Meter, refer to the Release Notes to ensure that the license server meets the requirements.

  • Uninstalling a Previous Version of Silk Meter
    Uninstall Silk Meter before installing the latest version.
  • Installing Silk Meter on Your License Server
    Install the Silk Meter licensing software to license your Silk products.
Parent topic: On-Premise Licensing
Related tasks
Generating a Silk Performer License


Uninstalling a Previous Version of Silk Meter

If a previous version of Silk Meter is installed on your license server, you must uninstall it before the latest version of Silk Meter can be installed.

  1. Choose Start > Programs > Silk > Silk Meter > Uninstall .
  2. Click Yes to uninstall Silk Meter. The Remove Settings dialog box opens.
  3. Click No to keep your Silk Meter settings.
    Attention: You must click No to preserve license policies that currently exist on your Silk Meter license server.
  4. Reboot your computer.
Silk Meter is now uninstalled, and you can install the latest version of Silk Meter.
Parent topic: Silk Meter Installation


Installing Silk Meter on Your License Server

Before installing Silk Meter, verify the following information:
  • Your user account possesses administrator privileges.
  • An instance of Silk Meter is not installed on your license server.
  1. Visit the product updates site and search for Silk Meter.
  2. Download and save the latest Silk Meter Installation Files.
  3. Navigate to the location where you saved the .exe file and double-click it. For a standard installation, follow the Silk Meter installation wizard by using the default options.
    Important: If setup prompts you to restart the computer, make sure to do so.
Parent topic: Silk Meter Installation
Related tasks
Generating a Silk Performer License


Modifying Your License Configuration

Use the Licensing Configuration Tool to modify or repair your license server configuration. This utility is installed with your Silk Performer installation.

  1. Choose Start > Programs > Silk > Silk Performer 21.0 > Licensing Configuration Tool .
  2. In the Application list box, select the product for which you want to modify the license configuration.
  3. Choose between the license technologies Silk Meter and AutoPass depending on which technology you want to use.
  4. Under Licensing mode select either Use a license server or Use standalone licensing.
    Note: Standalone licensing is available for Silk Meter only.
  5. When using a license server, type the computer name of the Silk Meter or AutoPass license server in the Host field. Unless your network administrator has defined a different port, do not change the Port Number. Default ports are 5416 for Silk Meter and 5814 for AutoPass.
  6. Click Apply to activate the license configuration.
  7. If you use a license server, click Test Connection to verify that the specified license server is accessible on the specified host and port. If the connection is successful, the Status field displays a SUCCESS message.
    Note: In some cases, specifying the simple name of the license server in the Host field, such as licenseserver, might not work. A message box stating Connection to Silk Meter license server failed opens. To resolve this issue, specify the hostname by using a fully qualified name, such as licenseserver.mycompany.com.
  8. Click Close to complete the license configuration.
Parent topic: On-Premise Licensing


Online Licensing

Besides on-premise licenses, you can also acquire online licenses. This means that you can purchase licenses with Micro Focus credits from your CloudBurst account.

For load test executions, you can either mix on-premise and online licenses, or you can instruct Silk Performer to use just on-premise or just online licenses. Click Settings > System in the menu, click the Licensing tab, and select your preferred setting in the Licensing options.

To determine how many on-premise licenses you have, click Help in the menu and click About Silk Performer. If, for example, you have 50 Virtual Users (Web) on-premise licenses available but you need 60 VUsers for a planned load test, you can quickly fill up the gap of 10 VUsers with online licenses.

Online licensing can be especially useful if you need additional VUsers on short notice, or you unexpectedly require more VUsers for just a few load tests, or you require an unusually large amount of VUsers for a limited period of time. Online licensing allows you to easily and quickly increase your amount of VUsers.

Online licenses are valid for 24 hours. The time span starts when the licenses are first used. For more information around fees for online licenses, see the section Virtual User License Fees in the topic CloudBurst Load Test Fees.

Parent topic: Silk Performer Licensing


Silk Performer SOA Edition Licensing

What is the Silk Performer SOA edition?

The Silk Performer SOA edition (Service Oriented Architecture) is specifically targeted at testing remote services and APIs, such as web services or remote Java and .NET components.

How does the SOA edition licensing work?

The SOA edition is a complete Silk Performer installation that is restricted by a SOA edition license. This license enables you to
  • execute load tests with up to 5 virtual users
  • perform .NET or Java testing
  • perform basic web and XML testing

What can be tested with the SOA Edition?

To be able to test remote components, you need to create test clients first. Silk Performer offers the following approaches to create test clients:
  • visual creation using Java Explorer (requires no programming)
  • visual creation using .NET Explorer (requires no programming)
  • recording an existing test client
  • importing JUnit tests
  • importing NUnit tests
  • importing Java classes
  • importing .NET classes
Parent topic: Silk Performer Licensing


Installing Silk Performer

Silk Performer can be installed in three versions:
  • Complete installation
  • Agent-only installation
  • SOA Edition installation

The standard installer comes with a graphical user interface (GUI) and offers all of these installation options. However, you can also install Silk Performer without a GUI and without any user interaction. This option is called silent mode installation.

To perform load tests with Silk Performer, you must install the complete software on at least one computer. The complete installation includes the Workbench, documentation, and sample files. The Workbench is an integrated script development environment including a load test controller and agent. To use other computers as load test agents, install the agent software on these computers.

  • Complete Installation
    Install a complete Silk Performer system on a single computer for load testing.
  • Agent-Only Installation
    Install a Silk Performer agent on a remote computer to execute Silk Performer scripts.
  • SOA Edition Installation
    Install Silk Performer SOA Edition for load testing Java and .NET applications.
  • Installing Silk Performer in Silent Mode
    Silent mode installation allows you to install Silk Performer without any user interaction.
Parent topic: Installation Guide


Complete Installation

Features installed with a complete Silk Performer installation:

  • Silk Performer Workbench
  • Silk Performer Agent
  • Performance Explorer
  • TrueLog Explorer
  • Java Explorer
  • .NET Explorer
  • all samples
Note: To avoid potential issues, make sure to run the installation with an administrator account that has unrestricted rights.
  1. Download and double-click the Silk Performer installer to start the setup wizard.
  2. The Copyright Information page displays. Click Next to read the Introduction, then click Next again.
  3. The License Agreement page displays. Read the license agreement carefully. If you accept the terms of the agreement, enable the I accept the terms of the License Agreement check box, then click Next.
  4. Click the Silk Performer 21.0 install set to install a complete Silk Performer environment and click Next.
  5. The Customize Installation page displays. Select the components you want to install:
    • Silk Performer 21.0 Workbench : Select this option to install a complete Silk Performer environment for load testing, Java and .NET applications.
    • Advanced Installation: Select this option to select which optional tools you want to install together with Silk Performer.
  6. The Choose Install Folder page displays. Specify the installation folder:
    1. Click Choose.
    2. Specify the installation folder.
    3. Click OK.
    4. To restore the default installation directory, click Restore Default Folder.
    Note: Product subfolders (for Silk Performer or TrueLog Explorer, for example) will be created automatically.
    Note: Silk Performer must be installed on a local drive.
  7. Select whether or not a desktop shortcut icon shall be created and click Next.
  8. Review the information on the Pre-Installation Summary page.
    • To change any settings, click Previous to return to the appropriate page.
    • If you are satisfied with the settings, click Install to start the installation process.
    The status bar on the Installing page provides information about the installation process.
  9. The Choose licensing mode page displays. Select one of the following options and click Next:
    • Evaluation – Installs an evaluation version of Silk Performer, which grants you full product functionality for 45 days. The usage is limited to 10 virtual users. To upgrade to a full version at a later point in time, contact your sales representative.
    • Licensed – Installs an unrestricted version of Silk Performer, which requires a Silk Performer license.
  10. Depending on the components you have selected for installation, the Select Licensing Option page displays. If you have not installed any of the components that require licensing and the page does not open, proceed to the next step. Select one of the following options and click Next:
    • Use a license server (floating licenses): In the Host field, type the name of the computer on which Silk Meter or AutoPass is installed. Do not change the default port number, (5461 for Silk Meter, 5814 for AutoPass), unless your network administrator has defined a different port. Click Test Connection to verify that the license server is accessible on the specified host and port.
      Note: In some cases, specifying the simple name of the license server in the Host field, such as licenseserver, might not work. A message box stating Connection to Silk Meter license server failed opens. To resolve this issue, specify the hostname by using a fully qualified name, such as licenseserver.mycompany.com.
    • Use a standalone license: Runs Silk Meter standalone. Specify the location of your Silk Meter license file using the Choose button.
  11. The Network Emulation Driver Installation page displays (this page does not display on Microsoft Windows 10 and Microsoft Windows Server 2016). The network emulation driver is required for packet loss and latency simulation. It is not required for network bandwidth simulation. Select one of the following options, then click Next:
    • Install the network emulation driver
    • Skip network emulation driver installation.
    Note: During installation and uninstallation of the network emulation driver, the network will be disconnected for a moment.
    Note: The network emulation driver is not compatible with all network adapters. In such a case, machines or network interfaces might no longer be accessible and the network might slow down.
    Note: The network emulation driver does not support Microsoft Windows 10 and Microsoft Windows Server 2016 and 2019.
  12. The Installation Complete page displays. Click Done to complete the installation.
    Note: If a file cannot be updated during the installation because a system library is locked by Windows, you are prompted to restart your computer. If you do not restart your computer, you might experience problems when accessing Silk Performer.
    Note: In case the installation fails, you can view the log file Install.log in the installation folder.
Parent topic: Installing Silk Performer


Agent-Only Installation

The Silk Performer agent software needs to be installed on each computer that you want to use as a load test agent. The agent software is used to execute Silk Performer scripts on remote computers.

Note: To avoid potential issues, make sure to run the installation with an administrator account that has unrestricted rights.
  1. Download and double-click the Silk Performer installer to start the setup wizard.
  2. The Copyright Information page displays. Click Next to read the Introduction, then click Next again.
  3. The License Agreement page displays. Read the license agreement carefully. If you accept the terms of the agreement, enable the I accept the terms of the License Agreement check box, then click Next.
  4. Click the Silk Performer 21.0 Agent install set to install Silk Performer agent software only and click Next.
  5. The Choose Install Folder page displays. Specify the installation folder:
    1. Click Choose.
    2. Specify the installation folder.
    3. Click OK.
    4. To restore the default installation directory, click Restore Default Folder.
    Note: Product subfolders (for Silk Performer or TrueLog Explorer, for example) will be created automatically.
    Note: Silk Performer must be installed on a local drive.
  6. Select whether or not a desktop shortcut icon shall be created and click Next.
  7. Review the information on the Pre-Installation Summary page.
    • To change any settings, click Previous to return to the appropriate page.
    • If you are satisfied with the settings, click Install to start the installation process.
    The status bar on the Installing page provides information about the installation process.
  8. The Network Emulation Driver Installation page displays (this page does not display on Microsoft Windows 10 and Microsoft Windows Server 2016). The network emulation driver is required for packet loss and latency simulation. It is not required for network bandwidth simulation. Select one of the following options, then click Next:
    • Install the network emulation driver
    • Skip network emulation driver installation.
    Note: During installation and uninstallation of the network emulation driver, the network will be disconnected for a moment.
    Note: The network emulation driver is not compatible with all network adapters. In such a case, machines or network interfaces might no longer be accessible and the network might slow down.
    Note: The network emulation driver does not support Microsoft Windows 10 and Microsoft Windows Server 2016 and 2019.
  9. The Installation Complete page displays. Click Done to complete the installation.
    Note: If a file cannot be updated during the installation because a system library is locked by Windows, you are prompted to restart your computer. If you do not restart your computer, you might experience problems when accessing Silk Performer.
    Note: In case the installation fails, you can view the log file Install.log in the installation folder.
Parent topic: Installing Silk Performer


SOA Edition Installation

Features installed with the Silk Performer SOA Edition:

  • SOA Workbench
  • Silk Performer Agent
  • Performance Explorer
  • TrueLog Explorer
  • Java Explorer
  • .NET Explorer
  • Java samples
  • .NET samples
Note: To avoid potential issues, make sure to run the installation with an administrator account that has unrestricted rights.
  1. Download and double-click the Silk Performer installer to start the setup wizard.
  2. The Copyright Information page displays. Click Next to read the Introduction, then click Next again.
  3. The License Agreement page displays. Read the license agreement carefully. If you accept the terms of the agreement, enable the I accept the terms of the License Agreement check box, then click Next.
  4. Click the Silk Performer 21.0 SOA Edition install set and click Next.
  5. The Customize Installation page displays. Select the components you want to install and click Next:
    • Silk Performer 21.0 SOA Edition: Select this option to install a complete Silk Performer SOA Edition environment for load testing Java and .NET applications.
    • Advanced Installation: Select this option to choose between either installing the tools for load testing Java applications, or for testing .NET applications.
  6. The Choose Install Folder page displays. Specify the installation folder:
    1. Click Choose.
    2. Specify the installation folder.
    3. Click OK.
    4. To restore the default installation directory, click Restore Default Folder.
    Note: Product subfolders (for Silk Performer or TrueLog Explorer, for example) will be created automatically.
    Note: Silk Performer must be installed on a local drive.
  7. Select whether or not a desktop shortcut icon shall be created and click Next.
  8. Review the information on the Pre-Installation Summary page.
    • To change any settings, click Previous to return to the appropriate page.
    • If you are satisfied with the settings, click Install to start the installation process.
    The status bar on the Installing page provides information about the installation process.
  9. The Choose licensing mode page displays. Select one of the following options and click Next:
    • Evaluation – Installs an evaluation version of Silk Performer, which grants you full product functionality for 45 days. The usage is limited to 10 virtual users. To upgrade to a full version at a later point in time, contact your sales representative.
    • Licensed – Installs an unrestricted version of Silk Performer, which requires a Silk Performer license.
  10. Depending on the components you have selected for installation, the Select Licensing Option page displays. If you have not installed any of the components that require licensing and the page does not open, proceed to the next step. Select one of the following options and click Next:
    • Use a license server (floating licenses): In the Host field, type the name of the computer on which Silk Meter or AutoPass is installed. Do not change the default port number, (5461 for Silk Meter, 5814 for AutoPass), unless your network administrator has defined a different port. Click Test Connection to verify that the license server is accessible on the specified host and port.
      Note: In some cases, specifying the simple name of the license server in the Host field, such as licenseserver, might not work. A message box stating Connection to Silk Meter license server failed opens. To resolve this issue, specify the hostname by using a fully qualified name, such as licenseserver.mycompany.com.
    • Use a standalone license: Runs Silk Meter standalone. Specify the location of your Silk Meter license file using the Choose button.
  11. The Network Emulation Driver Installation page displays (this page does not display on Microsoft Windows 10 and Microsoft Windows Server 2016). The network emulation driver is required for packet loss and latency simulation. It is not required for network bandwidth simulation. Select one of the following options, then click Next:
    • Install the network emulation driver
    • Skip network emulation driver installation.
    Note: During installation and uninstallation of the network emulation driver, the network will be disconnected for a moment.
    Note: The network emulation driver is not compatible with all network adapters. In such a case, machines or network interfaces might no longer be accessible and the network might slow down.
    Note: The network emulation driver does not support Microsoft Windows 10 and Microsoft Windows Server 2016 and 2019.
  12. The Installation Complete page displays. Click Done to complete the installation.
    Note: If a file cannot be updated during the installation because a system library is locked by Windows, you are prompted to restart your computer. If you do not restart your computer, you might experience problems when accessing Silk Performer.
    Note: In case the installation fails, you can view the log file Install.log in the installation folder.
Parent topic: Installing Silk Performer


Installing Silk Performer in Silent Mode

The setup provides the possibility to install Silk Performer without any user interaction. This option is called silent mode installation and it is especially useful if you want to distribute software over a LAN or the Internet through remote installation tools.

Note: To avoid potential issues, make sure to run the installation with an administrator account that has unrestricted rights.
  1. Open the folder with the installation file in a file manager.
  2. Create a new text file in this folder, rename it to silent.properties and open it in a text editor.
  3. Copy the following text lines and paste them into the file:
    INSTALLER_UI=silent

#Choose locale
#-------------
INSTALLER_LOCALE=en

#Choose installation set
#-----------------------
CHOSEN_INSTALL_SET=ENTERPRISE

#Choose installation folder
#--------------------------
#USER_INSTALL_DIR=C:\\Silk
CREATE_DESKTOP_ICON=1

#Choose licensing mode
#---------------------
USER_INPUT_RESULT_EVAL=0
USER_INPUT_RESULT_FULL=1

#Licensing settings
#-------------------------
SILKMETER_RUN_AUTOPASS_LICENSING=false
SILKMETER_RUN_STANDALONE=false
SILKMETER_LICENSESERVER_HOST=localhost
SILKMETER_LICENSESERVER_PORT=5461
AUTOPASS_LICENSESERVER_HOST=localhost
AUTOPASS_LICENSESERVER_PORT=5814

#User data collection
#--------------------
ALLOW_USER_DATA_COLLECTION=1

#Network emulation driver installation
#-------------------------------------
#Remove the comment in the following line to allow the driver installation
#INSTALL_NETWORKEMULATION_DRIVER=true
  4. Modify the parameters to your needs:
    • INSTALLER_LOCALE: Specify a language:
      • en: Installs the English version. This is the default setting.
      • ja: Installs the Japanese version.
      • zh_CN: Installs the Simplified Chinese version.
    • CHOSEN_INSTALL_SET: Specify one of the following installation sets:
      • ENTERPRISE: Installs a complete Silk Performer environment
      • SOA: Installs Silk Performer SOA edition
      • Agent: Installs Silk Performer agent software only
    • USER_INSTALL_DIR: Specify a folder for your Silk installations. Make sure to use double backslashes (\\) as folder separators. The default configuration is C:\\Program Files\\Silk on 32-bit operating systems and C:\\Program Files (x86)\\Silk on 64-bit operating systems.
    • CREATE_DESKTOP_ICON: Set to 1 to create a desktop icon or set to 0 to not create a desktop icon. The default value is 1.
    • USER_INPUT_RESULT_EVAL: Set to 1 to install an evaluation version of Silk Performer, which grants you full product functionality for 45 days.
    • USER_INPUT_RESULT_FULL: Set to 1 to install an unrestricted version of Silk Performer (requires a Silk Performer license).
      Note: Either USER_INPUT_RESULT_FULL or USER_INPUT_RESULT_EVAL must be set to 1. The other must be set to 0.
    • SILKMETER_RUN_AUTOPASS_LICENSING: Set to true if you want to use AutoPass license technology.
    • SILKMETER_RUN_STANDALONE: Set to true if you want to use a standalone license. Set to false if you want to use a Silk Meter or AutoPass license server.
    • SILKMETER_LICENSESERVER_HOST: Specify the name of the computer that hosts your Silk Meter license server. This parameter will be ignored if SILKMETER_RUN_STANDALONE is set to true.
    • SILKMETER_LICENSESERVER_PORT: Specify the port number on which your Silk Meter license server listens. This parameter will be ignored if SILKMETER_RUN_STANDALONE is set to true.
    • AUTOPASS_LICENSESERVER_HOST: Specify the name of the computer that hosts your AutoPass license server. This parameter will be ignored if SILKMETER_RUN_STANDALONE is set to true.
    • AUTOPASS_LICENSESERVER_PORT: Specify the port number on which your AutoPass license server listens. This parameter will be ignored if SILKMETER_RUN_STANDALONE is set to true.
    • ALLOW_USER_DATA_COLLECTION: Set to 0 to disable collecting usage data. The default value is 1. Silk Performer offers to collect data about which features of the tool are used in which way by customers. The data is rendered anonymous and sent to the R&D team, which uses the data as basis for improvements and further development.
    • INSTALL_NETWORKEMULATION_DRIVER: Set to true to install the network emulation functionality. You can skip this installation step, if issues with the network emulation occur and you do not need the functionality. The default value is false.
      Note: During installation and uninstallation of the network emulation driver, the network will be disconnected for a moment.
      Note: The network emulation driver is not compatible with all network adapters. In such a case, machines or network interfaces might no longer be accessible and the network might slow down.
      Note: The network emulation driver does not support Microsoft Windows 10 and Microsoft Windows Server 2016 and 2019.
  5. Save the file and close it.
  6. Open a command line prompt and navigate to the folder that holds the setup file and the properties file.
  7. Enter the following command:
    silkperformer-<version>.exe -f c:\<your directory>\silent.properties
    Note: Make sure to replace <version> with the actual version number of the installer package.

To check if the installation is complete, open the Windows Task Manager and click the Processes tab. When the Silk Performer installation process has disappeared, the installation is complete.

To uninstall Silk Performer in silent mode, open a command line prompt and navigate to the following folder:
<Silk installation folder>\Silk Performer 21.0\_Silk Performer 21.0_installation
Then enter the following command:
"Change Silk Performer 21.0 Installation.exe" -i silent
Parent topic: Installing Silk Performer


Installing Optional Components

  • Installing TrueLog Explorer
  • Installing TrueLog Explorer in Silent Mode
    Silent mode installation allows you to install TrueLog Explorer without any user interaction.
  • Installing the Network Emulation Driver
    Describes how to manually install and uninstall the network emulation driver.
  • Installing the Visual Studio Extension
    Install the Visual Studio Extension to use Silk Performer with Visual Studio.
  • Installing the Eclipse Plug-In
    Install the Eclipse plug-in to use Silk Performer with Eclipse.
  • Installing ShopIt V 6.0
    ShopIt V 6.0 is the sample web application provided by Silk Performer.
Parent topic: Installation Guide


Installing TrueLog Explorer

The TrueLog Explorer installer is named silktruelogexplorer-210.exe. To install TrueLog Explorer, start the installer and follow the instructions provided by the setup wizard.
Parent topic: Installing Optional Components


Installing TrueLog Explorer in Silent Mode

The setup provides silent mode installation for TrueLog Explorer as well.

Note: To avoid potential issues, make sure to run the installation with an administrator account that has unrestricted rights.
  1. Open the folder with the installation file in a file manager.
  2. Create a new text file in this folder, rename it to silent.properties and open it in a text editor.
  3. Copy the following text lines and paste them into the file.
    INSTALLER_UI=silent

#USER_INSTALL_DIR=C:\\Silk
#CREATE_DESKTOP_ICON=0
  4. Modify the following parameters to your needs. If you remove a particular parameter or comment it by prepending a hash (#) character, its default value is used.
    • USER_INSTALL_DIR: Specify a folder for your Silk installations. Make sure to use double backslashes (\\) as folder separators. The default configuration is C:\\Program Files\\Silk on 32-bit operating systems and C:\\Program Files (x86)\\Silk on 64-bit operating systems.
    • CREATE_DESKTOP_ICON: Set to 1 to create a desktop icon or set to 0 to not create a desktop icon. The default value is 1.
  5. Save the file and close it.
  6. Open a command line prompt and navigate to the folder that holds the setup file and the properties file.
  7. Enter the following command:
    silktruelogexplorer-210.exe -f silent.properties
To check if the installation is complete, open the Windows Task Manager and click the Processes tab. When the TrueLog Explorer installation process has disappeared, the installation is complete.
Parent topic: Installing Optional Components


Installing the Network Emulation Driver

The network emulation driver is required for packet loss and latency simulation. It is not required for network bandwidth simulation.

  1. Open an elevated command prompt: right-click the command prompt and click Run as administrator.
  2. Navigate to the Silk Performer installation folder by entering a string that resembles the following: c:\> cd "c:\Program Files (x86)\Silk\Silk Performer 21.0\NetworkDriver"
  3. Enter the following command ...
    • to install the network emulation driver: installNetworkDriver.exe -i netipfw.inf
    • to uninstall the network emulation driver: installNetworkDriver.exe -u
Note: During installation and uninstallation of the network emulation driver, the network will be disconnected for a moment.
Note: The network emulation driver is not compatible with all network adapters. In such a case, machines or network interfaces might no longer be accessible and the network might slow down.
Note: The network emulation driver does not support Microsoft Windows 10 and Microsoft Windows Server 2016 and 2019.
Parent topic: Installing Optional Components


Installing the Visual Studio Extension

By default, the Silk Performer Visual Studio Extension is not installed with the main Silk Performer installer. To create and run Silk Performer .NET Framework projects in Visual Studio, you need to install the extension:

  1. In the Silk Performer installation directory, open Templates\DotNet.
  2. Execute the file SpVsExtension.vsix.
Parent topic: Installing Optional Components
Parent topic: Silk Performer Visual Studio Extension


Installing the Eclipse Plug-In

You can download the Eclipse Plug-In from the product updates site.

The Eclipse SDK and Silk Performer must be installed on your computer. Make sure to run Silk Performer at least once before you start the installation.

  1. Use the standard procedure for installing Eclipse plug-ins from the Eclipse SDK ( Help > Install New Software ). If you are not sure how to install plug-ins in Eclipse, refer to the Eclipse documentation.
  2. When asked for the site to add, specify the site that contains your Silk Performer Extras folder. The Extras folder is located in the Silk Performer installation folder.
  3. Browse to and select the Eclipse Plug-in directory in your Silk Performer Extras directory (.../Extras/eclipseplugin/).
  4. Make sure that the Group items by category check box is not checked.
  5. Once the Silk Performer Eclipse Plug-in is listed, click the plus sign of the new local site to expand its contents.
  6. Check the check box of the plug-in feature (Silk Performer Feature) and then click Install. The Install dialog opens.
  7. Click Next. A license description appears on the Install dialog.
  8. If you agree to the terms of the license agreement, check the I accept the terms of the license agreement check box and then click Finish.
  9. Click Yes to restart the Eclipse Workbench. When the Eclipse Workbench is restarted, a Silk Performer menu entry appears in the Eclipse Workbench.
  • Eclipse Plug-In does not work on Microsoft Windows 8 and Microsoft Windows Server 2012
Parent topic: Installing Optional Components
Parent topic: Eclipse Plug-In


Installing ShopIt V 6.0

The Silk Performer sample web application is ShopIt V 6.0. ShopIt V 6.0 simulates a simple e-commerce website with a catalog of camping merchandise that is available for simulated online purchase. Use this application to experiment with Silk Performer's web application capabilities. ShopIt V 6.0 is designed to generate errors, including missing links (due to merchandise being out of stock) and session errors.

Before you install ShopIt V 6.0, refer to the Release Notes to ensure that your system supports the use of ShopIt V 6.0.

You can download the ShopIt V 6.0 setup from the product updates site.

  1. Double-click the file ShopItV60.exe
    Note: IIS (Internet Information Server) must be installed on the computer. For IIS 7, also install Role Services ASP and ISAPI Extensions.
  2. The Welcome page displays. Click Next.
  3. The Choose Destination Location page displays. To change the default installation directory, click Browse, specify a folder, and click OK. Click Next.
  4. Enter the name of the virtual directory for the web application. This is the name of the directory that will be created on the web server. Click Next.
  5. Setup installs the files and configures IIS to run the ShopIt V 6.0 web application.
  6. The Installation Complete dialog displays. Click Finish.
  7. For IIS 7: Add the virtual directory to IIS manually.
    • Alias: ShopItV60
    • Physical path: Install directory of ShopIt.
    Note: Make sure that ASP is available in IIS.
The ShopIt V 6.0 web application is now ready for use. You can access ShopIt V 6.0 with a browser of your choice by entering the following URL:
http://<computer name>/<virtual directory name>/

If the name of your computer is JohnSmith and you have not modified the default value ShopItV60 for the virtual directory, the URL is:

http://JohnSmith/ShopItV60/
Parent topic: Installing Optional Components
Parent topic: Sample Classic Web Application


Installing Agent Software on Remote Computers

Silk Performer provides a command-line tool that enables you to set up Silk Performer Agent software on remote machines within your Windows domain/workgroup.

For a smooth remote installation process, make sure that on the remote machine ...
  • the Windows firewall is disabled, and
  • the User Account Control is turned off or the built-in administrator account is used for the remote installation
  • Remote Installation
    Describes the command-line tool that allows you to install agent software on remote agent computers.
  • Scenarios
    Describes how to use the Remote Agent Setup to install, re-install, and uninstall Silk Performer Agent software on remote computers for several network environments.
  • Troubleshooting
    Lists error messages that might display during remote agent setup and suggests ways of solving them.
Parent topic: Installation Guide


Remote Installation

With the Silk Performer command-line tool you can install and uninstall agent software on remote agent computers. Remote agent computers can be located anywhere on the Internet.

To get a list of all available parameters for the command-line tool, open a command-line, go to the installation directory and call perfRsManager.exe

Note: You must start the command-line tool from the Silk Performer installation subdirectory.

Parameters for perfRsManager

The following parameters are available:

Note: -mode and -host are required. All other parameters are optional.
-mode
  • -i: Install the agent software on a remote agent computer.
  • -u: Update the agent software on a remote agent computer.
  • -r: Uninstall the agent software from a remote agent computer.
-host <hostname> | Hostname or IP address of the remote agent computer.
-log | Write an installation log file to the directory \Users\Public\Documents\Silk Performer <version>\Logs. The log file is named perfRsManager_<hostname>.log. For example: If you install the agent software on the host lab15, the log file will be named perfRsManager_lab15.log.
-user <user> | Name of a Windows domain user. For remote access, a user who has administrator permissions on the remote agent computer must be specified.
-domain <domain> | Name of the Windows domain or hostname, to which the specified user belongs. Omit this parameter if the user belongs to the same domain as the computer from which you invoke the installation.
-userAgent <user> | The Windows user account name that drives the agent.
-pwdUserAgent <password> | The Windows user account password for logging into the remote computer.
-pwdUser <password> | Password for the specified user. Omit this parameter if no password is required.
-port <port> | Number of the port to which the remote agent computer responds. The default port number is 19200.
-ssl | Use SSL for the communication with the remote agent computer. When SSL is used, the remote agent computer is contacted at the default port for secure connections, that is port 19201. If your agent computer responds to a different port, you must specify the port number with the -port parameter.
-httpProxy <name> <port> | Name and port number of the HTTP proxy via which the communication with the remote computer should take place.
-socksProxy <name> <port> | Name and port number of the SOCKS proxy via which the communication with the remote computer should take place.
-pwdService <password> | Password with which the agent software on the remote computer is protected from unauthorized access.
-userAgent <user> | The user that drives the agent.
-pwdUserAgent <password> | The password for logging into the remote agent computer.
-package <package file name> | The name of the remote agent installer package file. This parameter must be set for hotfix installations on remote agents and must match the EXE name of the hotfix file. If the hotfix package is not in the same folder as perfRsManager, you must define the name with the fully qualified path.
-silkInstallPath <path> | The target installation path on the remote agent computer. For example: -silkInstallPath "C:\Silk\Silk Performer".
-silkWorkingDir <path> | The working directory on the remote agent computer. For example: -silkWorkingDir "C:\WorkingDir"
-installNetworkEmulationDriver | Use this parameter to install the network emulation functionality.
-stopSilkExecutionServer | Stops and starts the Silk Execution Server if it is running.

Examples

perfRsManager -i -host deepblue
perfRsManager -i -host deepblue -log -domain intra
              -user nobody -pwdUser 1234
perfRsManager -i -host deepblue -user alex -domain test
              -pwdUser 1234
perfRsManager -i -host 192.168.20.11
perfRsManager -i -host deepblue -log -ssl -port 19251
              -socksproxy 192.168.20.111 1080
              -pwdService 1rt34xy
perfRsManager -r -host deepblue -httpproxy proxy1 8080 -log
perfRSManager -u -host deepblue -user alex -pwdUser 1234 -domain test
              -package "c:\temp\silkperformer-21.0-hf1.exe"
Parent topic: Installing Agent Software on Remote Computers


Scenarios

This section illustrates how to use the Remote Agent Setup to install, re-install, and uninstall Silk Performer Agent software on remote computers for several network environments.

  • Scenario 1: The controller and agent computers are located in the same Windows domain or workgroup.
  • Scenario 2: The controller and agent computers are located in different Windows domains or workgroups.
  • Scenario 3: The user who works on the controller computer is logged onto the computer locally, and is not logged onto a domain.
  • Scenario 4: The controller and agent computers are located in different local area networks that are connected using the Internet.
  • Scenario 5: The controller and agent computers are located in different local area networks that are connected using the Internet. At least one of the local area networks is protected by a firewall, so the controller and agent computers must communicate using an HTTP proxy.
  • Scenario 6: The controller and agent computers are located in different local area networks that are connected using the Internet. At least one of the local area networks is protected by a firewall, so the controller and agent computers must communicate using a SOCKS proxy.
  • Scenario 1: One Domain or Workgroup
    Describes the scenario of both the controller and agent computers being located in the same Windows domain or workgroup.
  • Scenario 2: Two Domains or Workgroups
  • Scenario 3: User is Logged On Locally
    Describes the scenario of the user who is logged onto the controller computer locally and is not logged onto a domain.
  • Scenario 4: Two Local Area Networks Connected Using the Internet
    Describes the scenario of two local area networks that must communicate using the Internet.
  • Scenario 5: Two Local Area Networks Connected Using HTTP Proxy
    Describes the scenario of two local area networks that communicate using an HTTP proxy.
  • Scenario 6: Two Local Area Networks Connected Using a SOCKS Proxy
    Describes the scenario of two local area networks that communicate using a SOCKS proxy.
Parent topic: Installing Agent Software on Remote Computers


Scenario 1: One Domain or Workgroup

In Scenario 1, the controller and agent computers are located in the same Windows domain or workgroup.

Working on the controller computer, you can install, re-install, and uninstall the Silk Performer Agent software on the remote agent computer (<agent name>).

To install the agent software, execute the following command:
PerfRsManager -i -host <agent name> -log

This command sets up the agent computer so that it can be configured and rebooted from remote computers.

To re-install or remove agent software, you must know the port to which the agent software responds (<port number>). By default, the agent uses port 19200. You must also know the password by which the agent software is protected from unauthorized access, if one is in use (<password>).

To upgrade agent software, execute the following command:
PerfRsManager -i -host <agent name> -port <port number>
              -pwdService <password> -log

If the agent software responds to the default port, you can omit the -port parameter.

The preceding commands generate log files with detailed information about the installation or uninstall process. If you do not want to generate these log files, omit the -log parameter.

Parent topic: Scenarios


Scenario 2: Two Domains or Workgroups

Describes the scenario of the controller and agent computers being located in different Windows domains or workgroups.

In Scenario 2, the controller and agent computers are located in different Windows domains or workgroups.

Working on the controller computer, you can install, re-install, and uninstall the Silk Performer Agent software on the agent computer (<agent name>) in the remote domain or workgroup (<domain name>). To install the agent software, you must specify a user who has administrator rights in the domain or workgroup where the agent computer is located and his or her password (<user name>, <password>).

To install the agent software, execute the following command:
PerfRsManager -i -host <agent name> -user <user name>
              -domain <domain name> -pwdUser <password> -log

This command sets up the agent computer so that it can be configured and rebooted from remote computers.

To re-install or remove agent software, you must know the port to which the agent software responds (<port number>). By default, the agent uses port 19200. You must also know the password by which the agent software is protected from unauthorized access, if one is in use (<password>).

To re-install agent software, execute the following command:
PerfRsManager -i -host <agent name> -port <port number>
              -pwdService <password> -log

If the agent software responds to the default port, you can omit the -port parameter.

To uninstall the agent software from the computer, execute the following command:
PerfRsManager -r -host <agent name> -port <port number>
              -pwdService <password> -log

If the agent software responds to the default port, you can omit the -port parameter.

The preceding commands generate log files with detailed information about the installation or uninstall process. If you do not want to generate these log files, omit the -log parameter.

Parent topic: Scenarios


Scenario 3: User is Logged On Locally

In Scenario 3, the user logs onto the controller computer locally and is not logged onto a domain.

Working on the controller computer, you can install, re-install, and uninstall the Silk Performer Agent software on the agent computer (<agent name>) in the remote domain or workgroup (<domain name>). To install the agent software, you must specify a user who has administrator rights in the domain or workgroup where the agent computer is located (<user name>, <password>) and his or her password.

To install or re-install the agent software, execute the following command:
PerfRsManager -i -host <agent name> -user <user name>
              -domain <domain name> -log

This command sets up the agent computer so that it can be configured and rebooted from remote computers.

To re-install or remove agent software, you must know the port to which the agent software responds (<port number>). By default, the agent uses port 19200. You must also know the password by which the agent software is protected from unauthorized access, if one is in use (<password>).

To uninstall the agent software, execute the following command:
PerfRsManager -r -host <agent name> -port <port number>
              -pwdService <password> -log

If the agent software responds to the default port, you can omit the -port parameter.

The preceding commands generate log files with detailed information about the installation or uninstall process. If you do not want to generate these log files, omit the -log parameter.

Parent topic: Scenarios


Scenario 4: Two Local Area Networks Connected Using the Internet

In Scenario 4, the controller and agent computers are located in different local area networks that are connected using the Internet.

Working on the controller computer, you can install and uninstall the Silk Performer Agent software on the remote agent computer (<agent name>).

You must know the port to which the agent software responds (<port number>). By default, the agent uses port 19200 for non-secured communication, and port 19201 for secure communication. You must also know the password by which the agent software is protected from unauthorized access, if one is in use (<password>).

To install or re-install agent software, execute the following command:
PerfRsManager -i -host <agent name> -port <port number>
              -pwdService <password> -ssl -log
To uninstall agent software, execute the following command:
PerfRsManager -r -host <agent name> -port <port number>
              -pwdService <password> -ssl -log

If the agent software responds to the default port, you can omit the -port parameter. Also, if you do not require communication over a secure communication channel, omit the -ssl option.

The preceding commands generate log files with detailed information about the installation or uninstall process. If you do not want to generate these log files, omit the -log parameter.

Parent topic: Scenarios


Scenario 5: Two Local Area Networks Connected Using HTTP Proxy

In Scenario 5, the controller and agent computers are located in different local area networks that are connected using the Internet. At least one of the local area networks is protected by a firewall, so the controller and agent computers must communicate using an HTTP proxy.

Working on the controller computer, you can install and uninstall the Silk Performer Agent software on the remote agent computer (<agent name>). The communication takes place by way of an HTTP proxy (<proxy name>, <proxy port>). To re-install or remove agent software, you must know the port to which the agent software responds (<agent port>). By default, the agent uses port 19200 for non-secured communication, and port 19201 for secure communication. You must also know the password by which the agent software is protected from unauthorized access, if one is in use (<password>).

To install or re-install the agent software, execute the following command:
PerfRsManager -i -host <agent name> -port <agent port>
              -pwdService <password> -ssl -log
              -httpProxy <proxy name> <proxy port>
To uninstall agent software, execute the following command:
PerfRsManager -r -host <agent name> -port <agent port>
              -pwdService <password> -ssl -log
              -httpProxy <proxy name> <proxy port>

If the agent software responds to the default port, you can omit the -port parameter. Also, if you do not require communication over a secure communication channel, omit the -ssl option.

The preceding commands generate log files with detailed information about the installation or uninstall process. If you do not want to generate these log files, omit the -log parameter.

Parent topic: Scenarios


Scenario 6: Two Local Area Networks Connected Using a SOCKS Proxy

In Scenario 6, the controller and agent computers are located in different local area networks that are connected using the Internet. At least one of the local area networks is protected by a firewall, so the controller and agent computers must communicate using a SOCKS proxy.

Working on the controller computer, you can install and uninstall Silk Performer Agent software on the remote agent computer (<agent name>). The communication thereby takes place by way of a SOCKS proxy (<proxy name>, <proxy port>). To re-install or remove agent software, you must know the port to which the agent software responds (<agent port>). By default, the agent uses port 19200 for non-secured communication, and port 19201 for secure communication. You must also know the password by which the agent software is protected from unauthorized access, if one is in use (<password>).

To install or re-install agent software, execute the following command:
PerfRsManager -u -host <agent name> -port <agent port>
              -pwdService <password> -ssl -log
              -socksProxy <proxy name> <proxy port>
To uninstall agent software, execute the following command:
PerfRsManager -r -host <agent name> -port <agent port>
              -pwdService <password> -ssl -log
              -socksProxy <proxy name> <proxy port>

If the agent software responds to the default port, you can omit the -port parameter. Also, if you do not require communication over a secure communication channel, omit the -ssl option.

The preceding commands generate log files with detailed information about the installation or uninstall process. If you do not want to generate these log files, omit the -log parameter.

Parent topic: Scenarios


Troubleshooting

This section lists error messages that might display during setup and suggests ways of solving them:

Error Message | Remarks
SYSTEM: 53 - The network path was not found . | Invalid host name specified or host not reachable. Check -host parameter and make sure the machine is running.
SYSTEM: 1326 - The user name or password is incorrect . | Check -user and -pwduser parameters. If you are using the credentials of the built-in administrator of the remote machine, make sure the account is enabled.
Info: Connected to remote machine. Warning: Could not start Remote Registry service. Error: Could not install and start temporary service. Remote setup failed! SYSTEM: 5 - Access is denied. | The remote machine could be reached with the given credentials but permissions of the specified user do not allow to start the installer process. Turn off User Account Control (UAC) on the remote machine or use its built-in administrator account. Check whether Remote Registry is running.
System: 1219 - The supplied credentials conflict with an existing set of credentials. A network connection to the target computer already exists. | A network connection to the target computer already exists. This connection was established with a different user/password combination. Execute the following DOS command to close the connection: net use \\<machine name> /delete To check if the connection has been closed, execute the following DOS command: net use
PerfOrb: 23 - The connection could not be established. | A connection attempt to the remote machine failed. Make sure the Windows firewall is disabled and User Account Control (UAC) is turned off.
Error: Could not install Remote Agent Setup on remote machine. Remote setup failed! PerfOrb: 20 - The orb is not connected. | The connection to the machine was lost during installation. Restart the remote installer.
Parent topic: Installing Agent Software on Remote Computers


Silk Performer Workbench 21.0

Welcome to Silk Performer Workbench 21.0.

Silk Performer is the enterprise-class solution for software-application performance, load, and stress testing. Silk Performer is used to assess the performance of Internet servers, database servers, distributed applications, and middleware, both before and after they are fully developed. Silk Performer helps you to quickly and cost-effectively produce reliable, high-quality application solutions.

  • What's New in Silk Performer 21.0
    Details the significant enhancements and changes introduced with Silk Performer 21.0.
  • Getting Started
    Includes information about new functionality, an overview of load-test execution , and a performance and scalability matrix for workload configuration.
  • Configuring Silk Performer
    Provides an overview of the Silk Performer Workbench, Silk Performer Recorder, remote agents, and Java configuration.
  • Managing Load Tests
    Lists the tasks that must be completed to prepare for, run, and analyze the results of a load test .
  • Load Testing Specific Application Types
    Silk Performer can test applications within a variety of computing environments, including AJAX, SAP eCATT, terminal emulation, GUI-level testing, and much more.
  • Load Testing in Specific Environments
    Describes how load testing in specific environments works.
  • Silk Performer Plug-Ins
    Provides an overview of the types of plug-ins available and the controls available for those plug-ins.
  • Silk Central Integration
    Explains how Silk Performer can be integrated with Silk Central, including configuration settings, test-result management, and the import of Silk Performer projects.
  • Silk Performance Manager Integration
    Describes how to integrate Silk Performer with Silk Performance Manager.
  • Source Control Integration
    Provides an overview of how source control integration works with Silk Performer.
  • Importing, Uploading, and Emailing Projects
    Explains how to export an entire test project to a separate directory or an archive file. Such exported project files can subsequently be imported into Silk Performer.
  • Troubleshooting
    Explains known issues and troubleshooting tips for Silk Performer.
  • Known Issues in Silk Performer


What's New in Silk Performer 21.0

Silk Performer 21.0 introduces significant enhancements and changes.

  • Web on Protocol-level Enhancements
    Silk Performer now supports Brotli compression and new authentication fallback scenarios for HTTP/2.
  • Browser-driven Load Testing Enhancements
    Besides a number of other enhancements for browser-driven load testing, Silk Performer now supports browser-driven script recording for Chrome, Firefox, Edge, and Opera browsers.
  • Convenience Functionality in BDL
    Silk Performer 21.0 adds a number of convenience features through the BDL API.
  • Integration Enhancements
    Silk Performer 21.0 provides a number of integration enhancements like new project upload wizards, new command-line tools, third-party plugin support for GUI-less environments, and more.
  • Other Enhancements
    Silk Performer provides a number of additional new features like support for AutoPass licensing, for Java 11, and more.
  • Technology Updates
    This release again provides a number of technology updates.
Parent topic: Silk Performer Workbench 21.0


Web on Protocol-level Enhancements

The following enhancements for web load testing on protocol-level have been implemented:

Brotli compression

Silk Performer now supports Brotli compression for protocol-level HTTP/HTML scripts. Brotli compression is an addition to other compression algorithms such as gzip.

Authentication fallback scenarios in HTTP/2

Many modern web applications use HTTP/2, however, negotiation for NTLM and Kerberos authentication is not defined for the HTTP/2 protocol. Thus, browsers are using various fallback strategies to HTTP/1.x to authenticate a user. Silk Performer 21.0 implements the fallback behavior of Google Chrome.

Parent topic: What's New in Silk Performer 21.0


Browser-driven Load Testing Enhancements

The following enhancements have been implemented for browser-driven load testing:

Browser-driven script recording for Chrome, Firefox, Edge and Opera browsers

Silk Performer now lets you record browser-driven scripts using Firefox, Chrome, Edge and Opera. To do so, it uses Silk WebDriver, which originally was a pure functional testing tool to record Silk Test or Selenium scripts. For Silk Performer 21.0 and onwards, the tool allows to generate browser-driven BDL scripts.

Locator Spy for Chrome, Firefox, Edge and Opera browsers

To facilitate locator generation and modification for all supported browsers except Internet Explorer, the Locator Spy is offered in the Tools menu.

Enhanced Silk WebDriver update for agents

You can update Silk WebDriver on your agents through the systems settings by selecting one or more agents on the Agent Pool tab, right-clicking, and clicking Update Webdriver. Another option is to update Silk WebDriver through the Summary page.

BrowserTypeKeys with delay parameter

The BDL function BrowserTypeKeys now offers a delay parameter, which lets you specify the delay between the separate keystrokes.

Identifying the determining TTI element

TrueLog Explorer now displays the element that determines the time to interact (TTI) in the Info tab.

Maximum length of DOM attribute values

For browser-driven scripts, Silk Performer lets you configure a number of settings, like which DOM attribute names to ignore and which to prefer. You can now also set the maximum length of DOM attribute values. If the value is longer than specified, it will be cut off.

Starting browsers with command-line arguments

You can now add custom command-line arguments in the profile settings for all supported browsers (except Internet Explorer).

Parent topic: What's New in Silk Performer 21.0


Convenience Functionality in BDL

Silk Performer 21.0 adds a number of convenience features through the BDL API:

ToUnicode() and FromUnicode() BDL functions

The new ToUnicode() BDL function lets you convert ANSI string representation into a unicode escape sequence of type \uxxxx. The FromUnicode() BDL function allows you to convert all unicode escape sequences of type \uxxxx from string into the corresponding characters.

HashSHA2() function

The new BDL function HashSHA2() calculates an SHA2 hash value of an input string. The required SHA2 hash length can be passed as a function argument.

WebFtpGetFileSize() and WebFtpGetFileTime() functions

WebFtpGetFileSize() retrieves the file size of a remote file through FTP. WebFtpGetFileTime() retrieves the file date and time properties of a remote file respectively.

Print Function() prints to the Output pane

The API function Print Function() prints additional information to the output that displays on the Virtual User tab in the Output pane. Additionally, the data passed to all Print* functions is now written to the log file.

Parent topic: What's New in Silk Performer 21.0


Integration Enhancements

Silk Performer 21.0 provides a number of integration enhancements like new project upload wizards, new command-line tools, third-party plugin support for GUI-less environments, and more.

Project upload to LoadRunner Enterprise and LoadRunner Cloud

You can now upload your Silk Performer projects to both LoadRunner Enterprise and LoadRunner Cloud using the wizards Silk Performer provides. Once LoadRunner Enterprise and LoadRunner Cloud provide support for the integration, you will be able you define and execute your Silk Performer workloads in the respective LoadRunner environment.

New command-line tools - PerfProj and PerfExec

Silk Performer provides the two new command-line tools PerfProj.exe and PerfExec.exe, which greatly simplifies the modification and execution of your Silk Performer projects in CI environments. Among other settings you can specify the standard host, the port, agents, or result folder paths through command-line arguments. More information is available directly in the command-line through the argument /?.

Third-party plugin support for GUI-less environments

When running projects in GUI-less environments like Silk Central, LoadRunner Enterprise, LoadRunner Cloud, Jenkins, or the command-line, third-party plugins such as Dynatrace and InfluxDB are now available.

JUnit style result file

Silk Performer can now generate a JUnit style result file, which can be automatically interpreted in various CI tools. The result file displays any errors that might have occurred and shows warnings if performance levels were not met.

Jenkins plugin support for 64-bit Java

The Silk Performer Jenkins plugin now works with 64-bit Java installations.

Project upload to BMC Helix Monitor

Silk Performer now provides a wizard to upload projects to BMC Helix Monitor.

Parent topic: What's New in Silk Performer 21.0


Other Enhancements

Silk Performer provides a number of additional new features like support for AutoPass licensing, for Java 11, and more.

AutoPass licensing

In addition to Silk Meter, Silk Performer now allows the use of Micro Focus AutoPass as a license technology for floating licenses. AutoPass provides additional functionality like user management, usage tracking, or reporting. For more information, refer to the Installation Guide.

Java 11

Silk Performer now supports Java 11 in the Java framework, Java Explorer, as well as other Java technologies.

Agent alias names

In the agent pool, Silk Performer now allows to specify an alias for Silk Performer agent machines. Aliases display in various places in the user interface.

Editor shortcuts

For the script editor of Silk Performer, additional shortcuts are now available: To toggle a comment, press Ctrl+Shift+Q. To duplicate a selection or line, press Ctrl+D. To create a new line above the current line, click Ctrl+Enter.

Silk Performer provides a PDF, which gives you an overview of all available shortcuts for the Workbench, the Recorder, the Browser Application, TrueLog Explorer, and more. Additionally, the PDF visualizes the features of the new script editor. To access the PDF, open the Startpage, click the Get Started tab, and click Reference Sheet with Keyboard Shortcuts (pdf).

Parent topic: What's New in Silk Performer 21.0


Technology Updates

OpenSSL

OpenSSL has been upgraded to version 1.1.1g.

Other components

Several third-party components have been upgraded to their latest versions to remediate all known vulnerabilities and other defects.

Parent topic: What's New in Silk Performer 21.0


Getting Started

Includes information about new functionality, an overview of load-test execution , and a performance and scalability matrix for workload configuration.

  • Introduction to Silk Performer
    Explains how to use Silk Performer to assess the performance of Internet servers, database servers, distributed applications, and middleware.
  • Benefits of Using Silk Performer
    Explains that Silk Performer is the industry's most powerful and easiest to use enterprise-class load and stress testing tool.
  • Tour of the UI
    Introduces the main elements of the Silk Performer UI.
  • Managing Your Load Testing: Start to Finish Overview
    Offers a high-level overview of the steps involved in preparing for, running, and analyzing the results of a load test.
  • Upgrading to Silk Performer 21.0
    Upgrade to either the full or evaluation version of Silk Performer 21.0.
  • Performance and Scalability Matrix
    Provides guidance for calculating the recommended maximum number of virtual users per agent.
  • Memory Footprints by Application Type
    Outlines the memory footprint sizes required by each application type that Silk Performer supports.
  • Sample Web 2.0 Application
    Explains that Silk Performer offers a modern sample Web application that you can use to learn about Web 2.0 application testing.
  • Silk Performer Keyboard Shortcuts
    Silk Performer provides a number of keyboard shortcuts to speed up your workflow.
Parent topic: Silk Performer Workbench 21.0


Introduction to Silk Performer

Silk Performer is the enterprise-class solution for software-application performance, load, and stress testing. Silk Performer is used to assess the performance of Internet servers, database servers, distributed applications, and middleware, both before and after they are fully developed. Silk Performer helps you to quickly and cost-effectively produce reliable, high-quality application solutions.

Silk Performer creates highly realistic and fully customizable load-tests . It accomplishes this task through the use of virtual users that automatically submit transactions to systems under test in the same manner as real users.

Using a minimum of hardware resources, you can generate tests that simulate hundreds or thousands of concurrent users. You can also use Silk Performer's powerful reporting tools both during and after load tests to analyze the performance of servers and to locate bottlenecks so you can maximize the potential of your system.

Questions That Silk Performer Can Help You Answer

  • How many simultaneous users can my server support?
  • What response times do my users experience during peak hours?
  • Which hardware and software products do I need to ensure optimum performance from my server?
  • Which components are the bottlenecks in my system?
  • What is the performance impact on my system of employing security technology?
  • Which areas of my application perform adequately, and which areas contain bottlenecks in the forms of business transactions, objects, and operations that can be evaluated?
  • Which factors affect performance? What effects do they have? And at what point do such factors impact service levels?
Parent topic: Getting Started


Benefits of Using Silk Performer

Silk Performer is the industry's most powerful and easiest to use enterprise-class load and stress testing tool. Visual script generation techniques and the ability to test multiple application environments with thousands of concurrent virtual users allow you to thoroughly test your enterprise applications' reliability, performance, and scalability before they are deployed-regardless of their size and complexity. Powerful root-cause analysis tools and management reports help you isolate problems and make quick decisions, thereby minimizing test cycles and accelerating your time to market.

Following are some of the key advantages that Silk Performer provides:

  • Ensure the scalability, performance, and reliability of your enterprise applications. Silk Performer ensures the quality of your enterprise applications by measuring their performance from the end-user perspective, as well as internally, in a variety of workload scenarios and dynamic load conditions.
  • Test remote components early in the development cycle. Dramatically reduce the cost of defects in your multi-tier enterprise application by testing the functionality, interoperability, and performance of remote components early in the development cycle, even before client applications have been built. You can rapidly generate test drivers for Web services, .NET remoting objects, EJBs and Java RMI objects by exploring them via a point and click interface. Alternatively, you can reuse unit test drivers written by developers for concurrency tests or you can build new testcases directly in Java and .NET languages such as C# and VB.NET using the Silk Performer Visual Studio .NET Add-On.
  • Pinpoint problems easily for quick resolution. Unrivaled TrueLogTM technology for HTML, XML, SQL, Oracle Forms, Citrix, TCP/IP, and UDP-based protocol data provides full visual root-cause analysis from the end-user perspective. TrueLogs visually recreate the data that users input and receive during load tests. For HTML pages, this includes all embedded objects. This enables you to visually analyze the behavior of your application as errors occur during tests. In addition, detailed response timer statistics help you uncover the root causes of missed service level agreements before your application goes live.
Parent topic: Getting Started


Tour of the UI

Silk Performer's UI features four main areas:

Tour of the user interface

Workflow Bar

The workflow bar guides you sequentially through the steps involved in creating a typical load test. Each button on the following workflow bar represents a task, organized chronologically from left to right, that must be completed to successfully create, configure and run a load test, and to analyze load test results. There are three types of the workflow bar:

The simple workflow bar:

Simple Workflow Bar

The full workflow bar:

Fulll Workflow Bar

The monitoring workflow bar:

Fulll Workflow Bar
Note: By default, Silk Performer displays the simple workflow bar. To switch between the workflow bar types, right-click on the workflow bar and click Show Simple Workflow Bar, Show Full Workflow Bar, or Show Monitoring Workflow Bar.
Workflow bar buttons
Outline Project
Give your project a name, description, and application-type profile.
Model Script
Create your test script. You can build your test script manually or have it recorded for you.
Try Script
Perform a trial run of your test script to make sure it runs as intended. If the trial run was successful, you can insert verification functions or parameterized input-data into your test script. Alternatively, you can edit your script so that it handles session information during replay.
Define User Types
A user type is a unique combination of a script, a user group, and a profile. Hence, by selecting a user type, you define which script shall be executed with what user group and what profile. User types are selected for a certain workload. You can use several workloads in your load test project and save them for further usage.
Find Baseline (only on the full workflow bar)
A baseline serves as a reference level for subsequent load tests. Silk Performer uses the results of a baseline test to calculate the number of concurrent users per user type.
View Baseline (only on the full workflow bar)
If you are happy with the results of a baseline test, you can set the baseline test as baseline. Then you can configure response time thresholds for the subsequent load tests.
Adjust Workload
Define the workload model that your test script will simulate and define the network bandwidth-type that the virtual users in your test will simulate.
Assign Agents
Configure the distribution of the virtual users in your load-testing environment. Assign VUsers to specific agents, agent clusters, or cloud agents, using wizards that calculate recommended capacities for you.
Try Agents
Perform a trial run of your script to make sure that it runs on the agents that you have configured for the load test.
Configure Monitoring
Define how Performance Explorer, the Silk Performer server monitoring tool, is to monitor local and remote servers involved in your test.
Run Test
Deploy your test to the agent computers in your test environment. You can monitor the progress of the test in real time.
Explore Results

Analyze the results of the test to assess the performance of the application and server under test.

Upload Project (only on the full workflow bar)
You can reuse your project by uploading it to Silk Central or to Performance Manager. The project can then be directly executed through Silk Central or Performance Manager.

Project Menu Tree

Contains all of your project assets, including one or more profiles and test scripts, a workload, agent computers, and data files.

Monitor/Script Window

The Monitor page provides real-time information about the progress of your load test. The displayed columns depend on the application type of your project and can be customized by right-clicking either the Summary or the User list box on the Monitor page and choosing Select Columns. The selected columns are saved per project.

The <script name> page displays the script editor. Use the this page to view and edit your test script.

Output Window

Displays status messages, such as errors, warnings, and other information, when you perform the following actions:
  • Compile a script – The Compiler page displays compiler messages, including errors and warnings.
  • Run a test – The Virtual User page displays messages related to the actions of a virtual user in a test, such as transaction information and time measures. The Simulation Controller page displays information about the Silk Performer controller.
Parent topic: Getting Started


Managing Your Load Testing: Start to Finish Overview

This section offers a high-level overview of the steps involved in preparing for, running, and analyzing the results of a load test.

Each task outlined below correlates directly with a button on the Silk Performer workflow bar. The workflow bar guides you sequentially through the steps involved in creating and managing a typical load test.

  • Outlining Projects
    Explains how to define name, description, and application-type-under-test parameters for your project.
  • Modeling Scripts
    Explains how test scripts are created (manually, recorded, or based on a sample script). Test scripts define the actions of virtual users in load tests.
  • Trying Out Scripts
    Ensure that your test script is free from error and accurately reproduces required interaction between client application and server.
  • Customizing Scripts
    Explains why it is recommended to customize your scripts before you run a load test and what problems can occur if you do not customize your scripts.
  • Defining User Types
    Explains how to define a user type for the active workload. Defining a user type determines what script, user group, and profile will be used in the test.
  • Finding Baselines
    Explains how to run a baseline test to determine your application's ideal performance baseline.
  • Viewing Baselines
    Provides an overview of how to confirm that the baseline test reflects the desired performance of the application under test and how to set the baseline test as the baseline.
  • Adjusting Workload
    Explains how to define the workload for load tests.
  • Assigning Agents
    Configure the distribution of virtual users in your load testing environment and assign VUsers to specific agents, agent clusters, or cloud agents.
  • Trying Out Agents
    Explains how to perform a trial run of a test script to verify that the script works on various agents.
  • Configuring Monitoring
    Explains options for monitoring local and remote computers with Performance Explorer during tests.
  • Running Tests
    Describes the procedures that must be run and the options that must be set for executing load tests.
  • Exploring Results
    Describes the approaches that are available for displaying, reporting, and analyzing test results.
Parent topic: Getting Started


Outlining Projects

When you create a Silk Performer load test you must define the basic settings for the load test project. The project is given a name, and optionally a brief description can be added. The type of application to be tested is specified from a range of choices that includes all of the major traffic available today on the Internet and on the Web, including the most important database and distributed applications.

The settings that are specified are associated with a particular load test project. It is easy to switch between different projects, to edit projects, and to save projects so that they can later be modified and reused.

A project contains all the resources needed to complete a load test. These include a workload, one or more profiles and load test scripts, a specific number of agent computers and information for server-side monitoring, and all the data files that are accessed from the script. Options for all of these resources are available directly from the project node in the Project menu tree.

  • Outlining a Project
    Configure basic settings such as project name and the application type under test.
Parent topic: Managing Your Load Testing: Start to Finish Overview


Outlining a Project

  1. Click Start here on the Silk Performer workflow bar.
    Note: If another project is already open, choose File > New Project from the menu bar and confirm that you want to close your currently open project.
    The Workflow - Outline Project dialog box opens.
  2. In the Name text box, enter a name for your project.
  3. Enter an optional project description in Description.
  4. From the Type menu tree, choose the type of application that you want to use in your test.
    Note: If you are testing a Web application, choose the Web business transaction (HTML/HTTP) option to create simpler scripts while incorporating advanced functionality. Choose the Web low level (HTTP) option if you want to put the highest possible load on your application. Web low level scripts are more complex than Web business transaction scripts, which require more effort to customize. It is recommended that you use the Web business transaction (HTML/HTTP) instead of the Web low level (HTTP) scripts for browser based applications.
  5. Click Next.
    Note: If you need to add additional resources to the project, right-click the project icon in the Project menu tree view. It is particularly important that all the user data files (.csv), random data files (.rnd), and .idl files needed by Silk Performer are set up for your project.
The Workflow - Model Script dialog box appears.
Parent topic: Outlining Projects
Parent topic: Outlining Projects
Related tasks
Recording a Test Script
Related reference
Available Application Types


Modeling Scripts

Before you can conduct a Silk Performer load test you need to create a test script that prescribes the actions of the simulated users run during the test. The script is written in Silk Performer's proprietary scripting language, the Benchmark Description Language (BDL).

Scripts can be created in different ways depending on the application type. The standard (and typically easiest) method for creating a test script is to use the Silk Performer Recorder to capture and record traffic that is representative of the type you need to simulate in your test. The Silk Performer Recorder automatically generates a BDL test script based on the recorded traffic.

Another method of creating a test script is to manually create a new script in BDL. A variant on the manual approach is to create a test script based on one of the sample BDL scripts that are provided by Silk Performer.

  • Recording a Test Script
    Create a test script with the Silk Performer Recorder, Silk Performer's engine for recording traffic and generating test scripts.
Parent topic: Managing Your Load Testing: Start to Finish Overview


Recording a Test Script

If you are an experienced user, you may want to create a script on your own and write your code manually. You can start with a blank script or you can customize one of the preinstalled sample scripts.

However, you can also use the Silk Performer Recorder, which does the scripting and the recording work for you. Here are the basic steps you need to perform when you use the Silk Performer Recorder:

  1. Open the project in which you want to work, or start a new project.
  2. Click Model Script on the workflow bar. The Workflow - Model Script dialog box appears.
  3. From the Recording Profile list, select the profile for the client application that you plan to test. If a profile has not yet been set up for the application you want to use, click Settings to the right of the list to set one up.
  4. Depending on the project type, enter either the application's URL in the URL field or the location of the application in the Command line field.
  5. Click Start recording. The Silk Performer Recorder dialog opens in minimized form, and the client application starts.
  6. To see a report of the actions that happen during recording, maximize the Recorder dialog by clicking the Change GUI size button. The maximized Recorder opens at the Actions page.
  7. Using the client application, conduct the kind of interaction with the target server that you want to simulate in your test. The interaction is captured and recorded by the Recorder. A report of your actions and of the data downloaded appears on the Actions page.
  8. Insert transactions and timers into the test script during the recording phase. You can create as many transactions and timers as you want. To insert a transaction, click the New Transaction button. A transaction represents a piece of work that can be assigned to a virtual user.
  9. In the ensuing dialog, enter a name for the transaction and click OK. The new transaction appears in the Actions log.
  10. To insert a timer, click the New Timer Session button. A timer is a user-defined measurement period in a test. You should create timers for each component of a transaction for which you want to analyze performance. In the ensuing dialog, enter a name for the timer and click OK.
  11. To end recording, click the Stop Recording button.
  12. Enter a name for the .bdf file and save it. The Capture File page displays. Click Generate Script to generate a script out of the capture file.
  13. Close the client application and close the Silk Performer Recorder.
Parent topic: Modeling Scripts
Parent topic: Recorded Test Scripts
Related tasks
Adding Recording Profiles


Trying Out Scripts

Part of the process of conducting a Silk Performer load test is to perform a trial run of the test script that was created during script modeling.

Normally, this is traffic recorded by the Silk Performer Recorder during script modeling. For a trial run, or Try Script, of a test script, options are automatically selected so that you can see a live display of the actual data downloaded. Log files, TrueLog files, report files, output files, and error files are created so that you can later confirm that the script works properly. Only one user is run, and the stress test option is enabled so that there is no think time and no delay between transactions. However, at this stage, the measurements typical of a real load test are not performed.

Try Script Settings

For Try Script runs, the following options are automatically set to these specified values (see also "Replay Options"):

  • The Stress test option is on, when think times are disabled.
  • The Stop virtual users after simulation time (Queuing Workload) option is off.
  • The Virtual user log files (.log) option is on.
  • The Virtual user output files (.wrt) option is on.
  • The Virtual user report files (.rpt) option is on.
  • The Virtual user report on error files (.rpt) option is on.
  • The TrueLog files (.xlg) option is on.
  • The TrueLog On Error files (.xlg) option is off.
  • The Compute time series data (.tsd) option is off.
  • All logging detail options ( Results > Logging and Results > Internet Logging page) are on.
  • The Enable all measure groups (TSD measure groups) option is off.
  • The Bandwidth option is set to High Speed (unlimited).
  • The Downstream option is set to unlimited.
  • The Upstream option is set to unlimited
  • The Duplex option is off.
  • Trying Out a Test Script
    Validate the results of a trial test-script run to ensure that your script works.
Parent topic: Managing Your Load Testing: Start to Finish Overview


Trying Out a Test Script

You must record or manually create a test script before you can run a Try Script.

  1. Click the Try Script button on the Silk Performer Workflow bar. The Workflow – Try Script dialog appears.
  2. Choose a script from the Script list box.
  3. In the Profile list box, the currently active profile is selected (this is the default profile if you have not configured an alternate profile).
    1. To configure simulation settings for the selected profile, click Settings to the right of the list box.
    2. To configure project attributes, select the Project Attributes link.
  4. In the Usergroup list of user groups and virtual users, select the user group from which you want to run a virtual user. Since this is a Try Script run, only one virtual user will be run.
  5. To view the actual data that is downloaded from the Web server during the Try Script in real-time, select the Animated Run with TrueLog Explorer check box. If you are testing anything other than a Web application, you should disable this option.
  6. Click Run. The Try Script begins.
All recorded think times are ignored during Try Script runs. The Monitor window opens, giving you detailed information about the progress of the Try Script run. If you have selected the Animated option, TrueLog Explorer opens. Here you can view the actual data that is downloaded during the Try Script run. If any errors occur during the Try Script run, TrueLog Explorer can help you to find the errors quickly and to customize session information. Once you have finished examining and customizing your script with TrueLog Explorer, your script should run without error.
Parent topic: Trying Out Scripts
Parent topic: Trying Out Scripts
Related concepts
Replay Settings
Project Attributes


Customizing Scripts

After you have recorded and tried out your script for the first time, you may need to customize it for two reasons:

  • The script does not replay without errors.

    Session-specific data that was captured during recording is usually not valid during replay. This is because data like session IDs change every time a new communication session is started with the application under test. Session-specific data can be represented by variables and is, consequently, dynamically adjusted during each run. This leads to clean scripts that work flawlessly every time they are executed.

  • You want to introduce more variety in virtual user behavior.

    The virtual users will behave identically during your load test, unless you introduce data or environmental variation, such as simulating different browsers, bandwidths, or paths through the application.

Therefore, it is recommended to customize your scripts before you start a load test. Customizing scripts offers the following advantages:

  • Your virtual users will be diverse.

    For example, you can set them up to use different browsers and bandwidths from different locations to access the application under test.

  • Your virtual users will behave more realistically and more natural.

    This can be achieved with randomized data. The virtual users will then, for example, input varying data in forms, like different names, addresses, and credit card numbers. They can vary the product names they search for, the products they order, and so on. This leads to accurate and meaningful result data.

Customizing scripts is typically done before you move on with the next step in the workflow bar.

  • Function and Transaction Declarations
    Explains how to insert function and transaction declarations into test scripts.
  • User Groups
    Explains how to customize the virtual user activity, using the concept of user groups.
  • Creating Parameters with the Parameter Wizard
    The Parameter Wizard enables realistic functionality to be created for virtual users during tests by replacing recorded or scripted values with constant values, random values, or values pulled from multi-column data files.
  • Serialization and Synchronization
    There are several Silk Performer functions that allow you to either serialize or synchronize transactions in your test scripts to better control the timing of loads in your simulation.
  • Check list for building robust scripts
    This topic provides tips and suggestions on customizing a script to make it more robust and less error-prone.
  • Custom DLLs
    Call functions that are provided in Dynamic Link Libraries (DLLs) from within a Silk Performer script.
  • Client IP Address Simulation
    Describes how to configure network interface cards for multiple IP addresses and the script functions that are used to set up local IP addresses.
Parent topic: Managing Your Load Testing: Start to Finish Overview
Parent topic: Managing Load Tests


Defining User Types

The next step in the process of conducting a Silk Performer load test is to define one or more user types for the active workload. A user type is a unique combination of a script, a user group, and a profile. By selecting a user type, you determine which script will be executed with which user group and profile.

To find out what your active workload is, expand the Workloads node in the Project tree. The active workload is shown in bold text.

Click Define User Types on the workflow bar to access all necessary settings.

Note: The Define User Types button on the workflow bar is only visible when the simple workflow bar is enabled. The workflow bar displays the simplified workflow by default. To switch between the workflow bar types, right-click on the workflow bar and click Show Simple Workflow Bar, Show Full Workflow Bar, or Show Monitoring Workflow Bar.
  • Defining a User Type
    Explains how to define user types for the active workload.
  • User Types
    Explains what a user type is and where to configure it.
Parent topic: Managing Your Load Testing: Start to Finish Overview
Parent topic: Managing Load Tests


Defining a User Type

To define user types for the active workload:
  1. Click Define User Types on the workflow bar. The Workflow - Define User Types dialog box appears.
  2. Optional: Narrow down the list of Available User Types by selecting entries from the Script and Profile lists.
  3. Optional: Click Add new to create a new profile. If you select a profile from the list, you can click Edit Profile to adjust the settings of the profile. For example, you can define a certain browser and bandwidth for this profile. Click Set as active to make the selected profile the active one.
  4. Select one or more user types in the Available User Types list and click the arrow buttons to assign the user types to the workload. You can also double-click user types to move them between the Available User Types list and the User Types in Workload list.
  5. User types that are assigned to the workload are automatically selected for execution. If you want a certain user type to not be executed during the baseline run, deselect it.
  6. Click Next to advance to the next step in the workflow.
Note: The Define User Type button is only visible when simple workflow bar is enabled.
Note: By default, Silk Performer displays the simple workflow bar. To switch between the workflow bar types, right-click on the workflow bar and click Show Simple Workflow Bar, Show Full Workflow Bar, or Show Monitoring Workflow Bar.
Parent topic: Defining User Types


Finding Baselines

A baseline serves as a reference level for subsequent load tests. Silk Performer uses the results of a baseline test to calculate the number of concurrent users per user type. Additionally, you can set response time thresholds based on the results of a baseline.

At first, you need to run a baseline test. After a baseline test run is finished, you can view all measurements and details of the run on the Baseline Test Summary page and in the baseline report. If you are happy with the results, you can set the baseline test as your new baseline. You can view the results and values of your baseline at any time by clicking View Baseline on the workflow bar. This opens the Baseline Summary page.

Note: To work with baselines, you must enable the full workflow bar.
Note: By default, Silk Performer displays the simple workflow bar. To switch between the workflow bar types, right-click on the workflow bar and click Show Simple Workflow Bar, Show Full Workflow Bar, or Show Monitoring Workflow Bar.
  • Finding a Baseline
    Run a baseline test to calculate concurrent-user and timer-threshold settings before load testing.
  • Baseline Tests
    Explains how to determine your application's ideal performance baseline.
  • Baseline Test Summary
    On the Baseline Test Summary page, you can analyze the measurements captured during a baseline test run and set the baseline test run as your baseline.
  • User Types
    Explains what a user type is and where to configure it.
  • Baseline Test Report
    Describes the contents of a baseline report.
  • Detailed Test Report Content
    Describes the sections, text boxes, and UI elements for a baseline report.
  • Setting a Baseline Test as Baseline
    Confirm that the results of a baseline test reflect the desired performance of the application under test.
Parent topic: Managing Your Load Testing: Start to Finish Overview
Parent topic: Managing Load Tests


Finding a Baseline

Customize your test script by assigning a user profile to it before running a baseline test.

  1. Click Find Baseline on the workflow bar. The Workflow - Find Baseline dialog box appears.
  2. Optional: Narrow down the list of Available User Types by selecting entries from the Script and Profile lists.
  3. Optional: Click Add new to create a new profile. If you select a profile from the list, you can click Edit Profile to adjust the settings of the profile. For example, you can define a certain browser and bandwidth for this profile. Click Set as active to make the selected profile the active one.
  4. Select one or more user types in the Available User Types list and click the arrow buttons to assign the user types to the workload. You can also double-click user types to move them between the Available User Types list and the User Types in Workload list.
  5. User types that are assigned to the workload are automatically selected for execution. If you want a certain user type to not be executed during the baseline run, deselect it.
  6. Click Run to perform the baseline test.
Silk Performer runs a baseline test to calculate average measures against which future test runs are measured.
Note: The Find Baseline button is only visible when the full workflow bar is enabled.
Note: By default, Silk Performer displays the simple workflow bar. To switch between the workflow bar types, right-click on the workflow bar and click Show Simple Workflow Bar, Show Full Workflow Bar, or Show Monitoring Workflow Bar.
Parent topic: Finding Baselines


Viewing Baselines

The next step in the process of conducting a Silk Performer load test is to set the baseline test (see the previous step Finding Baselines) as your baseline. The baseline will serve as a reference level for subsequent load tests and should reflect the desired performance of the application under test. Once you have set a baseline test as your baseline, you can configure response time thresholds.

Note: To work with baselines, you must enable the full workflow bar.
Note: By default, Silk Performer displays the simple workflow bar. To switch between the workflow bar types, right-click on the workflow bar and click Show Simple Workflow Bar, Show Full Workflow Bar, or Show Monitoring Workflow Bar.
  • Setting Response Time Thresholds
    Set thresholds to separate good, acceptable, and unacceptable web response times for a load test.
  • Baseline Summary
    On the Baseline Summary page, you can view the measurements of your baseline, access the baseline report with all detailed metrics, and set response time thresholds.
  • Response Time Thresholds
    Describes how the response time threshold is used with a load test.
  • Performance Levels
    Describes what performance levels are, the two approaches to use performance levels, and why they are useful.
Parent topic: Managing Your Load Testing: Start to Finish Overview
Parent topic: Managing Load Tests


Setting Response Time Thresholds

  1. Click View Baseline on the workflow bar. The Baseline Summary page appears.
  2. Click Set response time thresholds in the Next Steps area on the right side. The Automatic Threshold Generation dialog box opens.
  3. Select the timers for which you want to set thresholds.
  4. Specify the appropriate Lower bound and Upper bound multipliers for your load tests.
  5. If the corresponding timers from the baseline test are 0, specify minimum values.
  6. If you want to raise an error or a warning message in case a threshold is exceeded, you can specify the severity of the raised message.
  7. Click OK.
Note: The buttons Find Baseline and View Baseline are only visible when the full workflow bar is enabled.
Note: By default, Silk Performer displays the simple workflow bar. To switch between the workflow bar types, right-click on the workflow bar and click Show Simple Workflow Bar, Show Full Workflow Bar, or Show Monitoring Workflow Bar.
Parent topic: Viewing Baselines


Adjusting Workload

Configuring workload is part of the process of conducting a load test. Silk Performer offers different workload models to be used as a basis for your load test. Before configuring workload, you must select the model that best fits your needs.

You can define more than one workload model in your load test project and save them for further usage, but only one workload model can be active at a time. The accepted baseline results are associated with a workload model. If you copy or rename a workload model, the accepted baseline results are copied or renamed accordingly.

  • Workload Models
    Describes the types of workload models.
Parent topic: Managing Your Load Testing: Start to Finish Overview


Workload Models

Silk Performer provides the following workload models:
  • Increasing – At the beginning of a load test, Silk Performer does not simulate the total number of users defined. Instead, it simulates only a specified part of them. Step by step, the workload increases until all the users specified in the user list are running.

    This workload model is especially useful when you want to find out at which load level your system crashes or does not respond within acceptable response times or error thresholds.

  • Steady State – In this model, the same number of virtual users is employed throughout the test. Every virtual user executes the transactions defined in the load-testing script. When work is finished, the virtual user starts again with executing the transactions. No delay occurs between transactions, and the test completes when the specified simulation time is reached.

    This workload model is especially useful when you want to find out about the behavior of your tested system at a specific load level.

  • Dynamic – You can manually change the number of virtual users in the test while it runs. After the maximum number of virtual users is set, the number can be increased or decreased within this limit at any time during the test. No simulation time is specified. You must finish the test manually.

    This workload model is especially useful when you want to experiment with different load levels and to have the control over the load level during a load test.

  • All Day – This workload model allows you to define the distribution of your load in a flexible manner. You can assign different numbers of virtual users to any interval of the load test, and each user type can use a different load distribution. Therefore, you can design complex workload scenarios, such as workday workloads and weekly workloads. You can also adjust the load level during a load test for intervals that have not started executing.

    This workload model is especially useful when you want to model complex, long lasting workload scenarios in the most realistic way possible.

  • Queuing – In this model, transactions are scheduled by following a prescribed arrival rate. This rate is a random value based on an average interval that is calculated from the simulation time and the number of transactions per user specified in dcluser section of your script. The load test finishes when all of the virtual users have completed their prescribed tasks.
    Note: With this model, tests may take longer than the specified simulation time because of the randomized arrival rates. For example, if you specify a simulation time of 3,000 seconds and want to execute 100 transactions, then you observe an average transaction arrival rate of 30 seconds.

    This workload model is especially useful when you want to simulate workloads that use queuing mechanisms to handle multiple concurrent requests. Typically, application servers like servlet engines or transaction servers, which are receiving their requests from Web servers and not from end users, can be accurately tested by using the queuing model.

  • Verification – A verification test run is especially useful when combined with the extended verification functionality. This combination can then be used for regression tests of Web-based applications. A verification test performs a specified number of runs for a specific user type.

    This workload is especially useful when you want to automate the verification of Web applications and when you want to start the verification test from the command line interface.

  • Configuring Increasing Workload
    This workload model is especially useful when you want to find out at which load level your system crashes or does not respond within acceptable response times or error thresholds.
  • Configuring Steady State Workload
    This workload model is especially useful when you want to find out about the behavior of your tested system at a specific load level.
  • Configuring Dynamic Workload
    This workload model is especially useful when you want to experiment with different load levels and to have the control over the load level during a load test.
  • Configuring All Day Workload
    This workload model is especially useful when you want to model complex, long lasting workload scenarios in the most realistic way possible.
  • Configuring Queuing Workload
    This workload model is especially useful when you want to simulate workloads that use queuing mechanisms to handle multiple concurrent requests. Typically, application servers like servlet engines or transaction servers, which are receiving their requests from Web servers and not from end users, can be accurately tested by using the queuing model.
  • Configuring Verification Workload
    This workload is especially useful when you want to automate the verification of Web applications and when you want to start the verification test from the command line interface.
Parent topic: Adjusting Workload
Parent topic: Adjusting Workload


Assigning Agents

In support of large-scale load testing, Silk Performer has consolidated all agent-to-workload assignment features within a single workflow step, available via the Assign Agents workflow bar button. Here you can configure the distribution of virtual users in your load testing environment and assign VUsers to specific agents, agent clusters, or cloud agents. Wizards are available to assist you in calculating recommended capacity for specific agents.

The Assign Agents workflow bar button helps you get started with the following tasks:

  • Configuring individual agents and adding them to the workbench agent pool
  • Assigning individual agents to your project
  • Assigning clusters of agents with pre-defined capabilities to your project
  • Configuring your project to use agents that run as virtual machines in the cloud.
  • Assigning Agents to Workload
    After you define your workload and the replay capabilities of your agents, assign specific agents or agent clusters to deliver the workload.
Parent topic: Managing Your Load Testing: Start to Finish Overview
Parent topic: Assigning Agents
Related concepts
Silk Central Integration
Related tasks
Configuring Project Agents
Adding a Computer to the Agent Pool
Launching the Cloud Agent Manager


Assigning Agents to Workload

This task can only be performed after you have configured workload for your project.

  1. Click Run Test on the workflow bar. The Workflow - Workload Configuration dialog box appears.
  2. Click the Agent Assignment tab.
  3. Select the Assignment type:
    • Static assignment to project agents : Use this method to statically assign specific agent computers (rather than clusters of agents) to your project. No agent-availability check is performed with this method and agent locking is disabled. Select this method if you want to use Agents deployed in the cloud.
    • Dynamic assignment to project agents : With this method, workload is delivered using dynamic agent-assignment at execution time against the project's agents. Workload delivery is enhanced with agent-capability specifications to create optimized workload-to-agent assignments based on the capabilities of each agent. Agent locking at execution time is enabled with this method. Only responding agents that are not currently used by another controller are used with this method.
    • Dynamic assignment to Silk Central agent cluster : Silk Performer workload delivered by way of Silk Central can also use dynamic workload-to-agent assignment. Within Silk Performer you choose the name of the agent cluster (from the drop list) that should deliver your test's workload. Silk Central then provides the list of agent computers that are assigned to the cluster. Workload is then assigned to specific agents at the moment of execution based on the capabilities of the individual agents. After you connect to Silk Central, you are presented with the list of available agent clusters. In the right-most window, you can view the agents that are currently associated with the selected agent cluster.
  4. Define the agents that are to deliver the workload for your test.
    • If you selected Static assignment to project agents , you can check the Even user distribution check box to distribute all existing user types evenly across all agents, depending on each agent's general replay capabilities. To use agents that run as virtual machines in the cloud, check the Use cloud agents check box. Click Cloud Agent Manager to manage your agents in the cloud.
    • If you selected Dynamic assignment to project agents , workload is delivered automatically using dynamic agent-assignment at execution time against the project's agents.
    • If you selected Dynamic assignment to Silk Central agent cluster , you are asked to log in to Silk Central. When you are logged in, you can select the available agent cluster.
    The Agents list box displays the available agents.
  5. Check the Agent resource utilization check box to assign a maximum percentage of total virtual users that each agent can run based on the agent's replay capabilities.
  6. Check the Balance load across agents check box to apportion workload across agents.
  7. If you selected Static assignment to project agents , use the lower window of the Agent Assignment page to define workload assignments for user groups.
    Note: Available options vary depending on the selected workload model.
  8. Click User Distribution Overview to view the assignment of virtual users to the agent computers that are currently available and then click Close.
  9. Click OK to save your settings.

Workload will be assigned to agents based on the agent-assignment settings you have configured. If there are not enough agents with the required capabilities to deliver the required workload, you will be presented with an error message and details regarding the user types that did not receive an agent assignment.

  • Agent Assignment Tab
    Enables you to configure how agents are assigned to a workload profile to deliver required load, including static or dynamic assignment to specific project agents and dynamic assignment to Silk Central agent clusters.
Parent topic: Assigning Agents
Parent topic: Assigning Agents


Trying Out Agents

Before you start your load test, it can be useful to verify that the test script you created works on all agents you are planning to use for the load test.

Try Agents Settings

For Try Agents runs, the following options are automatically set to these specified values (see also "Replay Options"):

  • The Stress test option is on, when think times are disabled.
  • The Stop virtual users after simulation time (Queuing Workload) option is off.
  • The Virtual user log files (.log) option is on.
  • The Virtual user output files (.wrt) option is on.
  • The Virtual user report files (.rpt) option is on.
  • The Virtual user report on error files (.rpt) option is on.
  • The TrueLog files (.xlg) option is off.
  • The TrueLog On Error files (.xlg) option is on.
  • The Compute time series data (.tsd) option is off.
  • All logging detail options ( Results > Logging and Results > Internet Logging page) are on.
  • The Enable all measure groups (TSD measure groups) option is off.
  • The Bandwidth option is set to High Speed (unlimited).
  • The Downstream option is set to unlimited.
  • The Upstream option is set to unlimited
  • The Duplex option is off.
  • Trying Out a Test Script On Agents
    Perform a trial run of a test script with a single virtual user to verify that your script works on various agents before you start the actual load test.
  • Try Agents Summary
    On the Try Agents Summary page, you can analyze the results of the recent Try Agents run.
Parent topic: Managing Your Load Testing: Start to Finish Overview
Parent topic: Managing Load Tests


Trying Out a Test Script On Agents

You must record or manually create a test script before you can try out your script on various agents.
  1. Click the Try Agents button on the Silk Performer Workflow bar. The Workflow - Try Agents dialog box appears.
  2. Select one or more user types from the list User Types to execute. Each user type will be executed on each selected agent. For example: If you select two user types and three agents, Silk Performer will start six test runs in total.
  3. Select one or more agents from the list Agents.
    Note: You can select local agents and cloud agents, or more specifically: cloud regions. If you select a cloud region, all cloud agents from the respective region will be tested. It is not possible to test individual cloud agents. You can start cloud agents in the Cloud Agent Manager. Note that it can take some time until the cloud agents are ready to execute tests. A note beside the cloud regions tells you how many cloud agents are reachable and ready for a test execution. For example: 2/4 Agents ready means that 4 agents were started in the Cloud Agent Manager and 2 of these are ready for execution.
  4. Optional: Click Enable think times if you want to consider the think times in your script during the run. This option is disabled by default.
    Note: Usually, a Try Agent run is used to verify that a test script works correctly on various agents. For such a functional test, think times can be neglected, since they are a means to create a more realistic user behaviour and therefor a more realistic load. However, load issues can be neglected in a functional test.
  5. Click Run to try out the script on the specified agents.
  6. If you have selected cloud regions to be tested, the Review Estimated Micro Focus Credits Consumption dialog box displays. It gives you an estimation of how many Micro Focus Credits the runs will consume. Click Accept and Run.
The Monitor window opens, giving you detailed information about the progress of the Try Agents run. Once all runs are finished, the Try Agents Summary displays.
Parent topic: Trying Out Agents


Configuring Monitoring

Before running a test you need to define how Performance Explorer, the Silk Performer server monitoring tool, is to monitor local and remote servers involved in your test. Server monitoring reveals, locates, and assists in resolving server bottlenecks, allowing you to examine the performance of operating systems and application servers.

Three monitoring options are available:

  • Default monitoring - This option directs Performance Explorer to monitor a recommended set of data sources based on the application type under test. This is equivalent to enabling the Automatically start monitoring and Use default monitoring template settings for the Performance Explorer workspace (Settings > Active Profile > Replay > Monitoring > Use default monitoring template).

  • Custom monitoring - This option opens Performance Explorer in monitoring mode with the Data Source Wizard - Select Data Sources dialog box open, enabling you to manually configure data sources. Your Performance Explorer monitoring project settings will be saved along with your Silk Performer project settings.

  • No monitoring - This option enables you to run your test without monitoring of any local or remote servers. With this option the Automatically start monitoring setting is disabled (Settings > Active Profile > Replay > Monitoring > Use default monitoring template).

  • Defining Monitoring Options
    Explains how to select a monitoring option and proceed with testing.
  • Server Monitoring
    Provides an overview of the importance of monitoring a server.
  • Setting Up a Template for Server Monitoring
    Set up a template to perform live monitoring during the load test so that server-side results information can be generated for exploration and correlation after the test.
Parent topic: Managing Your Load Testing: Start to Finish Overview
Parent topic: Managing Load Tests
Parent topic: Load Testing Web 2.0 Applications (Protocol-Level)
Related concepts
Custom Data Sources
Related reference
Predefined Data Sources


Defining Monitoring Options

  1. Click Configure Monitoring on the workflow bar. The Workflow - Configure Monitoring dialog box appears.
  2. Select one of the following options and click Next:

    • Default monitoring - This option directs Performance Explorer to monitor a recommended set of data sources based on the application type under test. This is equivalent to enabling the Automatically start monitoring and Use default monitoring template settings for the Performance Explorer workspace (Settings > Active Profile > Replay > Monitoring > Use default monitoring template).

    • Custom monitoring - This option opens Performance Explorer in monitoring mode with the Data Source Wizard - Select Data Sources dialog box open, enabling you to manually configure data sources. Your Performance Explorer monitoring project settings will be saved along with your Silk Performer project settings.

    • No monitoring - This option enables you to run your test without monitoring of any local or remote servers. With this option the Automatically start monitoring setting is disabled (Settings > Active Profile > Replay > Monitoring > Use default monitoring template).

    (for Default Monitoring and Custom Monitoring only) A confirmation dialog box will notify you if you have logging enabled. Logging may skew your test results.
  3. Click OK to accept your logging settings or click Cancel to adjust your logging options (Settings > Active Profile > Results > Logging).
  4. (for Custom Monitoring only) Performance Explorer starts and the Data Source Wizard opens. Complete the steps outlined in the wizard.
  5. The Workflow - Workload Configuration dialog box appears. Click OK to accept your monitoring settings.
Parent topic: Configuring Monitoring
Related concepts
Custom Data Sources
Related reference
Predefined Data Sources


Running Tests

Real-time information regarding agent computers, virtual users, and transactions is displayed for you while load tests run. Real-time performance monitoring of the target server is presented in graphical format.

When a test is configured as a verification run, the following options are automatically set to the specified values:
  • A Baseline report file is automatically created.
  • The Stop virtual users after simulation time (Queuing Workload) option is disabled.
  • The Virtual user log files (.log) option is disabled.
  • The Virtual user report files (.rpt) option is enabled.
  • The Virtual user report on error files (.rpt) option is enabled.
  • The Compute time series data (.tsd) option is disabled.
  • Running a Load Test
    Run a test script against a target server to see how workload and multiple virtual users impact server performance.
Parent topic: Managing Your Load Testing: Start to Finish Overview


Running a Load Test

Run a load test after you set up your testing environment and configure all test settings.

  1. Click Run Test on the workflow bar. The Workflow - Workload Configuration dialog box appears.
  2. Configure the workload that you plan to use in your load test.
  3. (Optional) Click Connect on the Workload Configuration dialog box to initialize the agent connection without starting the test.
    1. Click OK on the New Results Files Subdirectory dialog box.
    2. Click Start all on the Silk Performer toolbar to manually start the test from monitor view.
  4. Click Run to start the load test.
  5. Click OK on the New Results Files Subdirectory dialog box. (Optional) To specify a name for the results subdirectory, uncheck the Automatically generate unique subdirectory check box and enter a name for the new subdirectory in the Specify subdirectory for results files text box.
Monitor test progress and server activity by viewing the Silk Performer tabular monitor view and the Performance Explorer graphical monitor view.
Parent topic: Running Tests
Parent topic: Running Load Tests
Related concepts
Adjusting Workload
Getting Started


Exploring Results

Silk Performer offers several approaches to displaying, reporting, and analyzing test results. Defined measurements take place during tests and can be displayed in a variety of graphical and tabular forms. Options include the following:
  • Performance Explorer: This is the primary tool used for viewing test results. A fully comprehensive array of graphic features displays the results in user-defined graphs with as many elements as are required. The results of different tests can be compared. There are extensive features for server monitoring. A comprehensive HTML based overview report that combines user type statistics with time series test result information is also available.
  • TrueLog On Error: Silk Performer provides full visual verification under load capabilities for various application types. It allows you to combine extensive content verification checks with full error drill-down analysis during load tests.
  • Virtual User Report files: When enabled, these files contain the simulation results for each user. Details of the measurements for each individual user are presented in tabular form.
  • Virtual User Output files: When enabled, these files contain the output of write statements used in test scripts.
  • Baseline Reports: A detailed XML/XSL-based report that provides you with a summary table, transaction response-time details, timers for all accessed HTML pages, Web forms, and errors that occurred. This information is available for all user types involved in baseline tests.
  • Silk Central Reports: Silk Performer projects can be integrated into Silk Central (Silk Central) test plans and directly executed from Silk Central. This allows for powerful test-result analysis and reporting. For detailed information on Silk Central reporting, refer to Silk Central Help.
  • Load Test Summary
    On the Load Test Summary page, you can analyze the results of the previous load test.
Parent topic: Managing Your Load Testing: Start to Finish Overview


Load Test Summary

When a load test run is complete, the Load Test Summary page appears. You can also open this page from the Results tree or by clicking Explore Results on the workflow bar. The Load Test Summary page contains:

  • a Quick Summary, which gives you an overview about the test duration, users, agents, and errors.
  • an Available User Types area, which you can use to drill down on the results for each user type. Select a user type from the list.

You can perform the following actions in the Next Steps and Analyze Result Files area on the right side:

  • Click Analyze load test to view all detailed metrics in Performance Explorer.
  • Click Analyze errors to view the errors in Performance Explorer (if any occurred). In the Error Details tab of Performance Explorer you can further drill into the errors. Double-click an error to open the TrueLog Explorer. This is only possible if you enabled TrueLog On Error on the Workflow - Workload Configuration dialog box before you started the load test.
  • Click Compare with baseline to compare the results of this test with the results of the baseline. This button is only visible if you have already set a baseline.
  • Click Set as baseline to make the test you have just run your baseline (your reference level) for the upcoming load tests.
  • Click Explore detailed report to open a detailed load test report.
  • Click Open results folder to view other result files like the virtual user report files or the virtual user output files for each virtual user.
Note: If you want to prevent the summary page to appear each time a test is complete, disable the Show Summary Page button in the toolbar of the Monitor page.
Parent topic: Exploring Results
Parent topic: Exploring Results


Upgrading to Silk Performer 21.0

Licensing: Silk Performer 21.0 requires a Silk Performer 21.0 license.

Project files: Project files can be upgraded from previous versions of Silk Performer by opening them in the current version. Downgrading from the current version to older Silk Performer versions has not been tested and is not supported.

Installation Information

Parallel installations: Silk Performer 21.0 (controller and agent) can be installed together with any older version of Silk Performer on the same machine without influencing each other.

Refer to the Silk Performer Installation Guide for installation instructions.

Evaluation: During the installation process, install one of the following versions:

  • Evaluation – Installs an evaluation version of Silk Performer, which grants you full product functionality for 45 days. The usage is limited to 10 virtual users. To upgrade to a full version at a later point in time, contact your sales representative.
  • Licensed – Installs an unrestricted version of Silk Performer, which requires a Silk Performer license.

Evaluation Version

If you have installed the evaluation version of Silk Performer 21.0, you can use the full product functionality for 30 days, limited to ten virtual users. The software stops operating when the evaluation period expires.

To ease you into the process of working with Silk Performer 21.0, it is recommended that you review Web Load Testing Tutorial. This PDF-based tutorial can be found in Silk Performer's documentation set.

Contact your sales representative to upgrade to the full version of Silk Performer 21.0.

Parent topic: Getting Started


Memory Footprints by Application Type

Web Business Transaction (HTML/HTTP)

Users | PerfRun (KB) | Per User (KB) | Per User (MB)
1 | 1,935 | 1,935 | 1.89
25 | 10,323 | 413 | 0.40
50 | 20,400 | 408 | 0.40

Web Low Level (HTTP)

Users | PerfRun (KB) | Per User (KB) | Per User (MB)
1 | 2,044 | 2,044 | 2.00
25 | 12,136 | 485 | 0.47
50 | 22,732 | 455 | 0.44

Web Browser Driven (AJAX)

The memory footprint for browser-driven Web load tests depends on several factors. Because browser-driven load tests use Internet Explorer for replay, you should be aware of the following:
  • The browser (Internet Explorer) uses memory. Depending on the version of Internet Explorer that you use, this memory footprint varies.
  • Memory usage depends on how you have configured the caching settings in Internet Explorer.
  • The application under test uses memory, which often increases as the VUser interacts with the application.

To get a basic understanding of how much memory a VUser requires when conducting a browser-driven Web load test, execute a try script run and monitor the memory usage (uncheck the Visible Client check box for exact results). Note that memory may increase while using the application under test though. It is recommended to script BrowserStart functions at certain points in your script to reset the browser state (cookies, cache and history).

Silverlight

Users | PerfRun (KB) | Per User (KB) | Per User (MB)
1 | 11,040 | 11,040 | 10.78
25 | 13,640 | 546 | 0.53
50 | 16,152 | 323 | 0.32

Flash Remoting

Users | PerfRun (KB) | Per User (KB) | Per User (MB)
1 | 1,912 | 1,912 | 1.87
25 | 12,776 | 511 | 0.50
50 | 20,896 | 418 | 0.41

WebDav (MS Outlook Web Access)

Users | PerfRun (KB) | Per User (KB) | Per User (MB)
1 | 3,588 | 3,588 | 3.50
25 | 17,724 | 709 | 0.69
50 | 33,364 | 667 | 0.65

Remedy Ars Web

Users | PerfRun (KB) | Per User (KB) | Per User (MB)
1 | 2,288 | 2,288 | 2.23
25 | 9,688 | 388 | 0.38
50 | 17,340 | 347 | 0.34

Email (SMTP/POP)

Users | PerfRun (KB) | Per User (KB) | Per User (MB)
1 | 1,904 | 1,904 | 1.86
25 | 5,268 | 211 | 0.21
50 | 8,912 | 178 | 0.17

Directory Server (LDAP)

Users | PerfRun (KB) | Per User (KB) | Per User (MB)
1 | 2,920 | 2,920 | 2.85
25 | not tested | N/A | N/A
50 | not tested | N/A | N/A

FTP

Users | PerfRun (KB) | Per User (KB) | Per User (MB)
1 | 2,420 | 2,420 | 2.36
25 | 5,352 | 214 | 0.21
50 | 8,348 | 167 | 0.16

TCP/IP based Application

Users | PerfRun (KB) | Per User (KB) | Per User (MB)
1 | 1,912 | 1,912 | 1.87
25 | 5,624 | 225 | 0.22
50 | 9,500 | 190 | 0.19

Mixed Protocols

Users | PerfRun (KB) | Per User (KB) | Per User (MB)
1 | N/A | N/A | N/A
25 | N/A | N/A | N/A
50 | N/A | N/A | N/A

TN3270

Users | PerfRun (KB) | Per User (KB) | Per User (MB)
1 | 2,224 | 2,224 | 2.17
25 | 7,424 | 297 | 0.29
50 | 13,652 | 273 | 0.27

TN5250

Users | PerfRun (KB) | Per User (KB) | Per User (MB)
1 | 1,495 | 1,495 | 1.46
25 | not tested | N/A | N/A
50 | not tested | N/A | N/A

VT100/VT200

Users | PerfRun (KB) | Per User (KB) | Per User (MB)
1 | 2,069 | 2,069 | 2.02
25 | 7,168 | 287 | 0.28
50 | 10,664 | 213 | 0.21

SAPGUI

Users | PerfRun (KB) | Per User (KB) | Per User (MB)
1 | 30,656 | 30,656 | 29.94
25 | 110,180 | 4,407 | 4.30
50 | 194,532 | 3,891 | 3.80

SAP NetWeaver (Web)

Users | PerfRun (KB) | Per User (KB) | Per User (MB)
1 | 2,072 | 2,072 | 2.02
25 | 10,084 | 403 | 0.39
50 | 17,936 | 359 | 0.35

Peoplesoft

Users | PerfRun (KB) | Per User (KB) | Per User (MB)
1 | 1,936 | 1,936 | 1.89
25 | 9,812 | 392 | 0.38
50 | 16,408 | 328 | 0.32

Oracle 11i

Users | PerfRun (KB) | Per User (KB) | Per User (MB)
1 | 22,636 | 22,636 | 22.11
25 | 34,748 | 1,390 | 1.36
50 | 51,104 | 1,022 | 1.00

Siebel 7 Web Client (incl. IE Option Pack)

Users | PerfRun (KB) | Per User (KB) | Per User (MB)
1 | 2,256 | 2,256 | 2.20
25 | 11,532 | 461 | 0.45
50 | 20,576 | 412 | 0.40

Radius

Users | PerfRun (KB) | Per User (KB) | Per User (MB)
1 | 16,104 | 16,104 | 15.73
25 | 21,284 | 851 | 0.83
50 | 26,268 | 525 | 0.51

XML/SOAP (recording Web Service client)

Users | PerfRun (KB) | Per User (KB) | Per User (MB)
1 | 2,676 | 2,676 | 2.61
25 | 8,460 | 338 | 0.33
50 | 16,436 | 329 | 0.32

.NET Framework using Visual Studio .Net Add-On

Users | PerfRun (KB) | Per User (KB) | Per User (MB)
1 | 19,964 | 19,964 | 19.50
25 | N/A | N/A | N/A
50 | N/A | N/A | N/A

Java Framework

Users | PerfRun (KB) | Per User (KB) | Per User (MB)
1 | 13,044 | 13,044 | 12.74
25 | 22,356 | 894 | 0.87
50 | 27,920 | 558 | 0.55

IIOP – Corba / EJB (RMI over IIOP)

Users | PerfRun (KB) | Per User (KB) | Per User (MB)
1 | 2,736 | 2,736 | 2.67
25 | 31,696 | 1,268 | 1.24
50 | 61,960 | 1,239 | 1.21

Jacada

Users | PerfRun (KB) | Per User (KB) | Per User (MB)
1 | 15,556 | 15,556 | 15.19
25 | 24,020 | 961 | 0.94
50 | 31,552 | 631 | 0.62

Citrix Server

Users | PerfRun (KB) | Per User (KB) | Per User (MB)
1 | 3,900 | 3,900 | 3.81
25 | 9,000 | 360 | 0.35
50 | 11,500 | 230 | 0.22

Visual Basic

Users | PerfRun (KB) | Per User (KB) | Per User (MB)
1 | 2,100 | 2,100 | 2.05
25 | 4,128 | 165 | 0.16
50 | 6,276 | 126 | 0.12

Oracle

Users | PerfRun (KB) | Per User (KB) | Per User (MB)
1 | 1,732 | 1,732 | 1.69
25 | 3,696 | 148 | 0.14
50 | 5,792 | 116 | 0.11

ODBC

Users | PerfRun (KB) | Per User (KB) | Per User (MB)
1 | 5,468 | 5,468 | 5.34
25 | 16,918 | 677 | 0.66
50 | 29,016 | 580 | 0.57

DB2 CLI

Users | PerfRun (KB) | Per User (KB) | Per User (MB)
1 | 5,168 | 5,168 | 5.05
25 | 21,952 | 878 | 0.86
50 | 37,468 | 749 | 0.73

Tuxedo (all Feat.) + Clarify

Users | PerfRun (KB) | Per User (KB) | Per User (MB)
1 | 2,400 | 2,400 | 2.34
25 | Not tested | N/A | N/A
50 | Not tested | N/A | N/A

Silk Test

Users | PerfRun (KB) | Per User (KB) | Per User (MB)
1 | 13,000 | 13,000 | 12.7
25 | N/A | N/A | N/A
50 | N/A | N/A | N/A

Siebel 6/DB2

Users | PerfRun (KB) | Per User (KB) | Per User (MB)
1 | Not tested | N/A | N/A
25 | Not tested | N/A | N/A
50 | Not tested | N/A | N/A

Siebel 6/Oracle

Users | PerfRun (KB) | Per User (KB) | Per User (MB)
1 | 9,428 | 9,428 | 9.21
25 | 66,540 | 2,662 | 2.60
50 | 125,720 | 2,514 | 2.46

Siebel 6/SQL Server

Users | PerfRun (KB) | Per User (KB) | Per User (MB)
1 | Not tested | N/A | N/A
25 | Not tested | N/A | N/A
50 | Not tested | N/A | N/A

GUI-level testing

Users | PerfRun (KB) | Per User (KB) | Per User (MB)
1 | 1,788 | 1,788 | 1.75
25 | 5,080 | 203 | 0.2
50 | Not tested | Not tested | Not tested

GUI-level tests require additional memory resources through the use of terminal services sessions and Silk Test, as follows:

  • 6,300 KB per VUser for Windows Terminal Services
  • 13,000 KB per VUser for SilkTest
  • 1,092 KB per VUser for Silk Performer's Session Manager
Parent topic: Getting Started


Sample Web 2.0 Application

Silk Performer offers a modern sample Web application that you can use to learn about Web 2.0 application testing. The InsuranceWeb sample Web application is built upon ExtJS and JSF frameworks, uses AJAX technology, and communicates via JSON and XML.

The sample application is hosted at http://demo.borland.com/InsuranceWebExtJS/.

Parent topic: Getting Started
Parent topic: Web Load Testing Overview
Parent topic: Browser-Driven Load Testing Overview
Previous topic: Support for Pop-Up Windows
Next topic: Pop-Up Window in the Sample Application
Parent topic: Sample Applications


Silk Performer Keyboard Shortcuts

Silk Performer provides a number of keyboard shortcuts to speed up your workflow.

General

Open Help | F1
Open Startpage | F11
Open Project Attributes | Ctrl + Alt + A
Close Workbench | Alt + F4

File Management

New file | Ctrl + N
Open file | Ctrl + O
Save file | Ctrl + S
Print file | Ctrl + P

Script Editing

Copy selection / line | Ctrl + C
Paste selection / line | Ctrl + V
Cut selection / line | Ctrl + X
Duplicate selection / line | Ctrl + D
Select all | Ctrl + A
Undo | Ctrl + Z
Redo | Ctrl + Y
Move line up | Alt + Up
Move line down | Alt + Down
Insert code snippet | Tab or Return
Cycle through snippet statements | Tab
Jump to codeblock (snippets) | Return
Select multiple lines | Ctrl + Alt + Left Mouse
Comment | Ctrl + Q
Uncomment | Ctrl + W
Toggle comment | Ctrl + Shift + Q
Create new line above | Ctrl + Enter
Convert to lower case | Ctrl + U
Convert to upper case | Ctrl + Shift + U

Editor Helpers

Open API Help | F1 (Cursor in function)
Show code completion | Ctrl + Space
Hide code completion | Esc
Show parameter info (tooltip) | Ctrl + I
Open String Converter | Ctrl + J

Bookmarks

Add / remove bookmark | Ctrl + F2
Jump to next bookmark | F2
Jump to previous bookmark | Shift + F2
Clear all bookmarks | Ctrl + Shift + F2

Script Navigation

Go to line number | Ctrl + G
Go to definition | F12
Go to last position | Ctrl + - (Minus)
Zooming | Ctrl + Mouse Wheel

Find & Replace

Open Find dialog | Ctrl + F
Open Replace dialog | Ctrl + R
Find next | F3
Find previous | Shift + F3

Script Execution

Compile script | F7
Run try script | F8
Run baseline | F9
Run test | F10
Stop all | Ctrl + Pause
Abort load test | Ctrl + T
Kill all | Ctrl + K

Recorder

Start application | Ctrl + W
Pause recording | Ctrl + B
Stop recording | Ctrl + S
Edit record settings | Ctrl + E
New transaction | Ctrl + N
New timer session | Ctrl + U
Start timer | Ctrl + I
Stop timer | Ctrl + P
Insert comment | Ctrl + A
Insert TrueLog Section | Ctrl + ,
Generate Script | Ctrl + G
Clear | Ctrl + D
Edit script settings | Ctrl + H
Change GUI size | Ctrl + Z
Keep on top | Ctrl + T

TrueLog Explorer

Add TrueLogs | Ctrl + O
Add TrueLog on Error files | Ctrl + U
Quick find | Ctrl + D
Find | Ctrl + F
Find next | F3
Find previous | Shift + F3
Find errors | Ctrl + E
Find next error | F5
Find previous error | Shift + F5
Step through TrueLog | Strg + S
Do a Try Script run | F8
Pause animation | Ctrl + P
Expand all TrueLogs | Ctrl + T

Browser Application

Find in Locator Spy | Ctrl + F
New tab | Ctrl + N
Display DOM hierarchy tree | F12 or Pause/Break
Replay step (in replay mode) | F11
Parent topic: Getting Started


Configuring Silk Performer

The Silk Performer configuration options provide the opportunity to set global Silk Performer settings that are not associated with a particular project.

Silk Performer Workbench: The basic characteristics of a Silk Performer load testing configuration are set here—those related to the agent computers used in tests, the directories where files used in and generated by tests are located, the layout of the text of test scripts, and how results information is generated.

Silk Performer Recorder: The basic settings used by Silk Performer's recording and script generating program, the Silk Performer Recorder, are defined here. These include the settings for capturing and recording the network traffic that will be modeled in your test scripts. Here, profiles are set up and managed for the client applications that are to be used during data capture and recording. Proxies can be added or removed, and their settings edited. Here you can set the port for the integrated Web server that is used by the Silk Performer Recorder, and enable recording to begin as soon as the client application starts.

Remote Agents: Silk Performer allows for remote agent computers to be located both in the LAN, out on the Internet, and even behind firewalls— connected through HTTP and SOCKS proxies. The communication between the remote agents and the controller can be configured to include secure, encrypted connections in a distributed secure environment.

Java Configuration: Java Framework projects and Java based APIs require a Java SDK Environment. The Java SDK version, its location, and parameters such as class path and optional Java Virtual Machine settings can be configured here.

  • System Settings
    Lists the configuration options for Silk Performer.
  • Remote Agents
    Describes where remote agents can be located and the types of communication protocols available.
  • Client Certificates
    Provides an overview of client certificates including handling client certificates with a Web browser and exporting client certificates.
  • Custom Screen Layouts
    Explains that higher screen resolutions enable you to comfortably view additional view panes, while presentations typically require you to work with lower screen resolutions and consequently fewer view panes.
  • Managing Multiple Versions of Silk Performer
    Explains how to specify the default version of Silk Performer that is open with each Silk Performer file type.
Parent topic: Silk Performer Workbench 21.0


System Settings

The basic characteristics of the Silk Performer testing configuration are set using the system settings. To access the system settings, click Settings > System.
  • Workbench Settings
    Sets the basic characteristics of the Workbench.
  • Recorder Settings
    Defines the basic settings that are used to capture and record the network traffic that is modeled in your test scripts.
  • Agents Settings
    Allows you to manage your agent pool and configure advanced agent settings.
  • Java Settings
    Explains how to configure your Java settings for Silk Performer.
Parent topic: Configuring Silk Performer
Related tasks
Configuring Silk Performer System Settings in Eclipse


Workbench Settings

To access the Workbench settings, click Settings > System > Workbench. The following tabs are available:
Tab | Description
Directories | Here you can specify where Silk Performer stores various types of files. Default directories are set up during installation; here you can specify alternative directories for projects, custom user data files, and custom include files.
Layout | Here you can customize the way the editor behaves when you manually insert text into a script file. Options can be set for formatting, printing, and how keywords are highlighted in the Silk Performer menu tree editor.
Control

Here you can set the options for the controller. Settings can be specified for the time interval within which a controller computer must communicate with an agent computer or a virtual user; if it fails, a timeout error will be reported. The frequency with which the controller will ping an agent computer until it receives a reply is set here, as can the number of virtual users per process and the number of transaction failures permitted for a virtual user before the user is terminated.

Note: Virtual user settings are only stored on a per-project basis. You must have a project open to enable this setting. After a project is loaded, the options apply only to the specific project configured with that setting.
Results

Use the Time series data option for merging time series data files (.tsd) on the agent computers where they were created and to ensure that only the merged files will be sent to the controller computer. This leads to quicker processing (because the data is processed by several computers) and less network traffic, which is especially useful for big and long-lasting load tests. The drawback, however, is that time series data files for individual virtual users are not available on the controller computer.

Note: If you disable this option, you have to merge the time series data manually in Performance Explorer to get overall results for the load test.
Workspace | In this area, you can specify general Workbench settings including start-up settings, workflow settings, file handling, and the display of dialog boxes.
Licensing | In this area, you can specify settings for your license server and for the Silk Performer online licensing model.
Silk Central | In this area, you can set up a connection to Silk Central.
Source Control | In this area, you can specify general SCC connection parameters.
  • Configuring Directory Settings
    Specify the directories where various Silk Performer file types are stored.
  • Configuring Layout Settings
    Set the tab size, auto indent, text type, font and color settings.
  • Configuring Print Layout Settings
    Configure line numbering, wrap markers, and font type, size, and style for printed script files.
  • Code Completion
    BDL code-completion reduces scripting errors and decreases the need to type text into BDL files by automatically completing functions, variables, and constants.
  • User-Defined Functions, Variables, and Constants
    To receive code completion features for user-defined functions, variables, and constants, you must create a new file with the same name, in the same directory as your .bdf or .bdh file that defines the function, variable or constant you want to enhance.
  • Configuring Control Settings
    Configure settings for virtual users, remote agent communication, and compressing data files.
  • Configuring Result Settings
    Configure Silk Performer to merge series data on agents, which enables Silk Performer to quickly process results for long load tests.
  • Configuring Workspace Settings
    Configure the files that open on startup, the workflow buttons that display in the workflow bar, document file locking, and whether or not suppressed dialog boxes should be displayed.
  • Configuring Licensing Settings
    Configure your license server settings, install a standalone license and enable online licensing.
Parent topic: System Settings


Configuring Directory Settings

  1. In the Silk Performer menu, click Settings > System .
  2. Click the Directories tab.
  3. Use the File locations area to specify the directories where various Silk Performer file types are stored. Default directories are set during installation.
  4. In the Projects field, specify the directory where the project files are to be saved.
  5. In the Custom user data files (.pem, .rnd, .csv, .txt, .idl) field, specify the directory where your self-created user data files (.csv), certificate files (.pem), random data files (.rnd), text files (.txt), and Interface Definition Language files (.idl) are located. In contrast to the specified User data files location, this location is used for your own user data files. As with Silk Performer pre-defined user data files, custom user data files in this directory can be shared across multiple projects.
  6. In the Custom include files (.bdh) field, specify the directory where your self-created include files (.bdh) are located. In contrast to the specified Include files location, this location is used for your own include files. As with Silk Performer pre-defined include files, custom include files in this directory can be shared across multiple projects.
Parent topic: Workbench Settings


Configuring Layout Settings

  1. In the Silk Performer menu, click Settings > System .
  2. Click the Layout tab. Use the Editor area to customize how the editor behaves when you manually insert text into a script file.
  3. In the Tab size field, enter the number of space characters that equal one tab character.
  4. Select the Auto indent option to automatically insert indents in your test script. Each time you create a new line in a script file, the line is automatically indented the same number of spaces as the previous line.
  5. Select the Replace tabs with spaces option to automatically insert four spaces each time a tab is used in a test script. This option makes it easier to view script files in a text editor.
  6. Select Enable CodeCompletion to have functions, variables, and constants completed for you automatically when you enter text into BDL files.
  7. Click the Font & Colors button to select a font and style for the Silk Performer script editor. You can select a different color to use for each type of content in a test script. The Editor Font and Colors Settings dialog opens.
  8. From the Text type list, select the type of text for which you want to adjust the font, size, style, and color. Choose one of the following:
    • Normal Text - Identifiers and symbols.
    • Keywords - Predefined statements.
    • Custom Keywords - Words added to the keyword list by the user.
    • Numbers - Whole numbers and floating-point values.
    • Comments - Notes in explanation included in a script.
    • Strings - Sequence of characters delimited by " characters.
  9. From the Font name, Font size, Style, and Color list boxes, select the format options you want to use for the currently selected text type.
  10. Click OK.
  11. You can add keywords to the Custom keywords list. These keywords will display in the script with the styles you have defined in the Editor Font and Colors Settings.
Parent topic: Workbench Settings


Configuring Print Layout Settings

  1. In the Silk Performer menu, click Settings > System .
  2. Click the Layout tab. Use the Printing area to specify options for how script files are formatted when they are printed.
  3. Select the Line number option to automatically number the lines in the printed script file.
  4. Select the Wrap marker option to automatically print a marker at the end of each line that wraps to the next line.
  5. Click the Font button to select a font and style for your printed test scripts. The Printer Font and Colors Settings dialog opens.
  6. From the Text type list, select the type of text for which you want to adjust the font, size, and style. Choose one of the following:
    • Normal Text - Identifiers and symbols.
    • Keywords - Predefined statements.
    • Custom Keywords - Words added to the keyword list by the user.
    • Numbers - Whole numbers and floating-point values.
    • Comments - Notes in explanation included in a script.
    • Strings - Sequence of characters delimited by " characters.
  7. From the Font name, Font size, and Style list boxes, select the format options you want to use for the currently selected text type.
  8. Click OK.
Parent topic: Workbench Settings


Code Completion

Code completion makes it easier to work with BDL. It significantly reduces scripting errors and decreases the need to type text into BDL files by automatically completing functions, variables and constants. There are four code completion options:

  • Code list: Shows a list box with all currently matching function names.
  • Code completion: Completes the current function, variable, or constant name.
  • Parameter info: Shows a tool tip with types and additional information for function parameters.
  • Quick info: Shows information about functions in a tool tip.
  • Smart indention: Positions the cursor based on the current logical context.

Code completion works with both Silk Performer-defined and user-defined BDL files.

To enable code completion, you must name and save new BDL files as either .bdf or .bdh files. Once a BDL file has been saved, code completion recognizes changes you make to it using the BDL Editor and includes all files you reference via BDL use statements.

Note: At all times, with all features of code completion, you are only able to receive information regarding functions, variables and constants that are defined in your local .bdf files, or in the included .bdh files of those files.

Code List

One of the key features of code completion is the code list mechanism, which offers a list of functions, variables, and constants. The code list includes either:

  • The entire list of available functions, variables, and constants
  • Or, a list of functions, variables, and constants that match the characters of the word currently selected in the script

The code list can be manually invoked using Ctrl+Space. The code list is invoked automatically when you type one of the following API prefixes:

Attribute | Iiop | DB_ | Dotnet | Ora | Pdce
Java | Jolt | Measure | Odbc | Web | Xml
Set | Str | Tux | Get |  |

When the code list is invoked, a list control with the following behavior displays:

  • If the cursor is not within a word or at the border of a word, the list control is scrolled to the top, and the first item receives focus, but it is not selected.
  • If the cursor is within a word or at the border of a word, the list control is scrolled to the first (selected) item that matches the word, and the item is selected.
  • By pressing the Tab, Space, or Enter key, the currently selected string is inserted into the view. If a string is not selected, the string with the focus is selected.
  • Double-clicking an item in the list inserts the name into the view.

Code Completion

If a word that should be used with the code list feature is unique, the code list will not open when you invoke it via Ctrl+Space, however the full word will be inserted.

In this context, unique means that only one word in the list control matches the partial word in question.

Parameter Info

Parameter info is displayed when you place an opening bracket after a function name in a script. Parameter info can also be invoked manually by pressing Ctrl+I when the cursor is placed between the opening and closing brackets of a function call. Parameter info is displayed as a tool tip that remains visible until (1) the Esc key is hit, (2) a closing bracket is inserted, (3) the arrow keys are used to move outside the brackets, or (4) input focus is set to another control.

Parameter info includes the following for functions:

  • Function name
  • Function parameters with names, types and modifiers (for example, in, out, and allownull)
  • The current parameter is displayed with bold letters and, if available, an additional description
  • Return value type and, if available, a description

Quick Info

Quick info is similar to parameter info except it shows information not only for functions, but also for variables and constants.

Quick info is presented in a form similar to a tool tip when you hold your cursor over a function, variable, or constant name. Quick info tool tips disappear when you move your cursor away.

For functions, available information is the same as with parameter info, with the exception that all parameters are shown with their descriptions rather than only the current parameter.

For variables and constants, only name, data type and optional descriptions are displayed.

Smart Indention

Smart indention is enabled when the Enter key is pressed within a BDL related view and a new line is to be inserted. Upon invocation, it places the cursor at a position that is calculated with respect to the current context (for example, indenting after inserting an initial keyword).

Parent topic: Workbench Settings


User-Defined Functions, Variables, and Constants

To receive code completion features for user-defined functions, variables, and constants, you must create a new file with the same name, in the same directory as your .bdf or .bdh file that defines the function, variable or constant you want to enhance, though with the extension .bdd.

A .bdd file has the following structure:

<CodeCompletionInfo>
  <Function id="FuncId">
    <Description>FuncDesc</Description>
    <ParamList>
      <Param no="1">
        <Name>ParamName</Name>
        <Description>ParamDesc</Description>
      </Param>
    </ParamList>
    <Returns>
      <Type>RetValTyp</Type>
      <Description>RetValDesc</Description>
    </Returns>
  </Function>
  <Global id="GlobalId">
    <Description>GlobalDesc</Description>
  </Global>
</CodeCompletionInfo>

This means that for each function you want to instrument with code completion information, you must insert a function node. For all others (variables and constants) you must insert a global node.

Code completion nodes
FuncID | Name of the function in your .bdf or .bdh file, for which code completion information should be provided.
FuncDesc | Textual description of the function.
ParamName | Parameter name
ParamDesc | Textual description of the parameter.
RetValTyp | Data type of the return value.
RetValDesc | Textual description of the return value.
GlobalId | Name of the global variable or constant.
GlobalDesc | Textual description of the variable or constant.
Parent topic: Workbench Settings


Configuring Control Settings

  1. In the Silk Performer menu, click Settings > System .
  2. Click the Control tab.
  3. The Virtual users area provides the following options:

    • Enable Automatic calculation to let Silk Performer calculate the number of virtual users per process.

    • Disable Automatic calculation to manually enter a value into the Virtual users per process field.

    • In the Stop virtual users after __ transaction failures field, enter the number of transaction failures after which virtual users should be stopped.

    Note: Virtual user settings are only stored on a per-project basis. You must have a project open to enable this setting. After a project is loaded, the options apply only to the specific project configured with that setting.
  4. The Remote agent communication area provides the following options:

    • Select LAN to optimize the controller-agent communication for a local area network.

      This is especially useful if all of the agent computers you are going to use for your load tests are located in the same local area network and all are using a fast connection.

    • Select WAN to optimize the controller-agent communication for a wide area network.

      This is especially useful if you are going to use many agent computers that are located somewhere on the Internet.

    • Select Custom to specify your own parameters.
      Note: Use the Custom option only if you run into problems with LAN or WAN settings.
  5. In the Connect field, enter the time, in which the controller computer should try to establish a connection to each remote agent computer. If the connection cannot be established within this time interval, Silk Performer reports an error.
    Note: It is not recommended to change this setting.
  6. In the Ping Interval field, enter the time, within which the controller computer should attempt to retrieve load test status data from the agent computers. The controller computer requests this information from the agent computers whenever the contents of the Monitor window need to be updated. If the agent computer fails while receiving data during this time interval, Silk Performer will report a warning.
    Note: It is not recommended to change this setting.
  7. In the Command field, enter the time in which the controller computer should try to send a command to a remote agent computer. If the command cannot be sent within this time interval, Silk Performer reports an error.
    Note: It is not recommended to change this setting.
  8. Enable the compressing and caching options if necessary. For more information, read Compressing Data Files and Caching Data Files.
    • Compress data files for LAN/WAN agents
    • Compress data files for cloud agents
    • Cache data files on agents
Parent topic: Workbench Settings


Configuring Result Settings

  1. In the Silk Performer menu, click Settings > System .
  2. Click the Results tab.
  3. Select the Merge time series data on agents option in the Time series data area for time series data files (.tsd) to be merged in the agent computers where they were created and to ensure that only the merged files are sent to the controller computer. This is especially useful for quickly processing the results of long load tests as the calculations will then be distributed to various processors and less traffic will be sent over the network. The drawback, however, is that time series data files for individual virtual users are not available on the controller computer.
    Note: If you do not select this option, you will have to manually merge the time series data files in Performance Explorer to get overall results for the load test.
  4. Select Write JUnit result to let Silk Performer generate a short load test summary in the standardized JUnit format.
  5. Enable Limit messages per agent and enter a value. If an agent exceeds this limit, Silk Performer reports a message with a customizable severity.
Parent topic: Workbench Settings


Configuring Workspace Settings

  1. In the Silk Performer menu, click Settings > System .
  2. Click the Workspace tab.
  3. Enable Open the last opened project file on startup to have the last project you worked on opened automatically each time you launch Silk Performer.
  4. Check Always enable all workflow buttons to enable all buttons in the workflow bar. By default, workflow buttons are enabled in sequence based on your progress through the Silk Performer workflow.
  5. Select a Workflow bar type:
    • Full: Displays the full workflow bar, including all workflow steps.
    • Simple: Displays the simple workflow bar. The simple workflow bypasses the baseline concept to make the load testing process quicker and easier.
    • Monitoring: Displays the monitoring workflow bar, including just the workflow steps necessary for monitoring purposes.
  6. Check Enable document file locking. The document file locking mechanism allows multiple users (on Silk Performer Controller machines) to work simultaneously on the same document files (.bdf script files, .bdh include files, data files) without overwriting each other's files. Locked document files from other users can be used in read-only mode, but they can not be edited. This option is enabled by default.
  7. Click Show all dialog boxes to reset any suppressed dialog boxes to their default active state. Certain dialog boxes include a Do not show this dialog again check box. Checking such a checkbox suppresses the dialog box from displaying until the Show all dialog boxes button is clicked.
Parent topic: Workbench Settings
Related tasks
Configuring Source Code Control Integration in Silk Performer
Configuring Silk Central Integration


Configuring Licensing Settings

  1. In the Silk Performer menu, click Settings > System .
  2. Click the Licensing tab.
  3. Click Change license server configuration to specify the settings for your Silk Meter licensing server.
  4. Click Install standalone license to provide the location of your license file and import it.
  5. Select one of the following Licensing options. These options allow you to use Silk Performer's online licensing model. For more information, read Online Licensing.
    • Use on-premise licensing only
    • Use online licensing only
    • Use online licensing if required
Parent topic: Workbench Settings


Recorder Settings

This topic explains the settings that are used by the Silk Performer recording and script generation program, the Silk Performer Recorder. These settings are used for capturing and recording the network traffic that is modeled in your test scripts. These settings comprise profiles that are applied to client applications during data capture and recording. Proxies can be added or removed, and their settings edited. You can set the port for the integrated Web server that is used by the Silk Performer Recorder, and enable recording to begin as soon as the client application is started. You can also configure recording rules that define how the Recorder captures network traffic.

Recording profiles

The Silk Performer Recorder uses recording profiles to determine what applications to record and how to record them. You can create new recording profiles and edit, remove, or copy existing ones. Within a recording profile you can specify the application that is to be recorded, a working directory, application arguments, additional executables to be recorded, protocol settings, and more.

Proxies

New proxies can be set up on your computer, and existing proxies can be edited or removed. A wide number of options can be specified for each proxy, including the protocol type, the listen port, details of the server to which the Silk Performer Recorder forwards intercepted traffic, and details concerning the client certificate that the Silk Performer Recorder presents to the Web server. When a SOCKS proxy is being set up, automatic protocol detection can be disabled for any port you want to specify. Whenever a client application sends SOCKS traffic to one of these specified ports, the Silk Performer Recorder records traffic at the TCP/IP level without trying to detect a familiar protocol first. A port range can be specified for which the recording of data by the Silk Performer Recorder will be suppressed.

Services

Options can be set for the Web server that is integrated into Silk Performer, and also for recording with the Silk Performer Recorder. The port that the integrated Web server listens to can be specified, and you can use this server to retrieve the root CA certificate that signed the Silk Performer Recorder server certificate. The root CA certificate may be downloaded from this Web site and installed into the Web browser to avoid security warnings by the browser.

The Silk Performer Recorder can be set to begin recording function calls automatically when an application is started from within the Silk Performer Recorder.

Recording Rules

The Silk Performer Recorder can be configured using recording rule files. Recording rule files are XML-based files that contain the rules by which the Silk Performer Recorder functions.

Recording rules allow you to configure the Recorder in a number of ways. Example use cases include session customizations, excluding JPG images from download while recording Web pages, and excluding Web pop-ups and ads that originate from a specific URL.

  • TCP/IP: By providing protocol descriptions of proprietary TCP/IP based protocols.
  • HTTP: By specifying the scenarios in which the Recorder should script parsing functions for dynamically changing values and generate replacements for those values.

Silk Performer enables you to create, edit, copy, and remove recording rules via the Recording Rules tab (System Settings > Recorder > Recording Rules).

Note: Creating recording rules based on existing templates, and editing individual rule properties as required, is the easiest method of configuring recording rules. Advanced users can manually script recording rules. Manually scripting recording rules requires extensive experience with Silk Performer and a thorough understanding of the involved protocols (TCP/IP, HTTP, and HTML). To learn about the structure and syntax of recording rules, and to see rule-file design examples, see the Rule-based Recording section.

You can create a new recording rule in TrueLog Explorer using values that you have specified in a parsing function. For example, creating a recording rule from a session-customization parsing function allows you to record an application while avoiding session customization issues entirely.

Note: All active recording rules are taken into account by the Recorder during recording. To avoid unwanted BDL scripting, ensure that only those rules that you require are active during recording. Recording rules are activated/deactivated via check boxes on the Recording Rules tab (System Settings > Recorder > Recording Rules).

Storing Recording Rules

The recording rules wizard saves recording rules in XRL format to <public user documents>\Silk Performer 21.0\RecordingRules. These rules can be shared between team members and can be added to any Silk Performer installation by copying the XRL file to any other \RecordingRules folder. Once in the folder, they are global in scope and are applied to all future projects.

You can control which recording rules are applied to subsequent recordings via Settings > System > Recorder > Recording Rules. To apply a rule, ensure the corresponding checkbox is checked. To have a rule ignored during recording uncheck the rule checkbox.

  • Adding Recording Profiles
    Create recording profile to specify the application path, working directory, and program arguments for each application, as well as the method that the Silk Performer Recorder uses for recording traffic.
  • Removing a Recording Profile
    Remove a recording profile.
  • Editing or Copying Recording Profiles
    Edit or copy existing recording profiles.
  • Recording Methods for Recording Profiles
    Describes the recording methods you can set for each of your recording profiles.
  • Specifying the Recorder Method for Capturing Web and TCP/IP-Based Traffic
    Select the method that the Recorder uses to capture Web and TCP/IP-based traffic. You can also enable any available Java APIs.
  • Configuring Proxy Settings
    Add, edit, or remove a proxy.
  • Configuring Services
    Configure the Web server and the port number it uses as well as whether the Silk Performer Recorder starts automatically or requires manual activation.
  • Adding a Recording Rule
    You can create a new recording rule based one of the provided rule templates.
  • Editing a Recording Rule
    You can edit the name, description, state, and properties of existing recording rules.
Parent topic: System Settings


Adding Recording Profiles

  1. In the Silk Performer menu, click Settings > System .
  2. Click the Recorder icon. The Recording Profiles page opens.
  3. Click Add to add a new recording profile to the list. The Recording Profile dialog opens.
  4. In the Profile name field, type a unique name for the recording profile. The profile name is required to identify the application in the Silk Performer Recorder window.
  5. In the Application path field, type the name of the application's executable and the directory in which it resides. To locate the executable, click the browse icon.
  6. In the Working directory field, type the working directory of the application. The working directory is the folder that contains the application or related files. Some applications need files located in other directories, so you might have to specify the folder in which these files reside.
  7. In the Application arguments field, type any number of application parameters. Passing parameters to an application is useful, for example, when recording the function calls performed by a command-line tool without a graphical UI.
  8. In the Executables to be recorded field, specify the executables that are to be recorded. This allows you to record processes that are different from the specified application's executable, which might be required if the application is hosted by another process that powers the communication process.
  9. Enable Record new and running instances (Secure Boot mode) to record all instances of an application that are already running at the time the Recorder is launched, as well as all instances that are started with the Recorder or later on. You can enable this option in case the conventional recording mechanism does not work as expected for your application. This option is automatically enabled on machines that have the UEFI feature secure boot enabled.
  10. In the Protocol selection area, check the check box that identifies the function library into which you want the Silk Performer Recorder to hook. Available options vary according to the selected application type, as follows:

    • Web – The Silk Performer Recorder hooks into a Web application, intercepts all function calls, and displays the results.

      When the Web option is selected, you can click Web Settings to open the Web Settings dialog box, which enables you to select the method that the Recorder uses to capture Web- and TCP/IP-based traffic.

    • TCP/IP – The Silk Performer Recorder hooks into a TCP/IP application, intercepts all function calls, and displays the results.
    • IIOP – The Silk Performer Recorder hooks into the IIOP function library of the client application, intercepts all the function calls, and displays the results.
    • Citrix XenApp – The Silk Performer Recorder hooks into a Citrix XenApp application, intercepts all function calls, and displays the results.
    • ODBC – The Silk Performer Recorder hooks into the ODBC function library of the client application, intercepts all function calls, and displays the results.
    • DB2 CLI – The Silk Performer Recorder hooks into the DB2 CLI function library of the client application, intercepts all function calls, and displays the results.

    • Oracle OCI – The Silk Performer Recorder hooks into the Oracle function library of the client application, intercept all functions calls, and displays the results.

      Click OCI Settings to open a dialog box that allows you to select the OCI client library to use for intercepting function calls. Select the appropriate library from the list box and click OK.

    • Tuxedo – The Silk Performer Recorder hooks into the TUXEDO function library of the client application, intercepts all function calls, and displays the results.
    • SAPGUI – The Silk Performer Recorder hooks into functions of SAP GUI interfaces, intercepts all the function calls, and displays the results.
  11. Click OK to add the new profile to the list.
Parent topic: Recorder Settings


Removing a Recording Profile

  1. In the Silk Performer menu, click Settings > System .
  2. Click the Recorder icon. The Recording Profiles page opens.
  3. Select the recording profile you want to remove and click Remove.
  4. Click Yes on the confirmation dialog.
  5. Click OK to save your settings.
Parent topic: Recorder Settings


Editing or Copying Recording Profiles

  1. In the Silk Performer menu, click Settings > System .
  2. Click the Recorder icon. The Recording Profiles page opens.
  3. Select a recording profile.
  4. Choose one of the following:
    • Click Edit to adjust the settings of the selected recording profile.
    • Click Copy to copy the selected recording profile.
    The Recording Profile dialog appears. See "Adding Recording Profiles" for detailed information on the available settings.
  5. Click OK to save your settings.
Parent topic: Recorder Settings


Recording Methods for Recording Profiles

You can set one of the following recording methods for each of your recording profiles. To view your recording profiles, click Settings > System > Recorder.

record new instances

When this method is set, the Recorder records all instances of an application that are started with the Recorder or afterwards. Instances that are already running at the time the Recorder is launched will not be recorded.

To set this method, select a recording profile, click Edit, and make sure that Record new and running instances (Secure Boot mode) is disabled. This option is automatically enabled on machines that have the UEFI feature secure boot enabled.

record new and running instances

When this method is set, the Recorder records all instances of an application that are already running at the time the Recorder is launched, as well as all instances that are started with the Recorder or afterwards.

To set this method, select a recording profile, click Edit, and enable Record new and running instances (Secure Boot mode).

record through system proxy
When this method is set, the Recorder records through the Windows system proxy.
Note: In this case, the Recorder captures the traffic of all applications that use the system proxy. You can exclude unwanted traffic from your script by using the filters and script generation settings on the Capture File page.

To set this method, select a recording profile, click Edit, click Web Settings, select Proxy, and select Automatic browser configuration.

record through application proxy

Some applications (including Firefox) allow you to use an application-specific proxy and therefore ignore the system proxy settings.

When this method is set, the Recorder records through the custom proxy of the respective application.

To set this method, select a recording profile, click Edit, click Web Settings, select Proxy, and select Manual browser configuration. In the application you want to record, set the proxy to localhost and the HTTP proxy port configured in the Recorder (the default is 8080).

The Recording Profiles page lists all recording profiles you have specified manually alongside a number of default recording profiles. When a recording profile is checked in this list, it is marked as active. All active recording profiles can be selected from the Recording Profiles list on the Model Script dialog.

You can select which of your recording profiles the Recorder uses for recording:
  • Profiles started from the Model Script dialog or recorder: When this option is selected, only the recording profile that is selected on the Model Script dialog is used, once you start the recording. However, when you select a recording profile directly within the Recorder and click the Start Application icon, this recording profile is used as well, since it is initiated explicitly.
  • All active profiles: When this option is selected, the Recorder uses all recording profiles that are active (checked), once you start the recording.
    Note: When you have selected this option and start your recording from the Model Script dialog, you still have to select a single Recording profile. However, the Recorder will use all active recording profiles during recording.
Tip: The Recorder shows you which recording profiles are in use by displaying the icons of the recorded applications on the bottom right.
Parent topic: Recorder Settings


Specifying the Recorder Method for Capturing Web and TCP/IP-Based Traffic

Before you can perform this task, you must add a recording profile.

  1. In the Silk Performer menu, click Settings > System .
  2. Click the Recorder icon. The Recording Profiles page opens.
  3. Select a recording profile.
  4. Click the Edit button. The Recording Profile dialog appears.
  5. In the Protocol selection area, select the Web option to have the Silk Performer Recorder hook into a Web application, intercept all function calls, and display results. The options available here vary based on the selected application type.
  6. Click the Web Settings button to open the Web Settings dialog, which enables you to select the method that the Recorder is to use to capture Web and TCP/IP-based traffic.
    • Select the WinSock option to have the Silk Performer Recorder hook into the WinSock function library of the client application, wrap all traffic the application produces in the SOCKS protocol, and redirect the traffic to a Recorder SOCKS proxy.
    • Select the Proxy option to have the Silk Performer Recorder redirect all traffic from the selected browser to the Recorder proxies.
  7. Click OK.
  8. You can also enable any available Java APIs by checking the corresponding check boxes in the field on the right of the dialog. The following Java APIs are available for selection:
    • Oracle Forms 6i on HTTP/HTTPS
    • Oracle Forms 6i on Socket
    • Oracle Forms 9i
    • Product Manager Sample Extensions
    • Borland Enterprise Server App. Client
    • Jacada
    • Java EJB (JBoss)
    • Java EJB (Other)
    • Java EJB (WebLogic)
    • Java EJB (WebSphere)
    • Java JNDI (Naming & Directory Interf.)
    • Java RMI (Custom Client-Server)
    • Jolt
    • Oracle Applications 11i
    • Oracle Applications 12i on Socket
    • Oracle Forms 10g
    • Oracle Forms 11g
    • Oracle Forms 12c
  9. When a Java API is enabled, click the Java Settings button to open a dialog that enables you to specify Java recording settings, such as the hooked Java Virtual Machine library or other settings.
    • Select the Java Virtual machine hooking option to automatically hook into the Java VM. If this option is enabled, select the dynamic link library from the JVM DLL list box that you want the Silk Performer Recorder to hook into for recording traffic.
    • Select the Network only option to only hook class and jar files that are downloaded via HTTP.
    • Select the Manual option if you have manually prepared a startup script for recording your Java application.
  10. Close all open dialogs by clicking the OK button to save your settings.
Parent topic: Recorder Settings


Configuring Proxy Settings

  1. In the Silk Performer menu, click Settings > System .
  2. Click the Recorder icon. The Recording Profiles page opens.
  3. Click the Proxies tab.
  4. Select one of the following options:
    • Click Add to set up a new proxy on the controller computer. You can set up proxies for recording a number of types of traffic, and you can have a number of proxies active at the same time.
    • Click Edit to edit a selected proxy.
    • Click Remove to remove a selected proxy.
    The Proxy Settings dialog appears.
  5. From the Protocol list box, select a protocol type for forwarding and recording traffic. You have to set up a proxy for each type of traffic you want to record. Forwarding and recording traffic with the following protocols is supported:
    • FTP - File Transfer Protocol
    • HTTP - Hypertext Transfer Protocol
    • LDAP - Lightweight Directory Access Protocol
    • POP3 - Post Office Protocol
    • SMTP - Simple Mail Transport Protocol
    • SOCKS - When capturing SOCKS traffic, the Silk Performer Recorder automatically detects other protocols like IIOP, FTP, POP3 and SMTP for recording.
    • TCP/IP Custom protocol based on TCP/IP.
  6. In the Listen port field, enter the port number to which traffic will be sent by the traffic-generating client computer. Although any port not in use can be chosen, avoid standard port numbers (usually smaller than 1500).
  7. In the Remote host area, choose the Type of host to which you want the Silk Performer Recorder to forward intercepted traffic. Choose one of the following:
    • Select the Any option to forward intercepted traffic to the host specified by the traffic-generating client computer.
    • Select the Proxy/Firewall option to forward intercepted traffic to a specified proxy or firewall.

      In this case, the host name and IP address specified by the traffic-generating client computer are ignored.

    • Select the Specified option to forward intercepted traffic to a specified remote host.

      In this case, the host name and IP address specified by the traffic-generating client computer are ignored.

  8. If you selected the Specified option for a remote host, check the Secure check box to record and forward Secure Socket Layer protocol traffic. If this option is selected, HTTPS traffic will be recorded instead of HTTP traffic, for example.
  9. In the Host name or IP address field, enter the host name or IP address of a specific server to which you want the Silk Performer Recorder to forward intercepted traffic.
  10. In the Port field, enter the port number that a specific server—the one to which the Silk Performer Recorder forwards intercepted traffic—listens to.
  11. From the Certificate list box, select a client certificate that the Silk Performer Recorder is to present to the Web server on behalf of the real client’s certificate.
  12. When setting up a SOCKS proxy, use the Record always at TCP/IP protocol level area to specify any number of ports for which to disable automatic protocol detection. You can enter multiple port numbers and ranges, separated by commas (,); a range specification consists of the lower and upper boundary, separated by a hyphen (-). Whenever a client application sends SOCKS traffic to one of the specified ports, the Silk Performer Recorder records traffic at the TCP/IP level without attempting to detect a familiar protocol first.
  13. In the Suppress recording (only forward data) area, specify a port range for which you want to suppress the recording of data by the Silk Performer Recorder. You can enter multiple port numbers and ranges, separated by commas (,); a range specification consists of the lower and upper boundary, separated by a hyphen (-). The data will still be forwarded, but no longer recorded.
  14. Click OK.
  15. To activate a proxy, check the check box to the left of the proxy name, in the Record column.
  16. Click OK to save your settings.
Parent topic: Recorder Settings


Configuring Services

  1. In the Silk Performer menu, click Settings > System .
  2. Click the Recorder icon. The Recording Profiles page opens.
  3. Click the Services tab.
  4. Use the Integrated Web server area to change the port number of the Web server that is integrated into the Silk Performer Recorder. The default address of the server is http://localhost:19100 (where 19100 is the default port number). You must have the Silk Performer Recorder running to use this Web server.
  5. In the Port field, enter the port that the integrated Web server listens to. The default is 19100. Using the integrated Web server, you can retrieve the root CA certificate that signed the Silk Performer Recorder server certificate. The root CA certificate may be downloaded from this Web server and installed into the Web browser to avoid security warnings by the browser.
  6. Select the Autostart recording option in the Recording area to start recording traffic and function calls automatically when the Silk Performer Recorder is started. If this option is disabled, you must use the Start Recording button on the Silk Performer Recorder toolbar to begin recording.
  7. Click OK to save your settings.
Parent topic: Recorder Settings


Adding a Recording Rule

By default, there are no predefined recording rules. You must script new recording rules manually or create them via the UI, as explained below.

  1. Navigate to System Settings > Recorder > Recording Rules.
  2. Click Add. The Recording Rule Properties dialog opens.
  3. From the Template list box, select a rule template. The Description text box explains what the selected template does.
  4. Edit the default Rule Name and Description as required.
  5. Check the Active check box to activate the rule.
  6. Edit the property values as required.
  7. Click OK. The new rule appears on the Recording Rules page.
Parent topic: Recorder Settings
Related tasks
Editing a Recording Rule


Editing a Recording Rule

  1. Navigate to System Settings > Recorder > Recording Rules.
  2. Select an existing rule in the Rule Name text box.
  3. Click Edit. The Recording Rule Properties dialog opens.
  4. Edit the Rule Name and Description as required.
  5. Check/uncheck the Active check box to activate/deactivate the rule.
  6. Edit the property values as required. Select a property row to view a description of the property in the description text box at the bottom of the dialog.
    Note: Grayed-out properties are read-only.
  7. Click OK to save your changes.
Parent topic: Recorder Settings
Related tasks
Adding a Recording Rule


Agents Settings

To access the Agents settings, click Settings > System > Agents. The following tabs are available:

  • Agent Pool: Here you can manage your pool of agents. You can add and remove LAN and WAN agents, set a number of agent properties, and export the agent pool.
  • Advanced: Here you can instruct Silk Performer to use a particular user account for your agents and to create multiple sessions on an agent computer.
  • Agent Pool
  • Advanced Agent Settings
    Explains a number of advanced settings for agents.
Parent topic: System Settings


Agent Pool

  • Configuring Agent Pool Settings
    Configure Silk Performer agent pool settings to set options for agent computers, including configuring multiple IP addresses.
  • Adding a Computer to the Agent Pool
    Add a computer to the default pool of agents associated with the controller computer.
  • Agent Connection Properties
    Add agents to the agent pool, remove them, and modify the connection settings of an agent.
  • Removing a Computer from the Agent Pool
    Remove a computer from the default pool of agents associated with the controller computer.
  • Updating WebDriver on an Agent
    Describes how to update WebDriver on an agent.
Parent topic: Agents Settings


Configuring Agent Pool Settings

  1. In the Silk Performer menu, click Settings > System .
  2. Click the Agents button.
  3. Click Check Availability to send a remote call to the selected agent and verify that it is available and active.
  4. Select an agent computer and click Manage to set the agent's configuration options, including the configuration of multiple IP addresses. The System Configuration Manager opens.
  5. Click OK to save your settings. Repeat the previous step for each agent computer that you want to configure.
  6. Back on the System Settings dialog box, click OK to save your agent pool settings.
Parent topic: Agent Pool
Related tasks
Configuring Project Agents


Adding a Computer to the Agent Pool

  1. In the Silk Performer menu, click Settings > System .
  2. Click the Agents button.
    Tip: Alternatively, click Assign Agents on the Silk Performer workflow bar. Then click the Configure Agent Pool link on the Setup Agents dialog box.
  3. On a LAN network:
    1. Click the Add LAN Agent button. The Add LAN Agent dialog appears, listing all compatible agent computers that are available on the subnet.
    2. From the Running agents list of computers in your local network, select the computer(s) you want to add to your agent pool.
    3. Click the Add button.
  4. On a WAN network:
    1. Click the Add WAN Agent button. The Add WAN Agent dialog appears.
    2. Enter connection parameters for the WAN agent.
    3. In the Host name or IP address field, enter the computer’s host name or IP address.
      Tip: If you want to add a computer from Windows domains outside your local network, click [...].
      The Browse for Computer dialog appears.
    4. Select the computer you want to add to the agent pool and click OK.
    5. Click OK again on the Add WAN Agent dialog.
Parent topic: Agent Pool


Agent Connection Properties

Before a Silk Performer agent can be assigned manually to a load test, it has to be added to the agent pool. To open the agent pool, click Settings > System in the Silk Performer menu and click the Agents icon.

You can add agents to the agent pool and remove them. To modify the connection settings, select an agent and click Properties.
  • Enable Encryption (SSL) to force the controller to secure the connection to the remote agent.
  • Enable Authenticate and specify a Password to connect to the remote agent using a password. The password must be identical to the password you specified in the System Configuration Manager.
  • When Encryption (SSL) is enabled, specify the port the controller uses to connect to the agent in the Connect to secure port field. The port must be identical to the agent connection secure port you specified in the System Configuration Manager.
  • When Encryption (SSL) is disabled, specify the port the controller uses to connect to the agent in the Connect to port field. The port must be identical to the agent connection secure port you specified in the System Configuration Manager.
  • Enable Use HTTP proxy server to connect to the agent using an HTTP firewall. Specify the Address and Port to which you want to tunnel. These can be obtained from your system administrator. See Connecting Through HTTP Firewalls.
  • Enable Use SOCKS proxy server to connect to the agent using the SOCKS protocol. Specify the Address and Port. See Connecting Through SOCKS Firewalls. If you use both the HTTP firewall and the SOCKS protocol, the agent will first connect to the SOCKS proxy and then connect to the HTTP proxy. See Connecting Through Multiple Firewalls.
  • Click Check Connection to verify that the controller is able to connect to the agent. If you specified a connection through a proxy server, you will be asked for user credentials if the proxy server requires authentication.
  • Click OK to save your settings.
Parent topic: Agent Pool


Removing a Computer from the Agent Pool

  1. In the Silk Performer menu, click Settings > System .
  2. Click the Agents button.
  3. On the Agent Pool tab, select the agents that you want to remove from the Agent Pool list and click the Remove button.
  4. Click OK on the ensuing dialog box to confirm that you want to remove the agent.
Parent topic: Agent Pool


Updating WebDriver on an Agent

  1. In the Silk Performer menu, click Settings > System.
  2. Click the Agents icon.
  3. On the Agent Pool tab, right-click an agent and click Update Webdriver.
    Tip: You can also select multiple agents using the Ctrl and Shift keys to update WebDriver on multiple agents at once.
The update process starts. If any issue should occur, a dialog with a Show Log button displays. Click the button to open the error log in the default text editor.
Parent topic: Agent Pool


Advanced Agent Settings

By default, remote agents run under the local SYSTEM account. This is because the Silk Launcher Service, which runs under the SYSTEM account, passes on its privileges to the Silk Performer agent and virtual user processes. This concept works fine for protocol web and related technologies. However, for browser-driven web and other technologies that need access to a user registry hive, there are methods to run virtual users under a particular user account.

  • Using a Particular User Account for a Single Agent
    With this option you can configure a specific agent to run its virtual users under a specific user account.
  • Using a Particular User Account for All Agents
    Configuring all agents to run virtual users under a particular user account.
  • Distributing Virtual Users Over Multiple Windows Sessions
    Instruct your agents to create multiple sessions during an execution.
Parent topic: Agents Settings


Using a Particular User Account for a Single Agent

With this option you can configure a specific agent to run its virtual users under a specific user account. If you want to run all your virtual users on all agents under a particular user account, use a different option (see Using a Particular User Account for All Agents).

  1. From the Silk Performer menu bar, select Tools > System Configuration Manager. The System Configuration Manager dialog displays.
  2. Click the Applications tab.
  3. Select Silk Performer in the group box on the left side of the dialog box.
  4. Click Change next to the Account text box and type the account name of a user on the agent workstation who has permission to execute remote tests.
  5. Click Change next to the Password text box and type the corresponding password.
  6. Click OK.
Parent topic: Advanced Agent Settings
Related concepts
Browser-Driven Virtual Users on Remote Agents


Using a Particular User Account for All Agents

You can specify particular user account credentials in a central location to be used for all agents, except for cloud agents which always use a dedicated user. This feature allows agents to be launched under a specific user account rather than the default SYSTEM account. For technologies such as browser-driven web, it is useful and recommended to run the virtual users in the context of a user account instead of the Windows built-in SYSTEM account. When you enable this setting, make sure that the specified user account is available on all the agent machines that are used for the load test.

By default agents are assigned to the SYSTEM account, but you also have the option to specify a dedicated user account to an agent through the System Configuration Manager (see Using a Particular User Account for a single Agent). Using this method to assign a specific user account can be cumbersome if you have a large amount of agents, because you have to specify user account credentials separately for each agent.

Note: Ensure that the specified user account is a member of the Remote Desktop Users Windows group on the remote agent.
  1. In the Silk Performer menu, click Settings > System .
  2. Click the Agents icon and the Advanced tab.
  3. Enable Use particular user account.
  4. In the fields Username and Password, specify the credentials for a user with permission to launch the agents to test.
  5. Click OK to save your settings.
Note: Any settings that are defined in the System Configuration Manager for agents will be overridden by this setting on the Advanced tab.
Note: If a Remote Desktop Server is installed on the agent, it is recommended to use the default SYSTEM account. If you used a particular user account instead and the session was unexpectedly disconnected, the agent's session including the agent would be ended. This is true if "End a disconnected session" is activated in the Remote Desktop Server configuration.
Parent topic: Advanced Agent Settings


Distributing Virtual Users Over Multiple Windows Sessions

Windows operating systems do not dedicate all available resources to a single Windows session. For load testing with UI-based technologies such as browser-driven web or SAPGUI, Silk Performer allows you to distribute virtual users over several Windows sessions. This allows you to make better use from resources of powerful hardware. Virtual users that execute Java or .NetFramework code that is not designed to run in multiple instances can be spread over several Windows sessions.

Unlike with GUI-level testing, where each virtual user creates its own Windows session, this setting allows you to run more than one virtual user within a session. How many sessions an agent machine can handle depends on its hardware resources, in particular on the CPU and memory. This setting is available for the following technologies: browser-driven web, Citrix, SAPGUI, Java Framework.

  1. In the Silk Performer menu, click Settings > System .
  2. Click the Agents icon and the Advanced tab.
  3. Enable Create multiple sessions.
  4. Specify the Maximum sessions Silk Performer is allowed to create.
  5. In the fields Username and Password, specify the credentials for the Windows sessions that are to be created.
  6. Click OK to save your settings.
When you start a load test, Silk Performer creates multiple Windows sessions, logs in to the sessions using the credentials, and starts virtual users within the sessions.
Note: When you enable this setting, make sure that your agent machines are set up identically. Also, the agent machines must be equipped with the Remote Desktop Services (RDS) with appropriately set up licensing options. The Windows sessions are opened locally from within the Remote Desktop Services host. Thus, per device licenses are better suited, although per user licenses work as well.
Tip: The number of virtual users you can run on an agent machine can be read from the agent's capabilities. These default capabilities are calculated based on the CPU and memory. However, a realistic number for your specific environment and conditions can only be determined if the user types (the script and settings) are taken into account. The Evaluate Agent VUser Capacity dialog helps you to determine a good maximum number of virtual users for a particular agent and user type. For more information, read Evaluating Agent VUser Capacity.
Parent topic: Advanced Agent Settings


Java Settings

You can configure your Java settings either through the system settings or the profile settings. System settings serve as default settings for new projects and new profiles within existing projects. During a running test, virtual users use the Java settings of the profiles they are assigned to.

Use the general Java settings to specify the JDK version, its location on your hard drive, and the class path. When a class path contains well-known locations such as a project directory or data directory, these path parts are automatically replaced with placeholders. Placeholders are useful when migrating projects or running virtual users on agent machines where the directories have different names than on the controller machine.

Note: When data files have typical Java archive file extensions, such as .jar and .zip, Silk Performer offers to add the files to the class path of the currently active profile.
  1. Configuring Java Version and Classpath Settings
    Configure general Java options, including classpath settings.
  2. Configuring Advanced Java System Settings
    Configure Java virtual machine settings including the command line options, JIT compiler option, and other advanced settings .
  3. Remote Agent Java Settings
    Explains how to configure remote-agent Java settings independent of workbench Java settings.
Parent topic: System Settings
Related concepts
Java Settings
Java Framework Support
Related reference
Oracle Forms Functions Reference


Configuring Java Version and Classpath Settings

  1. In the Silk Performer menu, click Settings > System .
  2. Click the Java icon. The General page opens.
  3. Specify the directory of the Java home path in the Java 32-bit home or Java 64-bit home field, depending on what Java architecture you use. You can switch between 32-bit and 64-bit on the Advanced tab. This option enables the Java Virtual Machine to be loaded from a different path than is specified in the PATH environment so that you can switch between various Java Virtual Machines without changing the system PATH environment.
    Note: Silk Performer automatically checks the path you specify here. If the path is not correct, the default Java home path of the operating system is used instead.
    The Classpath specified for the Java Virtual Machine displays. By default the classpath is set to the system classpath.
  4. Click Check JVM to verify your Java Virtual Machine configuration settings. To ensure that the Java environment is set up properly, the configuration should be tested.
  5. Click New File to navigate to a class file and add it to the classpath of the Java Virtual Machine.
    Note: Press Ctrl or Shift to select multiple class files and add them to the classpath.
  6. Click New Directory to navigate to a directory and add it to the classpath of the Java Virtual Machine.
  7. To move selected files up or down in the classpath hierarchy, click Move Item Up or Move Item Down.
  8. To delete a selected file from the classpath, click Delete.
  9. Click OK to save your settings.
Parent topic: Java Settings
Next topic: Configuring Advanced Java System Settings
Parent topic: Java Settings


Configuring Advanced Java System Settings

  1. In the Silk Performer menu, click Settings > System .
  2. Click the Java icon. The General page opens.
  3. Click the Advanced tab.
  4. In the Command line options field, enter any command line options that are to be passed to the Java Virtual Machine. Some Java classes require specific Virtual Machine options to run successfully. Tuning parameters may also be specified in VM parameters.
  5. Select the Disable JIT compiler check box if you want to disable the Just In Time (JIT) compiler of the Java Virtual Machine. The JIT compiler can be disabled when required and non-standard VM DLLs can be specified.
  6. Check the Use system classpath check box to ensure that the system classpath is used.
  7. Select 32-bit Java (default) or 64-bit Java.
  8. If you use 64-bit Java, specify an Execution timeout for the communication between the Silk Performer runtime and the JVM.
  9. Click OK to save your settings.
The specified Java architecture determines whether your Java test code is running in-process or out of process. This results in the following behavior:
  • 32-bit Java is enabled: When you execute a test, the jvm.dll and the required .jar files are loaded dynamically into the perfrun.exe. Note that this increases the memory usage of the perfrun.exe. Also be aware that during the early phase of a load test, the memory usage might be volatile. This can be misunderstood as a memory leak, but is in fact expected due to the Java garbage collector at work. By default, up to 50 virtual users share the same JVM, which helps reduce memory usage. However, this feature requires that your Java test code is thread-save (especially the static variables).
  • 64-bit Java is enabled: When you execute a test, the Java test code is running in a separate process - it is not loaded into the perfrun.exe.

You can also use the BDL function JavaSetOption to switch between 32-bit and 64-bit Java. Note that the settings defined in the BDL script override the options defined in the profile settings.

Parent topic: Java Settings
Previous topic: Configuring Java Version and Classpath Settings
Next topic: Remote Agent Java Settings


Remote Agent Java Settings

You can configure different Java settings for the controller (the Silk Performer Workbench) and for your remote agents. This means that you do not need to maintain identical Java environments (Java versions, settings, directories) for your controller and agent machines. For agents, a JRE is sufficient, but on the controller, usually a JDK is required.

If a class or .jar file is not found on the agent machine within the specified path, the local data directory will be searched in addition.

There is a corresponding profile settings tab at Settings > Active Profile > Java that pulls its initial values from the remote agent settings at Settings > System > Java. It is the values on the active profile tab that are actually applied to remote agents at test time.

Parent topic: Java Settings
Previous topic: Configuring Advanced Java System Settings


Remote Agents

Silk Performer allows for remote agent computers to be located both in your LAN or somewhere out on the Internet. The communication between the remote agents and the controller can be configured in a distributed secure environment to include secure and encrypted connections.

Communication between remote agents and the controller may be made in a variety of ways with a choice of proxies, including connections made through multiple firewalls and through TCP/IP, HTTP, or SOCKS firewalls. These connections include access through choices for secure or non-secure connections, with or without encryption.

  • Remote Agent Connection Scenarios
    Includes diagrams that illustrate various remote-agent connection types.
  • Specifying Port Settings for Remote Agents
    Explains how to set the unsecured and secured port numbers for the remote agent.
  • Specifying a Password for Remote Agents
    The controller must provide a password to connect to a remote agent.
  • Configuring Remote Agent Java Settings
    Enables you to configure remote agent Java settings independent of workbench Java settings.
Parent topic: Configuring Silk Performer


Remote Agent Connection Scenarios

Includes diagrams that illustrate various remote-agent connection types.

  • Direct Connection to Remote Agent (default settings)
    Details the port settings required for direct connections.
  • Connecting Through TCP/IP Firewalls
    Details how to set up a connection to a remote agent through a TCP/IP firewall.
  • Connecting Through HTTP Firewalls
    Details the port settings required for connections to remote agents through HTTP firewalls.
  • Connecting Through SOCKS Firewalls
    Details the settings required to connect to remote agents through a SOCKS firewall.
  • Connecting Through Multiple Firewalls
    Details the SOCKS and HTTP proxy server settings required when connecting to remote agents through multiple firewalls.
  • Connecting in the Cloud
    Details the settings required to connect to remote agents in the Cloud.
Parent topic: Remote Agents


Direct Connection to Remote Agent (default settings)

The following diagram illustrates a direct connection between the controller and the remote agent (no firewalls).

In this environment, the following ports are used to connect to the remote agent:

  • UDP 19200: Used for the broadcast (hard-coded, does not change)
  • TCP 19200: Initial unsecured connection to launcher service. Accessible through the System Configuration Manager on the agent, accessible through System > Settings > Agent Pool > Properties in the Workbench.
  • TCP 19202: The Silk Performer agent port. This port is the next free port after the maximum port number of the agent connection port (default 19200) and the secure agent connection port (default 19201).
  • TCP 19203: Real-time measure communication port of the Silk Performer agent. This port is only used if real-time measures are enabled. It is the next free port after the agent connection port.

Agent Connection Establishment Without Firewalls

  1. Controller opens initial direct connection to Silk Launcher Service.
  2. Service launches the Silk Performer agent process (perfLtcAgent.exe).
  3. Service returns agent's listener port (19202) to the controller.
  4. Controller connects directly to the agent on port 19202.
  5. Optional: For collecting real-time measure data, the controller connects directly to the agent on port 19203.
Parent topic: Remote Agent Connection Scenarios


Connecting Through TCP/IP Firewalls

  1. From the Silk Performer menu bar, select Tools > System Configuration Manager . The System Configuration Manager dialog box appears.
  2. Click the Service Status tab.
  3. In the Port and Secure port fields, enter the numbers of the unsecured port and the secured port. By default these settings are 19200 for the unsecured port and 19201 for the secured port, respectively. These port connections must be changed if your firewall blocks them. Ports that you might want to open on your firewall include:
    • 19200: Default connection port to Silk Performer Silk Launcher Service.
    • 19201: Secure connection to Silk Launcher Service (you only have to open this port if you want a secure connection).
    • 19202, 19203, and 19204: These ports are used for communication with Silk Performer Agent, real-time measure service and System Configuration Manager Agent. The port assignment follows a first-come, first-served pattern.
  4. Click OK to save your settings.
Parent topic: Remote Agent Connection Scenarios


Connecting Through HTTP Firewalls

Select the Use HTTP Proxy Server setting on the agent Properties dialog.

Agent Connection Establishment Through an HTTP Proxy

  1. Controller opens initial connection to Silk Launcher Service through an HTTP proxy.
  2. Service launches the Silk Performer agent process (perfLtcAgent.exe).
  3. Service returns agent's listener port (19202) to the controller.
  4. Controller connects to the agent on port 19202 through the proxy.
  5. Optional: For collecting real-time measure data, the controller connects to the agent on port 19203 through the proxy.
Parent topic: Remote Agent Connection Scenarios


Connecting Through SOCKS Firewalls

Select the Use SOCKS Proxy Server setting on the agent Properties dialog.

Agent Connection Establishment Through a SOCKS Proxy

  1. Controller opens initial connection to Silk Launcher Service through a SOCKS proxy.
  2. Service launches the Silk Performer agent process (perfLtcAgent.exe).
  3. Service returns agent's listener port (19202) to the controller.
  4. Controller connects to the agent on port 19202 through the proxy.
  5. Optional: For collecting real-time measure data, the controller connects tot the agent on port 19203 through the proxy.
Parent topic: Remote Agent Connection Scenarios


Connecting Through Multiple Firewalls

You can configure a Silk Performer agent connection so that it uses a SOCKS proxy and an HTTP proxy in a series. In such instances, an agent first connects to a SOCKS proxy, which in turn connects to an HTTP proxy.

Select both the Use HTTP Proxy Server and Use SOCKS Proxy Server settings on the agent Properties dialog.

Agent Connection Establishment Through Multiple Proxies

  1. Controller opens initial connection to Silk Launcher Service through a SOCKS proxy then an HTTP proxy.
  2. Service launches the Silk Performer agent process (perfLtcAgent.exe).
  3. Service returns agent's listener port (19202) to the controller.
  4. Controller connects to the agent on port 19202 through both proxies.
  5. Optional: For collecting real-time measure data, the controller connects to the agent on port 19203 through both proxies.
Parent topic: Remote Agent Connection Scenarios


Connecting in the Cloud

Before you begin, contact your sales representative for your Enterprise Cloud Services user name and password.

  1. Choose Tools > Cloud Agent Manager.
  2. Type your Enterprise Cloud Services User name and Password.
  3. Click Connection Settings if your company requires the use of a proxy.
    1. Select Enable Proxy.
    2. Enter the required information in Address and Port.
    3. Click OK.
  4. Click Login. If your company proxy requires authentication, you may be prompted with another dialog box to log in.

Agent Connection Establishment in the Cloud

  1. Controller opens initial connection to Silk Launcher Service through an HTTP Proxy and port 443. Silk Performer automatically uses the default port number of 443 for a secure connection. Connection goes through an additional HTTP proxy if company policy requires it.
  2. Service launches the Silk Performer agent process (perfLtcAgent.exe).
  3. Service returns agent's listener port (19202) to the controller.
  4. Controller connects to the agent on port 19202 through the proxy, port 443, and another proxy if required.
  5. Optional: For collecting real-time measure data, the controller connects to the agent on port 19203 through the proxy, port 443, and another proxy if required.
Parent topic: Remote Agent Connection Scenarios


Specifying Port Settings for Remote Agents

  1. From the Silk Performer menu bar, select Tools > System Configuration Manager . The System Configuration Manager dialog box appears.
  2. Click the Service Status tab.
  3. Enter port numbers for the unsecured port and the secured port. Port is the TCP/IP listener port for unsecured controller/agent connections (this is the default port used by the controller to connect to agents). Secure port is the TCP/IP listener port for secure controller/agent connections (a controller can also connect through a secure SSL connection. The controller connects to the secure port if you enable Encryption (SSL) in the Agent Connection Properties). By default these settings are 19200 for the unsecured port and 19201 for the secured port.
  4. Click OK to save your settings.
Parent topic: Remote Agents


Specifying a Password for Remote Agents

  1. From the Silk Performer menu bar, select Tools > System Configuration Manager . The System Configuration Manager dialog box appears.
  2. Click the Service Status tab.
  3. In the Password area, click the Change button.
  4. Specify a password and then confirm the password.
  5. Click OK.
    Note: The controller must supply a password to be able to connect to that remote agent.
Parent topic: Remote Agents


Configuring Remote Agent Java Settings

  1. Navigate to System > Settings > Java.
  2. Click the Remote tab.
  3. Enable Use different settings for remote agents. If this option is disabled, the Java settings for the Silk Performer controller will be applied to the agents also. The Java settings for the controller are defined on the General tab.
  4. Specify the direcotry of the Java home path in the Java 32-bit home or Java 64-bit home field, depending on what Java architecutre you use. This option enables the Java Virtual Machine to be loaded from a different path than is specified in the PATH environment so that you can switch between various Java Virtual Machines without changing the system PATH environment. The classpath specified for the Java Virtual Machine is displayed in the Classpath field. By default the classpath is set to the system classpath.
    Note: Classpath entries in the Classpath field can be edited manually.
  5. In the Command line options text box, type any command-line options to pass to the Java Virtual Machine.
  6. Click OK.
Parent topic: Remote Agents


Client Certificates

A secure Web server can be configured to refuse clients that do not have a proper client certificate from a trusted certification authority. In such cases, the server asks the client to send its certificate before performing any requests. As long as the client certificate is signed by a trusted CA, the server does not care what the client is. If the Web server requests a client certificate, it is necessary to export the client certificate from the Web browser and place it in the Silk Performer certificate store to be used for recording and replay.

Handling client certificates with the Web browser

A secure Web server can be configured to refuse clients that do not have a proper client certificate from a trusted certification authority. If a Web server requests a client certificate, it is necessary to export the client certificate from the Web browser and place it in the Silk Performer certificate store.

Exporting client certificates

Since the Silk Performer Recorder works as a proxy between a client and a Web server, and the replay engine represents the simulated client itself, successful connection to the server requires a certificate from the client. Therefore the certificate must be exported by the Web browser and imported into Silk Performer.

Note: When obtaining a client certificate from a certification authority, be sure to allow the private keys to be exported with the certificate. Otherwise, the certificate will be useless for the Secure Internet Recorder.
  • Installing Client Certificates
    If a Web server requests a client certificate, it is necessary to export the client certificate from the Web browser and import it into Silk Performer.
  • Using a Client Certificate for Recording
    Create a client certificate that the replay engine presents to the Web server on behalf of the actual client.
  • Using a Client Certificate for Replay in the GUI
    A secure Web server can be configured to refuse clients that do not have a proper client certificate from a trusted certification authority. In such cases, the server asks the client to send its certificate before performing any requests.
  • Using a Client Certificate for Replay in a Script
    A secure Web server can be configured to refuse clients that do not have a proper client certificate from a trusted certification authority. In such cases, the server asks the client to send its certificate before performing any requests.
  • Exporting a Client Certificate from Internet Explorer
    If a Web server requests a client certificate, it is necessary to export the client certificate from the Web browser and import it into Silk Performer.
  • Exporting a Client Certificate from Firefox
    If a Web server requests a client certificate, it is necessary to export the client certificate from the Web browser and import it into Silk Performer.
Parent topic: Configuring Silk Performer


Installing Client Certificates

Client certificates are typically stored on the system or in the web browser's certificate store. To use a client certificate in Silk Performer, export the certificate from your web browser and import it into Silk Performer.

  1. From the menu bar, select Settings > Active Profile .
  2. In the shortcut list on the left side, click the Internet icon.
  3. Switch to the Security tab.
  4. In the Client certificate area, click Import and locate a certificate file of the format .p12 or .pfx (for example, C:\clientcert\johndoe.pfx).
  5. Enter the password you used for encryption when exporting the certificate from your Web browser.
  6. Click OK.

    This confirmation also creates a certificate file (.pem) in the Silk Performer user data directory (for example, <public user documents>\Silk Performer 21.0\Data\johndoe.pem).

    Note: Each proxy connection set up in the Silk Performer Recorder can be associated with a client certificate. The Silk Performer Recorder presents the client certificate to the Web server on behalf of the actual client.
Parent topic: Client Certificates


Using a Client Certificate for Recording

Before you begin this procedure, make sure that a client certificate is installed in Silk Performer.

  1. In the Silk Performer menu, click Settings > System .
  2. Click the Recorder icon. The Recording Profiles page opens.
  3. In the System Settings - Recorder dialog, click the Proxies tab.
  4. Set up a new proxy connection or select an existing proxy of your choice to be associated with a client certificate (for example, SOCKS) and click the Edit button.
  5. Select an appropriate certificate from the Certificate list box in the Client Certificate area (for example, John Doe).
  6. Click OK.
  7. Restart the Silk Performer Recorder before you begin recording. The Silk Performer replay engine presents the client certificate to the Web server on behalf of the actual client.
Parent topic: Client Certificates


Using a Client Certificate for Replay in the GUI

Before you begin this procedure, make sure that a client certificate is installed in Silk Performer.

  1. From the menu bar, select Settings > Active Profile .
  2. In the shortcut list on the left side, click the Internet icon.
  3. Switch to the Security tab.
  4. In the Client certificate area, select an appropriate certificate from the Certificate list box (for example, John Doe).
  5. Click OK.
To make the certificate available on remote agents as well, make sure to add the certificate file to the data files of the project. The imported certificates are stored in the Silk Performer user data directory, for example: <public user documents>\Silk Performer <version>\Data.
Parent topic: Client Certificates


Using a Client Certificate for Replay in a Script

Before you begin this procedure, make sure that a client certificate is installed in Silk Performer.

Use the bdl function SslSetClientCert() to enable a virtual user to use the specified client certificate. For example:
SslSetClientCert("johndoe.pem")
To make the certificate available on remote agents as well, make sure to add the certificate file to the data files of the project. The imported certificates are stored in the Silk Performer user data directory, for example: <public user documents>\Silk Performer <version>\Data.
Parent topic: Client Certificates
Related reference
SslSetClientCert Function


Exporting a Client Certificate from Internet Explorer

  1. From the Internet Explorer menu bar, select Tools > Internet Options . The General page of the Internet Options dialog opens.
  2. Click the Content tab.
  3. In the Certificates area, click the Certificates button. The Certificates dialog opens.
  4. From the list, select the certificate to export then click Export. Internet Explorer automatically starts the Certificate Manager Export Wizard.
  5. Using the wizard, perform all steps described to export your client certificate.
    Note: You have to export the private key with the certificate for the certificate to be usable with the Silk Performer Recorder.
  6. In the Certificates dialog, click Close.
  7. Click OK to close the Internet Options dialog. The certificate file (.pfx) can now be imported by the Silk Performer Recorder.
Parent topic: Client Certificates


Exporting a Client Certificate from Firefox

  1. From the Firefox menu bar, select Tools > Options . The Options dialog opens.
  2. Click the Advanced icon.
  3. Select the Encryption tab.
  4. In the Certificates area, click View Certificates. The Certificate Manager dialog opens.
  5. From the list, select the certificate to export then click Export.
  6. In the Save Certificate To File dialog, enter a name of the certificate file, select the file type, and click Save.
  7. In the Certificate Manager dialog, click OK to close the dialog.
  8. Click OK to close the Options dialog.
Parent topic: Client Certificates


Custom Screen Layouts

Different screen layouts are useful for different scenarios. If you are a laptop user developing tests, running tests, and analyzing results, you will probably prefer your laptop's native screen resolution, which may be fairly high. In general the higher the resolution, the more panes you can view at one time. For such scenarios it makes sense to use High Resolution screen layout, which enables all panes.

When viewing Silk Performer on a low-resolution device or during the course of a presentation over a projector or Web meeting, your screen resolution will likely be more limited. For such scenarios it may be useful to use normal screen layout.

The customizations you make regarding the panes that you enable/disable and the positions in which you place the panes are saved along with both your high resolution and your normal layouts. For example, if you reposition the Project pane while working in high resolution layout and then switch to normal layout, the Project pane will appear in the same custom position the next time you return to high resolution layout.

  • Enabling/Disabling High Resolution Screen Layout
    Consider using high-resolution screen layout for day-to-day testing work and normal (low-resolution) layout for presentations and demos.
  • Resetting Default Screen Layouts
    You can return both your normal and high resolution screen layouts, including the panes that are enabled and their positions, to their default states.
Parent topic: Configuring Silk Performer


Enabling/Disabling High Resolution Screen Layout

  1. Choose View > Screen Layout.
  2. Select High Resolution to enable additional Silk Performer view panes for day-to-day testing work on high-resolution screens. A checkmark appears next to the High Resolution menu option when high resolution layout is enabled.
    Note: To disable high resolution layout and return to normal layout, select High Resolution.
Silk Performer screen layout will be redrawn based on your selection.
Parent topic: Custom Screen Layouts


Resetting Default Screen Layouts

  1. Choose View > Screen Layout.
  2. Select Reset to restore screen panes and the positions of those panes to their default states. The Reset command is only applied to your current layout, either high resolution or normal layout, not both layouts.
Silk Performer screen layout will be redrawn based on your selection.
Parent topic: Custom Screen Layouts


Managing Multiple Versions of Silk Performer

When multiple versions of Silk Performer are installed on a single machine it is possible that the wrong version of Silk Performer will launch when you double-click a project or script file from the desktop. All Silk Performer file types have an entry in the registry that determines what program is to be launched when a specific file type is double-clicked.

By default, the most recently installed version of Silk Performer is the version that is used for all Silk Performer file-type operations. If an older version of Silk Performer was installed most recently, that is the version that will be used when you double-click a Silk Performer file.

There are two ways you can change the default version:

  • Reinstall the latest version of Silk Performer - All registry entries that control version selection will be updated to reflect the latest version. This is a faster approach and is safer than manually modifying the registry.
  • Modify the registry manually - Navigate to HKEY_CLASSES_ROOT\Silk Performer Project Archive File\shell\Open\command and modify the default value for each file type. You can select a specific version for each file type.
    Note: Each Silk Performer file type has a registry key associated with it. You must modify each entry. While this may be time consuming, it enables you to specify that different versions of Silk Performer be used for different file types.
Parent topic: Configuring Silk Performer


Managing Load Tests

This section explains the tasks that must be completed to prepare for, run, and analyze the results of a load test .

  • Outlining Projects
    Explains how to define name, description, and application-type-under-test parameters for your project.
  • Modeling Scripts
    Explains how test scripts are created (manually, recorded, or based on a sample script). Test scripts define the actions of virtual users in load tests.
  • Trying Out Scripts
    Explains how to evaluate the success or failure of scripts.
  • Customizing Scripts
    Explains why it is recommended to customize your scripts before you run a load test and what problems can occur if you do not customize your scripts.
  • Defining User Types
    Explains how to define a user type for the active workload. Defining a user type determines what script, user group, and profile will be used in the test.
  • Finding Baselines
    Explains how to run a baseline test to determine your application's ideal performance baseline.
  • Viewing Baselines
    Provides an overview of how to confirm that the baseline test reflects the desired performance of the application under test and how to set the baseline test as the baseline.
  • Adjusting Workload
    Explains how to define the workload for load tests.
  • Assigning Agents
    Explains how to configure and assign individual agents and clusters of agents to your project.
  • Trying Out Agents
    Explains how to perform a trial run of a test script to verify that the script works on various agents.
  • Configuring Monitoring
    Explains options for monitoring local and remote computers with Performance Explorer during tests.
  • Running Load Tests
    Explains how to execute and monitor load tests.
  • Exploring Test Results
    Display and analyze results to assess application and server performance.
Parent topic: Silk Performer Workbench 21.0


Outlining Projects

Explains how to define name, description, and application-type-under-test parameters for your project.

  • Outlining Projects
    Explains how to define name, description, and application-type-under-test parameters for your project.
  • Project Profile Settings
    Project profile settings define test-script generation, replay simulation, and result-file output.
  • Test Scripts
    Explains how to prescribe the actions of virtual users in your tests.
  • Data Files
    Projects rely on a number of data file types: user-data files (CSV), IDL, certificate files (PEM), random data files (RND), and type library files (TLB, DLL, EXE, OCX, OLB, PKG).
  • Agent Computers
    Agent computers host the virtual users that are run during tests.
Parent topic: Managing Load Tests


Outlining Projects

When you create a Silk Performer load test you must define the basic settings for the load test project. The project is given a name, and optionally a brief description can be added. The type of application to be tested is specified from a range of choices that includes all of the major traffic available today on the Internet and on the Web, including the most important database and distributed applications.

The settings that are specified are associated with a particular load test project. It is easy to switch between different projects, to edit projects, and to save projects so that they can later be modified and reused.

A project contains all the resources needed to complete a load test. These include a workload, one or more profiles and load test scripts, a specific number of agent computers and information for server-side monitoring, and all the data files that are accessed from the script. Options for all of these resources are available directly from the project node in the Project menu tree.

  • Outlining a Project
    Configure basic settings such as project name and the application type under test.
  • Available Application Types
    Lists the application types (vendors, protocols, and versions) that can be tested with Silk Performer.
Parent topic: Outlining Projects
Related reference
Available Application Types


Available Application Types

The following application types can be tested with Silk Performer, both secure and unsecured:

  • Web Browser
    Web Browser application types are used for load testing applications that run within a Web browser.
  • Internet
    Select one of the Internet application types to test an application that relies upon Internet-based protocols and communication.
  • Terminal Emulation
    Silk Performer support for terminal emulation applications enables the recording of terminal-emulator traffic based on the Telnet protocol ("green screen" applications).
  • ERP/CRM
    Select an ERP/CRM application type to test an Enterprise Resource Planning or Customer Relationship Management application.
  • Web Services
    Select one of the Web Services application types to test an application which utilizes that Web services software framework.
  • Database
    Select one of the Database application types to test an application that relies on common database APIs.
  • Application Server/Component Models
    Select one of the Application Server/Component Models types to test an application that relies upon specific middleware.
  • Terminal Services
    Select one of the Terminal Services application types to test a Citrix-based application.
  • .NET
    Select one of the .NET application types to test Web Services, .NET Remoting objects, NUnit, or another .NET technology.
  • Java
    Select one of the Java application types to test Web Services, RMI, JUnit, or other Java-based technologies.
  • Frameworks
    Select one of the included frameworks to test an application using either the Java Framework, Visual Basic Framework, or .NET Framework Using Visual Studio .NET.
  • Monitoring
    Select a Monitoring application type to generate server-side results that can be archived for future viewing and comparison. Monitoring also reveals, locates, and resolves server bottlenecks, allowing you to examine the performance of operating systems and application servers.
  • Unit Testing
    Select a Unit Testing application type to perform JUnit, Java, NUnit, or .NET unit testing.
  • GUI-Level Testing
    GUI-Level application types are used for the load testing of client applications that cannot be tested on the protocol or API levels.
  • Legacy
    The legacy group contains project types offered in earlier versions of Silk Performer.
  • Samples
    Select one of these preconfigured test script Samples to save time in the manual creation of your test script.
Parent topic: Outlining Projects
Related concepts
Outlining Projects


Web Browser

Web Browser application types are used for load testing applications that run within a Web browser. Due to the multitude of technologies that browser-based applications are based on, different project types are available for selection.

  • Web business transaction (HTML/HTTP)
    Select Web business transaction (HTML/HTTP) to test Web applications with simple scripts that incorporate advanced functionality.
  • Web browser-driven (AJAX)
    Select Web browser-driven (AJAX) to use a Web browser (Internet Explorer) to drive your test.
  • Web (Async)
    Select Web (Async) to test Web applications that use asynchronous communication patterns such as polling, long-polling, and push. The characteristics of such applications is periodic, event-based, or server-triggered content updates without user interaction.
  • Web low-level (HTTP)
    Select Web low-level (HTTP) to test a Web application when you want to put the highest possible load on the application.
  • Mobile devices
    Select Mobile devices to test mobile Web applications. This application type offers simulation capabilities for a variety of mobile devices, such as iPhone, iPad, Android, Windows Phone, and Blackberry.
  • Flex/AMF3 (Adobe)
    Select Flex/AMF3 (Adobe) for the testing of both AMF0 and AMF3 based on the Adobe/BlazeDS implementation.
  • Flex/AMF3 (GraniteDS)
    Select Flex/AMF3 (GraniteDS) for the testing of Flex applications and the AMF3 protocol based on the GraniteDS implementation.
  • HTTP Live Streaming (HLS)
    Select HTTP Live Streaming (HLS) to test web applications that stream video or audio data through the HTTP Live Streaming protocol.
  • Java Over HTTP
    Select Java over HTTP to test Web applications that make use of Java Object Serialization to transfer objects between client and sever over the HTTP protocol.
  • WebDAV (MS Outlook Web Access)
    Select WebDAV to test clients that rely on WebDAV, for example Microsoft Outlook Web Access.
  • Silverlight
    Select Silverlight to test browser-based applications that are built using Microsoft Silverlight.
  • Oracle ADF
    Select Oracle ADF to test Web applications that are based on the Oracle Application Development Framework, a Java-based framework for building enterprise applications.
Parent topic: Available Application Types
Related concepts
Web Applications Support


Web business transaction (HTML/HTTP)

Select Web business transaction (HTML/HTTP) to test Web applications with simple scripts that incorporate advanced functionality. This application type should also be used for browser-based applications.

Parent topic: Web Browser
Related concepts
Load Testing Web 2.0 Applications (Protocol-Level)


Web browser-driven (AJAX)

Select Web browser-driven (AJAX) to use a Web browser (Internet Explorer) to drive your test. This application type is particularly useful when testing a Web application with built-in AJAX logic and testing on the protocol level (HTTP) has proved to be unsuccessful.

Parent topic: Web Browser
Related concepts
Load Testing Web 2.0 Applications (Browser-Driven)


Web (Async)

Select Web (Async) to test Web applications that use asynchronous communication patterns such as polling, long-polling, and push. The characteristics of such applications is periodic, event-based, or server-triggered content updates without user interaction.

Parent topic: Web Browser
Related concepts
Web Application Communication Overview


Web low-level (HTTP)

Select Web low-level (HTTP) to test a Web application when you want to put the highest possible load on the application. Web low-level scripts are more complex than Web business transaction scripts, which require more effort to customize.

Parent topic: Web Browser
Related concepts
Load Testing Web 2.0 Applications (Protocol-Level)


Mobile devices

Select Mobile devices to test mobile Web applications. This application type offers simulation capabilities for a variety of mobile devices, such as iPhone, iPad, Android, Windows Phone, and Blackberry. Other mobile browsers can be simulated using custom profiles.

Parent topic: Web Browser
Related concepts
Testing Apps for Mobile Devices


Flex/AMF3 (Adobe)

Select Flex/AMF3 (Adobe) for the testing of both AMF0 and AMF3 based on the Adobe/BlazeDS implementation. With this application type, profile settings related to Flex/AMF3, transform HTTP requests/responses, and JVM are configured automatically.

Parent topic: Web Browser
Related concepts
Flex/AMF3 Support


Flex/AMF3 (GraniteDS)

Select Flex/AMF3 (GraniteDS) for the testing of Flex applications and the AMF3 protocol based on the GraniteDS implementation. With this application type, profile settings related to Flex/AMF3, transform HTTP requests/responses, and JVM are configured automatically.

Parent topic: Web Browser
Related concepts
Flex/AMF3 Project Setup and Testing


HTTP Live Streaming (HLS)

Select HTTP Live Streaming (HLS) to test web applications that stream video or audio data through the HTTP Live Streaming protocol.

Parent topic: Web Browser


Java Over HTTP

Select Java over HTTP to test Web applications that make use of Java Object Serialization to transfer objects between client and sever over the HTTP protocol. This communication, based on the exchange of serialized Java objects, basically uses data in a binary format.

Parent topic: Web Browser
Related concepts
Java Over HTTP Support


WebDAV (MS Outlook Web Access)

Select WebDAV to test clients that rely on WebDAV, for example Microsoft Outlook Web Access. WebDAV is a set of methods based on HTTP that facilitates collaboration between users in editing and managing documents and files stored on Web servers.

Parent topic: Web Browser


Silverlight

Select Silverlight to test browser-based applications that are built using Microsoft Silverlight.

Note: The workflow for testing Microsoft Silverlight browser-based applications with Silk Performer is the same as the workflow used for testing Web-based applications.
Parent topic: Web Browser
Related concepts
Microsoft Silverlight Support


Oracle ADF

Select Oracle ADF to test Web applications that are based on the Oracle Application Development Framework, a Java-based framework for building enterprise applications. This project type uses pre-defined recording settings and recording rules to facilitate script customization.

Parent topic: Web Browser


Internet

Select one of the Internet application types to test an application that relies upon Internet-based protocols and communication.

  • Email (SMTP/POP)
    Select Email (SMTP/POP) to test applications and email clients that use the Simple Mail Transfer Protocol to send and receive email messages.
  • Directory Server (LDAP)
    Select Directory Server (LDAP) to test servers that use the Lightweight Directory Access Protocol (LDAP), for example Active Directory.
  • Radius
    Select Radius to test applications or devices that use the RADIUS (Remote Authentication Dial In User Service) networking protocol for authentication, authorization, and accounting to manage network access.
  • FTP
    Select FTP to test applications that use the File Transfer Protocol (FTP), the standard network protocol used to transfer files from one host to another host over a TCP-based network, such as the Internet.
  • TCP/IP based applications
    Select TCP/IP based application to test applications that use proprietary protocols based on TCP/IP.
  • Mixed Protocols
    Select Mixed Protocols to test applications that use multiple protocols, such as a combination of HTTP, ODBC, and other protocols.
Parent topic: Available Application Types
Related concepts
Internet


Email (SMTP/POP)

Select Email (SMTP/POP) to test applications and email clients that use the Simple Mail Transfer Protocol to send and receive email messages.

Parent topic: Internet
Related concepts
POP3 Functions Reference


Directory Server (LDAP)

Select Directory Server (LDAP) to test servers that use the Lightweight Directory Access Protocol (LDAP), for example Active Directory.

Parent topic: Internet
Related concepts
LDAP Functions Reference


Radius

Select Radius to test applications or devices that use the RADIUS (Remote Authentication Dial In User Service) networking protocol for authentication, authorization, and accounting to manage network access.

Parent topic: Internet
Related concepts
Radius Functions Reference


FTP

Select FTP to test applications that use the File Transfer Protocol (FTP), the standard network protocol used to transfer files from one host to another host over a TCP-based network, such as the Internet.

Parent topic: Internet
Related concepts
FTP Functions Reference


TCP/IP based applications

Select TCP/IP based application to test applications that use proprietary protocols based on TCP/IP.

Parent topic: Internet
Related concepts
TCP/IP Functions Reference


Mixed Protocols

Select Mixed Protocols to test applications that use multiple protocols, such as a combination of HTTP, ODBC, and other protocols.

Parent topic: Internet


Terminal Emulation

Silk Performer support for terminal emulation applications enables the recording of terminal-emulator traffic based on the Telnet protocol ("green screen" applications). Supported terminal types include VT100 and VT200 (UNIX, IBM AS400) and IBM mainframes accessed via TN3270(E) & TN5250. A prerequisite for recording terminal-emulator traffic is an installed terminal-emulator for accessing host applications.

Note: For full details regarding Silk Performer support for terminal emulation applications, see Miscellaneous Tutorials.
  • TN3270
    Select TN3270 to test an IBM mainframe application that is accessed using a TN3270(E) terminal emulator.
  • TN5250
    Select TN5250 to test an IBM mainframe application that is accessed using a TN5250 terminal emulator.
  • VT100
    Select VT100 to record an application that is accessed using a VT100 terminal emulator.
  • VT200+
    Select VT200+ to record an application that is accessed using a VT200+ terminal emulator.
Parent topic: Available Application Types
Related concepts
Terminal Emulation Support


TN3270

Select TN3270 to test an IBM mainframe application that is accessed using a TN3270(E) terminal emulator.

Parent topic: Terminal Emulation
Related concepts
Terminal Emulation Support


TN5250

Select TN5250 to test an IBM mainframe application that is accessed using a TN5250 terminal emulator.

Parent topic: Terminal Emulation
Related concepts
Terminal Emulation Support


VT100

Select VT100 to record an application that is accessed using a VT100 terminal emulator.

Parent topic: Terminal Emulation
Related concepts
Terminal Emulation Support


VT200+

Select VT200+ to record an application that is accessed using a VT200+ terminal emulator.

Parent topic: Terminal Emulation
Related concepts
Terminal Emulation Support


ERP/CRM

Select an ERP/CRM application type to test an Enterprise Resource Planning or Customer Relationship Management application.

Enterprise resource planning (ERP) systems integrate management information across an organization. Customer relationship management (CRM) systems organize business processes such as sales, marketing, customer service, and technical support.

  • SAP
    Select one of the SAP ERP and CRM application types to test SAP applications.
  • PeopleSoft
    Select one of the PeopleSoft application types to test a PeopleSoft ERP/CRM application.
  • Clarify 8-10 (Tuxedo)
    Select Clarify 8-10 (Tuxedo) to test an eFrontOffice application.
  • Oracle
    Select an Oracle Application type to test an application that is built on Oracle business (non-database) software.
  • Siebel
    Select a Siebel 6 application type or the Siebel Web Client application type to test a Siebel-based (Oracle) CRM application.
  • Remedy
    Select the correct Remedy version to test BMC Remedy IT Service Management.
Parent topic: Available Application Types
Related concepts
SAP Support
PeopleSoft Overview
Siebel Functions Overview
BMC Remedy IT Service Management Support


SAP

Select one of the SAP ERP and CRM application types to test SAP applications.

  • SAPGUI
    Select SAPGUI to test an SAP application that uses a SAPGUI client.
  • SAP NetWeaver (Web)
    Select SAP NetWeaver (Web) to test a SAP NetWeaver-based application.
Parent topic: ERP/CRM
Related concepts
SAP Support


SAPGUI

Select SAPGUI to test an SAP application that uses a SAPGUI client.

Parent topic: SAP
Related concepts
SAPGUI Support


SAP NetWeaver (Web)

Select SAP NetWeaver (Web) to test a SAP NetWeaver-based application. For example SAP GUI for HTML or SAP Enterprise Portal applications.

Parent topic: SAP
Related concepts
SAP Support


PeopleSoft

Select one of the PeopleSoft application types to test a PeopleSoft ERP/CRM application.

  • PeopleSoft8
    Select PeopleSoft8 to test a PeopleSoft 8.x application.
  • PeopleSoft9
    Select PeopleSoft9 to test a PeopleSoft 9.x application.
Parent topic: ERP/CRM
Related concepts
PeopleSoft Overview


PeopleSoft8

Select PeopleSoft8 to test a PeopleSoft 8.x application.

Silk Performer offers page-level support for testing of PeopleSoft 8.x applications. This application type adds PeopleSoft-specific enhancements for session handling, detection of application-level errors, easy customization of login data, thinktimes, page timer names, and access to table rows.

Parent topic: PeopleSoft
Related concepts
PeopleSoft Overview


PeopleSoft9

Select PeopleSoft9 to test a PeopleSoft 9.x application.

Silk Performer offers page-level support for testing of PeopleSoft 9.x applications. This application type adds PeopleSoft-specific enhancements for session handling, detection of application-level errors, easy customization of login data, thinktimes, page timer names, and access to table rows.

Parent topic: PeopleSoft
Related concepts
PeopleSoft Overview


Clarify 8-10 (Tuxedo)

Select Clarify 8-10 (Tuxedo) to test an eFrontOffice application.

Clarify eFrontOffice uses TUXEDO as part of its multi-tier architecture.

Parent topic: ERP/CRM
Related concepts
TUXEDO Data Structures Overview


Oracle

Select an Oracle Application type to test an application built on Oracle business (non-database) software.

Oracle Applications comprise the applications software or business software of Oracle Corporation. The term refers to the non-database parts of Oracle's software portfolio. Oracle sells many functional modules that use the Oracle RDBMS as a back-end, notably Oracle Financials, Oracle HRMS, Oracle Projects, Oracle CRM, and Oracle Procurement.

  • Oracle Applications 11i
    Select Oracle Applications 11i to test Oracle Applications 11i.
  • Oracle Applications 12i
    Select Oracle Applications 12i to test Oracle Applications 12i.
Parent topic: ERP/CRM
Related concepts
Oracle Forms / Oracle Applications Support


Oracle Applications 11i

Select Oracle Applications 11i to test Oracle Applications 11i.

Parent topic: Oracle
Related concepts
Oracle Forms / Oracle Applications Support


Oracle Applications 12i

Select Oracle Applications 12i to test Oracle Applications 12i.

Parent topic: Oracle
Related concepts
Oracle Forms / Oracle Applications Support


Siebel

Select a Siebel 6 application type or the Siebel Web Client application type to test a Siebel-based (Oracle) CRM application.

  • Siebel 6/DB2
    Select Siebel 6/DB2 to test a Siebel 6-based (Oracle) CRM application that is built on an IBM DB2 RDBMS.
  • Siebel 6/Oracle
    Select Siebel 6/Oracle to test a Siebel 6-based (Oracle) CRM application that is built on an Oracle RDBMS.
  • Siebel 6/SQL Server
    Select Siebel 6/SQL Server to test a Siebel 6-based (Oracle) CRM application that is built on a SQL Server RDBMS.
  • Siebel Web Client
    Select Siebel Web Client to test a Siebel-based (Oracle) CRM application that uses a Web client.
Parent topic: ERP/CRM
Related concepts
Siebel Functions Overview


Siebel 6/DB2

Select Siebel 6/DB2 to test a Siebel 6-based (Oracle) CRM application that is built on an IBM DB2 RDBMS.

Parent topic: Siebel
Related concepts
Siebel Functions Overview


Siebel 6/Oracle

Select Siebel 6/Oracle to test a Siebel 6-based (Oracle) CRM application that is built on an Oracle RDBMS.

Parent topic: Siebel
Related concepts
Siebel Functions Overview


Siebel 6/SQL Server

Select Siebel 6/SQL Server to test a Siebel 6-based (Oracle) CRM application that is built on a SQL Server RDBMS.

Parent topic: Siebel
Related concepts
Siebel Functions Overview


Siebel Web Client

Select Siebel Web Client to test a Siebel-based (Oracle) CRM application that uses a Web client.

Parent topic: Siebel
Related concepts
Siebel Functions Overview


Remedy

Select the correct Remedy version to test BMC Remedy IT Service Management. BMC has created an excellent tutorial that illustrates how to load test BMC Remedy IT Service Management (ITSM) applications with BMC Remedy Action Request System (AR System). To obtain the tutorial, contact BMC and request the following white paper: Performance Benchmarking Kit: Using Incident Management with Silk Performer

  • Remedy 7.5
    Select the correct Remedy version to test BMC Remedy IT Service Management.
  • Remedy 7.5 Patch 04
    Select the correct Remedy version to test BMC Remedy IT Service Management.
  • Remedy 7.6.02
    Select the correct Remedy version to test BMC Remedy IT Service Management.
  • Remedy 7.6.03
    Select the correct Remedy version to test BMC Remedy IT Service Management.
  • Remedy 7.6.04
    Select the correct Remedy version to test BMC Remedy IT Service Management.
  • Remedy 7.6.04 SP1
    Select the correct Remedy version to test BMC Remedy IT Service Management.
  • Remedy 7.6.04 SP3
    Select the correct Remedy version to test BMC Remedy IT Service Management.
  • Remedy 7.6.04 SP4
    Select the correct Remedy version to test BMC Remedy IT Service Management.
  • Remedy 7.6.04 SP5
    Select the correct Remedy version to test BMC Remedy IT Service Management.
  • Remedy 7.7
    Select the correct Remedy version to test BMC Remedy IT Service Management.
  • Remedy 8.0
    Select the correct Remedy version to test BMC Remedy IT Service Management.
  • Remedy 8.1
    Select the correct Remedy version to test BMC Remedy IT Service Management.
  • RemedyAR 8.1 SP1
    Select the correct Remedy version to test BMC Remedy IT Service Management.
  • RemedyAR 8.8
    Select the correct Remedy version to test BMC Remedy IT Service Management.
  • RemedyAR 9.0
    Select the correct Remedy version to test BMC Remedy IT Service Management.
Parent topic: ERP/CRM
Related concepts
BMC Remedy IT Service Management Support


Remedy 7.5

Select the correct Remedy version to test BMC Remedy IT Service Management. BMC has created an excellent tutorial that illustrates how to load test BMC Remedy IT Service Management (ITSM) applications with BMC Remedy Action Request System (AR System). To obtain the tutorial, contact BMC and request the following white paper: Performance Benchmarking Kit: Using Incident Management with Silk Performer

Parent topic: Remedy
Related concepts
BMC Remedy IT Service Management Support


Remedy 7.5 Patch 04

Select the correct Remedy version to test BMC Remedy IT Service Management. BMC has created an excellent tutorial that illustrates how to load test BMC Remedy IT Service Management (ITSM) applications with BMC Remedy Action Request System (AR System). To obtain the tutorial, contact BMC and request the following white paper: Performance Benchmarking Kit: Using Incident Management with Silk Performer

Parent topic: Remedy
Related concepts
BMC Remedy IT Service Management Support


Remedy 7.6.02

Select the correct Remedy version to test BMC Remedy IT Service Management. BMC has created an excellent tutorial that illustrates how to load test BMC Remedy IT Service Management (ITSM) applications with BMC Remedy Action Request System (AR System). To obtain the tutorial, contact BMC and request the following white paper: Performance Benchmarking Kit: Using Incident Management with Silk Performer

Parent topic: Remedy
Related concepts
BMC Remedy IT Service Management Support


Remedy 7.6.03

Select the correct Remedy version to test BMC Remedy IT Service Management. BMC has created an excellent tutorial that illustrates how to load test BMC Remedy IT Service Management (ITSM) applications with BMC Remedy Action Request System (AR System). To obtain the tutorial, contact BMC and request the following white paper: Performance Benchmarking Kit: Using Incident Management with Silk Performer

Parent topic: Remedy
Related concepts
BMC Remedy IT Service Management Support


Remedy 7.6.04

Select the correct Remedy version to test BMC Remedy IT Service Management. BMC has created an excellent tutorial that illustrates how to load test BMC Remedy IT Service Management (ITSM) applications with BMC Remedy Action Request System (AR System). To obtain the tutorial, contact BMC and request the following white paper: Performance Benchmarking Kit: Using Incident Management with Silk Performer

Parent topic: Remedy
Related concepts
BMC Remedy IT Service Management Support


Remedy 7.6.04 SP1

Select the correct Remedy version to test BMC Remedy IT Service Management. BMC has created an excellent tutorial that illustrates how to load test BMC Remedy IT Service Management (ITSM) applications with BMC Remedy Action Request System (AR System). To obtain the tutorial, contact BMC and request the following white paper: Performance Benchmarking Kit: Using Incident Management with Silk Performer

Parent topic: Remedy
Related concepts
BMC Remedy IT Service Management Support


Remedy 7.6.04 SP3

Select the correct Remedy version to test BMC Remedy IT Service Management. BMC has created an excellent tutorial that illustrates how to load test BMC Remedy IT Service Management (ITSM) applications with BMC Remedy Action Request System (AR System). To obtain the tutorial, contact BMC and request the following white paper: Performance Benchmarking Kit: Using Incident Management with Silk Performer

Parent topic: Remedy
Related concepts
BMC Remedy IT Service Management Support


Remedy 7.6.04 SP4

Select the correct Remedy version to test BMC Remedy IT Service Management. BMC has created an excellent tutorial that illustrates how to load test BMC Remedy IT Service Management (ITSM) applications with BMC Remedy Action Request System (AR System). To obtain the tutorial, contact BMC and request the following white paper: Performance Benchmarking Kit: Using Incident Management with Silk Performer

Parent topic: Remedy


Remedy 7.6.04 SP5

Select the correct Remedy version to test BMC Remedy IT Service Management. BMC has created an excellent tutorial that illustrates how to load test BMC Remedy IT Service Management (ITSM) applications with BMC Remedy Action Request System (AR System). To obtain the tutorial, contact BMC and request the following white paper: Performance Benchmarking Kit: Using Incident Management with Silk Performer

Parent topic: Remedy


Remedy 7.7

Select the correct Remedy version to test BMC Remedy IT Service Management. BMC has created an excellent tutorial that illustrates how to load test BMC Remedy IT Service Management (ITSM) applications with BMC Remedy Action Request System (AR System). To obtain the tutorial, contact BMC and request the following white paper: Performance Benchmarking Kit: Using Incident Management with Silk Performer

Parent topic: Remedy
Related concepts
BMC Remedy IT Service Management Support


Remedy 8.0

Select the correct Remedy version to test BMC Remedy IT Service Management. BMC has created an excellent tutorial that illustrates how to load test BMC Remedy IT Service Management (ITSM) applications with BMC Remedy Action Request System (AR System). To obtain the tutorial, contact BMC and request the following white paper: Performance Benchmarking Kit: Using Incident Management with Silk Performer

Parent topic: Remedy


Remedy 8.1

Select the correct Remedy version to test BMC Remedy IT Service Management. BMC has created an excellent tutorial that illustrates how to load test BMC Remedy IT Service Management (ITSM) applications with BMC Remedy Action Request System (AR System). To obtain the tutorial, contact BMC and request the following white paper: Performance Benchmarking Kit: Using Incident Management with Silk Performer

Parent topic: Remedy


RemedyAR 8.1 SP1

Select the correct Remedy version to test BMC Remedy IT Service Management. BMC has created an excellent tutorial that illustrates how to load test BMC Remedy IT Service Management (ITSM) applications with BMC Remedy Action Request System (AR System). To obtain the tutorial, contact BMC and request the following white paper: Performance Benchmarking Kit: Using Incident Management with Silk Performer

Parent topic: Remedy


RemedyAR 8.8

Select the correct Remedy version to test BMC Remedy IT Service Management. BMC has created an excellent tutorial that illustrates how to load test BMC Remedy IT Service Management (ITSM) applications with BMC Remedy Action Request System (AR System). To obtain the tutorial, contact BMC and request the following white paper: Performance Benchmarking Kit: Using Incident Management with Silk Performer

Parent topic: Remedy


RemedyAR 9.0

Select the correct Remedy version to test BMC Remedy IT Service Management. BMC has created an excellent tutorial that illustrates how to load test BMC Remedy IT Service Management (ITSM) applications with BMC Remedy Action Request System (AR System). To obtain the tutorial, contact BMC and request the following white paper: Performance Benchmarking Kit: Using Incident Management with Silk Performer

Parent topic: Remedy


Web Services

Select one of the Web Services application types to test an application which utilizes that Web services software framework. Your environment and prerequisites will determine which of these options is best for your needs. Some Web services only work with specific SOAP stacks, depending on the server-side implementation of the Web service.

  • XML/SOAP
    Select XML/SOAP to test Web services that utilize the SOAP (Simple Object Access Protocol) specification standards.
  • .NET Explorer
    Select .NET Explorer to test Web services, .NET Remoting objects, and other .NET components.
  • Java Explorer
    Select Java Explorer to test Web Services, Enterprise JavaBeans (EJB), RMI objects, and other GUI-less Java objects.
Parent topic: Available Application Types
Related concepts
Testing SOAP Web Services for .NET
Testing SOAP Web Services for Java


XML/SOAP

Select XML/SOAP to test Web service applications that utilize the SOAP (Simple Object Access Protocol) specification standards.

Parent topic: Web Services
Related concepts
Testing SOAP Web Services for .NET
Testing SOAP Web Services for Java


.NET Explorer

Select .NET Explorer to test Web services, .NET Remoting objects, and other .NET components.

.NET Explorer is a tool that allows you to create test cases through a point and click interface.

Parent topic: Web Services
Parent topic: .NET
Related concepts
Silk Performer .NET Explorer
Silk Performer .NET Explorer


Java Explorer

Select Java Explorer to test Web Services, Enterprise JavaBeans (EJB), RMI objects, and other GUI-less Java objects.

Java Explorer is a tool that allows you to create test cases through a point and click interface, suited for Java-based technologies.

Parent topic: Web Services
Parent topic: Java
Related concepts
Silk Performer Java Explorer
Java Explorer Help


Database

Select one of the Database application types to test an application that relies on common database APIs.

  • Oracle
    Select Oracle to test database applications that rely on Oracle APIs.
  • ODBC
    Select ODBC to test applications that utilize the Open Database Connectivity (ODBC) framework.
  • DB2 CLI
    Select DB2 CLI to test database applications that use the IBM DB2 CLI interface.
Parent topic: Available Application Types
Related concepts
Database (DBMS) Functions


Oracle

Select Oracle to test database applications that rely on Oracle APIs. Silk Performer provides Oracle API functions along with Oracle database traffic recording and replaying support for use in testing.

Parent topic: Database
Related concepts
Oracle API Functions Overview


ODBC

Select ODBC to test applications that utilize the Open Database Connectivity (ODBC) framework. An application can use ODBC to query data from a DBMS, regardless of the operating system or DBMS it uses.

Parent topic: Database
Related concepts
Working With Database Applications - Overview


DB2 CLI

Select DB2 CLI to test database applications that use the IBM DB2 CLI interface.

Parent topic: Database
Related concepts
Working With Database Applications - Overview


Application Server/Component Models

Select one of the Application Server/Component Models types to test an application that relies upon specific middleware.

  • CORBA (IIOP)
    Select CORBA (IIOP) to test an application that relies upon CORBA middleware, for example VisiBroker.
  • EJB (RMI over IIOP)
    Select EJB (RMI over IIOP) to test an application developed using Enterprise JavaBeans that communicates using RMI over IIOP.
  • EJB (Java Explorer)
    Select EJB (Java Explorer) to use Java Explorer to test an application developed using Enterprise JavaBeans.
  • Tuxedo (ATMI)
    Select Tuxedo (ATMI) to test an application that is built on Tuxedo middleware and the ATMI API.
  • Tuxedo (JOLT)
    Select Tuxedo (Jolt) to test an application that is built on Tuxedo middleware and relies on the Jolt interface.
  • .NET Remoting
    Select .NET Remoting to test widely-distributed applications that rely on .NET remoting communication.
  • Jacada
    Select Jacada to test an application that relies on Jacada unified desktop and process optimization software.
  • Oracle
    To test an application that uses an Oracle Forms client, select the appropriate Oracle Forms version.
Parent topic: Available Application Types
Related concepts
Working with Enterprise JavaBeans
Working with RMI Over IIOP


CORBA (IIOP)

Select CORBA (IIOP) to test an application that relies upon CORBA middleware, for example VisiBroker.

Parent topic: Application Server/Component Models
Related concepts
CORBA Functions Reference


EJB (RMI over IIOP)

Select EJB (RMI over IIOP) to test an application developed using Enterprise JavaBeans that communicates using RMI over IIOP. This application type enables you to use Silk Performer's record and replay workflow.

Parent topic: Application Server/Component Models
Related concepts
Working with RMI Over IIOP
Working with Enterprise JavaBeans


EJB (Java Explorer)

Select EJB (Java Explorer) to use Java Explorer to test an application developed using Enterprise JavaBeans. This application type enables you to use Java Explorer's visual scripting capabilities to create your test script.

Parent topic: Application Server/Component Models
Related concepts
Working with Enterprise JavaBeans
Silk Performer Java Explorer


Tuxedo (ATMI)

Select Tuxedo (ATMI) to test an application that is built on Tuxedo middleware and the ATMI API.

Parent topic: Application Server/Component Models
Related concepts
TUXEDO Functions Reference
TUXEDO Data Structures Overview


Tuxedo (JOLT)

Select Tuxedo (Jolt) to test an application that is built on Tuxedo middleware and relies on the Jolt interface.

Parent topic: Application Server/Component Models
Related concepts
TUXEDO Functions Reference
TUXEDO Data Structures Overview


.NET Remoting

Select .NET Remoting to test widely-distributed applications that rely on .NET remoting communication. This application type enables you to use .NET Explorer's visual scripting capabilities to create your test script.

Parent topic: Application Server/Component Models
Related concepts
Testing Web Services and .NET Remoting Objects with .NET Framework


Jacada

Select Jacada to test an application that relies on Jacada unified desktop and process optimization software.

Parent topic: Application Server/Component Models
Related concepts
Jacada Support


Oracle

Oracle Forms clients run in Web browsers as applets. By default, a Web browser will download and install a JRE when loading an Oracle Forms application for the first time. For Oracle Forms 10g or earlier, Oracle's JRE for Oracle Forms is named JInitiator. Using JInitiator is not mandatory. Once a JRE has been installed, Silk Performer is set up to record Oracle Forms applications.

  • Oracle Forms 10g
    Select Oracle Forms 10g to test an application that uses an Oracle Forms 10g client.
  • Oracle Forms 11g
    Select Oracle Forms 11g to test an application that uses an Oracle Forms 11g client.
  • Oracle Forms 12c
    Select Oracle Forms 12c to test an application that uses an Oracle Forms 12c client.
  • Oracle Forms 6i
    Select Oracle Forms 6i to test an application that uses an Oracle Forms 6i client.
  • Oracle Forms 9i
    Select Oracle Forms 9i to test an application that uses an Oracle Forms 9i client.
Parent topic: Application Server/Component Models
Related concepts
Oracle Forms / Oracle Applications Support


Oracle Forms 10g

Select Oracle Forms 10g to test an application that uses an Oracle Forms 10g client.

Parent topic: Oracle
Related concepts
Oracle Forms / Oracle Applications Support


Oracle Forms 11g

Select Oracle Forms 11g to test an application that uses an Oracle Forms 11g client.

Parent topic: Oracle
Related concepts
Oracle Forms / Oracle Applications Support


Oracle Forms 12c

Select Oracle Forms 12c to test an application that uses an Oracle Forms 12c client.

Parent topic: Oracle


Oracle Forms 6i

Select Oracle Forms 6i to test an application that uses an Oracle Forms 6i client.

Parent topic: Oracle
Related concepts
Oracle Forms / Oracle Applications Support


Oracle Forms 9i

Select Oracle Forms 9i to test an application that uses an Oracle Forms 9i client.

Parent topic: Oracle
Related concepts
Oracle Forms / Oracle Applications Support


Terminal Services

Select one of the Terminal Services application types to test a Citrix-based application which is hosted by Citrix XenApp.

  • Citrix
    Select Citrix to test a Citrix application that is accessed through the Citrix Online Plug-In.
  • Citrix Web Interface
    Select Citrix Web Interface to test a Citrix application that is launched from a Citrix Web Interface running within Internet Explorer.
  • Citrix StoreFront/Netscaler Gateway
    Select Citrix StoreFront/Netscaler Gateway to test a Citrix application that is launched from a Citrix StoreFront server.
Parent topic: Available Application Types
Related concepts
Terminal Emulation Support


Citrix

Select Citrix to test a Citrix application that is accessed through the Citrix Online Plug-In.

Parent topic: Terminal Services
Related concepts
Citrix XenApp Support


Citrix Web Interface

Select Citrix Web Interface to test a Citrix application that is launched from a Citrix Web Interface running within Internet Explorer.

Parent topic: Terminal Services
Related concepts
Citrix XenApp Support


Citrix StoreFront/Netscaler Gateway

Select Citrix StoreFront/Netscaler Gateway to test a Citrix application that is launched from a Citrix StoreFront server.

Parent topic: Terminal Services


.NET

Select one of the .NET application types to test Web Services, .NET Remoting objects, NUnit, or another .NET technology.

  • .NET Explorer
    Select .NET Explorer to test Web services, .NET Remoting objects, and other .NET components.
  • .NET Framework Using Visual Studio .NET Add-On
    Select .NET Framework using Visual Studio .NET Add-On to test Web Services or .NET components using the Silk Performer Add-On for Visual Studio .NET.
Parent topic: Available Application Types
Related concepts
.NET Support


.NET Framework Using Visual Studio .NET Add-On

Select .NET Framework using Visual Studio .NET Add-On to test Web Services or .NET components using the Silk Performer Add-On for Visual Studio .NET.

Parent topic: .NET
Related concepts
Silk Performer Visual Studio Extension


Java

Select one of the Java application types to test Web Services, RMI, JUnit, or other Java-based technologies.

  • Java RMI/EJB (recording)
    Select Java RMI/EJB (recording) to test an application developed using Enterprise JavaBeans.
  • Java Explorer
    Select Java Explorer to test Web Services, Enterprise JavaBeans (EJB), RMI objects, and other GUI-less Java objects.
  • Java Framework
    Select Java Framework to test a Java application using the Silk Performer Java Framework.
  • Java Message Service (JMS)
    Select Java Message Service (JMS) to test Java Message oriented middleware applications by replaying the created script.
Parent topic: Available Application Types
Related concepts
Java Testing Support


Java RMI/EJB (recording)

Select Java RMI/EJB (recording) to test an application developed using Enterprise JavaBeans. This application type enables you to use Silk Performer's record and replay workflow.

Parent topic: Java
Related concepts
Java RMI Support
Working with Enterprise JavaBeans


Java Framework

Select Java Framework to test a Java application using the Silk Performer Java Framework.

The Java Framework enables you to implement user behavior in Java. When testing an existing Java application you do not need to spend much time creating test scripts. The only effort required is embedding existing Java source code into the framework.

Parent topic: Java
Related concepts
Java Framework Developer Guide


Java Message Service (JMS)

Select Java Message Service (JMS) to test Java Message oriented middleware applications by replaying the created script.

Parent topic: Java


Frameworks

Select one of the included frameworks to test an application using either the Java Framework, Visual Basic Framework, or .NET Framework Using Visual Studio .NET.

  • .NET Framework Using Visual Studio .NET Add-On
    Select .NET Framework using Visual Studio .NET Add-On to test Web Services or .NET components using the Silk Performer Add-On for Visual Studio .NET.
  • Java
    Select Java to test a Java application using the Silk Performer Java Framework.
Parent topic: Available Application Types
Related concepts
.NET Framework Support
Java Framework Support


.NET Framework Using Visual Studio .NET Add-On

Select .NET Framework using Visual Studio .NET Add-On to test Web Services or .NET components using the Silk Performer Add-On for Visual Studio .NET.

Parent topic: Frameworks
Related concepts
The .NET Framework Approach


Java

Select Java to test a Java application using the Silk Performer Java Framework.

The Java Framework enables you to implement user behavior in Java. When testing an existing Java application you do not need to spend much time creating test scripts. The only effort required is embedding existing Java source code into the framework.

Parent topic: Frameworks
Related concepts
Java Testing Support


Monitoring

Select a Monitoring application type to generate server-side results that can be archived for future viewing and comparison. Monitoring also reveals, locates, and resolves server bottlenecks, allowing you to examine the performance of operating systems and application servers.

  • Silk Performance Manager - Infrastructure Monitor
    Select Silk Performance Manager - Infrastructure Monitor to create an infrastructure monitoring project that can be uploaded to Performance Manager for automated execution.
  • BDL Monitor for Performance Explorer
    Select BDL Monitor for Performance Explorer to create a BDL monitoring project that can be used for real-time monitoring in Performance Explorer.
Parent topic: Available Application Types
Related concepts
Monitoring Load Tests


Silk Performance Manager - Infrastructure Monitor

Select Silk Performance Manager - Infrastructure Monitor to create an infrastructure monitoring project that can be uploaded to Performance Manager for automated execution.

Parent topic: Monitoring


BDL Monitor for Performance Explorer

Select BDL Monitor for Performance Explorer to create a BDL monitoring project that can be used for real-time monitoring in Performance Explorer.

Parent topic: Monitoring


Unit Testing

Select a Unit Testing application type to perform JUnit, Java, NUnit, or .NET unit testing.

  • JUnit
    Select JUnit to perform JUnit unit testing.
  • Java Testing
    Select Java Testing to import a Java class and test its methods using the Java Framework.
  • NUnit
    Select NUnit to perform NUnit unit testing.
  • .NET Testing
    Select .NET Testing to import a .NET assembly and test its methods using the .NET Framework.
Parent topic: Available Application Types
Related concepts
JUnit Integration
NUnit Integration


JUnit

Select JUnit to perform JUnit unit testing.

The Silk Performer Unit Test Import tool allows you to select specific test methods and automatically generate BDL stub code.

Parent topic: Unit Testing
Related concepts
JUnit Integration


Java Testing

Select Java Testing to import a Java class and test its methods using the Java Framework.

Parent topic: Unit Testing
Related concepts
Java Testing Support


NUnit

Select NUnit to perform NUnit unit testing.

The Silk Performer Unit Test Import tool allows you to select specific test methods and automatically generate BDL stub code.

Parent topic: Unit Testing
Related concepts
NUnit Integration


.NET Testing

Select .NET Testing to import a .NET assembly and test its methods using the .NET Framework.

Parent topic: Unit Testing
Related concepts
.NET Support


GUI-Level Testing

GUI-Level application types are used for the load testing of client applications that cannot be tested on the protocol or API levels. Silk Performer controls the actual client's user interface (fat client) through Silk Test (Silk Test Classic, UFT Developer (Silk4J), or UFT Developer (Silk4NET)). During a load test, each virtual user operates in its own Windows session, using Terminal Services.

  • Silk Test
    Select Silk Test to perform GUI-level testing against client applications that cannot be tested on the protocol or API levels.
Parent topic: Available Application Types
Related concepts
GUI-Level Testing Support


Silk Test

Select Silk Test to perform GUI-level testing against client applications that cannot be tested on the protocol or API levels. Silk Performer controls the actual client's user interface (fat client) through Silk Test (Silk Test Classic, UFT Developer (Silk4J), and UFT Developer (Silk4NET)). During a load test, each virtual user operates in its own Windows session, using Terminal Services.

Parent topic: GUI-Level Testing
Related concepts
Silk Test Automation Functions Overview


Legacy

The legacy group contains project types offered in earlier versions of Silk Performer. These project types have been declared obsolete or replaced by other project types, which offer new or better capabilities. To ensure backward compatibility, some of these legacy project types are still available.

  • Legacy Web business transaction (HTML/HTTP)
    Select Legacy Web business transaction (HTML/HTTP) to test web applications without capturing the traffic during recording.
Parent topic: Available Application Types


Legacy Web business transaction (HTML/HTTP)

Select Legacy Web business transaction (HTML/HTTP) to test web applications without capturing the traffic during recording. A script is generated instantaneously, which means that it is not possible to regenerate the script with different settings later on.

Parent topic: Legacy


Samples

Select one of these preconfigured test script Samples to save time in the manual creation of your test script.

Sample script reuse is a timesaving option for generating Silk Performer test scripts manually (and bypassing the standard method, which uses the Silk Performer Recorder).

Sample project files include scripts, include files, data files, profile files, workload definitions, and more.

  • Internet
    Select an Internet sample if you plan to manually write a script to test cookies, POP3/SMTP, HTML forms, and more.
  • Java Framework
    Select a sample Java Framework application type to set up a JDBC, RMI, or RMI/IIOP test project that uses the Silk Performer Java Framework.
  • .NET
    Select a .NET application type to set up a simple .NET Remoting or Web services testing project that uses the Silk Performer .NET Framework.
  • JMS
    Select JMS to set up a project that shows you how to make use of Silk Performer JMS API functions for configuring, sending, and receiving messages.
  • ShopIt v6.0
    Select ShopIt v6.0 to set up a project that demonstrates usage of the Silk Performer sample Web e-commerce site.
  • XML
    Select XML to set up a project that shows you how to make use of Silk Performer XML API functions for reading, writing, and modifying XML documents.
Parent topic: Available Application Types
Related concepts
Sample Scripts


Internet

Select an Internet sample if you plan to manually write a script to test cookies, POP3/SMTP, HTML forms, and more.

  • Recording Rule with Custom Conversion DLL
    Select Recording Rule with Custom Conversion DLL to generate a Web project that shows you how to use custom conversion DLLs in recording rules.
  • Cookies
    Select Cookies to set up a sample project that demonstrates cookie support.
  • Email
    Select Email to set up a testing project that simulates POP3 and SMTP email clients.
  • Form-based File Upload
    Select Form-based File Upload to create a testing project for HTML-based file upload functionality.
  • FTP
    Select FTP to set up a generic preconfigured FTP testing project.
  • LDAP
    Select LDAP to set up a generic preconfigured LDAP testing project.
  • MAPI
    Select MAPI to setup a testing project that simulates a basic MAPI session.
Parent topic: Samples
Related concepts
Internet


Recording Rule with Custom Conversion DLL

Select Recording Rule with Custom Conversion DLL to generate a Web project that shows you how to use custom conversion DLLs in recording rules. This is useful when parsed output data requires transformation in order to serve as input for a subsequent operation.

Parent topic: Internet
Related concepts
CallConversionFunction Function
Conversion Functions


Cookies

Select Cookies to set up a sample project that demonstrates cookie support.

Before you can replay the sample WebCookie01.bdf, please fulfill the following prerequisites:

  1. Access to a Web server with Active Server Pages.
  2. Copy the file cookie_counter.asp to the Web root of your Web server.
Parent topic: Internet
Related concepts
Cookies


Email

Select Email to set up a testing project that simulates POP3 and SMTP email clients.

Parent topic: Internet
Related concepts
POP3 Functions Reference


Form-based File Upload

Select Form-based File Upload to create a testing project for HTML-based file upload functionality.

Parent topic: Internet
Related concepts
Page-Level Web Functions Overview


FTP

Select FTP to set up a generic preconfigured FTP testing project.

Parent topic: Internet
Related concepts
FTP Functions Reference


LDAP

Select LDAP to set up a generic preconfigured LDAP testing project.

Parent topic: Internet
Related concepts
LDAP Functions Reference


MAPI

Select MAPI to setup a testing project that simulates a basic MAPI session.

Parent topic: Internet
Related concepts
MAPI Functions Reference


Java Framework

Select a sample Java Framework application type to set up a JDBC, RMI, or RMI/IIOP test project that uses the Silk Performer Java Framework.

  • JDBC
    Select JDBC to set up a sample project that implements a simple JDBC client using the Silk Performer Java Framework.
  • RMI/IIOP
    Select RMI/IIOP to set up a sample project that invokes methods of a virtual user class using the Silk Performer Java Framework.
  • RMI
    Select RMI to set up a sample project that invokes methods of a virtual user class using the Silk Performer Java Framework.
Parent topic: Samples
Related concepts
Java Framework Developer Guide


JDBC

Select JDBC to set up a sample project that implements a simple JDBC client using the Silk Performer Java Framework.

The sample uses the JDBC THIN driver to execute a query that is specified in the associated BDL script. Before you run the sample, configure the Java runtime and compiler profile settings and add the jarfile of the JDBC THIN driver to the classpath.

Parent topic: Java Framework
Related concepts
Java Sample Projects


RMI/IIOP

Select RMI/IIOP to set up a sample project that invokes methods of a virtual user class using the Silk Performer Java Framework.

The sample invokes methods of a virtual user class implemented in ProductManagerServicesUser.java.

Parent topic: Java Framework
Related concepts
Java RMI Support
Java Sample Projects


RMI

Select RMI to set up a sample project that invokes methods of a virtual user class implemented in ServiceHelloUser.java. The RMI service is defined in ServiceHello.java and is implemented in ServiceHelloImpl.java.

Parent topic: Java Framework
Related concepts
Java RMI Support
Java Sample Projects


.NET

Select a .NET application type to set up a simple .NET Remoting or Web services testing project that uses the Silk Performer .NET Framework.

  • .NET Remoting
    Select .NET Remoting to setup a sample project that shows how to test .NET Remoting with the Silk Performer .NET Framework.
  • Web Services
    Select Web Services to set up a sample project that shows how to test SOAP Web Services with the Silk Performer .NET Framework.
Parent topic: Samples
Related concepts
.NET Support


.NET Remoting

Select .NET Remoting to setup a sample project that shows how to test .NET Remoting with the Silk Performer .NET Framework.

The sample tests remote objects that are hosted by a sample remote server (RemotingServApp.exe).

Parent topic: .NET
Related concepts
Testing Web Services and .NET Remoting Objects with .NET Framework


Web Services

Select Web Services to set up a sample project that shows how to test SOAP Web Services with the Silk Performer .NET Framework.

The sample tests an ASP.NET Web Service on a demo server.

Parent topic: .NET
Related concepts
Testing Web Services and .NET Remoting Objects with .NET Framework


JMS

Select JMS to set up a project that shows you how to make use of Silk Performer JMS API functions for configuring, sending, and receiving messages.

Parent topic: Samples


ShopIt v6.0

Select ShopIt v6.0 to set up a project that demonstrates usage of the Silk Performer sample Web e-commerce site.

ShopIt V 6.0 simulates a simple Web e-commerce site with a catalog of camping merchandise that is available for simulated online purchase. Use this application to experiment with Silk Performer Web-application capabilities. ShopIt V 6.0 is designed to generate errors, including missing Web links (due to merchandise being out of stock) and session errors.

Parent topic: Samples
Related concepts
Sample Classic Web Application


XML

Select XML to set up a project that shows you how to make use of Silk Performer XML API functions for reading, writing, and modifying XML documents.

Parent topic: Samples
Related concepts
Working With XML Applications - Overview


Project Profile Settings

When a project is set up, profiles can be added, copied, renamed, or deleted. A project can contain as many different profiles as necessary, each with its own project-specific settings.

In each profile, options can be set to manage how the Silk Performer Recorder generates scripts from recorded traffic. Options can also be set for the protocols that are used during recording, and simulation settings can be defined for script replay. Options for the results files that are generated can also be defined.

Options are available for the following types of network traffic:

  • Citrix
  • CORBA/IIOP
  • Database
  • Internet
  • Java
  • Jolt
  • .NET
  • Oracle Forms
  • TUXEDO
  • Web

Specified settings are associated with specific load test projects. It is easy to switch between different projects, edit projects, and save projects so that they can be modified and reused later.

  • Profile Administration
    Manage your project-setting profiles and apply them to your projects.
  • Recorder Settings
    Configure general script-recording settings and protocol-specific settings for your project.
  • Replay Settings
    Configure script-replay settings for your project such as workload simulation and error handling.
  • Result-File Settings
    Configure result-file settings for your project, including TrueLog, time-series data, client-side monitoring options, and logging.
  • Internet Settings
    Configure Internet-related settings for your project, including network simulation, host-server, security, and recording options.
  • Web (Protocol Level) Settings
    Configure Web-related settings for your project, including browser, proxy, recording, and verification options.
  • Setting Terminal Client Options
    Configure terminal-client profile settings related to Telnet, command prompts, default screens, and more, before recording IBM mainframe or VT 100+ applications.
  • Setting GUI-Level Testing Options
    Configure GUI-level testing settings related to console sessions, connection time-outs, execution time-outs, and more.
  • Setting Oracle Forms Options
    Configure Oracle Forms settings, including connection mode and the enabling of timers and counters for controls.
  • Setting SAPGUI Options
    Configure SAPGUI settings, including counters/timers, log level, and screenshots.
  • Configuring Citrix XenApp Options
    Configure Citrix settings, including window-position, mouse-speed, and think-time options to set up a Citrix test.
  • Setting .NET Options
    Configure .NET settings, including HTTP .NET- and SOAP-traffic routing options.
  • CORBA/IIOP Settings
    Configure CORBA/IIOP options, including recording, replay, and WChar/WString settings.
  • Java Settings
    Configure Java settings, including classpath, version, JVM, JIT compiler, and logging options.
  • Database Settings
    Configure database settings, including SQL, ODBC, and recording options.
Parent topic: Outlining Projects
Related tasks
Configuring Silk Performer Project Settings in Eclipse


Profile Administration

Manage your project-setting profiles and apply them to your projects.

  • Adding a Profile
    Create a new project-settings profile for your load test project.
  • Activating a Profile
    Select the settings profile that you want to apply to your project.
  • Editing a Profile
    Reconfigure your project's recording, replay-simulation, or result-output settings.
  • Renaming a Profile
    Rename your project's settings profile.
  • Deleting a Profile
    Delete a settings profile from your project.
  • Copying a Profile
    Copy an existing project-settings profile to use it as the basis for a new profile.
Parent topic: Project Profile Settings


Adding a Profile

  1. Select Project > New Profile . The New Profile dialog opens.
  2. Enter a Name for the new profile and click OK. The Profiles folder expands in the Project menu tree and the new profile is available.
Parent topic: Profile Administration


Activating a Profile

In the Project menu tree, right-click the profile that you want to set as the active profile and choose Set as Active Profile.

The active profile is displayed in bold text.

Parent topic: Profile Administration


Editing a Profile

  1. In Silk Performer, expand the Profiles node in the Project tree.
  2. Right-click the profile that you want to configure and choose Edit Profile.
    Tip: Alternatively, you can choose Settings > Active Profile from the menu bar.

    The Profile - [<profile name>] dialog box opens, and the Replay category is displayed in the shortcut list on the left.

  3. Edit the settings as required. For help on editing settings, see help topics related to the application type under test.
  4. Click OK to exit the dialog and save your changes.
Parent topic: Profile Administration
Related concepts
Project Profile Settings


Renaming a Profile

  1. In the Project menu tree, right-click the profile that you want to rename.
  2. Choose Rename Profile. The Rename Profile dialog opens
  3. Type a new name for the profile.
  4. Click OK.
Parent topic: Profile Administration


Deleting a Profile

  1. In the Project menu tree, right-click the profile you want to delete.
  2. Select Delete Profile.
  3. Click Yes on the confirmation dialog to delete the profile.
Parent topic: Profile Administration


Copying a Profile

  1. In the Project menu tree, right-click the profile you want to copy.
  2. Select Copy Profile from the context menu. A new profile appears in the Project menu tree, with the name Copy of <profile name>.
Parent topic: Profile Administration


Recorder Settings

Configure general script-recording settings and protocol-specific settings for your project.

  • Setting General Recording Options
    Define general traffic-recording settings for your project before recording a test script.
  • Setting Protocol-Specific Options
    Define traffic-recording settings for projects of specific protocol types.
Parent topic: Project Profile Settings


Setting General Recording Options

  1. In Silk Performer, expand the Profiles node in the Project tree.
  2. Right-click the profile that you want to configure and choose Edit Profile.
    Tip: Alternatively, you can choose Settings > Active Profile from the menu bar.

    The Profile - [<profile name>] dialog box opens, and the Replay category is displayed in the shortcut list on the left.

  3. In the shortcut list on the left, click the Record button. The Record category is displayed.
  4. In the shortcut list on the left, click the Script icon.
  5. Click the General tab and check the Comments check box. The Silk Performer Recorder automatically inserts comments into the generated script. Comments are left-delimited statements that use // symbols.
  6. Check the Commented functions check box to mark the function calls that are performed to retrieve return parameters as comments in the recorded script.
  7. Check the Include think time check box to generate ThinkTime function calls in the recorded script. The ThinkTime function calls produce delays that simulate typing time and thinking time in the recorded script to create a more realistic simulation.
  8. In the Min. think time recorded text box, type a time in milliseconds to define a lower limit for delays. This limit is included as ThinkTime function calls in the recorded script. Delays less than the time specified in the Min. think time recorded text box are not expanded to ThinkTime function calls.
  9. In the Max. line length text box, specify the maximum number of characters in a script line. Use this setting to split large amounts of recorded data into several script lines.
  10. Optional: In the Script namespace text box, type a prefix for the names that are declared in the generated script.
    The user groups, transactions, and variables defined in the script begin with the specified string.
  11. Check the Record passwords encrypted check box to make the recorder automatically encrypt recorded passwords before inserting them into generated scripts.
  12. Click OK to save your settings.
Parent topic: Recorder Settings


Setting Protocol-Specific Options

  1. In Silk Performer, expand the Profiles node in the Project tree.
  2. Right-click the profile that you want to configure and choose Edit Profile.
    Tip: Alternatively, you can choose Settings > Active Profile from the menu bar.

    The Profile - [<profile name>] dialog box opens, and the Replay category is displayed in the shortcut list on the left.

  3. In the shortcut list on the left, click the Record button. The Record category is displayed.
  4. Click the Script icon.
  5. Click the Protocols tab.
  6. In the Web comments area of the page, specify details about automatically-inserted comments (for Web functions) in the generated script. The settings for these options are only taken into account when the Comments option (General tab) for script generation is enabled.
    Option | Description
    Redirection / Authentication | Have comments inserted into the generated script when a redirection (HTTP 302, HTTP 407) from one URL to another is recorded.
    HTTP errors | Have comments inserted into the generated script when HTTP errors (HTTP 4xx, HTTP 5xx) are recorded.
    Link, form, custom URL search details | Have comments inserted into the generated script when links, forms, or customs URLs are recorded.
    Detailed info for form fields

    Have comments inserted into the generated script when hidden, changed, or filled out form fields are recorded.

    Note: If this option is not selected, comments for form fields are still recorded, but the additional detailed information (for example, if value is changed or unchanged) is not.
    Custom URL parsing details | Have comments inserted into the generated script when parsing details of custom URLs are recorded.
  7. In the IIOP area of the page, check the Generate IIOP Get functions check box to include functions in your test script that will retrieve the return parameters of CORBA operation calls. You can mark the corresponding function calls as comments. Use the Database area of the page to specify how SQL statements are displayed and whether to include fetched data in the generated test script.
  8. Check the SQL comment check box to include SQL statements marked as comments in the generated test script immediately before the parse operation.
  9. Check the Trim SQL check box to display SQL statements in the generated test script in a more readable format, with line breaks and indentation for SQL keywords.
  10. Check the Fetched data check box to include the fetched data, marked as comments, in the generated test script immediately after the fetch operation.
  11. In the Max. number of rows text box, enter the maximum number of data rows that are to be inserted as comments immediately after fetch operations.
  12. In the Max. column width text box, enter the maximum width of columns inserted as commentary.
  13. Click OK to save your settings.
Parent topic: Recorder Settings


Replay Settings

Configure script-replay settings for your project such as workload simulation and error handling.

  • Configuring Simulation Settings
    Configure project-profile simulation settings for script replay, including think-time and workload options.
  • Configuring Error-Handling Settings
    Configure error-handling settings for your project, including error codes and error descriptions, to customize how your test should handle specific error situations.
Parent topic: Project Profile Settings


Configuring Simulation Settings

  1. In Silk Performer, expand the Profiles node in the Project tree.
  2. Right-click the profile that you want to configure and choose Edit Profile.
    Tip: Alternatively, you can choose Settings > Active Profile from the menu bar.

    The Profile - [<profile name>] dialog box opens, and the Replay category is displayed in the shortcut list on the left.

  3. In the Simulation tab, check the Stress test check box to disable the use of wait periods that are specified in low-level web functions or invoked by calling think-time functions.
  4. Check the Random thinking time check box to replace recorded actual thinking periods that are specified in low-level web functions or invoked by calling think-time functions, with random values that follow an exponential distribution.
    • Exponential distribution - Click this option to replace recorded think-time periods that are specified in Web functions, or invoked by calling the ThinkTime function, with random values that follow an exponential distribution. Due to the nature of exponential distribution, extreme random think-time periods can result. Refer to the SetRandomThinkTime BDL function for more details.
    • Uniform distribution of +/- [] % - Click this option to replace recorded think-time periods that are specified in Web functions, or invoked by calling the ThinkTime function, with random values that follow a uniform distribution within a specified range. Use uniform distribution when extreme think times are undesirable. Refer to the SetRandomThinkTime BDL function for more details.
  5. Check the Think time limited to check box to define a limit for think times. When this option is selected, think times are limited to the specified maximum value. Enter an upper limit (in seconds).
  6. Check the Smooth transaction arrival rate (Queuing Workload) check box to have each virtual user perform its transactions within the specified simulation interval. With this option selected, the simulation time period and the total number of transactions to be called determine the mean arrival interval of the transactions. When this option is disabled, Silk Performer calculates the delay of each transaction arrival randomly.
    Note: This setting does not affect projects that are used for application monitoring.
  7. Check the Choose transactions randomly check box to force the simulation engine to execute all transactions defined in load-test scripts in random order, based on the queuing workload model. When this option is disabled, simulated virtual users perform their transactions exactly in the order in which they are defined in load-test scripts.
  8. Check the Stop virtual users after simulation time (Queuing Workload) check box to cancel users when simulation time expires.
    Note: This setting does not affect projects that are used for application monitoring.
  9. Check the Call end transactions for stopped virtual users check box to have stopped virtual users execute end transactions before stopping. When this option is disabled, virtual users complete their executions without calling end transactions.
  10. Check the Complete current transactions of stopped virtual users check box to allow stopped virtual users to complete active transactions before stopping. When this option is selected, virtual users check to see if they should stop at the beginning of each new transaction. Thus active transactions are completed before users stop. When this option is disabled, virtual users check during think and wait times, while in the queue, and at the beginning of each transaction to see if they should stop.
  11. Check the Stop virtual users when errors occur in begin transactions check box to immediately stop virtual users when errors occur during test initialization (which usually occurs in begin transactions). This setting overrides the Call end transactions for stopped virtual users and Complete current transactions of stopped virtual users options. This setting is useful for tests that involve connect operations that must be successful before tests can proceed.
  12. Click OK to save your settings.
Parent topic: Replay Settings
Related reference
SetRandomThinkTime Function


Configuring Error-Handling Settings

  1. In Silk Performer, expand the Profiles node in the Project tree.
  2. Right-click the profile that you want to configure and choose Edit Profile.
    Tip: Alternatively, you can choose Settings > Active Profile from the menu bar.

    The Profile - [<profile name>] dialog box opens, and the Replay category is displayed in the shortcut list on the left.

  3. Click the Errors tab.
  4. Use the Severity definition area to modify the severity of the simulation errors that Silk Performer reports in its Monitor window.
  5. Click Add to add a custom severity definition to the list.

    The Edit Replay Errors and Warnings dialog box opens.

  6. From the Module list box, select the module that might cause the simulation error for which you want to define a custom level of severity.
  7. From the Severity list box, select one of the following default severities of the error for which you want to define a custom level of severity.
    Severity | Description
    Success | Error is ignored
    Informational | Error is ignored but reported
    Warning | Error is ignored but generates a warning
    Error | Error is treated as an error
    All errors of the selected severity are displayed in the list box below.
  8. In the Error code text box, type the code of the error for which you want to define a custom level of severity. Alternatively, you can select the respective error from the list located above the text box.
  9. In the Description text box, type a description for native errors. Descriptions of other simulation errors are predefined and cannot be modified by the user.
  10. From the Custom severity list box, select one of the following custom severities for the specified error.
    Severity | Description
    Success | Error is ignored.
    Informational | Error is ignored, but reported.
    Warning | Error is ignored, but causes a warning.
    Error | Error is reported, but does not affect the simulation.
    Transaction exit | Current transaction is aborted.
    Process exit | User simulation is terminated.
  11. Click OK.
  12. To edit the custom severity of an error, select it from the Severity definition list box and click Edit. The Edit Replay Errors and Warnings dialog box opens.
  13. Edit the custom severity of the error as explained earlier in this task.
  14. To remove a custom severity definition from the list, select it from the Severity definition list box and click Remove.
  15. Click OK to save your changes and close the dialog box.
Parent topic: Replay Settings


Result-File Settings

Configure result-file settings for your project, including TrueLog, time-series data, client-side monitoring options, and logging.

  • Setting General Result Options
    Specify the output-file types you want your project to generate, including time-series data and log files.
  • Setting Time-Series Data Options
    Specify the types of time-series data that you want your project to generate, including computation intervals and overview reports.
  • Setting Monitoring Options
    Configure a monitoring template to define your project's replay monitoring needs.
  • Setting TrueLog Traffic-Capturing Options
    Configure how and when server-traffic data should be captured during script recording and replay.
  • Setting General Logging Options
    Define the data types you want to have logged when scripts are run, including timers, transactions, and function-call data.
  • Setting Internet-Specific Logging Options
    Define the Internet-specific data types you want to have logged when scripts are run, including HTTP-header, Java classes, and TCP/IP data.
  • Setting Hook Logging Options for the Recorder
    Configure logging options for the Silk Performer Recorder.
  • Enabling Real-Time Client-Side Monitoring
    Enable real-time client-side measures, the results of which can be analyzed with Performance Explorer.
Parent topic: Project Profile Settings


Setting General Result Options

  1. In Silk Performer, expand the Profiles node in the Project tree.
  2. Right-click the profile that you want to configure and choose Edit Profile.
    Tip: Alternatively, you can choose Settings > Active Profile from the menu bar.

    The Profile - [<profile name>] dialog box opens, and the Replay category is displayed in the shortcut list on the left.

  3. In the shortcut list, click the Results icon.
  4. Click the General tab. Use the Results files area to specify the types of result files you want to generate. While a test runs, a separate file is created for each virtual user in the current agent. Since generating results files alters the time measures of tests, these files should only be created for debugging purposes.
    • Check the Virtual user log files (.log) check box to generate log files (.log), one for each virtual user in the current agent. These files contain all the function calls that are invoked by the transactions of a specific user.
    • Check the Virtual user report files (.rpt) check box to generate report files (.rpt), one for each virtual user in the current agent. These files contain simulation results for each user.
    • Check the Virtual user output files (.wrt) check box to generate output files (.wrt), one for each virtual user in the current agent. These files contain the output of write statements used in the test script. An output file is generated for a particular user only if that user executes write statements.
    • Check the Virtual user report on error files (.rpt) check box to generate report on error files (.rpt) and error files (.err) for each virtual user only when an error (a specific severity level) occurs. These files contain the simulation results for each virtual user.
    • Check the Time series data (.tsd) check box to enable generation of throughput information (viewable via Performance Explorer). You can specify the interval at which data is computed. This setting does not affect projects that are used for application monitoring.
    • Check the Client-side measures in real-time check box to enable Silk Performer to retrieve real-time client-side measurements for use in Performance Explorer .
      Note: This option applies only to the current profile.
  5. In the Passwords area, select the Hide passwords in logs check box to ensure that characters are hidden when entered into password fields of HTML forms, and are replaced with asterisks ( * ) in recording and replay log files (*.xlg and *.log).
    Note: This feature is only supported for the Web business transaction (HTML/HTTP) project application type when the browser emulation level Page-level Web API (HTML/HTTP) is enabled, which is the default for this application type.
  6. Check the Add transaction name and an identifier to measure names check box to add the transaction name and an identifier as a prefix to measure names. This setting applies to all measure types beside transaction timers. Enabling this setting facilitates the navigation between reports and scripts as reports contain measures in the order that they appear in the script.
  7. Click OK to save your settings.
Parent topic: Result-File Settings
Related tasks
Configuring Load Test Monitoring


Setting Time-Series Data Options

  1. In Silk Performer, expand the Profiles node in the Project tree.
  2. Right-click the profile that you want to configure and choose Edit Profile.
    Tip: Alternatively, you can choose Settings > Active Profile from the menu bar.

    The Profile - [<profile name>] dialog box opens, and the Replay category is displayed in the shortcut list on the left.

  3. In the shortcut list, click the Results icon.
  4. Click the Time Series tab.
  5. From the Computation interval list box, select the interval at which you want data to be calculated. This setting is used for all generated time-series data. Keep in mind that the shorter the interval and the longer the test, the more data that will be generated.
  6. Check the Enable all measure groups check box to generate high-level throughput information for all the measure groups shown in the list below. To choose a particular combination of measure groups for which you want to generate high-level throughput information, uncheck the Enable all measure groups check box, and select your options in the measure group list.
  7. Specify a Detailed page timers generation setting. Choices include:
    • For the whole page
    • For documents only
    • Disabled
  8. To define an overview report template for generating overview reports with Silk Performance Explorer for this testing project, click [...] on the Overview report template portion of the Time Series page.
    1. From the Select Template File dialog box, select the overview report template (.ovt) file that you want to have applied to your project.
    2. Click Open.
    The file that you specify here will be used as an overview report template for the generation of all overview reports for this testing project. The template file name will also be preselected on the Overview Report Template workflow dialog box when new overview reports are created manually.
  9. Click OK to save your settings.
Parent topic: Result-File Settings


Setting Monitoring Options

Silk Performer enables you to define monitoring templates for your projects and to configure projects to automatically launch Performance Explorer when load tests begin.

  1. In Silk Performer, expand the Profiles node in the Project tree.
  2. Right-click the profile that you want to configure and choose Edit Profile.
    Tip: Alternatively, you can choose Settings > Active Profile from the menu bar.

    The Profile - [<profile name>] dialog box opens, and the Replay category is displayed in the shortcut list on the left.

  3. In the shortcut list, click the Results icon.
  4. Click the Monitoring tab.
  5. In the Monitoring options area, check the Automatically start monitoring check box to automatically launch Silk Performer's monitoring facility when the test starts.
  6. To automatically use the monitoring template that best suits the project, click the Use default monitoring template option button. For example, if you are creating a Web project, the template specifies the measurements that are useful for Web load tests.
  7. To use a custom monitor template, click the Use custom monitoring template option button and perform one of the following steps:
    • Type the name of the custom template file (.pew) that you want to use to monitor your server. Silk Performer creates a copy of the standard monitor template.
    • Click the folder icon in the name field to select an existing monitoring template.
  8. Optional: Click Edit Custom Monitor Template to add or remove any monitoring performance data. When you click this button, Silk Performance Explorer opens. Perform the following steps:
    1. Add or remove any monitoring performance data.
    2. Save the Silk Performance Explorer workspace to apply your changes to the template.
  9. In the Performance Monitor integration area, check the Compute online performance data check box to compute data for additional performance measurements to be displayed in the Windows Performance Monitor. You can use this data to view concurrent users, transaction throughput, sent and received data, and executed SQL statements.
  10. Click OK to save your settings.
When you perform a test, Silk Performer displays the server performance data that is relevant to the type of server under test.
Parent topic: Result-File Settings


Setting TrueLog Traffic-Capturing Options

  1. In Silk Performer, expand the Profiles node in the Project tree.
  2. Right-click the profile that you want to configure and choose Edit Profile.
    Tip: Alternatively, you can choose Settings > Active Profile from the menu bar.

    The Profile - [<profile name>] dialog box opens, and the Replay category is displayed in the shortcut list on the left.

  3. In the shortcut list, click the Results icon.
  4. Click the TrueLog tab.
  5. To enable generation of TrueLog files (.xlg) during recording, check the TrueLog files (.record.xlg) check box. TrueLog files contain all traffic that is sent to and received from the server, and the transactions and function calls that are to be generated in the test script.
    Note: TrueLog files should only be created for debugging purposes.
  6. Check the TrueLog files (.xlg) check box to generate a TrueLog file (.xlg) for each virtual user. These files contain all the function calls that are invoked by the transactions of a specific virtual user.
  7. To enable generation of TrueLog On Error files (.xlg), check the TrueLog On Error files (.xlg) check box.
    Note: Truelog On Error files can be turned on for even large tests where you expect a moderate number of errors without major impact on replay performance.
  8. Specify how much information is to be stored in the TrueLog using the Store TrueLog options. The options in the TrueLog On Error area of the dialog box are only available when TrueLog On Error file generation has been enabled above.
    • Click the For one transaction option button to log the entire transaction in which each error occurs. This option requires a significant amount of memory.
    • Click the Based on content history option button to log a minimum of relevant data (based on data kept in the history) to the TrueLog. If low-level web calls are used, this setting will have no impact on the size of stored data. This selection requires minimal memory.
  9. From the Generate TrueLog On Error for list box, select the severity level at which TrueLogs are to be generated (Errors, Severe errors, or Warnings). The default severity level is Errors.
  10. Click the Log all embedded objects option button to log all embedded objects (images, java files, etc) in the TrueLog. Logged objects appear in the cached documents section of the TrueLog.
  11. Click the Exclude cached embedded objects option button to only log embedded objects (images, java files, etc) that have been downloaded within the scope of the current log in the TrueLog. Objects may not be logged if they appear in the current log as a cache hit. Such objects may have been downloaded outside the scope of the current log. They may also no longer be present in the cache.
  12. Click the Exclude all embedded objects option button to exclude all embedded objects (images, java files, etc) from being logged in the TrueLog.
    Note: Optimal scalability is achieved by selecting this option.
  13. Click OK to save your settings.
Parent topic: Result-File Settings
Related reference
WebSetOption Function


Setting General Logging Options

  1. In Silk Performer, expand the Profiles node in the Project tree.
  2. Right-click the profile that you want to configure and choose Edit Profile.
    Tip: Alternatively, you can choose Settings > Active Profile from the menu bar.

    The Profile - [<profile name>] dialog box opens, and the Replay category is displayed in the shortcut list on the left.

  3. In the shortcut list, click the Results icon.
  4. Click the Logging tab.
  5. Check the Log all check box to include all available types of information in the generated log files. These files contain information about timers, transactions performed by the virtual user, and function calls invoked by the transactions. Keep in mind that creating log files can alter time measures.
  6. Use the General area to specify which types of data should be included in log files.
    • Check the Transactions check box to include an overview of the transactions the virtual user performs during the simulation.
    • Check the Timers check box to include custom timer information.
    • Check the API calls check box to include an overview of the Silk Performer API calls that the user performs during the simulation.
    • Check the Informational check box to include additional information, for example, connection information.
    • Check the Data check box to include the data that is exchanged with the server.
    • Check the Nonprintable characters check box to include nonprintable characters, represented as dots.
  7. Click OK to save your settings.
Parent topic: Result-File Settings


Setting Internet-Specific Logging Options

  1. In Silk Performer, expand the Profiles node in the Project tree.
  2. Right-click the profile that you want to configure and choose Edit Profile.
    Tip: Alternatively, you can choose Settings > Active Profile from the menu bar.

    The Profile - [<profile name>] dialog box opens, and the Replay category is displayed in the shortcut list on the left.

  3. In the shortcut list, click the Results icon.
  4. Click the Internet logging tab.
  5. Use the Data sent to server area to specify the level of detail at which data that Silk Performer and the Recorder send to the server are written to the log file.
    • Check the HTTP request header from client check box to write all client request headers that are sent to the server. This option is only available when recording HTTP traffic (not for replay).
    • Check the Header check box to write all the headers that are included in requests sent to the server.
    • Check the Printable data check box to write all printable data that is included in requests sent to the server.
    • Check the Binary data check box to write all the binary data that is included in requests sent to the server.
    • In the Max. number of lines text box, specify the maximum number of lines that can be written to the log file when lines containing request data are sent to the server.
  6. Use the Data received from server area to specify the level of detail at which the data that Silk Performer and the Recorder receive from the server is written to the log file.
    • Check the HTTP response header to client check box to write the client HTTP response headers (received from the server) to the log file. This option is only available when recording HTTP traffic (not for replay).
    • Check the Header check box to write all the headers that are included in responses received from the server.
    • Check the Printable data check box to write all the printable data included in responses that are received from the server.
    • Check the Binary data check box to write all binary data that is included in responses received from the server.
    • In the Max. number of lines text box, specify the maximum number of lines that can be written to the log file when lines containing response data are received from the server.
  7. Check the Images, applets, and Java classes check box to write all the images, applets, and Java classes that are received from the server. When this option is selected, these items are represented as binary data.
  8. Check the TCP/IP connection information check box to write additional information to the log file; for example, when connections to the server are established or closed.
  9. Click OK to save your settings.
Parent topic: Result-File Settings


Setting Hook Logging Options for the Recorder

  1. In Silk Performer, expand the Profiles node in the Project tree.
  2. Right-click the profile that you want to configure and choose Edit Profile.
    Tip: Alternatively, you can choose Settings > Active Profile from the menu bar.

    The Profile - [<profile name>] dialog box opens, and the Replay category is displayed in the shortcut list on the left.

  3. In the shortcut list on the left, click the Record button. The Record category is displayed.
  4. In the shortcut list, click the Results icon.
  5. Click the Hook logging tab.
  6. Use the Hooking area on the Silk Performer Recorder’s Log page to display all the function calls that the client application performs and the parameters that the client application passes to function calls.
    • Check the Function calls check box to display all the function calls that the client application performs.
    • Check the Function parameters check box to display all the parameters that the client application passes to function calls. To enable this option, you must first check the Function calls check box.
  7. Click OK to save your changes.
Parent topic: Result-File Settings


Enabling Real-Time Client-Side Monitoring

  1. In Silk Performer, expand the Profiles node in the Project tree.
  2. Right-click the profile that you want to configure and choose Edit Profile.
    Tip: Alternatively, you can choose Settings > Active Profile from the menu bar.

    The Profile - [<profile name>] dialog box opens, and the Replay category is displayed in the shortcut list on the left.

  3. Click the Results group icon.
  4. Click the General tab.
  5. Ensure that the Client-side measures in real-time check box is selected.
  6. Click the Client-side measures tab. You may have to use the buttons in the upper right-hand corner of the dialog box to scroll through the available tabs.
  7. Set the Computation interval to 5 sec.
  8. Check the Enable all measure groups check box to enable monitoring of all measure groups. Alternatively, you can check specific measure types from the list.
  9. Click OK to save your settings.
Parent topic: Result-File Settings


Internet Settings

Configure Internet-related settings for your project, including network simulation, host-server, security, and recording options.

  • Configuring Network Optimization Settings
    Configure simulation settings for virtual-user network environments.
  • Configuring Network Emulation Settings
    Emulate networks according to your specific needs by configuring values for bandwidth, latency, and packet drop rate.
  • Configuring Host Server Settings
    Specify the IP address and port settings of the host server if the data traffic in a test should be routed through a specific server, for example to negotiate a firewall.
  • Configuring Security Settings
    Configure security settings for the simulated network environment, including protocol, SSL, and encryption settings.
  • Configuring Recording Settings
    Configure recording settings for the simulated network environment, including SMTP and server-certificate settings.
Parent topic: Project Profile Settings


Configuring Network Optimization Settings

  1. In Silk Performer, expand the Profiles node in the Project tree.
  2. Right-click the profile that you want to configure and choose Edit Profile.
    Tip: Alternatively, you can choose Settings > Active Profile from the menu bar.

    The Profile - [<profile name>] dialog box opens, and the Replay category is displayed in the shortcut list on the left.

  3. In the shortcut list, click the Internet icon.
  4. Click the Optimization tab.
  5. From the Optimize network settings for list box, select the type of simulation for Silk Performer and WinSock buffers. This setting determines the size of the buffers that are used to transfer data both to and from the server. Large buffers provide good performance; however, Silk Performer needs more memory to achieve this performance. Small buffers may be useful on driver machines with less memory. Note that, when using modem simulation, small buffers create more realistic simulation.
  6. Check the Client IP address multiplexing check box to enable IP address multiplexing.
    Note: To assign individual IP addresses to virtual users, you first have to set up multiple IP addresses for the network device. You do this using the Silk Performer System Configuration Manager. Following that, you can assign each of the IP addresses to a different virtual user.
  7. Check the Passive FTP semantics check box to enable passive FTP semantics, which may be useful when connecting through firewalls or proxies. This option only affects FTP data transfers.
  8. In the Connect attempts text box, enter how often a simulated user is to attempt to connect to the server before an error is reported.
  9. In the Connect timeout text box, specify for how long a simulated user is to attempt to connect to the server before a timeout is reported.
  10. In the Send timeout text box, specify for how long the simulated user is to attempt to send data to the server before a timeout is reported.
  11. In the Receive timeout text box, specify for how long the simulated user is to attempt to receive data from the server before a timeout is reported.
  12. Click OK to save your settings.
Parent topic: Internet Settings


Configuring Network Emulation Settings

  1. In Silk Performer, expand the Profiles node in the Project tree.
  2. Right-click the profile that you want to configure and choose Edit Profile.
    Tip: Alternatively, you can choose Settings > Active Profile from the menu bar.

    The Profile - [<profile name>] dialog box opens, and the Replay category is displayed in the shortcut list on the left.

  3. In the shortcut list, click the Internet icon. The Emulation pane displays.
  4. Select a Connection Type: Mobile, Wired, or Wireless, and a specific technology (like LTE). Depending on your selection, Silk Performer will provide specific default values for the bandwidth, latency, and packet drop.
  5. Enable Use Network Emulation Driver only if the network emulation driver is installed on your agents. You can then adjust the Latency and Packet Drop settings to your needs. If the driver is not installed on your agents, do not enable this option. In such a case, the Latency and Packet Drop settings will not be used.
  6. Select a Distance To Server. Depending on your selection, the Latency changes.
  7. You can manually adjust the values for the settings Bandwidth Down, Bandwidth Up, Latency, and Packet Drop.
  8. You can click Reset to restore the default values for your selected connection type.
  9. You can click Default to completely restore all values on the Emulation pane.
  10. Click OK to save your settings.
Parent topic: Internet Settings


Configuring Host Server Settings

  1. In Silk Performer, expand the Profiles node in the Project tree.
  2. Right-click the profile that you want to configure and choose Edit Profile.
    Tip: Alternatively, you can choose Settings > Active Profile from the menu bar.

    The Profile - [<profile name>] dialog box opens, and the Replay category is displayed in the shortcut list on the left.

  3. In the shortcut list on the left, click the Internet icon.
  4. Click the Hosts tab.
  5. In the Standardhost area, specify the server you want to use as the standard host. You can use either a domain name or an IP address. The name you specify is used whenever the standardhost variable is included in test scripts. Optionally, you can use the Port text box to specify a port number to use with the standard host.
  6. In the SOCKS4 proxy area, use the Proxy name or IP address and Port text boxes to specify the host name or IP address as well as the port number of the SOCKS4 proxy through which all Internet traffic must be directed. Use this option when the traffic in a test must negotiate a firewall, for example.
  7. Click OK to save your settings.
Parent topic: Internet Settings


Configuring Security Settings

  1. In Silk Performer, expand the Profiles node in the Project tree.
  2. Right-click the profile that you want to configure and choose Edit Profile.
    Tip: Alternatively, you can choose Settings > Active Profile from the menu bar.

    The Profile - [<profile name>] dialog box opens, and the Replay category is displayed in the shortcut list on the left.

  3. In the shortcut list, click the Internet icon.
  4. Click the Security tab. Use the Protocol area to specify protocol-specific settings used for secure connections to remote servers.
  5. From the SSL version list box, select the Secure Socket Layer protocol version used when establishing a secure connection to the server.
  6. From the Encryption strength list box, select the encryption strength for data transferred to and from the server over a secure connection.
  7. From the Certificate list box in the Client certificate area, select the client certificate that Silk Performer is to present to the Web server on behalf of the actual client. To use a client certificate, you must first export it from the Web browser and place it in Silk Performer's certificate store.
  8. To view detailed information about the client certificate currently in use, click View.
  9. To import a new client certificate from a certificate file (.p12 or .pfx), click Import.
    1. Use the Open Certificate dialog box to navigate to and select the new client certificate.
    2. Click OK.
  10. To remove the currently selected client certificate from the list box, click Remove.
  11. Check the Force secure connection check box to use the Secure Socket Layer protocol for script replay. This is equivalent, for example, to replacing all the HTTP schemes with HTTPS in the URLs of low-level web functions. It can be used to simplify how tests are used to compare performance with and without the use of secure connections.
  12. Click OK to save your settings.
Parent topic: Internet Settings


Configuring Recording Settings

  1. In Silk Performer, expand the Profiles node in the Project tree.
  2. Right-click the profile that you want to configure and choose Edit Profile.
    Tip: Alternatively, you can choose Settings > Active Profile from the menu bar.

    The Profile - [<profile name>] dialog box opens, and the Replay category is displayed in the shortcut list on the left.

  3. In the shortcut list, click the Internet icon.
  4. Click the Recording tab.
  5. In the SMTP area, check the Enable SMTP data recording check box to record mail body data exchanged between the client application and the mail server. To record SMTP traffic, set up an appropriate proxy connection using the Proxy page (Web settings).
  6. Use the Recorder server certificate area to specify which server certificate you want the Silk Performer Recorder to present to the client on behalf of the actual server.
  7. Check the Use custom server certificate check box to have the Recorder present a custom server certificate to the client instead of the default Recorder server certificate.
    1. Click [...] to the right of the field to locate the server certificate you want to use.
  8. In the Pass phrase text box, enter the pass phrase that is to be used, if the server certificate you want the Recorder to use is protected with a pass phrase.
  9. Check the Send root CA during SSL handshake check box to have the Recorder send the root CA certificate during the SSL handshake. The root CA certificate may be requested by a client to authenticate the certificate authority that signed the Recorder server certificate.
    1. Click [...] to the right of the field to locate the root CA certificate that you want to use.
  10. Click OK to save your settings.
Parent topic: Internet Settings
Related tasks
Configuring Proxy Settings


Web (Protocol Level) Settings

Configure Web-related settings for your project, including browser, proxy, recording, and verification options.

  • Configuring Browser Settings
    Configure browser settings for the simulated network environment, including concurrent connections and HTTP version.
  • Proxy Settings
    Proxy settings allow you to specify how Silk Performer connects to the Internet, directly or through a proxy server.
  • Configuring Browser-Simulation Settings
    Configure browser-simulation settings to create realistic simulation of virtual users visiting Web sites.
  • Setting Browser-Authentication Options
    Configure how virtual users are to enter their login credentials.
  • Setting Browser-Emulation Authentication Options
    Configure browser-emulation behavior as related to authentication, including cookies, browsing history, redirects, and DNS lookup.
  • Setting Browser-Recording Options
    Configure how Web traffic is recorded, including options for traffic level, HTTP headers, context management, and page detection.
  • Setting Verification Options
    Configure how replayed Web traffic should be verified against recorded Web traffic.
  • Setting HTTP-Body Transformation Options
    Configure how an HTTP body transformation should be applied: to HTTP request bodies, HTTP response bodies, or both.
  • Transformation of Custom Content Types and Encodings
    Explains how to customize transformation triggers if the default content types and content encodings do not trigger the compression transformation.
Parent topic: Project Profile Settings
Related tasks
Configuring Browser-Driven Recording Settings
Configuring Browser-Driven Replay Settings


Configuring Browser Settings

  1. In Silk Performer, expand the Profiles node in the Project tree.
  2. Right-click the profile that you want to configure and choose Edit Profile.
    Tip: Alternatively, you can choose Settings > Active Profile from the menu bar.

    The Profile - [<profile name>] dialog box opens, and the Replay category is displayed in the shortcut list on the left.

  3. In the shortcut list, click the Web icon.
  4. Click the Browser tab. Use the Browser type area to specify browser-specific settings.
  5. From the Browser list box, select the Web browser you want to use for your simulation. The selection you make determines the format of the header information included in your HTTP requests and the threading model used for simulation.
    Note: For mobile Web application testing (iPhone, iPad, Android, Windows Phone or Blackberry) you can change the user agent string used for recording.
  6. Click the Limit connections per server option button to limit the connections on a per-server basis as real browsers do (for example, two connections to one server, four connections to two servers).
    Note: It is not recommended that you use this option for low-level Web API, as only the Max total connections value is considered.
    • In the Max concurrent connections to a HTTP 1.0 server text box, specify the connection limit to every server that uses HTTP 1.0.
    • In the Max concurrent connections to a HTTP 1.1 server text box, specify the connection limit to every server that uses HTTP 1.1.
    • In the Max total connections text box, specify the absolute maximum number of connections that the emulated browser can open. To perform an accurate connection simulation this value should be above the per-server setting.
  7. Click the Limit connections per virtual user option button to limit the connections on a per-user basis (for example, four connections to one user, four connections to two users).
    1. In the Max. concurrent connections text box, specify the maximum number of simultaneous connections that the client may establish to the server in the case of custom browsers. Since the server has to allocate more system resources for each connection, the server's performance decreases as the number of connections increases. As with Web browsers, Silk Performer uses one thread per connection to send and receive data concurrently. For single-threaded (synchronous) operations, set this value to 1. For multi-threaded simulations, choose a value between 2 and 32.
      Note: Values are pre-defined for each selected browser. You can only edit Max. concurrent connections if you select Custom from the Browser list box.
    2. Select the Single-threaded option to replay scripts using a single thread. This setting forces all low-level web functions to execute synchronously.
  8. From the HTTP version list box, select the HTTP version of the browser that is to be simulated. This is typically HTTP/1.0.
  9. Check the Keep-Alive semantics check box to set "keep-alive" for HTTP/HTTPS. Keep-alive is a feature that, when supported by both browser and server, allows connections to remain intact after requests and responses are complete.
  10. Check the Content-Encoding check box to enable Silk Performer to decode compressed data received from the server. When this option is enabled, Silk Performer sends an Accept-Encoding header to inform the server that encoded data can be submitted (via gzip and compression-deflation methods).
  11. In the User agent text box, specify user agent information that should be sent to the server when custom browsers are used. This is typically the browser name, including platform information. This string is used for the HTTP request header User-Agent: that is sent using Silk Performer's low-level web functions.
  12. In the Accept text box, specify the document types that the server may send to the client custom browsers are used. This string is used in the HTTP request header Accept: that is sent using Silk Performer's low-level web functions.
  13. In the Additional HTTP headers text box, specify one or more additional headers, using the exact syntax in the case of custom browsers. Use a new line for each header. These headers will be appended to each request that is sent using Silk Performer's low-level web functions.
  14. Click OK to save your settings.
Parent topic: Web (Protocol Level) Settings


Proxy Settings

Proxy settings allow you to specify how Silk Performer connect to the Internet. You can define one of the following methods:

  • Direct connection to the Internet – Connect to the Internet without using a proxy.
  • Connect simulated browsers through a proxy server – Connect to the Internet through a specific proxy server. You can specify separate proxies for HTTP, HTTPS, FTP, and SOCKS traffic.
  • Automatic proxy configuration URL – Connect to the Internet through dynamic proxy configuration. Dynamic proxy configuration is a technique used in Web browsers to determine a proxy for each request sent out from the Web browser to the Internet. Depending on the URL or the connection host, a proxy is dynamically determined.

    A proxy auto-config (PAC) file determines the proxy server for each request. A PAC file tells the browser to load its proxy configuration information from a remote JavaScript file rather than from static information you enter directly.

    For more information about the PAC file specification, refer to http://www.microsoft.com/technet/prodtechnol/ie/reskit/6/part6/c26ie6rk.mspx.

  • Configuring Proxy Settings
    Configure proxy settings to specify how Silk Performer should connect to the Internet.
Parent topic: Web (Protocol Level) Settings


Configuring Proxy Settings

  1. In Silk Performer, expand the Profiles node in the Project tree.
  2. Right-click the profile that you want to configure and choose Edit Profile.
    Tip: Alternatively, you can choose Settings > Active Profile from the menu bar.

    The Profile - [<profile name>] dialog box opens, and the Replay category is displayed in the shortcut list on the left.

  3. In the shortcut list, click the Web icon.
  4. Click the Proxy tab.
  5. Select one of the following:
    • Direct connection to the Internet: Connect to the Internet without using a proxy.
    • Automatic proxy configuration URL: Connect to the Internet through dynamic proxy configuration. Specify the location of the PAC file to be loaded using the steps outlined below.
    • Connect simulated browsers through a proxy server: Connect to the Internet through a specific proxy server (follow the steps outlined below):
    1. Click the Advanced button to open the Proxy Settings dialog box.
    2. In the Internet access area, configure the Host name or IP address and Port of the proxy server for each protocol. Check the Use the same proxy server for all protocols check box to use the same proxy for all Web traffic. Checking this setting enables Address and Port text boxes on the Profile - [<profile name>] - Web dialog box. To change the SOCKS proxy settings, click the Hosts tab on the Profile Settings - Internet dialog box.
    3. In the Exceptions area, list any host names, IP addresses, or subdomains for which you do not want to use the proxies specified in the Internet access area. This list can contain wildcards (*), which cause the application to bypass the proxy server for addresses that fit the specified pattern. To list multiple addresses and host names, separate them with semicolons.
    4. Click OK to save your settings.
  6. On the Profile - [<profile name>] - Web dialog box, click OK to save your proxy settings.
Parent topic: Proxy Settings
Related tasks
Configuring Recording Settings


Configuring Browser-Simulation Settings

  1. In Silk Performer, expand the Profiles node in the Project tree.
  2. Right-click the profile that you want to configure and choose Edit Profile.
    Tip: Alternatively, you can choose Settings > Active Profile from the menu bar.

    The Profile - [<profile name>] dialog box opens, and the Replay category is displayed in the shortcut list on the left.

  3. In the shortcut list, click the Web icon.
  4. Click the Simulation tab. Use the Simulation area to set options for realistic simulation of users visiting Web sites.
  5. Check the Simulate user behavior for each transaction check box to have each virtual users reset their browser emulation after each transaction. Depending on the additional option you select, Silk Performer either simulates users who visit a Web site for the first time or users who revisit the site. While users who visit a site for the first time have no persistent cookies stored and no documents cached, users who revisit a page typically have closed their browsers between the Web site visits, have documents cached, and persistent cookies set. Disabling this option lets the virtual user emulate a Web browser that is not closed until the end of the test, thereby reusing cached information throughout multiple transactions.
  6. Click the First time user option button to generate a realistic simulation of users who visit a Web site for the first time. Persistent connections will be closed, the Web browser emulation will be reset, and the document cache, the document history, the cookie database, the authentication databases, and the SSL context cache will be cleared after each transaction. In such instances, Silk Performer downloads the complete sites from the server, including all files.
  7. Click the Revisiting user option button to generate a realistic simulation of users who revisit a Web site. Persistent connections will be closed, and the document history, the non-persistent cookie database, the authentication database, and the SSL context cache will be cleared after each transaction. In such cases, users do not clear the document cache. For more details, review the WebSetUserBehavior function in the BDL Function Reference. Use the User tolerance area to adjust the advanced options of the user tolerance simulation.
  8. Use the slider to adjust the tolerance level of the simulated user.
  9. Click the Customize button to open the Advanced User Tolerance dialog box where you can alter the individual behavior of the selected user tolerance level. Use the Loading times tolerance area to specify the user tolerance regarding the loading times.
    1. Check the If no data arrives after check box to make the virtual user react if the server does not respond at all in a given time frame. Also specify the maximum time in seconds a user is willing to wait if the server does not respond.
    2. Check the If document is not complete after check box to make the virtual user react if the first document (root) is received, but the HTML content (frames) is not completely loaded within a given time frame. Also specify the maximum time in seconds a user is willing to wait if the first document (root) is received, but the HTML content (frames) is not complete.
    3. Check the If page is not complete after check box to make the virtual user react if the HTML content (documents) is received, but the embedded objects are not completely loaded within a given time frame. Also specify the maximum time in seconds a user is willing to wait if the HTML content (documents) is received, but the embedded objects are not completely loaded.
    4. Check the If the pure image load time exceeds check box to make the virtual user react if the loading time of the embedded objects exceeds a given time frame (The timer starts, when the last HTML document is received). Also specify the maximum time in seconds a user is willing to wait for the loading of all embedded objects. This time starts, when the last HTML document is loaded.
    5. Click the Continue waiting option button if the user is to continue to wait if the timeout occurs and the page has already been retried the specified number of times; unlimited or until another timeout occurs.
    6. Click the Abandon option button if the user should press the stop button (abandon) when a timeout occurs and the page has already been retried the specified number of times.
    7. Click the Wait additional option button if the user is to wait an additional period of time if the timeout occurs and the page has already been retried the specified number of times. If this time expires too, the user will press the Stop button (ending the load test). Also specify the number of seconds that the virtual user is to wait before pressing the stop button. Use the Error tolerance area to specify user tolerance regarding errors on a page.
    8. Check the Retry check box to make the virtual user react to errors in the page.
    9. Specify how often the user is to press the Refresh button in the case of errors.
    10. Click the Page option button to have the user press the Refresh button for any error in the page (for example, a missing image).
    11. Click the Documents option button to have the user press the Refresh button only when errors in the document portion of the page (for example, a missing frame) occur.
  10. Click OK to save your settings on the Advanced User Tolerance dialog box.
  11. Click OK to save your settings on the Profile - [<profile name>] dialog box.
Parent topic: Web (Protocol Level) Settings


Setting Browser-Authentication Options

Note: For replay, use browser authentication settings if you want all virtual users to login using the same credentials. If you want each virtual user to connect with different login credentials, specify the credentials using project attributes. See Project Attributes in the BDL Function Reference for detailed information or use script customization with data files.
  1. In Silk Performer, expand the Profiles node in the Project tree.
  2. Right-click the profile that you want to configure and choose Edit Profile.
    Tip: Alternatively, you can choose Settings > Active Profile from the menu bar.

    The Profile - [<profile name>] dialog box opens, and the Replay category is displayed in the shortcut list on the left.

  3. In the shortcut list, click the Web (Protocol-level) icon.
  4. Click the Authentication tab.
  5. In the User authentication area enter a Username and Password for authentication when connecting to a protected, remote server.
  6. The following applies only for recording:
    1. In the shortcut list, click Record.
    2. Enable Generate new user authentication token in recorder.
      Note: When recording a script, the Silk Performer Recorder forwards the authentication data that was generated by the browser to the server. This is the default behavior. However, you can also instruct the Recorder to generate a new user authentication token and send that to the server. For more information, see the note below.
  7. In the Proxy authentication area, enter a Login name and a Password for proxy authentication login (required when connecting to the Internet through a proxy server).
  8. Click OK to save your settings.
Note: By default, the Silk Performer Recorder acts as a blind proxy and forwards the authentication data that was generated by the browser to the server. If the browser is missing the correct authentication information, it can prompt the user for it, also during recording. This default behavior causes no additional overhead for the Recorder. However, the default behavior does not work if the server requires channel binding (also known as extended protection on IIS servers). In such a case, enable Generate new user authentication token in recorder. The Recorder will then replace the authentication data that was generated by the browser using the credentials specified below the check box. However, be aware of the following facts: (1) User name and password have to be configured before the recording is started. (2) This mode causes additional overhead for the Recorder. (3) When the browser prompts you for credentials, the credentials you enter are ignored, because the Recorder automatically replaces these with the credentials defined in the settings. Make sure to click OK (not Cancel) to close the prompt.
Parent topic: Web (Protocol Level) Settings
Related concepts
Data Files
Project Attributes


Setting Browser-Emulation Authentication Options

  1. In Silk Performer, expand the Profiles node in the Project tree.
  2. Right-click the profile that you want to configure and choose Edit Profile.
    Tip: Alternatively, you can choose Settings > Active Profile from the menu bar.

    The Profile - [<profile name>] dialog box opens, and the Replay category is displayed in the shortcut list on the left.

  3. In the shortcut list on the left, click the Web icon.
  4. Click the Emulation tab. Use the Emulation area to set options for realistic Web-browser emulation.
  5. Check the Accept cookies check box to store cookies in Silk Performer's cookie database for each virtual user.
    Note: The cookie database is non-persistent and exists only as long as a load test runs.
  6. Check the Allow automatic redirections check box to automatically parse redirection responses and redirect requests to the specified server. When this option is selected, the user name and password entered on the Authentication page are used for automatic authentication to the server whenever necessary.
    1. In the text box to the right of the check box, enter the maximum number of automatic redirections. Silk Performer automatically parses redirection responses and redirects requests to the specified server.
  7. Check the Automatically load images check box to download images from the server. It may be helpful to deselect this option if you are testing dynamic parts of a Web application. Usually images are static objects that stress the network more than the server. Note that ignoring images limits the realism of simulated browser traffic.
  8. Check the Document cache check box to have Silk Performer emulate a document cache. Silk Performer can emulate a document cache by keeping local copies of frequently accessed documents, thus reducing server hits and the time connected to the network. For more details, see the WebSetDocumentCache function in the BDL Function Reference.
  9. Click the Once per session option button to, once per session, check whether or not a page has changed on the Web server since the virtual user last viewed the page. The term session includes the entire sequence of starting a Web browser, surfing the Web, and closing the Web browser. The correlation of a session to Silk Performer transactions can be adjusted using the Simulate user behavior for each transaction option on the Simulation page. Once per session works as follows: Each time you start your Web browser, it first looks in its cache before sending a request. The request will either be a conditional request (if the document resides in the cache and is requested for the first time in the session), a normal request (if the document can not be looked up in the cache), or a cache hit (if the document has already been requested in the session). Click the Every time option button to always check if a page has changed on the Web server since the virtual user last viewed it. Documents with a future expiration date are not requested until their dates expire. The Every time strategy is slightly different from Once per session caching in that it checks for newer documents each time you reload a page. Click the Never option button to never check whether a page has changed since the virtual user last viewed it. Selecting this option speeds up the display of pages the user has already viewed.
  10. In the Document history size text box, enter the maximum number of pages that are to be stored in the history. When the maximum number is exceeded, the oldest page is dropped from the history.
    Note: As long as a page is stored in the history, all HTML document related information (links, forms, embedded objects, frames) is kept in memory. As soon as a page is dropped from the history the information is no longer available. Therefore related WebPageLink and WebPageSubmit calls will not succeed and subsequent page-level calls to the same URL will no longer find the document in the cache.
  11. Check the Emulate DNS lookup check box to have Silk Performer emulate a DNS lookup mechanism for each virtual user , which can be helpful for DNS-based load balancing. When this option is combined with a user behavior option, it allows each virtual user to send its individual DNS query to the DNS server. For more details, review the WebSetOption and WebSetUserBehavior functions.
  12. Click OK to save your settings.
Parent topic: Web (Protocol Level) Settings
Related reference
WebSetDocumentCache Function
WebSetOption Function
WebSetUserBehavior Function


Setting Browser-Recording Options

  1. In Silk Performer, expand the Profiles node in the Project tree.
  2. Right-click the profile that you want to configure and choose Edit Profile.
    Tip: Alternatively, you can choose Settings > Active Profile from the menu bar.

    The Profile - [<profile name>] dialog box opens, and the Replay category is displayed in the shortcut list on the left.

  3. In the shortcut list on the left, click the Record button. The Record category is displayed.
  4. In the shortcut list, click the Web (Protocol Level) icon.
    Note: For mobile Web application testing, you can select an alternative user agent string (for example, iPhone, iPad, Android, Windows Phone, or Blackberry) on the Browser tab.
  5. Click the Recording tab.
  6. Use the Browser emulation level area to specify the level at which you want Web traffic to be recorded for use in your test scripts.
    • Click the Page-level Web API (HTML / HTTP) option button to record Web traffic at the browser level. When you choose this option the Silk Performer Recorder generates scripts that call functions provided by the page-level web API.
    • Click the Low-level Web API (HTTP) option button to record Web traffic at the browser level. When you choose this option the Recorder generates scripts that call functions provided by the low-level web API.
    • Click the TCP/IP-level API (TCP/IP / HTTP) option button to record Web traffic on the TCP/IP level. Select this option to capture proprietary protocols carried by HTTP.
  7. Select an Advanced context management level from the list box. You can disable advanced context management, customize the individual settings, or choose one of the presets Level 1, Level 2 (default) or Level 3.

    These options are only available when the Browser emulation level is set to Page-level Web API (HTML / HTTP).

    • Click the View Settings button to view or customize the level of advanced context management.
  8. Check the Automatic page detection check box to enable the recorder's page-notation technology. When you use the page-level Web functions, this feature attaches embedded documents that are loaded by JavaScript code into a Web page. When you use the low-level functions, all the requests that load a web page are wrapped by WebUrlBeginPage and WebUrlEndPage function calls and so automatically creates page timers and synchronizes the downloading of Web pages for improved accuracy.
  9. Check the Convert URL query strings to forms check box to convert recorded URL query strings to Web forms and then include the forms in the dclform section of the generated test script. Disable this option only if the URLs are irregular.
  10. Check the Enable persistent-cookie recording for returning-user simulation check box to have the recorder generate a WebCookieSet function call at the beginning of the current transaction for each persistent cookie that you receive from the Web server. When your script is run, each WebCookieSet function then emulates a cookie that is persistently stored in the virtual user’s cookie database.
    Note: WebCookieSet function calls are marked as comments, so you must remove the comment marks to activate the function calls.
  11. Check the Encapsulate concurrent pages using timers check box to encapsulate concurrent pages with timers. Page timers, normally included in the page-level web functions or in calls of the function WebUrlBeginPage, are not scripted. Instead, functions MeasureStart and MeasureStop are inserted automatically (based on timings). A series of browser activities is considered "concurrent" if there is no browser-idle period longer than the value of the minimum recorded thinktime.
  12. Use the Record additional HTTP headers area to specify additional HTTP headers you want to record, such as those generated by a custom HTTP client.
  13. Click the Add button to add the name of an additional HTTP header you want to record, such as one generated by a custom HTTP client. You must know the exact name of the header you want to record to use this feature. The HTTP Headers dialog box opens.
    1. Enter the name of the header you want to add to the list, or select one from the list box.
    2. Click OK.
  14. Click the Edit button if you want to edit the name of a selected HTTP header. The HTTP Headers dialog appears.
    1. Edit the header name as required.
    2. Click OK.
  15. Click the Remove button if you want to remove a selected additional HTTP header from the list.
    1. Click Yes to confirm the deletion.
  16. Click OK to save your settings.
Parent topic: Web (Protocol Level) Settings


Setting Verification Options

  1. In Silk Performer, expand the Profiles node in the Project tree.
  2. Right-click the profile that you want to configure and choose Edit Profile.
    Tip: Alternatively, you can choose Settings > Active Profile from the menu bar.

    The Profile - [<profile name>] dialog box opens, and the Replay category is displayed in the shortcut list on the left.

  3. In the shortcut list on the left, click the Record button. The Record category is displayed.
  4. In the shortcut list, click the Web icon.
  5. Click the Verification tab. Use the Recording area to specify options for generating verification functions when recording a script based on captured Web traffic.
  6. Check the Record title verification check box to have the Recorder automatically generate a title verification function (WebVerifyHtmlTitle) for each Web page.
  7. Check the Record digest verification check box to have the Recorder automatically generate a response verification digest function (WebVerifyDataDigest). Verification functions are of the following types:
    • Click the All characters option button to include in the digest all of the characters that are received in HTTP response messages from the Web server.
    • Click the Printable characters option button to include in the digest only the printable characters that are received in HTTP response messages from the Web server.
    • Click the Alphanumeric characters option button to include in the digest only the alphanumeric characters that are received in HTTP response messages from the Web server.
    • Use the Verify data of content type area to list all HTTP response content types for which a response verification digest should be generated.
  8. Click the Add button to add a new HTTP response content type to be used for response verification. The Response Content Types dialog box opens.
    1. Enter the name of the new content type you want to add to the list, or select one from the list box.
    2. Click OK.
  9. Click the Edit button to edit the currently selected HTTP response content type. The Response Content Types dialog box opens.
    1. Edit the currently selected HTTP response content type.
    2. Click OK.
  10. Click the Remove button to remove the currently selected HTTP response content type from the list.
    1. Click Yes to confirm the deletion.
  11. In the shortcut list on the left, click the Replay button. The Replay category is displayed.
  12. Use the HTML / XML area to enable HTML and XML document verification when replaying scripts based on Web traffic captured by the Silk Performer Recorder. Check the Title verification check box to enable Silk Performer to verify the title of HTML documents.

    An operation (depending on the specified severity: error, warning, informational, or custom) will be performed if the verification fails. The setting used here is valid for both the page-level Web API and the low-level Web API (WebSetVerificationEx).

    When this option is selected it triggers the execution of the WebVerifyHtmlTitle function in the BDL script.

  13. Check the Table verification check box to enable Silk Performer to verify that a table within an HTML document contains specified text. An operation (depending on the specified severity: error, warning, informational, or custom) will be performed if the verification fails. The setting used here is valid for both the page-level Web API and the low-level Web API (WebSetVerificationEx). This option triggers the execution of the WebVerifyTable function in the BDL script.
  14. Check the Digest verification tolerance level check box to verify the HTML content of a server response.

    Use TrueLog Explorer to generate WebVerifyHtmlDigest function calls.

    Enter the maximum difference in character frequency, quantified in bytes, that may occur between the server response that has been used by TrueLog Explorer to generate the HTML digest and the response that is received during replay. An operation (depending on the specified severity: error, warning, informational, or custom) will be performed if the number of differing bytes exceeds this limit.

  15. Check the HTML verification check box to enable Silk Performer to verify that an HTML document contains specified text.

    An operation (depending on the specified severity: error, warning, informational, or custom) will be performed if the verification fails. The setting used here is valid for both the page-level Web API and the low-level Web API.

    When this option is checked, it triggers the execution of the WebVerifyHTML and WebVerifyHTMLBound functions in the BDL script.

  16. Check the Link checking check box to check the validity of links in HTML documents received during the test. The HTML document is parsed on receipt, and additional requests are sent to check that links are valid. An error message is generated if a target pointed to by a link is invalid. This feature is available only in the page-level Web API.
  17. Check the XML verification check box to enable Silk Performer to verify that an XML document contains specified values or attributes.

    An operation (depending on the specified severity: error, warning, informational, or custom) will be performed if the verification fails. The setting used here is valid for both the page-level Web API and the low-level Web API.

    When this option is checked it triggers the execution of the WebXmlVerifyNodeValue and WebXmlVerifyNodeAttribute functions in the BDL script.

  18. Use the Data area to specify options for HTTP response verification when replaying a script based on Web traffic captured by the Recorder. Check the Data verification check box to enable Silk Performer to verify that raw data received from the server contains specified data (for example, HTML source code containing specific code).

    An operation (depending on the specified severity: error, warning, informational, or custom) will be performed if the verification fails. The setting used here is valid for both the page-level Web API and the low-level Web API.

    When this option is checked it triggers execution of the WebVerifyData and WebVerifyDataBound functions in the BDL script.

  19. Check the Digest verification tolerance level check box to have Silk Performer verify server response data during tests.
    Note: The Recorder generates the digests needed for verification.

    In the field to the right, enter the maximum difference in character frequency, quantified in bytes, that may occur between the response message received from the server during recording and the response message received during replay. If the number of bytes that differ exceeds this limit, Silk Performer will report an error. The Recorder creates digests only for the content types that are included in the Verify data of content type list.

  20. Click OK to save your settings.
Parent topic: Web (Protocol Level) Settings


Setting HTTP-Body Transformation Options

  1. In Silk Performer, expand the Profiles node in the Project tree.
  2. Right-click the profile that you want to configure and choose Edit Profile.
    Tip: Alternatively, you can choose Settings > Active Profile from the menu bar.

    The Profile - [<profile name>] dialog box opens, and the Replay category is displayed in the shortcut list on the left.

  3. In the shortcut list, click the Web icon.
  4. Click the Transformation tab.
    Note: You may have to click one of the arrow buttons in the top-right corner of the dialog box to scroll through the available tabs to find the Transformation tab.
  5. Select a transformation type from the Type list box.
  6. Optionally, enter additional parameters for the transformation type.
  7. Use the check boxes to specify if the transformation should be applied to HTTP request bodies (Transform HTTP requests), HTTP response bodies (Transform HTTP responses), or both.
  8. Check the respective Log encoded check boxes to additionally log the encoded HTTP response bodies.
  9. Click OK to save your settings.
Parent topic: Web (Protocol Level) Settings


Transformation of Custom Content Types and Encodings

Overview

By default, transformation is enabled for HTTP requests and responses that have the HTTP header Content-Type or Content-Encoding set to the following values:
  • Flex/AMF3 (Adobe, BlazeDS, GraniteDS): Content-Type set to "application/x-amf"
  • Java over HTTP: Content-Type set to "application/octet-stream" or "application/x-java-serialized-object"
  • Microsoft Silverlight: Content-Type set to "application/soap+msbin1" or "application/msbin1"
  • GZIP POST Data: Content-Encoding set to gzip

If you need to transform data with a different HTTP Content-Type or Content-Encoding header, this can be customized in the profile settings under Settings > Active Profile > Web (Protocol Level) > Transformation in the Additional Parameters field.

Enabling Custom Transformation During Replay

  1. Select Settings > Active Profile > Web (Protocol Level) > Transformation.
  2. In the Additional Parameters field, type AdditionalContentTypes=application/<myApp1>;application/<myApp2>. myApp1 and myApp1 are the custom content types of the application under test.

Enabling Custom Transformation During Recording

Note: These steps are not required for Content-Encoding customization.
  1. Select Settings > Active Profile > Web (Protocol Level) > Transformation.
  2. In the Additional Parameters field, type AdditionalContentTypes=application/<myApp1>;application/<myApp2>. myApp1 and myApp1 are the custom Content-Types of your application under test.
  3. Open the Documents folder in your current project directory with a file explorer (<my documents>\Silk Performer 21.0\Projects\<current project>\Documents).
  4. If this folder contains recording rule files (xrl), open them with a text editor.
  5. Search the recording rule files for Content-Type and duplicate any existing entries with your custom Content-Type. Example:
    <CompareData>
  <ApplyTo>Http.Final.Response.Header.Content-Type</ApplyTo>
  <Data>application/x-amf</Data>
</CompareData>

<Or>
  <CompareData>
    <ApplyTo>Http.Final.Response.Header.Content-Type</ApplyTo>
    <Data>application/x-amf</Data>
  </CompareData>
  <CompareData>
    <ApplyTo>Http.Final.Response.Header.Content-Type</ApplyTo>
    <Data>application/myApp1</Data>
  </CompareData>
  <CompareData>
    <ApplyTo>Http.Final.Response.Header.Content-Type</ApplyTo>
    <Data>application/myApp2</Data>
  </CompareData>
</Or>
    Note: If the <CompareData> elements are not encapsulated with an <Or> element you need to add this.
Parent topic: Web (Protocol Level) Settings
Related concepts
Microsoft Silverlight Support
Java Over HTTP Project Setup and Testing
Flex/AMF3 Project Setup and Testing
Related tasks
Enabling Customization of GZIP POST Data


Setting Terminal Client Options

Note: Silk Performer offers tutorials that walk you through the process of load testing terminal client applications (IBM Mainframe Applications and VT 100+ Applications). The tutorial is available at Start > All Programs > Silk > Silk Performer 21.0 > Documentation > Tutorials > Miscellaneous Tutorials .
  1. In Silk Performer, expand the Profiles node in the Project tree.
  2. Right-click the profile that you want to configure and choose Edit Profile.
    Tip: Alternatively, you can choose Settings > Active Profile from the menu bar.

    The Profile - [<profile name>] dialog box opens, and the Replay category is displayed in the shortcut list on the left.

  3. In the shortcut list on the left, click the Record button. The Record category is displayed.
  4. In the shortcut list, click the Terminal Client icon.
  5. Click the Telnet tab.
  6. In the Telnet settings area, specify one of the following Telnet detection modes:
    • Click the Always assume Telnet-mode option button to instruct the recorder to assume that each connection is a Telnet connection. Use this option for troubleshooting purposes only.
    • Click the Auto-detect Telnet-mode option button to instruct the recorder to automatically detect Telnet on each new connection (default).
    • Click the Never assume Telnet-mode option button to instruct the recorder to assume that no connections are Telnet connections. Use this option for troubleshooting purposes only.
  7. In the Command prompt string text box, specify a command-prompt string that the recorder uses to script WebTcpipRecvPacketsUntilData functions wherever possible. This string increases the effectiveness of recorded scripts for dynamic content.
  8. In the Terminal properties section, select one of the following items from the Log level list box:
    • None
    • Error
    • Normal
    • Debug
  9. Ensure that the specific terminal type you are testing is displayed in the Terminal type list box. This setting was configured automatically when you selected the application type for the project. When correctly specified, the recorder scripts the appropriate terminal-type initialization functions and renders the screens to the TrueLog.
  10. In the Configuration string text box, initialize the terminal emulator with a custom configuration string. For available options, refer to your terminal emulator documentation.
  11. Specify the following Screen values to indicate the appearance of the terminal screen to the recorder:
    • Type a value in the rows text box to indicate the height of the terminal screen. An empty value lets Silk Performer detect the height during session initialization.
    • Type a value in the columns text box to indicate the width of the terminal screen. An empty value lets Silk Performer detect the width during session initialization.
    • Check the Colors check box to specify the default color to use on the terminal screen.
    The supplied values overrule the default values that Silk Performer may detect. If your terminal application uses a custom screen size, make sure to set these values before you record a script in order to replay the script without errors.
  12. In the Host code page text box, specify the code page that the server uses. The code page is used for various data conversions, and all available code pages have been installed with the system. If the required code page is not listed, you can install it. Ensure that the selected code page is also available on each agent computer. To review all installed code pages, or to enable a specific code page, go to Start > Control Panel > Regional and Language Options > Advanced . Only the host code pages that are listed and enabled with a checkmark are available.
  13. Click the Advanced tab and check the Record basic functions check box to prevent the recorder from scripting synchronized receive-functions, such as WebTcpipScreenRecvPacketsUntilCursor and WebTelnetScreenRecvRecordsUntilStatus. If this option is enabled, scripted receive functions do not rely on rendered screen content. This option is enabled by default when a terminal type is not specified.
  14. Click OK to save your settings.
Parent topic: Project Profile Settings


Setting GUI-Level Testing Options

  1. In Silk Performer, expand the Profiles node in the Project tree.
  2. Right-click the profile that you want to configure and choose Edit Profile.
    Tip: Alternatively, you can choose Settings > Active Profile from the menu bar.

    The Profile - [<profile name>] dialog box opens, and the Replay category is displayed in the shortcut list on the left.

  3. In the shortcut list, click the GUI-Level Testing icon. On the Session page, the Session settings area is used to configure the connection between your console session and remote desktop sessions.
  4. Check the Run Try Script on console check box to have Silk Performer run a Try Script on the console application. When this option is enabled, you can view what Silk Performer does during tests, but you are limited in what you can do on your computer because Silk Test uses your console. If disabled, Try Scripts will connect to and run Silk Test on remote desktop sessions.
  5. Check the Allow usage of console session on agents check box if you do not have a terminal-server license for all agents, or if your agents run on Windows Home or Windows Professional editions. Silk Performer only uses this option if the connection to a terminal services session fails, or if no user credentials are provided.
    Note: When this option is selected, you can start only one virtual user on each agent (for agents that have no Terminal Server license and Windows Home/Professional systems).
  6. Define a Connection timeout (in seconds) to specify how long Silk Performer should wait before a connection is established to remote desktops. Set this setting to 0 to have no timeout.
  7. Select a Color Depth setting. The Color Depth setting enables you to specify the color depth of terminal server sessions that are used by virtual users to drive applications via Silk Test. You can select from 8 bit (256 colors) up to 32 bit (true color).
    Note: Color depth settings defined using the BDL function StInitSession override profile settings configured here. When the optional uColorDepth parameter is omitted, profile settings are used.

    The server may limit maximum color depth. The client can not force a color depth setting that is higher than is supported by the server. Please see Terminal Services Configuration documentation for details about your server version's color-depth limitations.

  8. Complete the Username/Password settings to enable automatic login if you only require a single set of login credentials. These credentials will be automatically loaded into the StInitSession function. These credentials can be overruled by scripted settings, for example, by providing parameters to the StInitSession function using project attributes.
  9. On the Execution page, the Execution Settings area enables you to configure settings for the script and the runtime. Check the Log Silk Test errors check box to have errors and warnings that are sent back by Silk Test logged as informational warnings (this option is enabled by default).
  10. Select a TrueLog setting for the remote desktop session from the Generate TrueLog file for list box:
    • Select None (the default) to not have TrueLog written.
    • Select On Error to have TrueLog written only when errors are encountered.
    • Select Custom when you wish to have TrueLog written based on your custom settings.
    If you select Custom TrueLog settings, your TrueLog settings will be read from the Silk Test option file, or they can be set via the StSetOption function.
    Note: Even if you select OnError or Custom from the TrueLog on SilkTest list box, Silk Test will only write TrueLog files if you also specify in Silk Performer’s settings that TrueLog should be written. To do this, click the Generate TrueLog Files button or the Generate TrueLog On Error Files button on Silk Performer’s toolbar.
  11. Select a Screenshot mode:
    • None: Captures no screens.
    • Active Window: Captures the active window of the test application.
    • Active Application: Captures the test application and any other window within the test application.
    • Desktop: Captures the entire desktop.
    Note: This list box is just enabled for UFT Developer (Silk4J) and UFT Developer (Silk4NET) projects. It sets the screenshot mode used for the TrueLog file. This setting applies only to successful playback steps. If playback steps fail, the entire desktop is captured.
  12. Specify an Execution timeout (in seconds) to specify how long the runtime should wait before test cases execute. Set this setting to 0 to have no timeout.
  13. Results history size (set to 9 by default) specifies how many test-case results Silk Test can save in a .res file.
    Note: By starting a new test, the results in the .res file are reset.
  14. In the Silk Test Classicoption file field, browse to and select a Silk Test Classic option file. Refer to Silk Test Help for full details about option files.
    Note: This field is just enabled for Silk Test Classic projects.
  15. Click OK to save your settings.
Note: When a GUI-level monitor is deployed on a Silk Test Agent with Terminal Services installed, Silk Performer automatically looks up the RDP port used for Terminal Server session creation.
Parent topic: Project Profile Settings
Related concepts
User Credentials for GUI-Level Testing
GUI-Level Testing Support


Setting Oracle Forms Options

Oracle Forms-specific settings allow you to modify how Silk Performer interacts with Oracle Forms clients during replay.

  1. In Silk Performer, expand the Profiles node in the Project tree.
  2. Right-click the profile that you want to configure and choose Edit Profile.
    Tip: Alternatively, you can choose Settings > Active Profile from the menu bar.

    The Profile - [<profile name>] dialog box opens, and the Replay category is displayed in the shortcut list on the left.

  3. In the shortcut list, click the Oracle Forms icon.
  4. On the General page, select a Connection mode setting that reflects which type of connection the Oracle Forms server accepts. Oracle Forms clients can communicate with servers via Sockets, HTTP, or HTTPS.
    Note: This setting can be overridden by the OraFormsSetConnectMode(connectMode) BDL function call.
    • Click the Socket mode option button when the Oracle Forms server is set up for socket mode.
    • Click the HTTP mode option button for Oracle Forms servers that are configured for HTTP connections.
    • Click the HTTPS mode option button for Oracle Forms servers that are configured for secure HTTP connections.
  5. In the Connection timeout text box, specify a timeout period (in seconds) to specify how long emulated clients should attempt to establish communication with the server before they report an exception.
  6. To configure additional runtime settings, you can optionally have the virtual user send a heartbeat message to the server at a specified interval. This is useful when the Oracle Forms client is not communicating with the server for a long period of time, for example during a long think time period. Check the Enable heartbeat with frequency of check box and enter an interval (in seconds) in the sec field.
  7. Check the Automatically wait for application timers check box to direct the replay engine to wait for application timers to expire after each function call.
  8. The Application timer and window timeout text box specifies the maximum wait time for expiration of application timers and appearance of windows. Enter a timeout setting (in seconds). The replay engine waits for timers to expire after each function call. The function OraFormsWaitForTimer can be used to make an application wait for timers to expire. Maximum wait time is specified by this setting. The function OraFormsWaitForWindow may be used to have an application wait for windows to appear. This setting specifies the maximum wait time for window appearance.
  9. Oracle Forms servers can allow certain client releases. Use the Oracle Forms setting to specify the Oracle Forms client version. Oracle Forms clients send the required version when connecting to the Oracle Forms server. Create profiles and change this setting when testing applications deployed on different server versions.
    Note: This setting can be overridden by the BDL function call OraFormsSetInt("INITAL_VERSION", theVersion).
  10. Click the Logging tab. Here you can specify that additional properties have their values logged during replay.
  11. From the Log level list box, select the log level for virtual user logging:
    • None - TrueLogs will be generated, though no Oracle Messages will be logged and no detailed information about controls in the log file will be written.
    • Error - In addition to the None log level, errors that occur during replay are logged.
    • Normal - In addition to the Error log level, Oracle messages are logged to the TrueLog and the log file.
    • Debug - In addition to the Normal log level, detailed information about control messages is logged, for example in the In Body and Out Body tab in TrueLog Explorer. This information is helpful for customizing and debugging your script when comparing it with Try Script runs. This option should also be used when you encounter a problem during replay and you must send your log files to Micro Focus SupportLine for analysis.
    Additional properties to be logged in the TrueLog for each control in your application can also be defined. Such properties are Oracle Forms internal properties that must be defined using their internal names. In most cases you will not need to use this feature, as default properties (name, value) are logged for each control. The OraForms.bdh file contains a complete list of all internal properties, most of which are not used by controls and so will generally be ignored if you define them.
  12. In the Additional properties text box, you can specify other properties for which virtual users are to log values.
    • Click Add to open the Additional Properties dialog box and add a property that is to have its value logged during replay.
    • Click Edit to open the Additional Properties dialog box and edit the selected property.
    • Click Remove to remove a selected property. Click Yes on the deletion confirmation dialog. No further values will be logged for this property.
  13. Click the Measuring tab. Here you can specify a custom measurement level. By default, all available performance metrics are collected during test runs.
  14. Check the Enable all timers and counters for all controls check box to enable all timers and counters for all actions on controls during replay. Alternatively, uncheck the Enable all timers and counters for all controls check box and select a specific control from the Control list box and select the specific timer/counter types that you want to have applied to that control:
    • Enable timers - Measure how long it takes to complete an action on the selected control.
    • Count round trips - Count the round trips for each action on the selected control.
    • Count bytes - Count the bytes sent and received for each action on the selected control.
    • Count messages - Count the messages sent and received for each action on the selected control.
    Note: Alternatively, you can click the Apply to All Controls button to apply your timer/counter settings to all controls.
  15. Click OK to save your settings.
Parent topic: Project Profile Settings
Parent topic: Replay Concepts


Setting SAPGUI Options

Silk Performer offers a tutorial that walks you through the process of testing SAPGUI applications. The tutorial is available at Start > All Programs > Silk > Silk Performer 21.0 > Documentation > Tutorials > SAP .

  1. In Silk Performer, expand the Profiles node in the Project tree.
  2. Right-click the profile that you want to configure and choose Edit Profile.
    Tip: Alternatively, you can choose Settings > Active Profile from the menu bar.

    The Profile - [<profile name>] dialog box opens, and the Replay category is displayed in the shortcut list on the left.

  3. In the shortcut list on the left, click the Record button. The Record category is displayed.
  4. In the shortcut list, click the SAPGUI icon. On the General page you can define options for how the SAP Recorder records and replays scripts.
  5. Login to SAP systems involves several user interactions. With the Script logon as a single function option enabled, the recorder only scripts one function that performs all the required login actions.
  6. Check the Script low level functions check box to use a basic set of scripting functions instead of object-specific functions.
  7. Check the Script timers check box to script timers automatically. These timers are used to measure SAP API calls.
  8. Check the Attach to existing SAP session check box to have the recorder attach to an existing session rather than create a new session.
  9. Check the Record window title verification check box to record SapGuiSetActiveWindow functions in such a way that title verifications are automatically performed on activated windows during test runs.
  10. In the shortcut list on the left, click the Replay button. The Replay category is displayed.
  11. In the Replay timeout text box, specify a timeout period (in seconds) for automatic shutdown of SAPFewgsrv (when not otherwise closed at the end of test runs).
  12. Check the Show SAPGUI during single runs check box to display the R/3 client during test runs. GUI display is only an option for Try Script executions. This setting is ignored for baseline tests and load tests.
  13. Check the Enable client-side scripting check box to enable SAP client-side scripting via the registry. This option disables warnings that raise pop-up windows when new users start.
  14. Check the Use new SAP Visual Design check box to enable SAP Visual Design for the SAP client.
  15. Click the Logging tab to specify additional log levels.
    Note: These settings affect performance and resource utilization.
  16. From the Log level list box, select a log level for virtual user logging:
    • Disable - Virtual user logging is disabled.
    • Normal - Default logging.
    • Debug - Detailed information is logged, such as additional session information and errors.
  17. Check the Capture screenshots check box to generate screenshots for each activated window.
    Note: Screenshot capture is only enabled for Try Script executions. This setting is ignored for baseline tests and load tests.
  18. Check the Capture screenshots for every action check box to have each action performed by the script documented with a screenshot.
    Note: Screenshot capture is only enabled for Try Script executions. This setting is ignored for baseline tests and load tests.
  19. Check the Log control information in TrueLog check box to have additional control information written to the TrueLog.
  20. Check the Log control information for single run in TrueLog check box to have additional control information written to the TrueLog only for try script and verification tests.
  21. Check the Log control information on error check box to enable writing of control information to TrueLogs in the case of errors.
    Note:

    For large load-tests, it is also recommended that you uncheck Log control information in TrueLog and only select Log control information on error. These settings greatly improve overall performance, as not all information on each screen is logged. In the case of errors, control state is logged on the nodes that cause the errors; this allows you to troubleshoot problems, as you can see the full state of the active window.

  22. Check the Highlight controls check box to have controls highlighted as they are accessed by the script.
  23. Click the Measuring tab to specify a custom measurement level. By default, all available performance metrics are collected during test runs.
  24. Check the Enable all timers and counters for all controls check box to enable all timers and counters for all actions on controls during replay.Or, select a specific control from the Control list box and select the specific counter types that you want to have applied to that control:
    • Count round-trips - The number of round-trips for the action on the control.
    • Count response time - The time it takes a function to return requested data.
    • Count Interpretation time - The time it takes to interpret a request.
    • Count flushes - The number of flushes per action.
    Note: Alternatively, you can click the Apply to All Controls button to apply your counter settings to all controls.
  25. Click OK to save your settings.
Parent topic: Project Profile Settings
Parent topic: Recording and Replay Concepts


Configuring Citrix XenApp Options

  1. In Silk Performer, expand the Profiles node in the Project tree.
  2. Right-click the profile that you want to configure and choose Edit Profile.
    Tip: Alternatively, you can choose Settings > Active Profile from the menu bar.

    The Profile - [<profile name>] dialog box opens, and the Replay category is displayed in the shortcut list on the left.

  3. In the shortcut list, scroll down to and click the Citrix icon. The General tab opens.
  4. In the Synchronization timeout text box, type a default synchronization timeout in milliseconds that is to be used by all CitrixWaitForXXX functions that do not specify a timeout value. The default value is 60000 ms.
  5. Check Force window position to make the calls to CitrixWaitForWindowCreation and CitrixWaitForWindowRestore move windows to the coordinates captured during recording (enabled by default). When this check box is not checked, both the CitrixWaitForWindowCreation and CitrixWaitForWindowRestore functions provide the parameter bForcePos to enable this option for each individual call.
  6. Check Disconnect on transaction end to disconnect the Citrix client following the end of each transaction, including the TInit transaction (disabled by default).
  7. Check Gracefully disconnect session to perform a log-off when disconnecting from a Citrix XenApp session (enabled by default).
  8. Check Log screen before each user action to capture and write a screenshot at the beginning of each user action (enabled by default). When TrueLog generation is enabled, a screenshot is taken at the end of each synchronization function and written to the TrueLog.

    The CitrixWaitForScreen function captures a screen region and checks it against a specified condition instead of against a hash value that is captured at recording. This file can later be examined or compared to what was captured during recording for error analysis.

    If the function call CitrixWaitForScreen fails and Dump window region on unsuccessful screen synchronization is checked , the captured screen region is written to a file in the result directory. The function call CitrixWaitForScreen may fail, for example, if the condition does not match when the timeout period expires.

  9. Check Use RAM disk to use a different drive for the intermediate storage of images.
    Note: If you check Use RAM disk, you must select the appropriate drive letter of the RAM disk from the list box. TrueLog generation performance improves if the specified drive is a RAM disk.
  10. Select the Simulation tab.
  11. In the Length of time mouse button remains pressed field, type the length of time that the virtual user is to hold the mouse button in the pressed state. The default value is 200 ms. The functions CitrixMouseClick and CitrixMouseDblClick use this value.
  12. In the Length of time between the clicks of a double-click field, type the maximum length of time that can pass between the two clicks of a double-click. The default value is 100 ms. The function CitrixMouseDblClick uses this value.
  13. In the Mouse speed field, type the speed (in pixels per second) at which the mouse is to move across the screen. The default value is 1000 pixels.
  14. In the Length of time each key remains pressed field, type the length of time that the virtual user must hold a keyboard key in the down state. The default value is 50 ms. The functions CitrixKey and CitrixKeyString use this value.
  15. In the Length of time between keystrokes when entering strings field, type the length of time that must pass between the individual keystrokes. The default value is 100 ms. The function CitrixKeyString uses this value.
  16. In the Key repeat time field, type the time required for a complete key stroke when simulating repeat functionality. The default value is 50 ms. A value of 50 ms represents 20 keys per second.
  17. In the Delay after successful synchronization field in the Think times area of the tab, type the length of time that virtual users are to remain inactive after passing a successful synchronization point. The default value is 1000 ms. The function CitrixWaitForXXX uses this value.
  18. In the Delay after each user action field, type the length of time that virtual users remain inactive between actions. The default value is 100 ms.
  19. Click the Citrix client tab to specify Citrix client options.
  20. From the Network protocol drop box, select the low-level network protocol to use for locating and connecting to the Citrix server. For more information, refer to Citrix client documentation.
  21. Check the Use data compression check box to compress all transferred data (enabled by default). This feature reduces file size but requires additional processor resources.
  22. Check the Use disk cache for bitmaps check box to store commonly used graphical objects, such as bitmaps, in a local disk cache (disabled by default).
  23. Check the Queue mouse movements and keystrokes check box to queue mouse and keyboard updates (disabled by default). This feature reduces the number of network packets sent from the Citrix client to the Citrix XenApp server.
  24. From the SpeedScreen latency reduction drop box, select one of the following to enhance user experience on slower network connections:
    • For WANs and other slower connections, select On.
    • For LANs and other faster connections, select Off.
    • To turn latency reduction on and off based on the latency of the connections, select Auto.
  25. From the Encryption level drop box, select a level of encryption for the ICA connection. The Citrix XenApp server must be configured to allow the selected encryption level or higher.
    Note: Using an encryption level other than the server default or Basic disables automatic logon to the Citrix XenApp server.
  26. Click OK to save your settings.
Parent topic: Project Profile Settings
Parent topic: Project and System Settings


Setting .NET Options

  1. In Silk Performer, expand the Profiles node in the Project tree.
  2. Right-click the profile that you want to configure and choose Edit Profile.
    Tip: Alternatively, you can choose Settings > Active Profile from the menu bar.

    The Profile - [<profile name>] dialog box opens, and the Replay category is displayed in the shortcut list on the left.

  3. In the shortcut list on the left, click the .NET icon.
  4. Check the Route HTTP .NET through Silk Performer web engine check box to route all HTTP/HTTPS traffic that is generated by your .NET test driver through the Silk Performer Web engine. This allows you to take advantage of the features that Silk Performer offers for accurate testing, such as its high performance Web engine, modem simulation, detailed timing/throughput information for each transmission, HTTP/XML TrueLog, and IP spoofing. The Routed web service proxy classes text box displays the .NET Web Service client classes that are used in your .NET test driver. HTTP/SOAP traffic of selected classes is routed through Silk Performer’s Web engine, regardless of the setting above. This setting can only be changed via the Silk Performer .NET AddIn.
  5. Click the One application domain for each virtual user container process option button to share one .NET application domain among all virtual users running in a virtual user process. This minimizes the administrative overhead for the .NET Common Language Runtime, but may cause runtime problems because all objects will be loaded into the same application domain.
  6. Click the One application domain for each virtual user option button to give each virtual user its own .NET application domain. This increases the administrative overhead of the .NET Common Language Runtime, but ensures that objects from different virtual users will not interfere with one another.
  7. Click OK to save your settings.
Parent topic: Project Profile Settings


CORBA/IIOP Settings

  • Setting CORBA/IIOP Replay Options
    Configure CORBA/IIOP replay options, including chunk sizes and fragmentation before running a test.
  • Setting CORBA/IIOP WChar/WString Options
    Configure CORBA/IIOP WChar/WString options, including encoding and code-setting options.
  • Setting CORBA/IIOP Recording Options
    Configure CORBA/IIOP recording options, including ORB, IDL, and preprocessor-argument options.
Parent topic: Project Profile Settings


Setting CORBA/IIOP Replay Options

  1. In Silk Performer, expand the Profiles node in the Project tree.
  2. Right-click the profile that you want to configure and choose Edit Profile.
    Tip: Alternatively, you can choose Settings > Active Profile from the menu bar.

    The Profile - [<profile name>] dialog box opens, and the Replay category is displayed in the shortcut list on the left.

  3. In the shortcut list, click the CORBA/IIOP icon.
  4. Click the Replay tab.
  5. Use the IIOP 1.2 area to specify the default settings for IIOP 1.2 replay.
  6. In the Max. chunk size for value type text box, type the maximum byte size for a single part of a chunked-encoded value type. A chunked-encoded value type is a value type that has been broken into smaller parts
  7. Check the Use fragmentation check box to fragment IIOP request and response messages when they exceed the length set in the Fragmentation size text box.
  8. In the Fragmentation size text box, set the fragmentation byte size for a chunked-encoded value type. When a request or response message exceeds this size, fragmentation is used to send the message.
  9. Click OK to save your settings.
Parent topic: CORBA/IIOP Settings


Setting CORBA/IIOP WChar/WString Options

  1. In Silk Performer, expand the Profiles node in the Project tree.
  2. Right-click the profile that you want to configure and choose Edit Profile.
    Tip: Alternatively, you can choose Settings > Active Profile from the menu bar.

    The Profile - [<profile name>] dialog box opens, and the Replay category is displayed in the shortcut list on the left.

  3. In the shortcut list on the left, click the CORBA/IIOP icon.
  4. Click the WChar / WString tab.
  5. Use the Code set area to specify the settings for the wide-character code set. In general, a code set determines the encoding rules for characters and wide characters. Code sets can be byte-oriented or non-byte-oriented (for example, ASCII is a byte-oriented code set for single byte characters). Multibyte characters defined by non-byte-oriented code sets have a byte-orientation (big-endian, little-endian); byte-oriented code sets do not.
  6. Check the Unicode check box to use the Unicode code set. Unicode is a non-byte-oriented code set for two-byte characters. The byte orientation of Unicode characters is determined by the IIOP message byte order.
  7. From the WChar size list box, select the size of a CORBA wide character (wchar).
  8. Click the Byte-oriented option button to have a byte-oriented code set used for CORBA wchars and wstrings. Alternatively, click the Non-byte-oriented option button to use a non-byte-oriented code set for CORBA wchars and wstrings. If you select this option, use the Script byte order list box to select the byte orientation of non-byte-oriented CORBA wchar/wstring representation in the BDL script. The byte orientation can be little-endian (least significant bit first) or big-endian (most significant bit first).
    Note: Use the IIOP 1.2 area to specify settings for IIOP 1.2. The wchar and wstring encoding in IIOP 1.2 differs from the encoding in previous IIOP versions. However, not all ORBs use the correct encoding for IIOP 1.2.
  9. Check the CORBA compliant check box if the ORB uses CORBA compliant wchar/wstring encoding in IIOP 1.2.
  10. In the WChar area, check the No length encoding check box to use pre IIOP 1.2 encoding. CORBA compliant IIOP 1.2 encoded wchars use a length indication for the size of the wchar.
  11. In the WString area, check the Null-terminated check box if the ORB uses null-terminated wstrings. CORBA compliant IIOP 1.2 encoded wstrings are not null-terminated.
  12. Click the Chars option button if the ORB uses the number of chars as wstring length. CORBA compliant IIOP 1.2 encoded wstrings specify the string length in bytes (chars). Alternatively, click the WChars option button if the ORB uses the number of wchars as wstring length.
  13. Click OK to save your settings.
Parent topic: CORBA/IIOP Settings


Setting CORBA/IIOP Recording Options

  1. In Silk Performer, expand the Profiles node in the Project tree.
  2. Right-click the profile that you want to configure and choose Edit Profile.
    Tip: Alternatively, you can choose Settings > Active Profile from the menu bar.

    The Profile - [<profile name>] dialog box opens, and the Replay category is displayed in the shortcut list on the left.

  3. In the shortcut list on the left, click the Record button. The Record category is displayed.
  4. In the shortcut list, click the CORBA/IIOP icon.
  5. Click the Recording tab.
  6. Use the Proprietary ORB features support area to specify whether to consider ORB-specific features when generating test scripts based on recorded IIOP traffic. When appropriate options are selected, generated scripts become more readable.
  7. Select IIOP traffic-recording options:
    • Orbix for Orbix-specific features
    • OrbixWeb for OrbixWeb-specific features
    • VisiBroker C++ for VisiBroker for C++ features
    • VisiBroker Java for VisiBroker for Java features
    • M3 C++ for BEA Millennium for C++ features
    • M3 Java for BEA Millennium for Java features
  8. From the CORBA version of IDL file list box, select the CORBA version of the application under test. When an application uses a CORBA version between 2.0 and 2.2, select 2.0 from the list box. When an application uses CORBA 2.3 or CORBA 3.0, select 3.0 from the list box.
  9. In the Preprocessor arguments text box, enter any number of arguments that are to be passed to the preprocessor of the IDF file parser. For example, the arguments may be used to specify the include directory and to execute predefined macros.
  10. Use the IDL files loaded list to view all of the IDL files that are currently used by the Silk Performer Recorder to generate high-level test scripts. Whenever the corresponding interface is defined in an IDL file, the Recorder generates type-dependent functions for specifying the parameters of CORBA operation calls in the test script.
  11. Click OK to save your settings.
Parent topic: CORBA/IIOP Settings


Java Settings

Configure Java settings, including classpath, version, JVM, JIT compiler, and logging options.

  • Configuring Java Version and Classpath Settings
    Configure general Java options, including classpath settings.
  • Setting Advanced Java Options
    Configure advanced Java options, including JVM and JIT compiler settings before testing a Java application.
  • Setting Java Logging Options
    Configure Java logging options, including properties to be logged and log levels.
Parent topic: Project Profile Settings
Related concepts
Java Settings


Setting Advanced Java Options

  1. In Silk Performer, expand the Profiles node in the Project tree.
  2. Right-click the profile that you want to configure and choose Edit Profile.
    Tip: Alternatively, you can choose Settings > Active Profile from the menu bar.

    The Profile - [<profile name>] dialog box opens, and the Replay category is displayed in the shortcut list on the left.

  3. In the shortcut list, click the Java icon.
  4. Click the Advanced tab. Use the Advanced area to set advanced options for the Java Virtual Machine.
  5. In the Command line options text box, type any command-line options to pass to the Java Virtual Machine.
  6. Check the Disable JIT compiler check box to disable the Just In Time (JIT) compiler of the Java Virtual Machine.
  7. In the JVM dll text box, type the name of any Dynamic Link Library (DLL) that implements the Java Virtual Machine that is to be used. If necessary, click (...) to navigate to and select the Dynamic Link Library to use.
  8. Click Check JVM to verify your Java Virtual Machine configuration settings.
  9. Click OK.
Parent topic: Java Settings


Setting Java Logging Options

  1. In Silk Performer, expand the Profiles node in the Project tree.
  2. Right-click the profile that you want to configure and choose Edit Profile.
    Tip: Alternatively, you can choose Settings > Active Profile from the menu bar.

    The Profile - [<profile name>] dialog box opens, and the Replay category is displayed in the shortcut list on the left.

  3. In the shortcut list on the left, click the Record button. The Record category is displayed.
  4. In the shortcut list, click the Java icon.
  5. Click the Logging tab. Use the Record settings area to specify that additional properties have their values logged during recording.
  6. Set the log level for virtual user logging from the Log level list box.
    Note: To disable logging, set the log level to None.
    The following log levels are available:
    • None – No additional logs will be written.
    • Error – Only errors that occur during replay will be logged.
    • Normal – Java messages will be logged.
    • Debug – Additional information will be logged (for example, events).
  7. Click OK to save your settings.
Parent topic: Java Settings


Database Settings

Configure database settings, including SQL, ODBC, and recording options.

  • Setting SQLSTATE-specific Error Handling
    Configure SQLSTATE-specific error handling options related to simulation exceptions and error codes.
  • Setting ODBC-specific Error Handling
    Configure ODBC-specific error handling options related to error definitions and error codes.
  • Setting High-Level ODBC Options
    Configure high-level ODBC options related to database-login credentials and SQL.
  • Setting Database Recording Options
    Configure database-recording settings related to Oracle OCI before recording.
Parent topic: Project Profile Settings


Setting SQLSTATE-specific Error Handling

  1. In Silk Performer, expand the Profiles node in the Project tree.
  2. Right-click the profile that you want to configure and choose Edit Profile.
    Tip: Alternatively, you can choose Settings > Active Profile from the menu bar.

    The Profile - [<profile name>] dialog box opens, and the Replay category is displayed in the shortcut list on the left.

  3. In the shortcut list, click the Database icon.
  4. Click the SQLSTATE tab.
  5. Use the Simulation exceptions list to define exceptions for specific ODBC error codes to prevent termination of the simulation. When a database error occurs, Silk Performer automatically terminates the entire simulation. This list includes all the exceptions that Silk Performer uses for handling database-specific errors. The Error field lists the native error code. The Class field ranks the severity of the error. Class 0 errors can be handled within a Silk Performer transaction. Class 1 errors end the transaction but do not cause the simulation to terminate.
  6. To add an error to the list of database-specific error exceptions, click the Add button. The Edit Error dialog box opens.
    1. In the Error field, add the error code for an error to be added to the exceptions list.
    2. In the Class field, add the error class.
    3. In the Description field, add a description for the error.
    4. Click OK.
  7. To edit an error, select it from the list, and click Edit. The Edit Error dialog box opens.
    1. Edit the error code, class, and description as required.
    2. Click OK.
  8. To remove an error from the exceptions list, select it and click the Remove button.
    1. Click Yes on the deletion confirmation dialog.
  9. On the Profile - [<profile name>] dialog box, click OK to save your changes.
Parent topic: Database Settings


Setting ODBC-specific Error Handling

  1. In Silk Performer, expand the Profiles node in the Project tree.
  2. Right-click the profile that you want to configure and choose Edit Profile.
    Tip: Alternatively, you can choose Settings > Active Profile from the menu bar.

    The Profile - [<profile name>] dialog box opens, and the Replay category is displayed in the shortcut list on the left.

  3. In the shortcut list, click the Database icon.
  4. Click the ODBC Database Errors tab.
  5. Use the Error definition list to define exceptions for specific database error codes in order to prevent the termination of simulations.
  6. To add an error to the list of database-specific error exceptions, click the Add button. The Edit Error dialog box opens.
    1. In the Error field, add the error code for an error that is to be added to the exceptions list.
    2. In the Class field, add the error class.
    3. In the Description field, add a description for the error.
    4. Click OK.
  7. To edit an error, select it from the list, and click Edit. The Edit Error dialog box opens.
    1. Edit the error code, class, and description as required.
    2. Click OK.
  8. To remove an error from the exceptions list, select it and click the Remove button.
    1. Click Yes on the deletion confirmation dialog.
  9. On the Profile - [<profile name>] dialog box, click OK to save your changes.
Parent topic: Database Settings


Setting High-Level ODBC Options

  1. In Silk Performer, expand the Profiles node in the Project tree.
  2. Right-click the profile that you want to configure and choose Edit Profile.
    Tip: Alternatively, you can choose Settings > Active Profile from the menu bar.

    The Profile - [<profile name>] dialog box opens, and the Replay category is displayed in the shortcut list on the left.

  3. In the shortcut list, click the Database icon.
  4. Click the ODBC High-Level tab.
  5. Use the Database area to specify details about the ODBC data source you will use and how Silk Performer should interact with the ODBC driver.
  6. From the Data Source Name list box of available ODBC data sources, select the data source that you want to connect to for testing.
    Note: To set up an additional ODBC data source, use Windows 32-bit ODBC Administrator (via the Windows Control Panel).

    The data source you select here is used only if you use high-level ODBC functions that perform an implicit connection to the database. When you use medium-level ODBC functions, this data source is not used. Instead, the connection is performed with an explicit DB_Connect("connection string") function in the script.

  7. In the UserID text box, enter the user name that is to be used to connect to the data source. You must specify a valid user for the DBMS to which you want to connect. If you use a trusted connection to connect to your DBMS, leave this field blank. Note that the user ID you enter here will only be used if you use high-level ODBC functions.
  8. In the Password text box, enter the password that is to be used when connecting to the data source. You must specify a valid password for the database user you are connecting. If you use a trusted connection, or if the user has no password, leave this field blank. Note that the password you enter here, as well as all remaining options you choose in this area, are used only if you use high-level ODBC functions.
  9. From the Isolation list box, select the level of isolation for the entire test. For a detailed description of isolation levels, consult your DBMS documentation and see the ODBC functions reference. You can change the isolation level and any other DBMS specific settings using the ODBC functions SQLSetConnectOption and SQLSetStmtOption in your script.
  10. From the SQL concurrency list box, select a type of cursor concurrency to use for the scrollable cursors in your test script. For a detailed description of concurrency settings, consult your DBMS documentation.
  11. From the SQL cursor type list box, select a cursor type for the scrollable cursors in your test script. For a detailed description of cursor type settings, consult your DBMS documentation.
  12. Check the Autocommit check box to commit the database automatically after each SQL command. Otherwise the database will be committed only after an explicit commit statement. This setting is effective for all connected cursors.
  13. Check the Reprepare SQL commands check box to prepare and execute a SQL statement each time it is called. Otherwise Silk Performer prepares SQL statements only when necessary. This setting is effective for all cursors used in your test.
  14. Click OK to save your settings.
Parent topic: Database Settings


Setting Database Recording Options

  1. In Silk Performer, expand the Profiles node in the Project tree.
  2. Right-click the profile that you want to configure and choose Edit Profile.
    Tip: Alternatively, you can choose Settings > Active Profile from the menu bar.

    The Profile - [<profile name>] dialog box opens, and the Replay category is displayed in the shortcut list on the left.

  3. In the shortcut list on the left, click the Record button. The Record category is displayed.
  4. In the shortcut list, click the Database icon.
  5. Click the Recording tab.
  6. In the Oracle OCI area, click the Generate random input for long placeholders option button to replace large amounts of data exchanged between the client application and the database server with random data. Because original data is rarely required for replay, this option helps to prevent large data files from being carried along with test scripts.
  7. Click the Generate files for long placeholders option button to store large amounts of data exchanged between the client application and the database server in a file. During replay, the file is used to send exactly the same data to the database server that is sent to the client application.
  8. Click OK to save your changes.
Parent topic: Database Settings


Test Scripts

Test scripts prescribe the actions of the virtual users that are run during tests. Scripts are written in Silk Performer's proprietary scripting language, the Benchmark Description Language (BDL). The usual way to create scripts is to have the Silk Performer Recorder generate them from real network traffic that has been captured and recorded. Scripts can also be generated manually, or sample scripts provided by Silk Performer can be modified for reuse.

As many test scripts as necessary can be added to a project, and existing scripts can be removed. Scripts need to be compiled before they can be used. Individual scripts in a project can be compiled, or all the scripts associated with a particular project can be recompiled at once.

  • Adding Test Scripts
    Projects must contain at least one test script to prescribe virtual-user actions.
  • Compiling Test Scripts
    Test scripts must be compiled before they can be run.
  • Removing Test Scripts
    As many test scripts as necessary can be added to a project, and existing scripts can be removed.
Parent topic: Outlining Projects


Adding Test Scripts

  1. In the Project menu tree, right-click the Project node and choose Add Existing Script.
    Tip: Alternatively, choose Project > Add Existing Script from the menu bar.
    The Select Script(s) dialog box opens.
  2. Navigate to and click the script to add to the project.
  3. Click OK to save your settings.
Parent topic: Test Scripts


Compiling Test Scripts

  1. In the Project menu tree, expand the Scripts node.
  2. Right-click the script you want to compile.
  3. Select Compile Script from the context menu. Alternatively, select Script > Compile from the menu bar. You can monitor the results of the compilation below in the Compiler page.
Parent topic: Test Scripts


Removing Test Scripts

  1. In the Project menu tree, expand the folder of the current project.
  2. Expand the Scripts folder.
  3. Right-click the script you want to remove.
  4. Select Remove Script from the context menu. You can optionally select Remove all Scripts to remove all scripts from your project.
  5. Click Yes on the deletion confirmation dialog.
Parent topic: Test Scripts


Data Files

Data files that are required by Silk Performer scripts [user-data files (CSV), IDL, certificate files (PEM), random data files (RND), and type library files (TLB, DLL, EXE, OCX, OLB, PKG)] are added to projects by specifying the directory where they are located. The compiler first searches for random data files in the directory where the BDF file is located, then in the specified directory. If a random data file from a different location needs to be used, the full path to the file can be specified in the script file.

Note: It is important that all the user data files needed by your script are added to your project. Otherwise they will not be available to remote agent computers during tests.
  • Adding Data Files
    All user data files needed by your test script must be added to your project to make them available to remote agent computers during tests.
  • Removing Data Files
    As many data files as necessary can be added to a project, and existing data files can be removed.
  • Compressing Data Files
    Describes how to enable data file compression and when compressing data files is useful.
  • Caching Data Files
    Describes how to enable data file caching and why caching data files is useful.
Parent topic: Outlining Projects


Adding Data Files

  1. In the Project menu tree, right-click the Project node and choose Add Data File. Alternatively, you can choose Project > Add Data File from the menu bar. The Select Data File(s) dialog box opens.
  2. Use the Select Data File(s) dialog box to navigate to and select the data file to add to the project.
  3. Optional: Select data files for addition by inserting wildcard characters into the File name text box.
    Note: If you insert wildcard characters into the File name text box, you must also click Add with wildcards to select the files that match the specified characters and add them to your project's data files.
  4. Optional: Check the Include subfolders check box to add files from subfolders that match the specified wildcard characters.
  5. Click OK to save your settings.
Parent topic: Data Files


Removing Data Files

  1. In the Project menu tree, expand the current project.
  2. Expand the Data Files folder.
  3. Right-click the data file you want to remove.
  4. Select Remove Data File from the context menu.
  5. Click Yes on the deletion confirmation dialog.
Parent topic: Data Files


Compressing Data Files

In some scenarios you can speed up initializing your load test by compressing the data files prior to transferring them to the agent computers. To compress data files, click Settings > System in the Silk Performer menu, click the Control tab, and enable the check boxes Compress data files for LAN/WAN agents and Compress data files for cloud agents.

Compression of data files for cloud agents is enabled by default.

Compressing data files can be especially useful ...
  • when you are using network connections with a small bandwidth. When your agents reside in a local area network (LAN), compressing data files is not as useful, because local area networks are usually fast. If, however, your agents reside in a wide area network (WAN), deploying compressed data files can save a lot of time.
  • when you are using many agents for your load test. Compressing data files is done only once (on the controller), decompressing data files is done once on each agent. The decompression process is done in parallel, so it does not necessarily slow down initializing your load test. Nevertheless: the more agents you use, the more likely it is that you save time with compressed data files.
  • when you are using data files that are well compressible. Text files or .csv files are examples for well compressible files. These can be shrinked considerably and compressing such files is done rapidly.

Whether compressing data files is useful, depends on your very specific environment and load test. As a general rule: If compressing, transferring the smaller data files, and decompressing files takes less time than just transferring the uncompressed files, then data file compression is useful.

Parent topic: Data Files


Caching Data Files

Before a load test is executed, it first needs to be initialized. Part of the initialization is the deployment of data files from the controller to the agents. Deploying data files can take some time, depending on their number and size. To speed up initialization, you can instruct Silk Performer to cache data files on the agents. In this case, data files must be deployed only for the first load test. Subsequent load tests will then be initialized quicker.

To cache data files, click Settings > System in the Silk Performer menu, click the Control tab, and enable the check box Cache data files on agents.

When caching is disabled, data files are transferred to the remote agent and stored in the remote project folder. When caching is enabled, the data files are stored in <public documents>\Silk Performer <version>\DataCache. The GetDataFilePath function provides the correct data file path in either case. Do not use the function GetDirectory with DIRECTORY_PROJECT to locate data files, as it does not work when data file caching is enabled.

Parent topic: Data Files


Agent Computers

Agent computers host the virtual users that are run during tests. As many agent computers as necessary can be added to a project to support the required number of virtual users.

Agent computers are assigned to particular projects from the pool of agent computers that are available to the controller computer. The maximum number of virtual users who will run on each agent is computed automatically by Silk Performer; Alternatively, this number can be set manually. New agents can be added to the agent pool from the local area network or from other Windows domains; they are then available to be added to projects. Agents can be checked for availability, and agents can be removed from the pool.

  • Configuring Project Agents
    Agent computers are assigned to projects from the pool of agent computers that are available to the controller computer.
  • Removing Agent Computers
    Agents can be removed from the pool of available agent computers.
Parent topic: Outlining Projects


Configuring Project Agents

  1. On the Project menu tree, right-click the Project node and choose Configure Project Agents. The Configure Project Agents dialog box opens.
    Note: Place your cursor over an agent name to view that agent's system and agent-version details.
    Tip: Alternatively, click Assign Agents on the Silk Performer workflow bar. Then click the Configure Project Agents link on the Setup Agents dialog box.
  2. Double-click an agent computer in the Available Agents pane to add the agent to the project.
    Note: It is not possible to remove all agents from the Project Agents pane. Localhost is added by default when you leave the list empty.
  3. To add a foreign agent (indicated by a question mark icon) from the Project Agents pane to the agent pool, right click the agent and choose Add to Agent Pool. Foreign agents are agents that have been configured for a project that have not been added to the agent pool.
    1. To make a newly added agent available for assignment, click Configure Agent Pool and configure the agent on the System Settings - Agents page.
  4. To add an agent that does not appear in the Available Agents list to the agent pool, click Configure Agent Pool to go to the System Settings - Agents page.
  5. Click OK.
Parent topic: Agent Computers
Related tasks
Configuring Agent Pool Settings


Removing Agent Computers

  1. In the Project menu tree, expand the current project.
  2. Expand the Agents folder.
  3. Right-click the agent computer you want to remove.
  4. Select Remove Agent from the context menu. Note that you must leave at least one active agent in your project.
  5. Click Yes on the deletion confirmation dialog.
Parent topic: Agent Computers


Modeling Scripts

Before you can conduct a Silk Performer load test you need to create a test script that prescribes the actions of the simulated users run during the test. The script is written in Silk Performer's proprietary scripting language, the Benchmark Description Language (BDL).

Scripts can be created in different ways depending on the application type. The standard (and typically easiest) method for creating a test script is to use the Silk Performer Recorder to capture and record traffic that is representative of the type you need to simulate in your test. The Silk Performer Recorder automatically generates a BDL test script based on the recorded traffic.

Another method of creating a test script is to manually create a new script in BDL. A variant on the manual approach is to create a test script based on one of the sample BDL scripts that are provided by Silk Performer.

  • Recorded Test Scripts
    Describes how the Silk Performer Recorder records traffic and generates a test script or a capture file.
  • Manually Written Test Scripts
    Explains the prerequisites for writing test scripts manually.
  • Sample Scripts
    Explains how sample scripts can save you time in preparation for script modeling.
Parent topic: Managing Load Tests
Related concepts
Benchmark Description Language (BDL) Reference


Recorded Test Scripts

The standard, and easiest, method of creating a test script is to use the Silk Performer Recorder, Silk Performer's engine for capturing and recording traffic and generating test scripts.

First, the Silk Performer Recorder captures and records a representative amount of real traffic between a client application and the server to be tested. When recording is complete, the Silk Performer Recorder generates either a test script or a capture file. You can create scripts out of the capture file later on. The script is written in Silk Performer's proprietary scripting language, the Benchmark Description Language (BDL).

During the recording phase, you define transactions. A transaction is a discrete piece of work that will later be assigned to a virtual user in a load test and for which separate time measurements will be made. You should create a new transaction only for a piece of work that has no dependencies on another piece of work. Individual time measurements can be made for any action or series of actions that happen during recording.

Using the Silk Performer Recorder has a number of advantages:

  • Recorded traffic and function calls include a lot of static information. Replay of static information ordinarily does not lead to reliable benchmark results. Because recorded scripts can easily be customized, you can add random functions to generate dynamic and realistic workloads .
  • Transactions defined during recording modularize the script into clearly laid out sections. It is easy to modify workloads based on different statistics or requirements using the randomization functions embedded in Silk Performer.
  • Timers set during recording provide user-defined granularity for measuring any part of a transaction.
  • Development time and costs can be reduced considerably. There is no need to change the front-end application to simulate new behaviors. It is sufficient to modify the script and repeat the simulation until the requirements are met. The front-end application has to be implemented only once; the script then becomes its prototype and reproduces its behavior.
  • Recording a Test Script
    Create a test script with the Silk Performer Recorder, Silk Performer's engine for recording traffic and generating test scripts.
  • Secure Connections and Certificates
    Explains the role of certificates for recording and replaying scripts over secure connections.
  • Generating Scripts from Capture Files
    Describes what a capture file is and when it is generated.
  • Traffic Filters
    Lists the filters Silk Performer provides to exclude unwanted traffic from a script.
  • Rule-Based Recording
    This chapter explains how to configure Silk Performer's Recorder (HTTP, TCP/IP) using recording rule files.
Parent topic: Modeling Scripts
Related concepts
Benchmark Description Language (BDL) Reference
Related reference
Available Application Types


Secure Connections and Certificates

If your application under test is accessed over a secure connection, Silk Performer needs to be configured so that the communication between the client and the server is trusted. This is done with certificates, where you can chose between the following two approaches:

Micro Focus Certificate Authority (CA) Certificate

The Micro Focus CA certificate, located at C:\Program Files\Silk\Silk Performer 21.0\IRCAcert.crt, needs to be installed on the client to establish a secure connection between the client and the server. The according server certificate, issued by the Micro Focus Certificate Authority, is located at C:\Program Files\Silk\Silk Performer 21.0\IRServerCert.pem.

Connection route:
  1. The client opens a secure connection to the Recorder, which acts as a server.
  2. The Recorder sends back the Micro Focus server certificate.
  3. The client receives the certificate and checks whether it was issued by one of the Trusted Root Authorities (Micro Focus CA certificate). If the check is successful, the secure connection is established.
  4. The Recorder tries to open a second secure connection to the system under test.
  5. The system under test sends back its own server certificate.
  6. The Recorder accepts this certificate and establishes a secure connection to the system under test.

Server Certificates

If you have the server certificate of your system under test, you can specify it in the Profile Settings to enable secure recording and replay.

Connection route:
  1. The client opens a secure connection to the Recorder and receives the server certificate that you specified in the Profile Settings, so the client thinks it is already connected to the system under test.
  2. The Recorder opens a second secure connection to the system under test.
  3. The system under test sends back its own server certificate.
  4. The Recorder accepts this certificate and establishes a connection to the system under test.

Native Mobile Apps

Native apps on mobile devices that communicate over a secure connection often match received server certificates (either the server certificate from the system under test or the Micro Focus server certificate) against a specific string, for example a company or domain name. This security approach prevents the Micro Focus certificate approach from working.

Parent topic: Recorded Test Scripts
Related tasks
Recording a Test Script Over a Secure Connection


Generating Scripts from Capture Files

What is a capture file?

While recording a user transaction, the Silk Performer recorder creates a so-called Silk Performer capture file, which contains the entire traffic of the recorded session. When you stop the recording, Silk Performer saves the capture file, analyzes the traffic in the background, and displays the Capture File page. On the Capture File page you can adjust a variety of settings, like resolving potential problems, applying filters, or setting recording rules. When you are done, click Generate Script to generate a .bdf file out of the .spcap file.

Tip: You can click the check box Always show Capture File page after recording, which displays on the bottom right of the Capture File page. If you disable this check box, Silk Performer will not show the Capture File page and will automatically create a script out of the capture file.
Tip: It is possible to generate several scripts (with different options) from the same capture file.

Which project types use capture files?

Capture files will be created for the following project types:

  • Web business transaction (HTML/HTTP)
  • Web (Async)
  • Web low level (HTTP)
  • Mobile Devices
  • Flex/AMF3 (Adobe)
  • Flex/AMF3 (GraniteDS)
  • Silverlight
  • HTTP Live Streaming (HLS)
  • Java over HTTP
  • WebDAV (MS Outlook Web Access)
  • Oracle ADF
  • Email (SMTP/POP)
  • Directory server (LDAP)
  • Radius
  • FTP
  • TCP/IP based application
  • Mixed Protocols

Specifics for Recording Flex/AMF3 and Java over HTTP

When you work with the project types Flex/AMF3 (Adobe), Flex/AMF3 (GraniteDS), or Java over HTTP, the following specifics apply:

When the Capture File page displays issues (which can occur during creation of the capture file, due to missing .jar files for example), use the buttons in the Resolve Problems area to fix these. Once all problems are resolved, click Generate Script.

Parent topic: Recorded Test Scripts


Traffic Filters

When you record a web application, the resulting script can include a lot of unwanted, application-independent traffic. This unwanted traffic can overload a script considerably and it can make a script look messy when it actually contains just a few lines of application-relevant code.

To tidy up a script and include only the traffic that was intended to be recorded, you can use the filters on the Capture File page. Silk Performer provides the following filters:

  • A general filter: This filter allows you to exclude proprietary TCP/IP traffic, UDP traffic, and traffic from browser-specific domains.
  • A domain filter: This filter allows you to exclude traffic from specific domains. You can use it to filter traffic from third-party components that are embedded into a website, like social media or statistic plugins.
  • A path and query filter: This filter allows you to exclude web requests (API calls) from a script.
  • Filtering General Traffic from Capture Files
    Describes how to filter proprietary TCP/IP traffic, UDP traffic, and browser-specific domains from your script.
  • Filtering Domains from Capture Files
    Describes how to filter domains from a capture file to exclude unwanted traffic in the script that will be generated.
  • Filtering Paths and Queries from Capture Files
    Describes how to filter paths and queries from a capture file to exclude web requests (API calls) from the script that will be generated.
Parent topic: Recorded Test Scripts


Filtering General Traffic from Capture Files

You can exclude proprietary TCP/IP traffic, UDP traffic, and browser-specific domains from your script by using the following filter on the Capture File page.
  1. In the Project tree, expand the Capture Files node and double-click a capture file.
  2. Enable Exclude proprietary TCP/IP traffic. Silk Performer automatically recognizes traffic of standard TCP/IP-based web protocols such as HTTP. Traffic from non-standard web protocols is often generated by the browser and can be described as proprietary TCP/IP traffic. It can be useful to exclude this traffic as it can clutter up a script and usually it is not the traffic that was intended to be recorded.
  3. Enable Exclude UDP traffic. Browsers and web applications often use the UDP for device and service detection. UDP traffic is also usually not intended to be recorded.
  4. Enable Exclude browser-specific domains When you record a web application, your script will usually also contain additional , browser-specific web calls. These web calls are independent of the recorded application and are only scripted when you use a certain browser to do the recording. Therefore, it is typically desirable to exclude these web calls, which helps to create a cleaner script. The tooltip shows which browser-specific domains Silk Performer found in your capture file.
  5. Click Generate Script.
Parent topic: Traffic Filters


Filtering Domains from Capture Files

While recording a user transaction, the Silk Performer Recorder might also capture third-party components that are embedded into a website, like social media or statistic plugins. To remove this unwanted traffic, open a capture file, apply the domain filter, and generate a new script. The script will just contain the desired code from the user transaction.
  1. In the Project tree, expand the Capture Files node and double-click a capture file.
  2. To include the traffic from one specific domain, click Include traffic from and select a domain from the list box.
  3. To include or exclude multiple domains, select one of the following options:
    • Click Include only traffic from domains selected below to preserve only the traffic from the below selected domains in the script.
    • Click Exclude traffic from domains selected below to leave out the traffic from the below selected domains in the script.
  4. Expand the list of domains and select all domains that shall be included or excluded.
    Tip: To quickly drill into the list, right-click the nodes and click Expand all or Collapse all.
  5. Click Generate Script.
The generated script will be modified as follows:
  • Calls to filtered domains will be removed from the script.
  • The BDL function WebSetDomainSuppress will be added to the script. Embedded objects are loaded automatically by page-level functions, even if they are not explicitly listed in the script. WebSetDomainSuppress avoids that.
Parent topic: Traffic Filters


Filtering Paths and Queries from Capture Files

You can exclude web requests (API calls) from a script by using the following filter on the Capture File page.
  1. In the Project tree, expand the Capture Files node and double-click a capture file.
  2. In the Path and Query Filter Settings enter one or more patterns. The matches in the script display immediately.
  3. Click Generate Script.
The defined patterns are removed from the generated script.
Parent topic: Traffic Filters


Rule-Based Recording

This section explains how to configure Silk Performer's Recorder (HTTP, TCP/IP) using recording rule files. It describes the structure and syntax of recording rules and shows examples. Recording rules are an advanced Silk Performer concept. You need to have a thorough understanding of the involved protocols (TCP/IP, HTTP and HTML) and of Silk Performer.

Note: You can not only manually script recording rules, you can also use templates from the Recording Rules tab.
Recording rules allow you to configure the Recorder in a number of ways:
  • TCP/IP: By providing protocol descriptions of proprietary TCP/IP based protocols.
  • HTTP: By specifying the scenarios in which the Recorder should script parsing functions for dynamically changing values and generate replacements for those values.
  • Recording Rule Files
    Describes what recording rule files are, where they are stored, and the three types of recording rules.
  • General Attributes of Recording Rules
    Describes the Name attribute and the Active attribute.
  • HTTP Parsing Rules
    Describes the HTTP parsing rules.
  • TCP/IP Protocol Rules
    Describes how to use TCP/IP protocol rules to detect proprietary TCP/IP protocols.
  • StringScriptingRule
    Describes how to use StringScriptingRule to hook into the process of scripting strings.
  • HttpScriptingRule
    Describes the HttpScriptingRule, which allows to hook into script generation decisions the recorder has to make.
  • ProxyEngineRule
    Describes the ProxyEngineRule, which allows to control some aspects of the ProxyEngine's operation.
  • Conditions
    Conditions allow you to specify exactly when rules should be applied.
  • Troubleshooting
    Provides recommendations for troubleshooting recording rules that do not operate as expected.
Parent topic: Recorded Test Scripts


Recording Rule Files

Recording rule files are written in XML and have the file extension .xrl. They contain the rules for the Silk Performer Recorder.

Project specific recording rules are stored in the documents directory of the respective project, for example: <my documents>\Silk Performer <version>\Projects\TestProj\Documents\

Global recording rule files are stored in the public or the user's RecordingRules directory, for example: <public user documents>\Silk Performer <version>\RecordingRules\

The root node for all recording rule file node trees is RecordingRuleSet. Here are the three types of recording rules with their respective XML node:
  • HTTP parsing rules: HttpParsingRule
  • TCP rules for WebTcpipRecvProto(Ex): TcpRuleRecvProto
  • TCP rules for WebTcpipRecvUntil: TcpRuleRecvUntil
  • Writing XML Files
    Describes the XML encoding requirements.
  • Recording Rule File Example
    Shows a file example of recording rules.
  • Recording Rule Data Types
    Lists all valid recording rule data types.
Parent topic: Rule-Based Recording


Writing XML Files

Consider the following encoding requirements when you write XML files:

Encoding Special Characters

Some characters and symbols must be encoded for a proper XML syntax:

Description | Character | XML representation
Less Than | < | &lt;
Greater Than | > | &gt;
Quote | " | &quot;
Ampersand | & | &amp;
Apostrophe | ' | &apos;

Encoding Binary Data

Binary data must be encoded in hexadecimal notation:

Description | XML representation
CR (carriage return) | &#x0D;
LF (line feed) | &#x0A;
NULL-byte | &#x00;
Any byte hex code | &#x<byte hex code>;
Parent topic: Recording Rule Files


Recording Rule File Example

Naming conventions used in this example

XML nodes are referred to by their full path names: RecordingRuleSet\HttpParsingRule\Search\LB\RegExpr

When base paths are clear, the relative paths of XML nodes are used: Search\LB\RegExpr

Example

<RecordingRuleSet>
  <HttpParsingRule>
    <Name>Siebel Session Cookie</Name>
    ...
  </HttpParsingRule>
  <TcpRuleRecvProto>
    <Name>Siebel TCP Protocol</Name>
    ...
  </TcpRuleRecvProto>
  <TcpRuleRecvUntil>
    <Name>Telnet screen</Name>
    ...
  </TcpRuleRecvUntil>
</RecordingRuleSet>
Parent topic: Recording Rule Files


Recording Rule Data Types

Recording rule attributes come in a variety of data types. The following table lists all valid data types and associated attribute descriptions:
Data Type | Description
Strings | All string values, including binary data (except NULL-Bytes), are valid.
Binary Data | All binary data, including NULL-Bytes, are valid.
Numbers | Unsigned numbers in the range of 0 thru 4294967295 are valid. The value 4294967295 is the Max unsigned number.
Signed Numbers | Signed numbers in the range of -2147483648 thru 2147483647 are valid. The value 2147483647 is the Max signed number.
Numeric Ranges | Numeric ranges are notated using the following syntax: [ MinValue ] [ "-" ] [ MaxValue ] MinValue and MaxValue are unsigned numbers. If MinValue is omitted, a default value of 0 is used. If MaxValue is omitted, a default value of Max unsigned is used.
Boolean Values | Boolean values are valid data types. These include true and false.
Extended Boolean Values | Extended Boolean values are valid data types. These include true, unknown and false.
Distinct Values | Many distinct values are valid. Valid values depend on specific attributes.
Distinct Value Lists | Comma-Separated Value (CSV) lists are valid. Valid values depend on specific attributes.
Structured Data | Compound data types consisting of nested XML nodes are valid.
Parent topic: Recording Rule Files


General Attributes of Recording Rules

All recording rule types allow users to specify both Name and Active attributes.
Attribute | Description
Name attribute | Data type strings Default value: Unnamed Rule This attribute specifies a name for a given recording rule. Names do not require a special meaning or syntax. They may appear in recorded script comments.
Active attribute | Data type Boolean Values Default value: true This attribute specifies whether or not a given recording rule is active. Inactive recording rules are ignored. This attribute allows for the temporary disabling of recording rules without them being deleted from recording rule files.
Parent topic: Rule-Based Recording


HTTP Parsing Rules

HTTP parsing rules are specified by XML nodes with the name HttpParsingRule.

Purpose

HTTP parsing rules specify when the Recorder should generate the parsing function WebParseDataBoundEx() for dynamically changing values, and then substitute parsing results where appropriate. This enables the Recorder to directly generate working scripts-and thereby eliminates the need for visual script customization using TrueLog Explorer.

When recording HTTP traffic, the Recorder applies HTTP parsing rules with the following settings:
  • Page-level Web API
  • Low-level Web API with/without automatic page detection

The Recorder does not apply HTTP parsing rules when recording HTTP traffic with the TCP/IP-level API setting.

How HTTP Parsing Rule Application Works

HTTP parsing rule application involves two main steps:
  • Finding possible replacements (called "Rule Hits" or simply "Hits").
  • Scripting parsing functions and replacements.

Details regarding both steps can be specified in HTTP parsing rules.

Finding possible replacements

During recording, each server response is parsed for rule hits. HTTP parsing rules specify how parsing is to be done and which parsing results (hits) are to be retained for future use. Parsing functions are not generated in this step; hits are simply retained for future use.

Scripting Parsing Functions

When the Recorder scripts a string value (either a parameter of a function, or a form field value or name), it examines all identified hits and determines a set of hits that are non-overlapping substrings of the string that is to be scripted. The Recorder then scripts the necessary parsing functions and replacements, rather than scripting the original string.

  • Structuring HTTP Parsing Rules
    Shows an example of how to structure HTTP parsing rules.
  • Conversion Functions
    Describes how to write your own custom conversion functions and how to specify these conversion functions in a recording rule.
  • Guided HTTP Parsing Rule Example
    Provides a guided example of designing a HTTP parsing rule.
  • Section Search - Finding Rule Hits
    Describes how to search for and find rule hints.
  • Scripting Parsing Functions and Replacements
    Describes how the ScriptGen section allows users to specify conditions that restrict the usage of rule hits to script locations where replacement is appropriate.
  • Section ScriptGen
    Describes the ScriptGen section and the respective attributes.
Parent topic: Rule-Based Recording


Structuring HTTP Parsing Rules

To keep the two values separate, HTTP parsing rules consist of two sections named Search and ScriptGen.

<?xml version="1.0" encoding="UTF-8" ?>
<RecordingRuleSet>

  <HttpParsingRule>
    <Name>Example Rule</Name>
    <Active>true</Active>
    <Search>
      ...
    </Search>
    <ScriptGen>
      ...
    </ScriptGen>
  </HttpParsingRule>
</RecordingRuleSet>
Parent topic: HTTP Parsing Rules


Conversion Functions

You can write your own custom conversion function and specify this conversion function in a recording rule. The conversion function is contained in a native DLL file (programmed in C/C++). Within the conversion function, the value in the parsing rule is converted using the specified function, while the parsing function only parses the original value.

For example, when values are returned by the server in a double format they are sent by the client in an integer format. Therefore, a simple parsing rule will not find any matches in the script. However by applying a custom conversion function that converts the integer to a double format, the parsing rule is able to find the expected matches again.

Note: A conversion function can only be specified for HTTP Parsing Rules.

Sample Recording Rule

Below is an example of a recording rule with the conversion function specified.

<RecordingRuleSet>
  <HttpParsingRule>
    <Name>Parse by Boundaries, Convert and Replace (with custom conversion DLL)</Name>
    <Search>
      <SearchIn type="Select{Body|Header|All}">Body</SearchIn>
      <LB>
        <Str>&gt;</Str>
      </LB>
      <RB>
        <Str>&lt;/strong&gt;</Str>
      </RB>
      <Conversion>
        <Dll>SampleConversion.dll</Dll>
        <Function>ConvertToUpperCase</Function>
      </Conversion>
    </Search>
    <ScriptGen>
      <ReplaceIn type="MultiSelect{FormFieldValue|Url|PostedData}">FormFieldV alue, Url, PostedData</ReplaceIn>
      <VarName>ParsedByBoundary</VarName>
      <GenDebugPrint>true</GenDebugPrint>
      <Conversion>
        <BdlFunction>MyConvertToUpperCase</BdlFunction>
      </Conversion>
    </ScriptGen>
  </HttpParsingRule>
</RecordingRuleSet>
Parent topic: HTTP Parsing Rules


Guided HTTP Parsing Rule Example

This section steps through the process of designing a HTTP parsing rule for the sample application, ShopIt V 6.0, which ships with Silk Performer.

  • Recording ShopIt V 6.0 Without Parsing Rules
    Shows a script example that allows you to record ShopIt V 6.0 without parsing rules.
  • Customizing ShopIt V 6.0 With TrueLog Explorer
    Describes how to customize ShopIt V 6.0 with TrueLog Explorer.
  • Transferring Customization Details to the Recorder
    Describes how to use HTTP parsing rule to automatically generate recorded scripts without needing manual customization.
  • Try the Recording Rule
    Describes how to try the recording rule and shows the result, that is a recorded script.
  • Create a More Specific Rule
    Describes how to create a specific rule that creates a parsing function only for the session ID.
  • Creating a Conversion DLL
    Describes how to create a conversion DLL with the help of sample projects.
Parent topic: HTTP Parsing Rules


Recording ShopIt V 6.0 Without Parsing Rules

The Silk Performer sample Web application, ShopIt V 6.0, was deliberately built in such a way that the Recorder has to script the context-less function WebPageUrl() with a form definition that contains a session ID. This was achieved by having JavaScript assemble an URL.

Recording ShopIt V 6.0 without recording rules results in a script with a hard coded session ID, as shown in the following example.

WebPageUrl(sParsedUrl, "Unnamed page", SHOPITV60_ KINDOFPAYMENT_ASP002);

// …

dclform
  SHOPITV60_KINDOFPAYMENT_ASP002:
    "choice" := "CreditCard",
    "price"  := "69.9",
    "sid"    := "793663905";
Parent topic: Guided HTTP Parsing Rule Example


Customizing ShopIt V 6.0 With TrueLog Explorer

In executing a Try Script run, the hard-coded session ID causes a replay error. The session handling customization feature of TrueLog Explorer solves this problem, modifying the script as shown in the following example.
dclparam
  sSessionInfo1 : string;

dcluser
  user
    VUser
  transactions
    TInit : begin;
    TMain : 1;

var
  sFormSid1 : string;

// ...

  WebParseDataBoundEx(sSessionInfo1, STRING_COMPLETE,
    "name=\"", 3, "\"", WEB_FLAG_IGNORE_WHITE_SPACE
      | WEB_FLAG_CASE_SENSITIVE, 1);
  WebPageLink("Check out", "ShopIt - Check Out");// Link 3
  Print("sSessionInfo1: " + sSessionInfo1);

  sFormSid1 := sSessionInfo1;
  WebPageUrl("http://u2/ShopItV60/kindofpayment.asp",
    "Unnamed page", SHOPITV60_KINDOFPAYMENT_ASP003);

// ...

dclform
  SHOPITV60_KINDOFPAYMENT_ASP003:
    "choice" := "CreditCard",
    "price" := "15.9",

//  "sid" := "348363999";
    "sid" := sFormSid1;

A second Try Script run reveals that the customization was successful and that the script now runs correctly.

Parent topic: Guided HTTP Parsing Rule Example


Transferring Customization Details to the Recorder

The script runs correctly now that it has been customized. However a problem exists in that every script that will be recorded in the future must be also customized.

HTTP parsing rules enable the Recorder to continue this type of customization automatically in the future-so that recorded scripts can be automatically generated without needing manual customization.

To do this, research must be done into how the session ID can be parsed. The customization offered by TrueLog Explorer offers a good place to begin. It reveals the API call where the session ID first occurs, and boundaries that can be used to parse the session ID.

Using TrueLog Explorer, the first occurrence of the session ID can be located in the HTML code, as shown in the following example.

<script LANGUAGE="JavaScript">
  function doProcess(mylink)
  {
    scheme="http://";
    server="u2";
    serverport="";
    path="/ShopItV60/";
    file="kindofpayment.asp?";
    name="348364005";
    price="15.9";
    choice="CreditCard";
    mylink.href=scheme + server + serverport + path
    + file + "choice=" + choice + "&price="
    + price + "&sid=" + name;
  }
</script>

The left boundary ("name=\"") and the right boundary ("\"") identified by TrueLog Explorer seem to be reasonable choices for parsing the session ID. Now an initial version of a HTTP parsing rule can be written for the Recorder.

<?xml version="1.0" encoding="UTF-8" ?>
<RecordingRuleSet>
  <HttpParsingRule>
    <Name>ShopIt V6.0 Session Id</Name>
    <Search>
      <SearchIn>Body</SearchIn>
      <LB>
        <Str>name=&quot;</Str>
      </LB>
      <RB>
        <Str>&quot;</Str>
      </RB>
    </Search>
    <ScriptGen>
      <VarName>ShopItSessionId</VarName>
    </ScriptGen>
  </HttpParsingRule>
</RecordingRuleSet>

This rule file may be saved to the public RecordingRules directory of Silk Performer-so that the rule will be globally available to all projects. The file name doesn't matter, but the file extension ".xrl" must be used. Alternately, if the recording rule is to be used with only one project, the file may be saved to the Documents directory of a Silk Performer project.

ShopIt V 6.0 Session ID's don't appear in HTTP response headers, so it is specified that only response bodies are to be searched (using attribute Search\SearchIn).

The session ID can be found by searching a left boundary. This boundary is specified in the attribute Search\LB\Str. Note that the quote symbol must be encoded in XML using the character sequence "&quot;".

A single quote marks the end of session ID's. This is specified in the attribute Search\RB\Str. Here again, the quote character must be encoded.

Finally, specifics regarding how the variable for the parsing result should be named need to be defined. Names are specified using the attribute ScriptGen\VarName.

Parent topic: Guided HTTP Parsing Rule Example


Try the Recording Rule

When the rule is used in a recording session, the result is a recorded script with lots of variables.

var
  gsShopItSessionId : string; // Confirm-Button
  gsShopItSessionId_001 : string; // 348364008
  gsShopItSessionId_002 : string; // myForm
  gsShopItSessionId_003 : string; // address
  gsShopItSessionId_004 : string; // city
  gsShopItSessionId_005 : string; // state
  gsShopItSessionId_006 : string; // zip
  gsShopItSessionId_007 : string; // ZipCode
  gsShopItSessionId_008 : string; // cardtype
  gsShopItSessionId_009 : string; // cardnumber
  gsShopItSessionId_010 : string; // expiration
  gsShopItSessionId_011 : string; // sid

MYFORM004:
  gsShopItSessionId_003 := "a",
  gsShopItSessionId_004 := "b",
  gsShopItSessionId_005 := "c",
  gsShopItSessionId_006 := "" <SUPPRESS> ,
  gsShopItSessionId_007 := "d",
  gsShopItSessionId_008 := "Visa",
  gsShopItSessionId_009 := "111-111-111",
  gsShopItSessionId_010 := "07.04",
  gsShopItSessionId_011 := "" <USE_HTML_VAL> ;

This is because the rule is too general. The boundaries specified don't simply apply to the parsing of the session ID, they apply to almost all of the form fields. Although this doesn't prevent the script from replaying successfully, it's overkill.

Parent topic: Guided HTTP Parsing Rule Example


Create a More Specific Rule

A more specific rule that creates a parsing function only for the session ID is needed. There are several ways of achieving this.

The Recorder uses the boundary strings in the Search attribute of parsing rules to extract substrings from each HTTP response. These substrings are called "rule hits" or simple "hits." The Recorder remembers each hit. When scripting a string, the Recorder checks to see if any of the identified rule hits are included in the scripted string. If they are, the Recorder generates a parsing function for the rule hit and substitutes the resulting variable into the scripted strings.

Limit the number of rule hits

A more specific rule can be created based on the unique characteristics of ShopIt V 6.0 Session IDs.

Session ID properties to consider:
  • They consist of digits only.
  • Their length is always 9 digits.

Taking this into account, the rule can be extended.

Limit the number of rule hits by conditions

<?xml version="1.0" encoding="UTF-8" ?>
<RecordingRuleSet>

  <HttpParsingRule>
    <Name>ShopIt V6.0 Session Id</Name>
      <Search>
        <SearchIn>Body</SearchIn>
        <LB>
          <Str>name=&quot;</Str>
        </LB>
        <RB>
          <Str>&quot;</Str>
        </RB>
        <CondRegExpr>[0-9]+</CondRegExpr>
        <CondResultLen>9-9</CondResultLen>
      </Search>
    <ScriptGen>
      <VarName>ShopItSessionId</VarName>
    </ScriptGen>
  </HttpParsingRule>
</RecordingRuleSet>

The attribute Search\CondRegExpr specifies a regular expression that is applied to each rule hit. Rule hits that do not match this regular expression are dropped. The regular expression in the example above specifies that only rule hits consisting of digits are relevant.

The attribute Search\CondResultLen specifies a range of acceptable length for rule hits. Example above specifies that only hits with exactly nine characters are relevant. A subsequent recording session using this modified rule is successful: The recorded script contains a parsing function for the session ID only.

Script recorded using a modified rule

var
  gsShopItSessionId : string; // 348364011

dclform
  SHOPITV60_KINDOFPAYMENT_ASP003:
  "choice" := "CreditCard",
  "price" := "15.9",
  "sid" := gsShopItSessionId; // value: "348364011"

MYFORM004:
  "address" := "a", // changed
  "city" := "b", // changed
  "state" := "c", // changed
  "zip" := "" <SUPPRESS> , // value: ""
  "ZipCode" := "d", // added
  "cardtype" := "Visa", // added
  "cardnumber" := "111-111-111", // changed
  "expiration" := "07.04", // changed
  "sid" := "" <USE_HTML_VAL> ;//value:"348364011"

Specify allowed usage of rule hits

Rather than limiting the number of rule hits, one can be more specific in specifying where in scripts rule hits are to be used. Consider the following for this example: The session ID occurs only in form field values where the form field name is "sid". By extending the ScriptGen section of the parsing rule (as shown in the example below), rule hits are used only under these specific criteria.

Be more specific in script generation

<RecordingRuleSet>

  <HttpParsingRule>
    <Name>ShopIt V6.0 Session Id</Name>
    <Search>
      <SearchIn>Body</SearchIn>
      <LB>
        <Str>name=&quot;</Str>
      </LB>
      <RB>
        <Str>&quot;</Str>
      </RB>
    </Search>
    <ScriptGen>
      <VarName>ShopItSessionId</VarName>
      <ReplaceIn>FormFieldValue</ReplaceIn>
      <Conditions>
        <CompareData>
          <Data>sid</Data>
          <ApplyTo>FormFieldName</ApplyTo>
        </CompareData>
      </Conditions>
    </ScriptGen>
  </HttpParsingRule>

</RecordingRuleSet>

The attribute ScriptGen\ReplaceIn specifies that rule hits may only be used when the Recorder scripts a form field value. The condition additionally specifies that a replacement is allowed only if the associated form field name is sid. Recording with this modified rule generates a script that is identical to the script generated using the original rule.

Parent topic: Guided HTTP Parsing Rule Example


Creating a Conversion DLL

The conversion DLL has to be a native Win32 DLL (no .NET assembly). To create it in Microsoft Visual Studio, you have to create a Win32 project and select the application type DLL.

On 64-bit operating systems, Silk Performer uses a 64-bit process to analyze capture files and generate scripts. Thus, you have to build two versions of the conversion DLL: a 32-bit DLL, which is used for replaying scripts, and a 64-bit DLL, which is used for generating scripts. The 64-bit DLL has to be named <name of the 32-bit DLL>_x64.dll and located in the same directory as the 32-bit DLL.

If you cannot create a 64-bit DLL for any reason, you can force Silk Performer to use a 32-bit process for script generation by setting the following registry key to 1: HKEY_LOCAL_MACHINE\SOFTWARE\Silk\SilkPerformer\<version>\Force32BitCaptureAnalyzer.
Attention: Using the 32-bit script generator can cause issues with large capture files.

Silk Performer has provided sample Microsoft Visual Studio projects with header and .cpp files that give you guidance on how to create your own custom conversion DLL. The samples are located at <public user documents>\Silk Performer <version>\SampleApps\SampleConversion.

After you have created the project, there are some additional project settings to change:
  • The Character Set option has to be set to Use Multi-Byte Character Set (MBCS). This is a requirement, because the strings to be converted are passed as MBCS strings.
  • It is recommended that you use the static version of the C-runtime to remove dependencies to C-runtime DLLs. These dependencies could cause problems if the C-runtime DLLs (of used version) are not installed on the agent or controller machine. To use the static C-runtime libraries, change the Runtime Library setting in C++ / Code Generation to the following:
    • Multi-threaded (/MT) in the Release configuration
    • Multi-threaded Debug (/MTd) in the Debug configuration

Recommendation

If you reference the conversion DLL in a recording rule, you have to copy the DLL either into the Silk Performer recording rules directory or into the project directory. When developing the conversion DLL in Microsoft Visual Studio, you could copy the DLL to one of these directories (recording rules or project) in a post-build step or change the output directory path in the Release configuration to the recording rules directory.

Exporting the conversion function

You must export the conversion function with the following signature:

extern "C"
{
  __declspec( dllexport )
  long MyConversionFunction(
  LPCSTR sOriginalValue,
  LPSTR sConvertedValue,
  unsigned long* psConvertedValueLen,
  void* pReserved);
}

The purpose of using C linkage (extern "C") is to turn off C++ name mangling of the exported function. If using C++ linkage, other information like the types of arguments would be put into the exported name of the function. Use the "pure" function name as the exported function name (this is MyConversionFunction in the example above).

Function arguments:
sOriginalValue | The MBCS string value that has to be converted.
sConvertedValue | The string buffer that receives the converted value as MBCS string.
psConvertedValueLen | Points to a variable which contains the length of the string buffer sConvertedValue. This variable’s value has to be set to the number of bytes written to sConvertedValue if the conversion succeeded. This variable value has to be set to the number of bytes required for the converted value if the size of the string buffer sConvertedValue is too small.
pReserved | Reserved for future usage.
Return value
  • ERROR_SUCCESS (0): Returned if the conversion was successful. *psConvertedValueLen now contains the number of bytes written to sConvertedValue.
  • ERROR_INSUFFICIENT_BUFFER (122): Returned if the conversion failed because the size of of sConvertedValue (*psConvertedValueLen) is too small for the converted value. *psConvertedValueLen now contains the number of bytes required to store the converted value. The function will be called again with size of sConvertedValue increased to *psConvertedValueLen.
  • Return any other value to indicate that the conversion failed.
Parent topic: Guided HTTP Parsing Rule Example


Section Search - Finding Rule Hits

Details about finding rule hits are specified in the Search section. All XML paths of properties described in the section are relative to HttpParsingRule\Search.

  • Introduction
    Describes how to define boundaries and apply regular expressions.
  • LB\Str Attribute
    Shows the type and the default value of the attribute LB\Str, provides a description and an example.
  • LB\RegExpr Attribute
    Shows the type and the default value of the attribute, provides a description and an example.
  • LB\Offset Attribute
    Shows the type and the default value of the attribute LB\Offset, provides a description and an example.
  • RB\Str Attribute
    Shows the type and the default value of the attribute RB\Str, provides a description and an example.
  • RB\CharType Attribute
    Shows the type and the default value of the attribute RB\CharType, provides a description and an example.
  • RB\RegExpr Attribute
    Shows the type and the default value of the attribute RB\RegExpr, provides a description and an example.
  • RB\Length Attribute
    Shows the type and the default value of the attribute RB\Length, provides a description and an example.
  • RegExpr and RegExprTag Attribute
    Shows the type and the default value of the attributes RegExpr and RegExprTag, provides a description and an example.
  • SearchIn Attribute
    Shows the type and the default value of the attribute SearchIn and provides an example.
  • CaseSensitive Attribute
    Shows the type and the default value of the attribute CaseSensitive and provides a description.
  • IgnoreWhiteSpaces Attribute
    Shows the type and the default value of the attribute IgnoreWhiteSpaces, provides a description and an example.
  • CondContentType Attribute
    Shows the type and the default value of the attribute CondContentType, provides a description and an example.
  • CondRegExpr Attribute
    Shows the type and the default value of the attribute CondRegExpr, provides a description and an example.
  • CondResultLen Attribute
    Shows the type and the default value of the attribute CondResultLen and provides a description.
  • Conditions Attribute
    Shows the type and the default value of the attribute Conditions and provides a description.
  • Conversion\Dll Attribute
    Shows the type and the default value of the attribute Conversion\Dll and provides a description.
  • Conversion\Function Attribute
    Shows the type and the default value of the attribute Conversion\Function and provides a description.
Parent topic: HTTP Parsing Rules


Introduction

Rule hits can be extracted from HTTP responses in two ways:
  • by defining boundaries
  • by applying a regular expression

Defining boundaries

When a rule defines boundaries, any occurrence of a left boundary within an HTTP response marks the beginning of a rule hit. From this point onward within the HTTP response, the first occurrence of a right boundary marks the end of the rule hit.

Left boundaries can be defined in three ways:
  • Strings: Any occurrence of a given string in an HTTP response marks the beginning of a rule hit.
  • Regular Expressions: Any substring of a HTTP response that matches a specified regular expression marks the beginning of a rule hit.
  • Offset Calculations: HTTP responses are run through the Offset Calculation to determine the beginning of a rule hit. Offset Calculation is explained in section “Offset, Length”.
Right boundaries can be defined in four ways:
  • Strings: The next occurrence of a given string after the left boundary position marks the end of the rule hit.
  • Regular Expressions: The next sub string of the HTTP response matching the given regular expression after the left boundary position marks the end of the rule hit.
  • Length: The end of a rule hit is determined by running part of an HTTP response (from the beginning of the rule hit through to the end of the response) through a Length Calculation. Length Calculation is explained in Section “Offset, Length”.
  • Character type: The next character that matches a given set of character types marks the end of the rule hit.

Applying regular expressions

If a rule defines a regular expression, any substring of an HTTP response that matches that regular expression yields a rule hit. By default, the entire match is the rule hit. Alternately, the rule can define a tag number so that the tagged subexpression is the rule hit.

Note: Recording rules use the regular expression implementation as described in Structure of Regular Expressions. Additionally, some characters need special encoding since recording rules are stored in XML format. For more information, see Writing XML Files.
Parent topic: Section Search - Finding Rule Hits


LB\Str Attribute

Value | Description
Type | Binary Data
Default | (empty)
Description | This attribute specifies a string for searching rule hits. Each occurrence of this string marks the beginning of a rule hit. When searching, the attributes CaseSensitive and IgnoreWhiteSpaces are used.

Examples

<LB>
  <Str>name=&quot;</Str>
</LB>

<LB>
  <Str>BV_EngineID=</Str>
</LB>
Parent topic: Section Search - Finding Rule Hits


LB\RegExpr Attribute

Value | Description
Type | Strings
Default | (empty)
Description | This attribute specifies a regular expression for searching rule hits. Each substring of an HTTP response that matches the regular expression marks the beginning of a rule hit. When searching matching substrings, the attributes CaseSensitive and IgnoreWhiteSpaces are not used.

Examples

<LB>
  <RegExpr>name *= *[&quot;']</RegExpr>
</LB>

Matches:
 - name="
 - name = "
 - name= '
 - name   ='
 - ...
Note: Recording rules use the regular expression implementation as described in Structure of Regular Expressions. Additionally, some characters need special encoding since recording rules are stored in XML format. For more information, see Writing XML Files.
Parent topic: Section Search - Finding Rule Hits


LB\Offset Attribute

Value | Description
Type | Signed Numbers
Default | (empty)
Description | This attribute specifies an offset value for an Offset/Length calculation, as described in Section “Offset, Length”, Offset, Length. This calculation is applied to the entire HTTP response with the given offset and the length of 0. The beginning of the calculation's result marks the beginning of the rule hit.

Example

<LB>
  <Offset>17</Offset>
</LB>
Parent topic: Section Search - Finding Rule Hits


RB\Str Attribute

Value | Description
Type | Binary Data
Default | (empty)
Description | This attribute specifies a string that searches for the end of rule hits. It is used with the beginning of each rule hit identified using LB\Str, LB\RegExpr or LB\Offset. The attributes CaseSensitive and IgnoreWhiteSpaces are used during searches.

Example

<RB>
  <Str>&quot;</Str>
</RB>
Parent topic: Section Search - Finding Rule Hits


RB\CharType Attribute

Value | Description
Type | Distinct Value Lists
Default | (empty)
Description | This attribute specifies a list of character types and is used to search for the end of each rule hit found using LB\Str, LB\RegExpr or LB\Offset. The ends of rule hits are defined by the first character that matches one of the character types specified below.
Allowed values are:
  • UpperCase: Uppercase characters
  • LowerCase: Lowercase characters
  • NewLine: Newline characters
  • Digit: Digits 0-9
  • HexDigit: Hexadecimal digits 0-9, a-z, A-Z
  • Letter: letters a-z, A-Z
  • White: Whitespaces
  • WhiteNoSpace: Whitespaces, excluding blank spaces
  • Printable: Printable characters
  • NonPrintable: Non-printable characters
  • EndOfString: End of Strings (single and double quote)
  • NonBase64: Characters not used in Base 64 encoding

Example

<RB>
  <CharType>EndOfString, White</CharType>
</RB>
Parent topic: Section Search - Finding Rule Hits


RB\RegExpr Attribute

Value | Description
Type | Strings
Default | (empty)
Description | This attribute specifies a regular expression that searches for the end of rule hits. It is used with the beginning of rule hits found using LB\Str, LB\RegExpr or LB\Offset. The attributes CaseSensitive and IgnoreWhiteSpaces are not used during searches.

Example

<RB>
  <RegExpr>[&quot;' *value]</RegExpr>
</RB>

Matches:
 - ]
 - "
 - '
 -  (blank char)
 - *
 - v
 - a
 - l
Note: Recording rules use the regular expression implementation as described in Structure of Regular Expressions. Additionally, some characters need special encoding since recording rules are stored in XML format. For more information, see Writing XML Files.
Parent topic: Section Search - Finding Rule Hits


RB\Length Attribute

Value | Description
Type | Signed Numbers
Default | (empty)
Description | This attribute specifies a length value for an Offset/Length calculation, as described in section “Offset, Length”. The calculation is applied from the portion of an HTTP response where a rule hit begins through to the end of the response; it uses the offset of 0, and the given length. The end of the calculation's result marks the end of the rule hit.

Example

<RB>
  <Length>4</Length>
</RB>
Parent topic: Section Search - Finding Rule Hits


RegExpr and RegExprTag Attribute

Value | Description
Type | Strings, Numbers
Default | (empty), 0
Description

These two attributes specify a regular expression that is used for searching rule hits. If the attribute RegExprTag is not omitted, it must specify the number of a tagged sub-expression within the given regular expression.

Rule hits are searched for by applying the given regular expression to HTTP responses. Each substring of an HTTP response that matches the regular expression is a rule hit. If the attribute RegExprTag is specified, the rule hit is not the entire match, but the given tagged sub-expression.

Example

<RegExpr>name=&quot;\([0-9]+\)&quot;</RegExpr>
<RegExprTag>1</RegExprTag>

Matches:
 - name="1234"
 - name="0"
 - name="007"
 - ...
Note: Recording rules use the regular expression implementation as described in Structure of Regular Expressions. Additionally, some characters need special encoding since recording rules are stored in XML format. For more information, see Writing XML Files.
Parent topic: Section Search - Finding Rule Hits


SearchIn Attribute

Value | Description
Type | Distinct Value Lists
Default | All
Allowed values are:
  • All: This is an abbreviation for the complete list of other values.
  • Header: Search HTTP response headers
  • Body: Search HTTP response bodies
  • HeaderName: Refers to the first parameter of the function WebHeaderAdd.
  • HeaderValue: Refers to the second parameter of the function WebHeaderAdd.

This attribute specifies where to search for rule hits, either in response headers, response bodies, or both.

Example

<SearchIn>Body</SearchIn>
<SearchIn>Header</SearchIn>
Parent topic: Section Search - Finding Rule Hits


CaseSensitive Attribute

Value | Description
Type | Boolean Values
Default | false
Description

This attribute specifies whether searches should be case-sensitive or caseinsensitive when searching the strings LB\Str and RB\Str.

It also specifies if the option flag WEB_FLAG_CASE_SENSITIVE should be scripted when scripting the function WebParseDataBoundEx.

Parent topic: Section Search - Finding Rule Hits


IgnoreWhiteSpaces Attribute

Shows the type and the default value of the attribute and provides a description.

Value | Description
Type | Boolean Values
Default | true
Description

This attribute specifies whether searches should ignore white spaces when searching the strings LB\Str and RB\Str.

It also specifies whether to script the option flag WEB_FLAG_IGNORE_WHITE_SPACE when scripting the function WebParseDataBoundEx.

Parent topic: Section Search - Finding Rule Hits


CondContentType Attribute

Value | Description
Type | Strings
Default | (empty)
Description | This attribute specifies a string that restricts rule hit searches to server responses that match the specified content type. The comparison is done using a prefixmatch.

Example

<CondContentType>text/</CondContentType>

This restricts the searching for rule hits to server responses with a content type such as "text/html" or "text/plain."

Parent topic: Section Search - Finding Rule Hits


CondRegExpr Attribute

Value | Description
Type | Strings
Default | (empty)
Description | This attribute specifies a regular expression that is used to determine if a rule hit should be retained for future use. Each rule hit is checked to see if it matches the regular expression. Matching rule hits are retained, non-matching rule hits are dropped.

Example

<CondRegExpr>eCS@Store@[0-9]+-.*</CondRegExpr>

Matches:
- eCS@Store@01234-Any other characters, even special chars like '"'
- eCS@Store@0-
- eCS@Store@987-0
- …
Note: Recording rules use the regular expression implementation as described in Structure of Regular Expressions. Additionally, some characters need special encoding since recording rules are stored in XML format. For more information, see Writing XML Files.
Parent topic: Section Search - Finding Rule Hits


CondResultLen Attribute

Value | Description
Type | Numeric Ranges
Default | 2-
Description | This attribute specifies a range that is used to determine if a rule hit should be retained for future use. If the number of bytes in the hit doesn't match the given range, the hit is dropped.
Parent topic: Section Search - Finding Rule Hits


Conditions Attribute

Value | Description
Type | Structured Data
Description

This attribute specifies conditions that are applied to determine if a rule hit should be retained for future replacement.

The conditions for each rule hit are evaluated within an environment that allows access to the HTTP request/response that included the hit, in addition to other relevant data.

If the conditions aren't determined to be true, the hit is dropped. See “Conditions” for more information regarding conditions. See the Section “ConditionEvaluation Environment” for more information regarding what may be subject to conditions.

Parent topic: Section Search - Finding Rule Hits
Parent topic: Scripting Parsing Functions and Replacements


Conversion\Dll Attribute

Value | Description
Type | Strings
Default | (empty)
Description | This attribute is the name of the conversion DLL used for modifying a parsed value. Make sure that the conversion DLL specified is added as a data file. The runtime searches for the DLL in the project directory and in the recording rules directory.
Parent topic: Section Search - Finding Rule Hits


Conversion\Function Attribute

Value | Description
Type | Strings
Default | (empty)
Description | This attribute is the name of the conversion function exported by the conversion DLL.
Parent topic: Section Search - Finding Rule Hits


Scripting Parsing Functions and Replacements

While the Search section specifies how to find rule hits in HTTP responses, the ScriptGen section specifies details regarding script generation. All XML paths of attributes described here are relative to: HttpParsingRule\ScriptGen.

The ScriptGen section allows users to specify conditions that restrict the usage of rule hits to script locations where replacement is appropriate, and to exclude locations where rule hits appear purely by coincidence. Additionally, some attributes can be used to instruct the Recorder as to which variable names to use and what comments are to be added to scripts to increase their readability.

  • VarName Attribute
    Shows the type and the default value of the attribute VarName and provides a description.
  • OnlyIfCompleteResult Attribute
    Shows the type and the default value of the attribute OnlyIfCompleteResult and provides a description.
  • MaxLbLen Attribute
    Shows the type and the default value of the attribute MaxLbLen and provides a description.
  • ReplaceIn Attribute
    Shows the type and the default value of the attribute ReplaceIn and provides a description.
  • AlwaysNewFunc Attribute
    Shows the type and the default value of the attribute AlwaysNewFunc and provides a description.
  • CommentToVar Attribute
    Shows the type and the default value of the attribute CommentToVar and provides a description.
  • CommentToFunc Attribute
    Shows the type and the default value of the attribute CommentToFunc and provides a description.
  • GenBytesReadVar Attribute
    Shows the type and the default value of the attribute GenBytesReadVar and provides a description.
  • GenDebugPrint Attribute
    Shows the type and the default value of the attribute GenDebugPrint and provides a description.
  • Conditions Attribute
    Shows the type and the default value of the attribute Conditions and provides a description.
  • Tokenizing of Rule Hits
    Describes how to extract rule hits by tokenizing the search result.
Parent topic: HTTP Parsing Rules


VarName Attribute

Value | Description
Type | Strings
Default | (empty)
Description | This attribute specifies a variable name to script for the result of parsing functions. If omitted, the name of the rule is used as the variable name.
Parent topic: Scripting Parsing Functions and Replacements


OnlyIfCompleteResult Attribute

Value | Description
Type | Boolean Value
Default | false
Description | This attribute specifies that a replacement should be scripted only if a complete string to be scripted can be replaced with a single variable. If false, replacements are scripted when a rule hit is a substring of the string to be scripted.
Parent topic: Scripting Parsing Functions and Replacements


MaxLbLen Attribute

Value | Description
Type | Numbers
Default | Max unsigned
Description | When scripting a parsing function, the Recorder chooses a left boundary. This attribute can be used to specify a maximum length for the left boundary, in cases where there is danger that the left boundary may contain session information.
Parent topic: Scripting Parsing Functions and Replacements


ReplaceIn Attribute

Value | Description
Type | Distinct Value Lists
Default | All
Description This attribute specifies script locations that may contain hits to be replaced. Valid values are:
  • All: This is an abbreviation for the complete list of other values.
  • Url: Replace in URL parameters (various functions, for example WebPageUrl)
  • LinkName: Replace in link names (function WebPageLink). Link names that result from WebPageParseUrl are not replaced.
  • FormName: Replace in form names (function WebPageSubmit)
  • PostedData: Replace in binary posted data (various functions, for example WebPagePost)
  • FormFieldName: Form field name in the dclform section of the script
  • FormFieldValue: Form field value in the dclform section of the script
  • SetCookie: Parameter of the function WebCookieSet
  • HeaderName: Refers to the first parameter of the function WebHeaderAdd.
  • HeaderValue: Refers to the second parameter of the function WebHeaderAdd.
Parent topic: Scripting Parsing Functions and Replacements


AlwaysNewFunc Attribute

Value | Description
Type | Boolean Values
Default | false
Description | This attribute specifies whether or not a rule hit, once parsed, can be reused or if the Recorder should script a new parsing function to parse the most recent occurrence of the string to be replaced.
Parent topic: Scripting Parsing Functions and Replacements


CommentToVar Attribute

Value | Description
Type | Boolean Values
Default | true
Description | This attribute specifies whether or not a comment should be generated for the variable that contains the parsing result. If true, a comment that includes the value during recording is generated.
Parent topic: Scripting Parsing Functions and Replacements


CommentToFunc Attribute

Value | Description
Type | Boolean Values
Default | false
Description | This attribute specifies whether or not a comment should be generated for the parsing function WebParseDataBoundEx. If true, a comment is generated during recording that includes the rule name that triggered the parsing function and the parsing result during recording.
Parent topic: Scripting Parsing Functions and Replacements


GenBytesReadVar Attribute

Value | Description
Type | Boolean Values
Default | false
Description | This attribute specifies whether or not to generate a variable for the number of bytes parsed by a parsing function (see WebParseDataBoundEx, parameter nBytesParsed).
Parent topic: Scripting Parsing Functions and Replacements


GenDebugPrint Attribute

Value | Description
Type | Boolean Values
Default | false
Description | This attribute specifies whether or not to generate a diagnostic Print function after the script function where a generated parsing function is in effect. If true, a Print function that prints the parsing result to the Silk Performer controller output window is scripted.
Parent topic: Scripting Parsing Functions and Replacements


Tokenizing of Rule Hits

The Search section used both in HttpParsingRules and StringScriptingRules contains a feature that allows to extract rule hits by tokenizing the search result. The idea is that each substring extracted (for example, using the various left/right boundary options) is not the rule hit itself, but can be "tokenized" to yield several rule hits. This tokenizing can be done in several ways and is specified by the xml tag Tokenize.

Valid values for the tag Tokenize are:
  • SiebelTokenHtmlSingleQuote
  • SiebelTokenHtml
  • siebelTokenApplet

The tokenizing methods SiebelTokenHtmlSingleQuote and SiebelTokenHtml tokenize the search result into individual strings enclosed either in single or in double quotes. The tokenizing method SiebelTokenApplet tokenizes the search result assuming a series of length prefixed strings as used in applet responses in the Siebel 7 web application.

Example for SiebelTokenHtml

The search result ["TestName","TestSite","USD","02/21/2003","N","1-2T"] will be tokenized and results in the following rule hits:
  • TestName
  • TestSite
  • USB
  • 02/21(2003
  • N
  • 1-2T

Example for SiebelTokenApplet

The search result 19*02/21/2003 08:20:176*SADMIN4*Note5*1-1P5 will be tokenized and results in the following rule hits:
  • 02/21/2003 08:20:17
  • SADMIN
  • Note
  • 1-1P5
The recorder will use these rule hits in the script by generating one of the tokenizing functions to extract the tokens at runtime. For a recording rule with tokenizing in the Search section:
<HttpParsingRule>
  <Name>Siebel Submit Data Array in HTML (from Javascript function call)</Name>
  <Active>true</Active>
  <Search>
    <SearchIn>Body</SearchIn>
    <LB>
      <Str>SWESubmitForm</Str>
    </LB>
    <RB>
      <Str>'</Str>
    </RB>
    <Tokenize>SiebelTokenHtml</Tokenize>
    <CondResultLen>1-</CondResultLen>
  </Search>
  <ScriptGen>
    ...
  </ScriptGen>
</HttpParsingRule>
Script fragments from Siebel where tokenizing is used:
var
gsRowValArray_003 : string; // 0*19*02/21/2003 08:20:176*SADMIN4*Note5*1-1P5
// ...
WebParseDataBoundEx(gsRowValArray_003, sizeof(gsRowValArray_003),
"ValueArray`", WEB_OCCURENCE_LAST, "`",
WEB_FLAG_IGNORE_WHITE_SPACE, 1);
WebPageForm("http://lab72/sales_enu/start.swe", SALES_ENU_START_SWE026,
"Account Note Applet: InvokeMethod: NewRecord");
Print("Parsed \"RowValArray_003\", result: \"" + gsRowValArray_003 + "\"");
// Was "0*19*02/21/2003 08:20:176*SADMIN4*Note5*1-1P5" when recording
// ...
dclform
// ...
SALES_ENU_START_SWE027:
"SWEMethod" := "GetQuickPickInfo",
"SWEVI" := "",
"SWEView" := "Account Note View",
"SWEApplet" := "Account Note Applet",
"SWEField" := "s_2_2_24_0",
"SWER" := "0",
"SWEReqRowId" := "1",
"s_2_2_26_0" := "2/21/2003 08:20:17 AM",
"s_2_2_27_0" := SiebelTokenApplet(gsRowValArray_003, 2), // value: "SADMIN"
"s_2_2_24_0" := SiebelTokenApplet(gsRowValArray_003, 3), // value: "Note"
"s_2_2_25_0" := "",
"SWERPC" := "1",
"SWEC" := "11",
"SWEActiveApplet" := "Account Note Applet",
"SWEActiveView" := "Account Note View",
"SWECmd" := "InvokeMethod",
"SWERowId" := SiebelTokenApplet(gsRowValArray_003, 4),
// value: "1-1P5"
"SWERowIds" := "SWERowId0=" + SiebelTokenHtml(gsRowValArray_002, 18),
// value: "SWERowId0=1-2T"
"SWEP" := "",
"SWEJI" := "false",
"SWETS" := GetTimeStamp(); // value: "1045844419057"
Parent topic: Scripting Parsing Functions and Replacements


Section ScriptGen

This section describes the ScriptGen section and the respective attributes.

  • MinRbLen LinLbLen
    Shows the type and the default value of the attributes MinRbLen and LinLbLen, provides a description and an example.
  • LastOccurence
    Shows the type and the default value of the attribute LastOccurence and provides a description.
  • ExpectBinaryData
    Describes the attribute ExpectBinaryData.
  • Conversion\Bdl Attribute
    Describes the attribute Conversion\Bdl.
  • Attribute Action
    Shows the values of the attribute Action and provides an example.
  • Attributes VarName VarNamePrefix IsExternalVar
    Provides a description for the attributes VarName, VarNamePrefix, and IsExternalVar.
Parent topic: HTTP Parsing Rules
Parent topic: StringScriptingRule


MinRbLen LinLbLen

Value | Description
Type | Numbers
Default | 1
Description | This option allows to specify a minimum length for the right / left boundary string which will be determined by the recorder and scripted as a parameter of the function call WebParseDataBoundEx.

Examples

<LB>
  <Str>name=&quot;</Str>
</LB>

<LB>
  <Str>BV_EngineID=</Str>
</LB>
Parent topic: Section ScriptGen


LastOccurence

Value | Description
Type | Boolean Values
Default | false
Description | If this option is set to true, the recorder will script the constant WEB_OCCURENCE_LAST instead of the actual occurence of the left boundary, if the found occurence indeed was the last one during recording.
Parent topic: Section ScriptGen


ExpectBinaryData

If this option is set to true, the recorder will generate a "bin-cast" for every use of the variable which is generated by this rule. This is necessary with the introduction of dynamic strings, if it is expected that the parsing result will contain binary data.

Instead of "SomeText" + gsParsedValue + "some other text", the recorder will generate "SomeText" + bin(gsParsedValue) + "some other text".

Default: false

Parent topic: Section ScriptGen


Conversion\Bdl Attribute

This attribute is optional. It is the name of the BDL function wrapping the call of the conversion DLL function. If missing or left empty, the BDL wrapper function will have the same name as the Conversion\Dll Attribute function.

Parent topic: Section ScriptGen


TCP/IP Protocol Rules

The Recorder uses TCP/IP protocol rules to detect proprietary TCP/IP protocols. If detected, the Recorder generates functions (depending on the protocol detected) that are better suited to handling dynamic server responses than is the WebTcpipRecvExact function, which is automatically scripted for unknown protocols.

  • Types of TCP/IP Protocol Rules
    Describes the two types of TCP/IP Protocol Rules: TcpRuleRecvProto and TcpRuleRecvUntil.
  • Structure of TCP/IP Protocol Rules
    Describes the basic structure that both types of TCP/IP protocol rules share.
  • TcpRuleRecvProto
    Describes the TcpRuleRecvProto rule and the respective attributes.
  • Guided TcpRuleRecvProto Example
    Shows examples of how to use the TcpRuleRecvProto rule.
  • TcpRuleRecvUntil
    Describes the TcpRuleRecvUntil rule and the respective attributes.
  • Guided TcpRuleRecvUntil Example
    Shows examples of how to use the TcpRuleRecvUntil rule.
Parent topic: Rule-Based Recording


Types of TCP/IP Protocol Rules

There are two types of TCP/IP protocol rules.

TcpRuleRecvProto

Use TcpRuleRecvProto rules to describe length-based protocols. Length-based protocols are protocols in which the number of bytes to be received from the server can be extracted from a fixed location in a protocol header. This rule type is specified by XML nodes with the name TcpRuleRecvProto.

TcpRuleRecvUntil

Use TcpRuleRecvUntil rules to describe protocols in which the end of a server response can be detected by a terminating sequence of bytes. This rule type is specified by XML nodes with the name TcpRuleRecvUntil.

Parent topic: TCP/IP Protocol Rules


Structure of TCP/IP Protocol Rules

Both types of TCP/IP protocol rules share the same basic structure. The Identify section contains attributes specific to the rule type. The Conditions section contains additional conditions that can be specified to avoid "detecting" protocols where they should not be detected (in cases where server responses coincidentally resemble protocols).
<TcpRuleRecvProto>
  <Name>Sample TCP RecvProto Rule</Name>
  <Active>true</Active>
  <Identify>
    …
  </Identify>
  <Conditions>
    …
  </Conditions>
</TcpRuleRecvProto>

<TcpRuleRecvUntil>
  <Name>Sample TCP RecvUntil Rule</Name>
  <Active>true</Active>
  <Identify>
    …
  </Identify>
  <Conditions>
    …
  </Conditions>
</TcpRuleRecvUntil>
Parent topic: TCP/IP Protocol Rules


TcpRuleRecvProto

The TcpRuleRecvProto rule type describes protocols with the following basic structure:

The number of bytes to be received can be extracted from the protocol header at offset LengthOffset using LengthLen number of bytes. This can be interpreted either in big endian or little endian representation. Additionally, the obtained value may be multiplied by a value (attribute LengthFactor), and/or a constant value may be added (attribute LengthAdd).

  • Identify\LengthOffset Attribute
    Shows the type and the default value of the attribute Identify\LengthOffset and provides a description.
  • Identify\LengthLen Attribute
    Shows the type and the default value of the attribute Identify\LengthLen and provides a description.
  • Identify\OptionFlags Attribute
    Shows the type and the default value of the attribute Identify\OptionFlags and provides a description.
  • Identify\LengthFactor Attribute
    Shows the type and the default value of the attribute Identify\LengthFactor and provides a description.
  • Identify\LengthAdd Attribute
    Shows the type and the default value of the attribute Identify\LengthAdd and provides a description.
  • Conditions
    Describes additional conditions that can be specified to exclude the "detection" of protocols.
  • GenVerify Attribute Of Conditions
    Shows the type and the default value of the attribute Identify\LengthAdd and provides a description.
Parent topic: TCP/IP Protocol Rules


Identify\LengthOffset Attribute

Value | Description
Type | Numbers
Default | 0

This attribute specifies the offset of the length specification within the protocol header. This corresponds to the parameter nProtoStart of the functions WebTcpipRecvProto(Ex).

Parent topic: TcpRuleRecvProto


Identify\LengthLen Attribute

Value | Description
Type | Numbers
Default | 4

This attribute specifies the number of bytes for the length specification within the protocol header. This corresponds to the parameter nProtoLength of the functions WebTcpipRecvProto(Ex).

Parent topic: TcpRuleRecvProto


Identify\OptionFlags Attribute

Value | Description
Type | Distinct Value Lists
Default | (empty)

This attribute specifies how to interpret the length specification. Valid values correspond to the options available for the parameter nOption of the functions WebTcpipRecvProto(Ex). The empty default value means: big endian.

Valid values are:
  • LittleEndian: Option TCP_FLAG_LITTLE_ENDIAN
  • ProtoIncluded: Option TCP_FLAG_INCLUDE_PROTO
Parent topic: TcpRuleRecvProto


Identify\LengthFactor Attribute

Value | Description
Type | Numbers
Default | 1

This attribute specifies a factor. The protocol length is multiplied by this factor. This corresponds to the parameter nMultiply of the function WebTcpipRecvProtoEx.

Parent topic: TcpRuleRecvProto


Identify\LengthAdd Attribute

Value | Description
Type | Signed Numbers
Default | 0

This property specifies a constant value. This value is added to the protocol length. This corresponds to the parameter nSum of the function WebTcpipRecvProtoEx.

Parent topic: TcpRuleRecvProto


Conditions

Additional conditions can be specified to exclude the "detection" of protocols in situations where server responses coincidentally resemble protocol specifications.

See “Conditions” for more information regarding conditions. See section “Condition Evaluation Environment” for more information regarding what may be subject to conditions.

Parent topic: TcpRuleRecvProto
Parent topic: TcpRuleRecvUntil


GenVerify Attribute Of Conditions

Value | Description
Type | Boolean Values
Default | false

In the course of specifying basic conditions, the attribute GenVerify can be used to specify scripting for the parameters sVerify, nVerifyStart and nVerifyLength of the function WebTcpipRecvProtoEx.

When the conditions are evaluated, the first basic condition that results in an evaluation of true and specifies the attribute GenVerify, determines that the data to which this condition has been applied should be used to script the verification part of the function WebTcpipRecvProtoEx.

Parent topic: TcpRuleRecvProto


Guided TcpRuleRecvProto Example

This example illustrates how to write a recording rule for the Siebel 6 Thin Client.

This client is an ActiveX control that runs in a Web browser. A recorded script consists of one WebPageUrl() call followed by TCP/IP traffic from the ActiveX control. Without recording rules, the server responses are scripted by WebTcpipRecvExact() calls.

Portion of a Recorded Siebel 6 TCP/IP Script

WebTcpipSendBin(hWeb0,
  "\h00000030000000000000000000000001" // ···0············ 00000000
  "\h0000000C0000001C0000019100000000" // ················ 00000010
  "\h00000020000002580000000C00000000" // ··· ···X········ 00000020
  "\h00000000", 52); // ···· 00000030
WebTcpipRecvExact(hWeb0, NULL, 40);

Server responses can be analyzed with the help of TrueLog Explorer.

Each response contains a protocol header consisting of 4 bytes that specify the number of bytes following the protocol header. This length specification is in big endian notation (most significant byte first).

With these findings a recording rule can be written, as shown below.

Recording Rule for Siebel 6 Thin Client TCP/IP Traffic

<?xml version="1.0" encoding="UTF-8" ?>
<RecordingRuleSet>
  <TcpRuleRecvProto>
    <Name>Siebel TCP Protocol</Name>
    <Identify>
      <LengthOffset>0</LengthOffset>
      <LengthLen>4</LengthLen>
    </Identify>
  </TcpRuleRecvProto>
</RecordingRuleSet>

This rule specifies that the protocol header contains the length of the data block at offset 0 using 4 bytes. Using this rule, the Recorder generates scripts that use the function WebTcpipRecvProto() for the server responses, as shown below.

Portion of a Recorded Script using Recording Rules

WebTcpipSendBin(hWeb0,
  "\h00000030000000000000000000000001" // ···0············ 00000000
  "\h0000000C0000001C0000019100000000" // ················ 00000010
  "\h0000001F000002580000000C00000000" // ·······X········ 00000020
  "\h00000000", 52); // ···· 00000030
WebTcpipRecvProto(hWeb0, 0, 4);

Scripts recorded with this rule replay correctly even when the number of bytes to be received differs from the number of bytes received during recording.

Parent topic: TCP/IP Protocol Rules


TcpRuleRecvUntil

The TcpRuleRecvUntil rule type specifies protocols whereby the end of a server response can be detected by searching for a terminating byte sequence.
  • Identify\TermData Attribute
    Shows the type and the default value of the attribute Identify\TermData and provides a description.
  • Identify\IgnoreWhiteSpaces Attribute
    Shows the type and the default value of the attribute Identify\IgnoreWhiteSpaces and provides a description.
  • Conditions
    Describes additional conditions that can be specified to exclude the "detection" of protocols.
Parent topic: TCP/IP Protocol Rules


Identify\TermData Attribute

Value | Description
Type | Binary Data
Default | (empty)
This attribute specifies the terminating byte sequence of the protocol.
Parent topic: TcpRuleRecvUntil


Identify\IgnoreWhiteSpaces Attribute

Value | Description
Type | Boolean Values
Default | false
This attribute specifies whether or not the Recorder should ignore white spaces while searching for terminating data. Scripted terminating data (parameter sPattern of the function WebTcpipRecvUntil) exactly reflects what was seen during recording and therefore, with respect to white spaces, may differ from what is specified in the property Identify\TermData.
Parent topic: TcpRuleRecvUntil


Guided TcpRuleRecvUntil Example

This example shows how to improve recorded scripts for telnet sessions.

Recording a telnet session without recording rules results in scripts that have lots of WebTcpipRecvExact() function calls, as shown below.

Portion of a recorded Telnet script without recording rules

WebTcpipSend(hWeb0, "l");
WebTcpipRecvExact(hWeb0, NULL, 1);
WebTcpipSend(hWeb0, "s\r\n");
WebTcpipRecvExact(hWeb0, NULL, 1);
WebTcpipRecvExact(hWeb0, NULL, 2);
WebTcpipRecvExact(hWeb0, NULL, 1220);

TrueLog Explorer is used to analyze server responses. Each server response ends with a command prompt. The command prompt ends with the three-character sequence blank, hash, blank, which seems a reasonable choice for the terminating data of a server response.

A recording rule can be written for this kind of server response. The rule instructs the Recorder to watch for server responses that end with the special terminating sequence, and to script the function WebTcpipRecvUntil() instead of WebTcpipRecvExact() for those server responses.

TCP/IP recording rule for Telnet

<?xml version="1.0" encoding="UTF-8" ?>
<RecordingRuleSet>
  <TcpRuleRecvUntil>
    <Name>Telnet Command Prompt</Name>
    <Active>true</Active>
    <Identify>
      <TermData> # </TermData>
      <IgnoreWhiteSpaces>false</IgnoreWhiteSpaces>
    </Identify>
    <Conditions>
      <NoBlockSplit>true</NoBlockSplit>
    </Conditions>
  </TcpRuleRecvUntil>
</RecordingRuleSet>

The terminating data is specified in the attribute Identify\TermData. Since the terminating data contains significant white spaces, not to ignore white spaces must be specified in the attribute Identify\IgnoreWhiteSpaces.

The rule should not be applied if a server response coincidentally contains the same terminating sequence elsewhere in the response. Therefore the condition NoBlockSplit should be specified. This means that the end of the terminating data must be aligned with the end of a TCP/IP packet received from the telnet server; otherwise the rule won't be applied.

Portion of a recorded Telnet script using a recording rule

WebTcpipSend(hWeb0, "l");
WebTcpipRecvExact(hWeb0, NULL, 1);
WebTcpipSend(hWeb0, "s");
WebTcpipRecvExact(hWeb0, NULL, 1);
WebTcpipSend(hWeb0, "\r\n");
WebTcpipRecvUntil(hWeb0, NULL, 0, NULL, " # ");

This example shows that the rule works. This script is better equipped to handle varying server responses during replay.

Note that the terminating sequence may be different for other Telnet servers and may depend on operating system and user settings. Therefore the rule shown here is not a general rule that works for all Telnet servers. It can however easily be adapted by changing the terminating character sequence. With the help of TrueLog Explorer, it's easy to determine suitable terminating byte sequences for other Telnet servers.

Parent topic: TCP/IP Protocol Rules


StringScriptingRule

The purpose of the StringScriptingRule is to hook into the process of scripting strings.

Whenever the Web recorder generates a string into the script (no matter where, this can be any parameter of an API function or a form field name or value), rules of this type are evaluated and may result in special actions, so that the string is not generated "as is", but processed in some way.

  • Structure
    Describes the basic structure of a StringScriptingRule.
  • Section Search
    Describes the search section of a StringScriptingRule.
  • Section ScriptGen
    Describes the ScriptGen section and the respective attributes.
Parent topic: Rule-Based Recording


Structure

The basic structure of a StringScriptingRule is very similar to the structure of a HttpParsingRule. It also consists of two sections named Search and ScriptGen (see example below).

<StringScriptingRule>
  <Name>Replace TimeStamp</Name>
  <Active>true</Active>
  <Search>
    <SearchIn>FormFieldValue</SearchIn>
    <LB>
      <Offset>0</Offset>
    </LB>
    <RB>
      <Length>0</Length>
    </RB>
  </Search>
  <ScriptGen>
    <Action>CheckTimeStamp</Action>
  </ScriptGen>
</StringScriptingRule>
Parent topic: StringScriptingRule


Section Search

While the details of the Search section of a HttpParsingRule are applied to any HTTP response (with the goal to extract rule hits which are candidates for future replacements), the Search section of a StringScriptingRule is applied to the string being scripted, with the goal to extract substrings that should be treated in a special way. All techniques how substrings can be extracted (see “Section Search - Finding Rule Hits”) can also be used in the Search section of a StringScriptingRule.

The only difference is the meaning of the attribute SearchIn:

For a HttpParsingRule, the attribute SearchIn specifies where to look for rule hits. Allowed values are: Header, Body, All.

For a StringScriptingRule, the attribute SearchIn specifies a list of script locations where this rule should be applied. This can be a list of script locations for the condition type Scripting, as described in “Scripting Condition”.

Additionally, there are two new script locations HeaderName and HeaderValue, which identify the two parameters of the function WebHeaderAdd. See “Additional ApplyTo values” for detailed information.

There is one additional possibility how to search for substrings (which is also applicable in the Search section of a HttpParsingRule):

The attribute Special allows to specify a special search algorithm. The only value currently supported is SiebelParam. This will search the string for any substring that looks like a length-prefixed value as it is used in the Siebel 7 Web application.

<StringScriptingRule>
  <Name>SiebelParam Function Call</Name>
  <Active>true</Active>
  <Search>
    <SearchIn>FormFieldValue</SearchIn>
    <Special>SiebelParam</Special>
    <Conditions>
    </Conditions>
  </Search>
  <ScriptGen>
    <Action>CheckSiebelParam</Action>
  </ScriptGen>
</StringScriptingRule>
Parent topic: StringScriptingRule


Attribute Action

This attribute specifies which action should be taken for the substring identified by the Search section.

The following values are allowed:

Value | Description
CreateVariable | This will create a variable initialized to the value of the string, and the variable will be substituted in the script instead of the original value.
CheckTimeStamp | This will create the function call GetTimeStamp() instead of the original string, if the original string indeed looks like a plausible timestamp value.
CheckSiebelParam | Checks if the original string is structured like a length prefixed value like used in the Siebel 7 Web application. If so, it will replace the original value with the function call Siebel7Param(...). Example: "5*Value" will become: Siebel7Param("Value")
DecodeSiebelJavaScriptString | Checks if the original string contains special characters that are usually escaped with a backslash within JavaScript code, modifies the string in a way it would be if it was embedded in JavaScript code, and creates the function SiebelDecodeJsString(...) with the encoded string as parameter. The function SiebelDecodeJsString will reverse this encoding during script replay, so that the same network traffic is generated. The purpose of this is that the modified parameter may now be parseable by HttpParsingRules, which might not be possible without this substitution.
CheckSiebelDateTime | Checks if the original string looks like a date/time combination in the format which is sent by the Siebel Web client, and transforms it to an equivalent date/ time combination in the format which appears in server responses to the Siebel Web client. If this is the case, the wrapper function SiebelDateTime is recorded which undoes this transformation during script replay. The purpose of this is that date/time combinations can then be parsed by the other parsing rules, because they appear in the script in the same format as they appear in server responses.
CheckSiebelDate | The same as CheckSiebelDateTime, but for dates only. Records the wrapper function SiebelDate.
CheckSiebelTime | The same as CheckSiebelDateTime, but for times only. Records the wrapper function SiebelTime.
CheckSiebelPhone | The same as CheckSiebelDateTime, but for phone numbers. Records the wrapper function SiebelPhone.

For examples, see the recording rules of the Siebel 7 Web SilkEssential.

Example (create variable for the quantity in an online shop): This example assumes that the quantity is sent in a form field named qty.

<?xml version="1.0" encoding="UTF-8" ?>
<RecordingRuleSet>
  <StringScriptingRule>
    <Name>Parameterize item quantity</Name>
    <Active>true</Active>
    <Search>
      <SearchIn>FormFieldValue </SearchIn>
      <LB>
        <Offset>0</Offset>
      </LB>
      <RB>
        <Length>0</Length>
      </RB>
      <Conditions>
        <CompareData>
          <ApplyTo>FormFieldName</ApplyTo>
          <Length>0</Length>
          <Data>qty</Data>
        </CompareData>
      </Conditions>
    </Search>
    <ScriptGen>
      <Action>CreateVariable</Action>
      <VarName>Quantity</VarName>
    </ScriptGen>
  </StringScriptingRule>
</RecordingRuleSet>
Parent topic: Section ScriptGen


Attributes VarName VarNamePrefix IsExternalVar

These attributes are only applicable if the Action attribute is CreateVariable. This allows to specifiy either a variable name (attribute VarName) or a prefix for the variable name (attribute VarNamePrefix). In the latter case, the actual variable name will be built from the given prefix and the actual string value during recording.

The attribute IsExternalVar (boolean, Default: false) can be used to suppress the scripting of a declaration for the variable. This is useful if it is known that this variable is already declared in some bdh-file within a SilkEssential.

Parent topic: Section ScriptGen


HttpScriptingRule

The rule type HttpScriptingRule allows to hook into script generation decisions the recorder has to make. It allows to override the default heuristics the recorder employed prior to this rule type and still employs in the absence of such rules.

  • Structure
    Describes the basic structure of the HttpScriptingRule.
  • HttpScriptingRule Actions
    Provides descriptions and examples to all HttpScriptingRule actions.
Parent topic: Rule-Based Recording


Structure

The basic structure of a HttpScriptingRule is quite simple. The only tag allowed, additional to the common tags Name and Active, is the tag Action. The Action tag specifies which decision is to be hooked.

The actual decision is implemented with conditions. The result of evaluating the conditions is the return value of such a rule. Conditions have access to the HTTP request / response which is being scripted.

<HttpScriptingRule>
  <Name>Suppress some cookie</Name>
  <Active>true</Active>
  <Action>SuppressCookie</Action>
  <Conditions>
    ...
  </Conditions>
</HttpScriptingRule>
Parent topic: HttpScriptingRule


HttpScriptingRule Actions

  • ForceTcp
    Provides a description and an example of the action ForceTcp.
  • NoHtml ForceHtml
    Provides a description and an example of the actions NoHtml, ForceHtml.
  • NoFuzzyFormDetection ForceFuzzyFormDetection
    Provides a description and an example of the actions NoFuzzyFormDetection, ForceFuzzyFormDetection.
  • NoDynLinkParsing ForceDynLinkParsing
    Provides a description and an example of the actions NoDynLinkParsing, ForceDynLinkParsing.
  • DefinePageName
    Provides a description and an example of the action DefinePageName.
  • SuppressCookie CommentCookie
    Provides a description and an example of the actions SuppressCookie and CommentCookie.
  • ScriptCookieDomainAsRequestHost
    Provides a description and an example of the action ScriptCookieDomainAsRequestHost.
  • SuppressFrameName SuppressLinkName SuppressFormName SuppressCustomUrlName
    Provides a description and an example of the actions SuppressFrameName, SuppressLinkName, SuppressFormName, and SuppressCustomUrlName.
  • MapFunctionName
    Provides a description and an example of the action MapFunctionName.
  • AddInitFunction
    Provides a description and an example of the action AddInitFunction.
  • NoAddUrl
    Provides a description of the action NoAddUrl.
  • SuppressRecording
    Provides a description of the action SuppressRecording.
  • ForceContextless
    Provides a description of the action ForceContextless.
  • DontUseHtmlVal
    Provides a description of the action DontUseHtmlVal.
  • NoQueryToForm ForceQueryToForm
    Provides a description of the actions NoQueryToForm, ForceQueryToForm.
Parent topic: HttpScriptingRule


ForceTcp

This recording rule ensures that a script is generated using TCP/IP low-level functions. No protocol detection is performed. The recording rule only applies to scripts that are generated out of capture files.
<RecordingRuleSet>
  <HttpScriptingRule>
    <Name>Force TCP/IP Scripting</Name>
    <Active>true</Active>
    <Action>ForceTcp</Action>
  </HttpScriptingRule>
</RecordingRuleSet>
Parent topic: HttpScriptingRule Actions


NoHtml ForceHtml

The recorder will evaluate HttpScriptingRules with Action NoHtml or ForceHtml whenever it needs a decision if a HTTP response body is HTML or not. In the absence of such rules or if no such rules return true, the recorder inspects the content-type header of the HTTP response.

This rule type is useful to suppress or force the scripting of a page-level function in cases where the default recording result is not satisfactory.

Often a "404 Not Found" response comes back with an HTML error description, which will cause the scripting of a WebPageUrl or WebPageLink, even when a WebPageAddUrl would be more appropriate.

<HttpScriptingRule>
  <Name>No HTML for zip files</Name>
  <Active>true</Active>
  <Action>NoHtml</Action>
  <Conditions>
    <CompareData>
      <ApplyTo>Http.Initial.Request.Url.Ext</ApplyTo>
      <Data>zip</Data>
    </CompareData>
  </Conditions>
</HttpScriptingRule>
Parent topic: HttpScriptingRule Actions


NoFuzzyFormDetection ForceFuzzyFormDetection

These actions of a HttpScriptingRule can be used to override the setting Fuzzy form detection from the profile settings for individual HTTP requests.

This rule allows fuzzy form detection (provided this is enabled in the profile settings) only for forms which contain a form field named sid.

<HttpScriptingRule>
  <Name>No fuzzy form detection except for forms with field sid</Name>
  <Active>true</Active>
  <Action>NoFuzzyFormDetection</Action>
  <Conditions>
    <Not>
      <Exists>
        <ApplyTo>Form.Field(Name:sid)</ApplyTo>
      </Exists>
    </Not>
  </Conditions>
</HttpScriptingRule>
Parent topic: HttpScriptingRule Actions


NoDynLinkParsing ForceDynLinkParsing

These Actions of a HttpScriptingRule can be used to override the setting "Dynamic link parsing" from the profile settings for individual HTTP requests.

This example forces dynamic link parsing (even if it turned off in the profile settings) for HTTP requests where the query string contains the string sid=.

<HttpScriptingRule>
  <Name>Force dynamic link parsing for some query strings</Name>
  <Active>true</Active>
  <Action>ForceDynLinkParsing</Action>
  <Conditions>
    <FindData>
      <ApplyTo>Http.Initial.Request.Url.QueryData</ ApplyTo>
      <Data>sid=</Data>
    </FindData>
  </Conditions>
</HttpScriptingRule>
Parent topic: HttpScriptingRule Actions


DefinePageName

This action allows defining an alternate page name for a HTML page. The recorder generates various strings (page timer name, name of stored context variable, ...) based on the name of a HTML page. By default the recorder uses the title of an HTML page for the page name, or "Unnamed page" if no title exists.

Such a rule must have conditions which:
  • return true
  • save a non-empty string to the variable PageName (by means of the tag SaveAs of a condition)

The conditions have access to the default page name the recorder would use through the variable DefaultPageName.

The following example checks if the default page name does not exist (the recorder would use "Unnamed page" then), and defines the page name to be the URL of the HTTP document instead, if it is at least 3 characters long.

<HttpScriptingRule>
  <Name>Define Page Name</Name>
  <Active>true</Active>
  <Action>DefinePageName</Action>
  <Conditions>
    <Not>
      <Exists>
        <ApplyTo>DefaultPageName</ApplyTo>
      </Exists>
    </Not>
    <CheckRange>
      <ApplyTo>Http.Initial.Request.Url</ApplyTo>
      <Range>3-</Range>
      <SaveAs>PageName</SaveAs>
      <SaveMode>Replace</SaveMode>
    </CheckRange>
  </Conditions>
</HttpScriptingRule>
Parent topic: HttpScriptingRule Actions


SuppressCookie CommentCookie

In some cases the function WebCookieSet may be recorded where this is not useful or even incorrect.

This may happen when there is a tight succession of client side "Cookie" and server side "Set-Cookie" headers in embedded objects of a page, with tight timing. In such a case it is possible that a browser does not send a cookie or sends a cookie with an older value, although the browser already received a "Set-Cookie" header which should cause it to send a different cookie value.

In such cases, these actions can be used to script WebCookieSet function calls commented or suppress the recording completely.

This rule suppresses scripting of any WebCookieSet function call if the cookie name is PS_TOKENEXPIRE (from the Peoplesoft SilkEssential).

<HttpScriptingRule>
  <Name>Suppress Cookie PS_TOKENEXPIRE</Name>
  <Active>true</Active>
  <Action>SuppressCookie</Action>
  <Conditions>
    <CompareData>
      <ApplyTo>Cookie</ApplyTo>
      <Data>PS_TOKENEXPIRE</Data>
    </CompareData>
  </Conditions>
</HttpScriptingRule>
Parent topic: HttpScriptingRule Actions


ScriptCookieDomainAsRequestHost

Usually, when recording a client-side cookie, Silk Performer uses a generic form for the domain attribute. The domain is cropped by the first dot, for example: http://demo.borland.com/testsite will be cropped to .borland.com. Usually, this is the desired behaviour, because such a cookie is valid for a variety of domains, including demo.borland.com and example.borland.com regarding the above example.

The recording rule ScriptCookieDomainAsRequestHost defines the domain for a cookie more precisely. The domain attribute matches exactly the request host.

The recording rule can be applied to certain cookies, by adding the name of the cookie to the <data> tag.

<HttpScriptingRule>
  <Name>MyCookieRecordingRule</Name>
  <Active>true</Active>
  <Action>ScriptCookieDomainAsRequestHost</Action>
  <Conditions>
    <CompareData>
      <ApplyTo>Cookie</ApplyTo>
      <Data>MyClientsideTestCookie</Data>
    </CompareData>
  </Conditions>
</HttpScriptingRule>
Parent topic: HttpScriptingRule Actions


SuppressFrameName SuppressLinkName SuppressFormName SuppressCustomUrlName

Functions like WebPageLink, WebPageSubmit and WebPageSetActionUrl use a name (of a link, form or parsed URL resp.), a frame name, and an ordinal number to reference a link, form, or parsed URL.

In cases where for example a link or form name changes dynamically, it is common practice to do the so-called "name to number customization", which means one does not specify the name (of the link or form), but instead specifies the overall ordinal number within the page or within the frame.

These actions can be used to let this customization be done already by the recorder.

Assume a shop application which uses form names which are built by adding the numeric session ID to the string cart_.

This rule will not record the form name within the WebPageSubmit calls, but will record NULL instead, with an ordinal number which references the form in the entire page.

<HttpScriptingRule>
  <Name>Suppress XML to form conversion</Name>
  <Active>true</Active>
  <Action>SuppressFormName</Action>
  <Conditions>
    <RegExpr>
      <ApplyTo>FormName</ApplyTo>
      <Data>cart_[0-9]*</Data>
      <ExpectMatch>Complete</ExpectMatch>
    </RegExpr>
  </Conditions>
</HttpScriptingRule>
Parent topic: HttpScriptingRule Actions


MapFunctionName

This action can be used to define a function name mapping, so that the recorder scripts a wrapper function (which needs to be present, for example in a BDH file, for the script to be compileable) instead of the original function. Such a wrapper function must have the same parameter list as the original function, because this rule does not modify the function parameters in any way.

The recorder scripts the wrapper function instead of the original function, if the condition returns true and in the course of the evaluation of the condition something was saved to the variable FunctionName.

If the conditions also save a non-empty string to the variable BdhFileName, the recorder will also generate a use statement to include the given BDH file into the script.

This rule replaces each WebPageLink function call with a MyWebPageLink function call.

<HttpScriptingRule>
  <Name>Replace WebPageLink with my wrapper function</Name>
  <Active>true</Active>
  <Action>MapFunctionName</Action>
  <Conditions>
    <CompareData>
      <ApplyTo>DefaultFunctionName</ApplyTo>
      <Data>WebPageLink</Data>
    </CompareData>
    <Exists>
      <ApplyTo>Literal:MyWebPageLink</ApplyTo>
      <SaveAs>FunctionName</SaveAs>
    </Exists>
    <Exists>
      <ApplyTo>Literal:MyFunctions.bdh</ApplyTo>
      <SaveAs>BdhFileName</SaveAs>
    </Exists>
  </Conditions>
</HttpScriptingRule>
Parent topic: HttpScriptingRule Actions


AddInitFunction

This action can be used to add function calls to the TInit or TMain transaction. This is the only action, which allows additional tags, besides the Conditions tag. While conditions are allowed, they are not useful because they can not reference any data.

There can be any number of functions specified, each one with its own Function tag. Within the Function tag, there must be the tag FunctionName and optionally the tag BdhFileName.

There can be any number of Param tags to specify parameters. Each parameter must have a Value tag and a Type tag. The Type tag can be either String or Const. String will put the parameter in quotes, Const won't.

<HttpScriptingRule>
  <Name>Automatically insert my useful function</Name>
  <Active>true</Active>
  <Action>AddInitFunction</Action>
  <Function>
    <FunctionName>InitMyLogLibrary</FunctionName>
    <BdhFileName>Log.bdh</BdhFileName>
    <Param>
      <Value>C:\Logs\xx.log</Value>
      <Type>String</Type>
    </Param>
    <Param>
      <Value>true</Value>
      <Type>Const</Type>
    </Param>
  </Function>
</HttpScriptingRule>

This will generate the following script fragments:

use "Log.bdh"

transaction TInit
begin
  // ...
  InitMyLogLibrary("C:\\Logs\\xx.log", true);
end TInit;
Silk Performer allows the tag Location with the following values:
  • TInit
  • TMainBegin
  • TMainEnd
Parent topic: HttpScriptingRule Actions


NoAddUrl

This action can be used to suppress the generation of a WebPageAddUrl function for particular HTTP requests. The recorder will then choose the next best way to record this request, usually a WebUrl function will be scripted instead, but it might also be another function (for example WebPageLink, WebPageUrl, ...) depending on circumstances.

This can be useful, because parsing rules never parse data from embedded objects of a web page. If a HTTP request is scripted by a WebUrl function call instead, it is possible to apply HTTP parsing rules to this request.

Parent topic: HttpScriptingRule Actions


SuppressRecording

This action can be used to suppress the recording of individual HTTP requests. It is used by the Silk Performer Oracle Forms support to suppress the recording of HTTP requests which come from an Oracle Forms applet which is recorded at a different API level.
Parent topic: HttpScriptingRule Actions


ForceContextless

This action can be used to suppress the recording of HTTP requests with a context-full function like WebPageLink or WebPageSubmit. Instead, the recorder will record an appropriate context-less function instead.

Parent topic: HttpScriptingRule Actions


DontUseHtmlVal

This action can be used to suppress the recording of the <USE_HTML_VAL> tag for individual form fields, even if the recorder would do so otherwise.

This can be useful if the form field value is required in the script, for example because another recording rule should be applied to the value.

In the PeopleSoft project type, the user name in the login form is forced to be in the script with this rule (even if the user name input field is pre-populated), and then another rule of type StringScriptingRule with the action CreateVariable creates a variable for it. In this way the script is better prepared for randomization of the login data.

Parent topic: HttpScriptingRule Actions


NoQueryToForm ForceQueryToForm

These actions can be used to override the profile setting Convert URL query strings to forms on a per HTTP request basis.

Parent topic: HttpScriptingRule Actions


ProxyEngineRule

The rule type ProxyEngineRule allows to control some aspects of the ProxyEngine's operation.

  • Structure
    Describes the basic structure of the ProxyEngineRule.
  • ProxyEngineRule Actions
    Describes all ProxyEngineRule actions and provides examples.
Parent topic: Rule-Based Recording


Structure

The basic structure of a ProxyEngineRule is quite simple. The only tag allowed, additional to the common tags Name and Active, is the tag Action. The Action tag specifies what to do. The actual decision is implemented with conditions. The result of evaluating the conditions is the return value of such a rule.
<ProxyEngineRule>
  <Name>Switch on GUI recording for Jacada</Name>
  <Active>true</Active>
  <Action>AddAppletParam</Action>
  <Conditions>
    <FindData>
      <ApplyTo>Attribute.ARCHIVE</ApplyTo>
      <Data>clbase.jar</Data>
    </FindData>
    <Exists>
      <ApplyTo>Literal:GUIMode</ApplyTo>
      <SaveAs>Param.Name</SaveAs>
      <SaveMode>Replace</SaveMode>
    </Exists>
    <Exists>
      <ApplyTo>Literal:GUIRecorder</ApplyTo>
      <SaveAs>Param.Value</SaveAs>
      <SaveMode>Replace</SaveMode>
    </Exists>
  </Conditions>
</ProxyEngineRule>
Parent topic: ProxyEngineRule


ProxyEngineRule Actions

  • AddAppletParam
    Provides a description for the action AddAppletParam.
  • RemoveAppletParam ChangeAppletParam
    Provides a description and an example for the actions RemoveAppletParam and ChangeAppletParam.
  • DetectProtoFtp DetectProtoSmtp
    Provides a description for the actions DetectProtoFtp and DetectProtoSmtp.
  • DontModifyRequestHeader DontModifyResponseHeader
    Provides a description and an example for the actions DontModifyRequestHeader and DontModifyResponseHeader.
  • DontDetectProtoHttp
    Provides a description for the action DontDetectProtoHttp.
  • BypassBlockingHttp
    Provides a description for the action BypassBlockingHttp.
Parent topic: ProxyEngineRule


AddAppletParam

This Action allows modifying applets contained in HTML before the HTML is forwarded to the client. The modification will not be visible in the log files. If the conditions evaluate to true, and the conditions save values to Param.Name and Param.Value, this parameter will be added to the applet tag.

Any ProxyEngineRule with Action AddAppletParam will be evaluated once per applet. The conditions have access to the attributes of the applet using the following syntax: Attribute.attr. attr may be any attribute of the applet tag.

Parent topic: ProxyEngineRule Actions


RemoveAppletParam ChangeAppletParam

This action allows modifying applets contained in HTML before the HTML is forwarded to the client. The modification will not be visible in the log files. If the conditions evaluate to true, the parameter will be removed from the applet (RemoveAppletParam), or its value will be changed to whatever was saved by the conditions to Param.Value (ChangeAppletParam).

Any ProxyEngineRule with one of these actions will be evaluated once per applet parameter. The conditions can access the name and value of the applet parameter by Param.Name and Param.Value.

<ProxyEngineRule>
  <Name>Remove Cabbase applet param</Name>
  <Active>true</Active>
  <Action>RemoveAppletParam</Action>
  <Conditions>
    <Or>
      <CompareData>
        <ApplyTo>Param.Name</ApplyTo>
        <Data>Cabbase</Data>
        <Length>0</Length>
      </CompareData>
      <CompareData>
        <ApplyTo>Param.Value</ApplyTo>
        <Data>.cab</Data>
        <Offset>-4</Offset>
      </CompareData>
    </Or>
  </Conditions>
</ProxyEngineRule>
Parent topic: ProxyEngineRule Actions


DetectProtoFtp DetectProtoSmtp

In the course of protocol detection, it is sometimes hard do distinguish between FTP and SMTP, since these protocols start with very similar traffic. The actions DetectProtoFtp and DetectProtoSmtp can be used to force detecting FTP or SMTP in cases where the recorder would misdetect the protocol otherwise.

The conditions can assess the following pieces of information in the ApplyTo tag:
  • WelcomeMsg: The welcome message of the server
  • NoopResponse: The server response to a NOOP command which is sent by the ProxyEngine
  • TargetPort: The target port
Parent topic: ProxyEngineRule Actions


DontModifyRequestHeader DontModifyResponseHeader

The recorder routinely modifies some request/response headers of HTTP traffic to ensure best recording results with common browsers. However, some uncommon user agents may misbehave when recorded.

An Action enables you to suppress the modification of request/response HTTP headers for individual requests, and thus allow for such recording problems.

Conditions can reference the header name and value, which can be modified in the ApplyTo tag using the values HeaderName and HeaderValue.

This example is from the Flex/AMF3 project type. This rule suppresses the modification of the Pragma and Cache-Control response header, if there is no Accept-Language request header.

<ProxyEngineRule>
  <Name>Suppress modification of some server response headers for HTTP requests coming from Shockwave/Flash</Name>
  <Active>true</Active>
  <Action>DontModifyResponseHeader</Action>
  <Conditions>
    <Not>
      <Exists>
        <ApplyTo>Http.Initial.Request.Header.Accept-Language</ApplyTo>
      </Exists>
    </Not>
    <Or>
      <CompareData>
        <ApplyTo>HeaderName</ApplyTo>
        <Data>Pragma</Data>
        <Length>0</Length>
      </CompareData>
      <CompareData>
        <ApplyTo>HeaderName</ApplyTo>
        <Data>Cache-Control</Data>
        <Length>0</Length>
      </CompareData>
    </Or>
  </Conditions>
</ProxyEngineRule>
Parent topic: ProxyEngineRule Actions


DontDetectProtoHttp

Sometimes it is necessary to record a TCP connection on TCP/IP level, although the automatic protocol detection would detect HTTP. The Actions DontDetectProtoHttp can be used to suppress detecting HTTP in such cases.

The conditions can assess the following pieces of information in the ApplyTo tag:
  • PeekData: The first chunk of data sent by the client.
Parent topic: ProxyEngineRule Actions


BypassBlockingHttp

Sometimes the recorder must be stopped from analyzing network traffic so as to avoid blocking network communication. Use the action BypassBlockingHttp to suppress recording in such cases. When this action is used, data on the connection is still forwarded, but it is not recorded until the connection is closed.

Conditions assess the following pieces of information in the ApplyTo tag:

  • PeekData: The relative request URL contains a specific value.
Parent topic: ProxyEngineRule Actions


Conditions

Conditions are an important aspect of HttpParsingRule, TcpRuleRecvProto and TcpRuleRecvUntil rule types.

They are a powerful means of specifying exactly when rules should be applied.

  • Introduction
    Describes compound conditions, extended boolean values, basic conditions, the condition evaluation environment, and how conditions operate on data.
  • Specifying Data for Conditions
    Describes the sets of attributes that specify what data is to be used for conditions.
  • Saving Temporary Variables
    Describes how to save a block of data to a temporary variable so that it can be referenced by the ApplyTo attribute of a subsequent condition.
  • Condition Evaluation Environment
    Describes which attribute ApplyTo values are allowed for conditions, depending on where conditions are used.
  • CompareData Condition
    Describes the CompareData condition, which checks to see if certain data has a specific value.
  • FindData Condition
    Describes the FindData condition, which checks to see if certain data contains a specific value.
  • RegExpr Condition
    Describes the RegExpr condition, which applies a regular expression to certain data.
  • CheckRange Condition
    Describes the CheckRange condition, which checks to see if a numeric value lies within a given range.
  • ResultLen Condition
    Describes the ResultLen condition, which is a special form of the CheckRange condition.
  • NoBlockSplit Condition
    Describes the NoBlockSplit condition, which determines what data is to be subject to the test and what the return value should be if the data is not available.
  • Scripting Condition
    Describes the type and default value of the condition and provides a description and an example.
  • Exists Condition
    Describes the Exists condition, which checks if the data specified in the ApplyTo tag is not null.
  • Loop Condition
    Describes the Loop condition, which evaluates its subconditions as long as they evaluate to true.
Parent topic: Rule-Based Recording


Introduction

Compound Conditions

Complex conditions can be created using Boolean operators And, Or and Not.

<And>
  <Or>
    <SomeBasicCondition> … </SomeBasicCondition>
    <SomeBasicCondition> … </SomeBasicCondition>
    <Not>
      <SomeBasicCondition> … </SomeBasicCondition>
    </Not>
  </Or>
  <Not>
    <And>
      <SomeBasicCondition> … </SomeBasicCondition>
      <SomeBasicCondition> … </SomeBasicCondition>
    </And>
  </Not>
</And>

Extended Boolean Values

The result of a condition, once evaluated, is an extended Boolean value. Extended Boolean values have the values true, unknown or false. Think of the value unknown as: "Cannot be evaluated now, but may be evaluated when more data becomes available".

This is important for TcpRuleRecvProto and TcpRuleRecvUntil type rules. If conditions in a TCP rule result in a value of unknown, the Recorder defers scripting and reevaluates conditions when more data arrives from the server.

Basic Conditions

There are a number of basic condition types that execute checks and can be combined (using the Boolean conditions And, Or and Not) to build complex compound conditions.

Basic condition types include:
  • CheckRange: Checks to see if a numeric value lies within a given range.
  • ResultLen: A special form of the condition CheckRange.
  • CompareData: Compares data.
  • FindData: Searches data.
  • Verify: A special form of the condition CompareData.
  • RegExpr: Applies a regular expression.
  • NoBlockSplit: Checks block boundaries.
  • Scripting: Checks for the type of string being scripted.

Condition evaluation environment

A condition is evaluated within an environment. Through the environment, the condition has access to a number of strings to which the condition can be applied. Environment configuration differs with each rule type. See section “Condition Evaluation Environment” for details.

Conditions operate on data

Most conditions (except the Scripting condition) apply specific checks on specific blocks of data. There are flexible means of specifying what data is to be checked. See section “Specifying Data for Conditions” for more information.

Parent topic: Conditions


Specifying Data for Conditions

Most conditions (except the Scripting condition) operate on specific blocks of data.

Conditions have sets of attributes that specify what data is to be used and what should be done if required data is not available.

These attributes are:
  • ApplyTo
  • Offset
  • Length
  • IfNull
  • UseDataAvail
The basic idea is:
  1. ApplyTo specifies a block of data (for example a request URL, a response body, the string to be scripted, and so on).
  2. Offset and Length are optionally used to target data subsets.
  • ApplyTo
    Shows the type and the default value of the attribute ApplyTo, provides a description and an example.
  • Offset Length
    Shows the type and the default value of the attribute Offset Length, provides a description and an example.
  • UseDataAvail
    Shows the type and the default value of the attribute UseDataAvail and provides a description.
  • IfNull
    Shows the type and the default value of the attribute IfNull and provides a description.
Parent topic: Conditions


ApplyTo

Value | Description
Type | Strings
Default | Self
Description | ApplyTo specifies the data that the condition operates on. ApplyTo is resolved within the current environment. The valid values for ApplyTo are therefore dependent on the environment configuration, which is different for each rule type.

Literal

With the Literal value in the ApplyTo tag it is possible to specify a literal as data for conditions. This is useful in conjunction with the Exists condition and the SaveAs attribute.

<Conditions>
  <Exists>
    <ApplyTo>Literal: - </ApplyTo>
    <SaveAs>PageName</SaveAs>
    <SaveMode>AppendSeparator</SaveMode>
  </Exists>
  <Exists>
    <ApplyTo>Form.Submit.Field(Name:SWECmd).Value</ApplyTo>
    <SaveAs>PageName</SaveAs>
    <SaveMode>Append</SaveMode>
  </Exists>
</Conditions>

Additional ApplyTo values

Additional ApplyTo values in the ScriptGen section of a HttpParsingRule.

In addition to the possible values LinkName, FormName, FormFieldName, FormFieldValue and TargetFrame in the ScriptGen section of a HttpParsingRule, there are four new possibilities:

CustomUrlName | The current name of a custom URL, if used in a function WebPageLink, WebPageSetActionUrl or WebPageQueryParsedUrl.
PostedData | The value of (possibly binary) posted data that appears as a parameter to WebPagePostBin and similar functions. The name of a HTTP header, when the function WebHeaderAdd is recorded (1st parameter of this function).
HeaderName | The name of a HTTP header, when the function WebHeaderAdd is recorded (1st parameter of this function).
HeaderValue | The value of a HTTP header, when the function WebHeaderAdd is recorded (2nd parameter of this function).

Access to forms

Both rules of type HttpParsingRule (ScriptGen section), HttpScriptingRule and StringScriptingRule (Search section) also have convenient access functions for form data according to the following syntax: "Form" [ ".Query" | ".Body" | ".Submit" ]

This allows specifying the form in the query string ("Query") or in the request body ("Body") of the current HTTP request.

The value Submit, which is the default, is automatically equivalent to Query if the HTTP request uses the method GET, and to Body if the HTTP request uses the method POST.

Once a form is specified according to the syntax above, it is possible to extract details about this form:
  • ActionUrl: Specifies the action URL of a form. It is possible to get more details of the action URL.
  • Encoding: Specifies the encoding to be scripted (for example ENCODE_BLANKS)
<ApplyTo>Form.ActionUrl</ApplyTo>
<ApplyTo>Form.ActionUrl.Host</ApplyTo>
<ApplyTo>Form.ActionUrl.Coords</ApplyTo>
<ApplyTo>Form.Query.Encoding</ApplyTo>
<ApplyTo>Form.Body.Encoding</ApplyTo>
<ApplyTo>Form.Submit.Encoding</ApplyTo>

Moreover, it is possible to specify the individual form fields according to the following syntax: ".Field(" ( "Name" | "Value" | "Index" ) ":" Selector ")" "." ( "Name" | "Value" | "Encoding" | "Usage" )

So it is possible to reference a form field by name, value, or index (zero-based), and extract the name, value, encoding, or usage of such a form field. Encoding means one of the following: "ENCODE_FORM". Usage means one of the following: "SUPPRESS", "USE_HTML_VAL", "USE_SCRIPT_VAL".

<ApplyTo>Form.Submit.Field(Name:SWECmd).Value</ApplyTo>
<ApplyTo>Form.Field(Name:sid).Usage</ApplyTo>
<ApplyTo>Form.Field(Name:sid).Encoding</ApplyTo>
<ApplyTo>Form.Field(Index:0).Name</ApplyTo>
<ApplyTo>Form.Field(Index:2).Value</ApplyTo>
<ApplyTo>Form.Field(Value:Submit with GET).Name</ApplyTo>
Parent topic: Specifying Data for Conditions
Related concepts
Condition Evaluation Environment
Related reference
Access to HTTP request/response pairs
Access to Special Strings


Offset Length

Value | Description
Type | Signed Numbers
Default value | 0
Description | Offset and Length can be used to target subsets of data referenced with ApplyTo.

First, Offset is applied

If Offset >= 0, Offset specifies the number of bytes that are to be removed from the beginning of the data.

If Offset < 0, -Offset specifies the number of bytes that are to be kept, counting backward from the last byte.

Second, Length is applied

If Length > 0, Length specifies the number of bytes that are to be used, counting forward from the first byte.

If Length <= 0, -Length specifies the number of bytes that are to be removed, counting backward from the last byte.

Offset and Length calculations may not be possible, or may be only partially possible.

Example 1

ApplyTo returns 30 Bytes of data, Offset specifies "40" => Offset calculation is not possible.

In this case the resulting data has the value Null.

Example 2

ApplyTo returns 30 Bytes of data, Length specifies "35" => Length calculation is possible, however the length must be adjusted to the maximum available value of "30."

In this case the resulting data may have the special value Null or it may equal the maximum data available, depending on the condition attribute UseDataAvail.

Parent topic: Specifying Data for Conditions


UseDataAvail

Value | Description
Type | Boolean Values
Default value | true
Description | This attribute specifies what data is to be used when an Offset/Length calculation is only partially possible. If true, the maximum data available is used. If false, the result of the Offset/Length calculation is Null.
Parent topic: Specifying Data for Conditions


IfNull

Value | Description
Type | Extended Boolean Values
Default value | unknown
Description | This attribute specifies the return value of the condition if there is no data to operate on (that is, fi calculations with ApplyTo, Offset, Length and UseDataAvail return Null).
Parent topic: Specifying Data for Conditions


Saving Temporary Variables

Conditions which apply to a block of data can specify this data as described in Specifying Data for Conditions.

This block of data can now be saved to a "temporary variable" so that it can be referenced by the ApplyTo attribute of a subsequent condition.

The new attributes of such conditions are:
  • SaveAs
  • SaveIfTrue
  • SaveIfUnknown
  • SaveIfFalse
  • SaveMode
  • SaveTag
  • SaveAs
    Provides a description and the type of the attribute SaveAs.
  • SaveIfTrue SaveIfUnknown SaveIfFalse
    Shows the type and the default value of the attributes SaveIfTrue, SaveIfUnknown, and SaveIfFalse, and provides a description.
  • SaveMode
    Shows the type and the default value of the attribute SaveMode and provides a description.
  • SaveTag
    Shows the type and the default value of the attribute SaveTag and provides a description.
  • SaveWhat
    Shows the type and the default value of the attribute SaveWhat, provides a description and an example.
Parent topic: Conditions


SaveAs

Value | Description
Type | Strings
Description | This attribute causes the data to be saved and specifies the name of the temporary variable to which the data is saved to.
Parent topic: Saving Temporary Variables


SaveIfTrue SaveIfUnknown SaveIfFalse

Value | Description
Type | Strings
Default values
  • SaveIfTrue: true
  • SaveIfUnknown: false
  • SaveIfFalse: false
Description | This attribute specify if the data should be saved in case the result of the condition is true, unknown, or false.
Parent topic: Saving Temporary Variables


SaveMode

Value | Description
Type | Distinct Values
Default value | IfNew
Description | This attribute specifies how to save the data to the temporary variable.
Allowed values:
  • IfNew: Saves the data only if there is no value associated with the given variable name yet.
  • Replace: Always saves the data, replaces an existing value.
  • AppendSeparator: Appends the data to the existing value if the existing value is not empty, no action otherwise.
  • Append: Appends the data to the existing value.
  • PrpendSeparator: Prepends the data to the existing value if the existing value is not empty, no action otherwise.
  • Prepend: Prepends the data to the existing value.
Parent topic: Saving Temporary Variables


SaveTag

Value | Description
Type | Numbers
Default value | 0
Description | This tag is only applicable to the RegExpr condition and allows to specify a tag number referencing a tagged sub-expression of the regular expression is saved
Parent topic: Saving Temporary Variables


SaveWhat

Value | Description
Type | Distinct Values
Default value | Self
Description | A condition extracts a fragment of the entire block of data which is identified by the ApplyTo tag. The SaveWhat tag allows to specify if the extracted fragment should be saved, or the fragment left or right of the extracted fragment.
Allowed values:
  • Self: Saves the fragment identified by the condition.
  • Left: Saves fragment left of Self.
  • Right: Saves the fragment right of Self.

Example

<Conditions>
  <RegExpr>
    <ApplyTo>Http.Final.Response.Body</ApplyTo>
    <Data>Instructions:\([^&lt;]+\)&lt;</Data>
    <SaveAs>Instructions</SaveAs>
    <SaveTag>1</SaveTag>
  </RegExpr>
  <FindData>
    <ApplyTo>Instructions</ApplyTo>
    <Data>Download</Data>
  </FindData>
</Conditions>
Parent topic: Saving Temporary Variables


Condition Evaluation Environment

The condition attribute ApplyTo is resolved within an environment that is configured based on the rule type in which the condition is used.

This chapter explains which attribute ApplyTo values are allowed for conditions, depending on where conditions are used.

  • Access to Special Strings
    Describes how to access the special strings All, Self, Left, Right, and Rest.
  • Access to HTTP request/response pairs
    Describes how to access HTTP request/response pairs.
Parent topic: Conditions


Access to Special Strings

HttpParsingRule, TcpRuleRecvProto and TcpRuleRecvUntil rule types can reference the strings All, Self, Left, Right and Rest.

Conditions in the ScriptGen sections of HTTP parsing rules have additional options for referencing specific data using the ApplyTo property:
  • LinkName: The current link name (only available when scripting a WebPageLink function)
  • FormName: The current form name (only available when scripting a WebPageSubmit function)
  • FormFieldName: The current form field name (only available when scripting a form field name or form field value)
  • FormFieldValue: The current form field value (only available when scripting a form field name or form field value)
  • TargetFrame: The current target frame name (only available when scripting a WebPageLink or WebPageSubmit(Bin) function)

Examples

<ApplyTo>All</ApplyTo>
<ApplyTo>Self</ApplyTo>
<ApplyTo>FormFieldName</ApplyTo>
Parent topic: Condition Evaluation Environment


Access to HTTP request/response pairs

Conditions used within HttpParsingRule rules can access details of HTTP requests / responses with the ApplyTo property.

"Http" [ ".Initial" | ".Final" ] ( ".Request" | ".Response" ) [ "." Component ]

The optional component Initial or Final is only significant in cases where HTTP requests are part of a redirection chain. In such cases, Initial returns the first HTTP request in the chain; Final returns the last request in the chain.

Final is the default for conditions in the HttpParsingRule\Search section.

Initial is the default for conditions in the HttpParsingRule\ScriptGen section.

Valid Component values for HTTP requests, plus return values:
(empty) | Equal to Header
Body | Request body
RequestLine | Request line (i.e., Method + URL + HTTP version)
Method | HTTP method
Version | HTTP version
Header | Complete request header, including request line
Header.* | Use this to reference any HTTP request header
Url | Complete request URL
Url.Complete | Complete request URL
Url.BaseUrl | URL without query string
Url.DirectUrl | Relative request URL (without scheme and host)
Url.BaseDirOnlyUrl | URL without query string and file name
Url.Scheme | URL scheme (HTTP, HTTPS or FTP)
Url.Host | Host name in URL
Url.Port | Port in URL
Url.Path | Path (directory plus file name)
Url.Dir | Directory
Url.File | File name
Url.Ext | File extension
Url.Username | User name
Url.Password | Password
Url.Query | Query string, including "?"
Url.QueryData | Query string, excluding "?"
Url.Coords | Image coordinates
Valid Component values for HTTP responses:
(empty) | Equal to Header
Body | Response body
StatusLine | Response status line (i.e., HTTP version plus status code and status phrase)
Version | HTTP version
StatusCode | HTTP response status code
StatusPhrase | HTTP response status phrase
Header | Complete response header, including status line
Header.* | Use this to reference any HTTP response header

Examples

<ApplyTo>Http.Response.Header.Content-Type</ApplyTo>
<ApplyTo>Http.Response.Header</ApplyTo>
<ApplyTo>Http.Request.Url.QueryData</ApplyTo>
<ApplyTo>Http.Request.Body</ApplyTo>
<ApplyTo>Http.Response.StatusCode</ApplyTo>
Parent topic: Condition Evaluation Environment


CompareData Condition

The CompareData condition checks to see if certain data has a specific value. It uses the attributes ApplyTo, Offset, Length, UseDataAvail and IfNull to determine what data is subject to the test and what the return value should be if the data isn't available.

Also see section “Specifying Data for Conditions”.

In contrast to other condition types, if the Length property is omitted, the number of bytes specified in the Data property is used as the Length property. By omitting the Length property, this allows for a prefix match rather than an exact match.

The Verify condition is an alias for .

Data Attribute

Type | Binary Data
Default | (empty)
Description | The Data attribute specifies what data is to be compared to the data referenced by ApplyTo, Offset and Length.

CaseSensitive Attribute

Type | Boolean Values
Default | false
Description | Specifies whether to search for the data in case-sensitive or case-insensitive format.

GenVerify Attribute

This attribute is only applicable if the condition is used within a TcpRuleRecvProto rule. See section "GenVerify Attribute Of Conditions" for details.

Example

<CompareData>
  <ApplyTo>Http.Response.Header.Content-Type</ApplyTo>
  <Data>text/css</Data>
  <IfNull>true</IfNull>
  <CaseSensitive>false</CaseSensitive>
</CompareData>
Parent topic: Conditions


FindData Condition

The FindData condition checks to see if certain data contains a specific value. It uses the attributes ApplyTo, Offset, Length, UseDataAvail and IfNull to determine what data is to be subject to the test and what the return value should be if the data is not available.

Also see section “Specifying Data for Conditions”.

Data Attribute

Type | Binary Data
Default | (empty)
Description | The Data attribute specifies what data is to be found in the data referenced by ApplyTo, Offset and Length.

CaseSensitive Attribute

Type | Boolean Values
Default | false
Description | Specifies whether to search for the data in case-sensitive or case-insensitive format.

IgnoreWhiteSpaces Attribute

Type | Boolean Values
Default | false
Description | Specifies whether or not to ignore white spaces while searching.

GenVerify Attribute

This attribute is only applicable if the condition is used within a TcpRuleRecvProto rule. See section "GenVerify Attribute Of Conditions" for details.

Example

<FindData>
  <ApplyTo>Http.Request.Url</ApplyTo>
  <Data>/images/</Data>
  <CaseSensitive>true</CaseSensitive>
</FindData>
Parent topic: Conditions


RegExpr Condition

The RegExpr condition applies a regular expression to certain data. It uses the properties ApplyTo, Offset, Length, UseDataAvail and IfNull to determine what data will be subject to the regular expression test and what the return value will be if the data isn't available. Also see section “Specifying Data for Conditions”.

Data Attribute

Type | Binary Data
Default | (empty)
Description | The Data attribute specifies the regular expression to be applied to the data referenced by ApplyTo, Offset and Length.

ExpectMatch Attribute

Type | Distinct Values
Default | Any
Description

Specifies the regular expression must match the complete data or if any substring matching the regular expression is sufficient.

Allowed values are:
  • Any: Matching any substring is sufficient.
  • Complete: Complete data must match the regular expression.

GenVerify Attribute

This attribute is only applicable if the condition is used within a TcpRuleRecvProto rule. See section "GenVerify Attribute Of Conditions" for details.

Example

<RegExpr>
  <ApplyTo>Http.Response.Body</ApplyTo>
  <Data>&lt;html&gt;.*&lt/html&gt;</Data>
</RegExpr>
Parent topic: Conditions


CheckRange Condition

The CheckRange condition checks to see if a numeric value lies within a given range. It uses the properties ApplyTo, Offset, Length, UseDataAvail and IfNull to determine what data is to be converted to a numeric value and what the return value should be if the data isn't available or the conversion fails. Also see section “Specifying Data for Conditions”.

Range Attribute

Type | Numeric Ranges
Default | -
Description | Specifies the allowed range for the numeric value.

Convert Attribute

Type | Distinct Values
Default | Length
Description | Specifies how to convert the data (obtained through the properties Apply, Offset, Length, and UseDataAvail) into a number.
Allowed values are:
Length (default) | The data is converted to a number by measuring the length (number of bytes) of the data.
Parse | The data is converted to a number by assuming a textual numeric value and parsing it. If parsing fails, no range check is performed and the attribute IfNull determines the result of the condition.
LittleEndian | The data is treated as a binary representation of a number in little endian format. If the data is empty or is longer than 4 bytes, this fails and the attribute IfNull determines the result of the condition.
BigEndian | The data is treated as a binary representation of a number in big endian format. If the data is empty or is longer than 4 bytes, this leads to a failure and the attribute IfNull determines the result of the condition.

Example

<CheckRange>
  <ApplyTo>Http.Response.StatusCode</ApplyTo>
  <Range>200-299</Range>
  <Convert>Parse</Convert>
</CheckRange>
Parent topic: Conditions


ResultLen Condition

The ResultLen condition is a special form of the CheckRange condition, with two differences:
  1. The default value for the ApplyTo attribute is not Self, but All.
  2. The accepted range is not specified in the Range attribute, but directly within the ResultLen - tag.

Example

<ResultLen>5-15</ResultLen>
Parent topic: Conditions


NoBlockSplit Condition

The NoBlockSplit condition is only applicable within TcpRuleRecvProto and TcpRuleRecvUntil rules.

It uses the attributes ApplyTo, Offset, Length, UseDataAvail and IfNull to determine what data is to be subject to the test and what the return value should be if the data isn't available.

Also see section “Specifying Data for Conditions”.

In contrast to other conditions, the default value for the ApplyTo attribute is All, rather than Self.

Semantics

When recording TCP/IP traffic, servers may send responses in multiple TCP/IP packets (blocks). The NoBlockSplit condition tests to see if the end of the data obtained by ApplyTo, Offset and Length is identical to the end of one of the packets.

The result is false if the end of the tested data is not on a block boundary; otherwise the result is true.

Example

<NoBlockSplit></NoBlockSplit>

<NoBlockSplit>
  <ApplyTo>Left<ApplyTo>
</NoBlockSplit>
Parent topic: Conditions


Scripting Condition

The Scripting condition does not operate on specific data, therefore the attributes ApplyTo, Offset, Length, UseDataAvail and IfNull are not available.

Attribute

Type | Distinct Values Lists
Default | All
Description | The attribute value is specified directly within the Scripting tag, not within a sub node of the condition.
Allowed values are:
All | An abbreviation for the complete list of other values
Url | Scripting any URL parameter
LinkName | Scripting a link name of WebPageLink
FormName | Scripting a form name of WebPageSubmit
PostedData | Scripting binary posted data (for example WebPagePost)
FormFieldName | Scripting a form field name in the dclform section
FormFieldValue | Scripting a form field value in the dclform section
SetCookie | Scripting the first parameter of the function WebCookieSet

True is returned if the condition is evaluated while scripting a string parameter in one of the specified script locations, otherwise it's false.

Examples

<Scripting>Url, FormFieldValue</Scripting>
<Scripting>All</Scripting>
<Scripting>LinkName, FormName, PostedData</Scripting>
Parent topic: Conditions


Exists Condition

The condition type Exists checks if the data specified in the ApplyTo tag is not null. It is especially useful in conjunction with the SaveAs condition tag.

Example

<Conditions>
  <Or>
    <Exists>
      <ApplyTo>Form.Submit.Field(Name:SWECmd).Value</ApplyTo>
      <SaveAs>Command</SaveAs>
    </Exists
    <Exists>
      <ApplyTo>Form.Submit.Field(Name:SWEMethod).Value</ApplyTo>
      <SaveAs>Command</SaveAs>
    </Exists>
  </Or>
  <Exists>
    <ApplyTo>Command</ApplyTo>
    <SaveAs>PageName</SaveAs>
    <SaveMode>Append</SaveMode>
  </Exists>
</Conditions>
Parent topic: Conditions


Loop Condition

The new compound condition Loop is similar to the condition And in that it evaluates its sub-conditions as long as they evaluate to true. However, unlike the And condition, it doesn't stop once all conditions have been evaluated. Instead, the Loop condition starts over again and repeatedly evaluates its sub-conditions and stops only when a condition evaluates to false. Of course this only makes sense if at least one sub-condition has side-effects by using the SaveAs tag, otherwise it would loop forever once all sub-conditions have returned true on the first pass.

Example

This example is taken from the Flex/AMF3 project type and shows how the page timer name is assembled from the response body.

<Conditions>
  <Exists>
    <ApplyTo>Http.Initial.Request.Body</ApplyTo>
    <SaveAs>RestOfBody</SaveAs>
    <SaveMode>Replace</SaveMode>
  </Exists>
  <Loop>
    <RegExpr>
      <ApplyTo>RestOfBody</ApplyTo>
      <Data>operation=&amp;quot;\([^&amp;quot;]*\)</Data>
      <SaveAs>operation</SaveAs>
      <SaveMode>Replace</SaveMode>
      <SaveTag>1</SaveTag>
    </RegExpr>
    <RegExpr>
      <ApplyTo>RestOfBody</ApplyTo>
      <Data>operation=&amp;quot;\([^&amp;quot;]*\)</Data>
      <SaveAs>RestOfBody</SaveAs>
      <SaveMode>Replace</SaveMode>
      <SaveWhat>Right</SaveWhat>
    </RegExpr>
    <Exists>
      <ApplyTo>Literal:, </ApplyTo>
      <SaveAs>OperationList</SaveAs>
      <SaveMode>AppendSeparator</SaveMode>
    </Exists>
    <Loop>
      <FindData>
        <ApplyTo>operation</ApplyTo>
        <Data>.</Data>
        <SaveAs>operation</SaveAs>
        <SaveMode>Replace</SaveMode>
        <SaveWhat>Right</SaveWhat>
      </FindData>
    </Loop>
    <Exists>
      <ApplyTo>operation</ApplyTo>
      <SaveAs>OperationList</SaveAs>
      <SaveMode>Append</SaveMode>
    </Exists>
  </Loop>
  <Exists>
    <ApplyTo>OperationList</ApplyTo>
    <SaveAs>PageName</SaveAs>
    <SaveMode>Replace</SaveMode>
  </Exists>
</Conditions>
Parent topic: Conditions


Troubleshooting

This section offers some recommendations for troubleshooting recording rules that do not operate as expected. The Recorder outputs diagnostic information to the Log tab window, as shown in the screenshot below.

This output contains:
  • The recording rule files that have been read by the Recorder.
  • The recording rules contained in the recording rule files.
  • "+" signs preceding rules that are correct and active.
  • "-" signs preceding rules that are incorrect or inactive.
  • Reasons why rules aren't used ("not active" or an error description).
If a rule file does not appear in this diagnostic output, check the following:
  • Is the rule file in the Documents directory of the current project or the public or user’s RecordingRules directory?
  • Does the file have the extension .xrl?

Ensure that the setting Hide file extensions for known file types is not checked in the Windows Explorer Folder Options dialog box, as shown in the screenshot below. Otherwise Windows may show a file name such as Rule.xrl when the file name is actually Rule.xrl.txt.

Parent topic: Rule-Based Recording


Manually Written Test Scripts

If you do not want to use the Silk Performer Recorder to generate test scripts, you have the option of creating them manually.

Silk Performer test scripts are written in the program's proprietary scripting language, the Benchmark Description Language (BDL), which is a high-level language that resembles Pascal. To edit scripts manually, you must be familiar with BDL and be able to create prototypes of user requests. You must also be able to define the typical components of a test script, including modules, functions, workload definitions, transactions, and Web forms.

  • Writing Test Scripts Manually
    Create a new test script from scratch, using the Benchmark Description Language (BDL).
  • Editor Keyboard Shortcuts
    The script editor provides a number of keyboard shortcuts and keyboard mouse combinations that facilitate the scripting work.
Parent topic: Modeling Scripts
Related concepts
Benchmark Description Language (BDL) Reference
Related reference
Available Application Types


Writing Test Scripts Manually

  1. Click File > New > Plain Script (.bdf) . The Save As dialog box appears.
  2. Give the script a name and click Save.
Use Benchmark Description Language (BDL), Silk Performer's proprietary scripting language to write your script.
Parent topic: Manually Written Test Scripts
Related concepts
Benchmark Description Language (BDL) Reference
Related tasks
Adding Recording Profiles


Editor Keyboard Shortcuts

The script editor provides a number of keyboard shortcuts and keyboard mouse combinations that facilitate the scripting work.

press and hold Shift+Alt and drag with mouse | Vertical selection. This lets you edit several rows at once. You can also use the arrow keys instead of the mouse to expand the selection.
press and hold Alt and press the arrow up/arrow down key | Move the current line/selected lines up and down.
press and hold Ctrl and click an identifier | Takes you to the definition of the identifier (go to jump).
Ctrl+Minus | Takes you back to your previous position. Particularly useful after a go to jump.
Ctrl+Space | Opens the code completion box.
Ctrl+i | Shows the parameter information box.
double-click the vertical line of a group | Collapses the group.
Ctrl+Shift+L | Deletes the current line.
Ctrl+Enter | Creates a new line above the current line.
Ctrl+U | Converts the selected text to lower case.
Ctrl+Shift+U | Converts the selected text to upper case.
Tab | Increments the indentation.
Shift+Tab | Decrements the indentation.
Ctrl+Q | Comments the selected lines.
Ctrl+W | Uncomments the selected lines.
Ctrl+G | Go to line. Lets you jump to a specific line in the script.
Parent topic: Manually Written Test Scripts


Sample Scripts

Sample script reuse is a timesaving possibility for those who want to generate Silk Performer test scripts manually (and bypass the standard method, which uses the Silk Performer Recorder).

Sample project files, including scripts, include files, data files, profile files, workload definitions, and more, are available from the Type list on the Outline Project dialog when you are initially prompted to outline a new project. These files can be used as templates that you can edit manually to meet your needs.

Silk Performer test scripts are written in the program's proprietary scripting language, the Benchmark Description Language (BDL), which is a high-level language that resembles Pascal. To edit scripts manually, you must be familiar with BDL and be able to create prototypes of user requests. You must also be able to define the typical components of a test script, including modules, functions, workload definitions, transactions, and Web forms.

  • Working From Sample Scripts
    Create a new test script based on a sample script, using the Benchmark Description Language (BDL).
Parent topic: Modeling Scripts


Working From Sample Scripts

  1. Open the project in which you want to work, or start a new project.
  2. Click File > Open > Script File (.bdf). The Open dialog box appears.
  3. Browse to the Samples folder (<public user documents>\Silk Performer 21.0\Samples\<...>). Select a sample script and click Open.
  4. Confirm that you want to add the script to your project.
Parent topic: Sample Scripts
Related tasks
Adding Recording Profiles


Trying Out Scripts

Silk Performer offers several means of evaluating test scripts, starting with the execution of a Try Script run.

  • Try Script Overview
    Ensure that your test script is free from error and accurately reproduces required interaction between client application and server.
  • Trying Out a Test Script
    Validate the results of a trial test-script run to ensure that your script works.
  • Try Script Summary
    On the Try Script Summary page, you can analyze the results of the recent Try Script run.
  • Visual Analysis with TrueLog Explorer
    Describes how to use TrueLog Explorer to analyze test results.
  • Log Files
    Details the purpose and contents of a log file.
  • Viewing Report Files
    View general information, virtual users, summary tables, transaction response times, HTML page timers, and Web form measurements.
  • Output Files
    Describes the content and purpose of an output file.
Parent topic: Managing Load Tests


Try Script Overview

Part of the process of conducting a Silk Performer load test is to perform a trial run of the test script that was created during script modeling.

Normally, this is traffic recorded by the Silk Performer Recorder during script modeling. For a trial run, or Try Script, of a test script, options are automatically selected so that you can see a live display of the actual data downloaded. Log files, TrueLog files, report files, output files, and error files are created so that you can later confirm that the script works properly. Only one user is run, and the stress test option is enabled so that there is no think time and no delay between transactions. However, at this stage, the measurements typical of a real load test are not performed.

Try Script Settings

For Try Script runs, the following options are automatically set to these specified values (see also "Replay Options"):

  • The Stress test option is on, when think times are disabled.
  • The Stop virtual users after simulation time (Queuing Workload) option is off.
  • The Virtual user log files (.log) option is on.
  • The Virtual user output files (.wrt) option is on.
  • The Virtual user report files (.rpt) option is on.
  • The Virtual user report on error files (.rpt) option is on.
  • The TrueLog files (.xlg) option is on.
  • The TrueLog On Error files (.xlg) option is off.
  • The Compute time series data (.tsd) option is off.
  • All logging detail options ( Results > Logging and Results > Internet Logging page) are on.
  • The Enable all measure groups (TSD measure groups) option is off.
  • The Bandwidth option is set to High Speed (unlimited).
  • The Downstream option is set to unlimited.
  • The Upstream option is set to unlimited
  • The Duplex option is off.
Parent topic: Trying Out Scripts
Related concepts
Replay Settings
Project Attributes


Try Script Summary

When a Try Script run is complete, the Try Script Summary page appears. You can also open this page from the Results tree. You can perform the following actions in the Next Steps area on the right side:
  • Click Customize user data to open the TrueLog Explorer and customize your script.
  • Click Define User Types to continue with the next step in the workflow bar. This button is only visible if you use the Simple Workflow Bar.
  • Click Find Baseline to continue with the next step in the workflow bar. This button is only visible if you use the Full Workflow Bar.

In the Analyze Result Files area, you can open various reports and log files.

Note: If you want to prevent the summary page to appear each time a test is complete, disable the Show Summary Page button in the toolbar of the Monitor page.
Parent topic: Trying Out Scripts


Visual Analysis with TrueLog Explorer

TrueLog Explorer guides you through the process of visually analyzing Try Script runs with its Workflow bar.

TrueLog Explorer provides an accurate view of the actual data that is downloaded during tests. This enables you to verify that the data specified to be received from the server under test was, in fact, received. In the case of Web application testing for example, TrueLog Explorer shows the actual Web pages that are received during tests. Through the use of TrueLog Explorer’s animated mode, live monitoring of downloaded data is available—data is displayed as it is received during tests.

TrueLog Explorer provides different views of received data, enabling you to:

  • Inspect the rendered HTML code, as a real user would see it.

  • Inspect the native HTML code.

  • Inspect a difference table that shows the differences between replay and recorded TrueLogs.

  • Validating Scripts with TrueLog Explorer
    Examine the Virtual User Summary report, view downloaded web pages, and find errors to validate your test script.
Parent topic: Trying Out Scripts


Validating Scripts with TrueLog Explorer

Run a script before performing this task.

  1. From the Silk Performer menu bar, select Results > Explore TrueLog .
    Note: Selecting the Animated Run with TrueLog Explorer check box before running a Try Script operation opens TrueLog Explorer automatically.
  2. Examine the Virtual User Summary report. A Virtual User Report is shown automatically when the first node of the menu tree at the left side of the window is checked. The report shows detailed information about the Try Script run in tabular form.
  3. Use the menu tree on the left of the window to expand and collapse folders as necessary to locate and view data downloaded during the test.
  4. To view a downloaded Web page, select its URL or link description in the menu tree.
  5. To locate replay errors, click the Analyze Test button on the workflow bar and select Find Errors. A new window appears that helps you navigate from one error to the next. HTML errors often occur one or two steps before they are apparent to end users. With TrueLog Explorer you can easily examine the Web pages that were displayed preceding errors.
  6. Compare a replay TrueLog with the TrueLog that was produced during recording of the application.
Parent topic: Visual Analysis with TrueLog Explorer


Log Files

If log-file generation has been enabled, then any errors that are encountered in load tests are reported in log files. Log files contain a record of all the function calls that are invoked by the transactions of each virtual user in load tests. These files contain session and error information, including details for each type of event executed during a simulation, the API calls in a transaction, and the data exchanged with the server.

The process of generating log files alters the time measurements of tests. Therefore, use log files for debugging purposes only. Do not generate them for full load tests.

  • Viewing Log Files
    View session and error information, including details for each type of event executed during a simulation, the API calls in a transaction, and the data exchanged with the server, as well as other information.
Parent topic: Trying Out Scripts


Viewing Log Files

Choose one of the following:
  • From the Silk Performer menu bar, select File > Open > Virtual User Log File and then locate the appropriate file (.log).
  • Right-click the line for a virtual user in the Silk Performer Monitor window and select Show Virtual User Log File from the context menu.
The log file opens.
Parent topic: Log Files


Viewing Report Files

Report files contain the same information as baseline reports for one specific virtual user. This report is based on XML/XSL and includes the most important test results in tabular format.

Note: When TrueLog Explorer opens, the Virtual User Report file is displayed automatically.
Choose one of the following:
  • From the Silk Performer menu bar, select File > Open > Virtual User Report File and then locate the appropriate file (.rpt).
  • Right-click the line for a virtual user in the Silk Performer Monitor window and select Show Virtual User Report File from the context menu.
The report file opens.
  • Report Contents
    Describes the sections of a report.
Parent topic: Trying Out Scripts


Report Contents

A report file contains the following sections:

  • General Information

  • Virtual User

  • Summary Tables

  • Transaction Response Times

  • HTML Page and Action Timers

  • Web Form Measurements

General information

The general information section includes administrative information in a tabular form.

Administrative information includes the Silk Performer version info, the project name, a description of the project, the date and time of the test run, the workload definition, the workload model and the number of errors that occurred.

User types

For the virtual user, a section is available with details of the measured response times. The summary line shows the duration of the test, the session time, the session busy time, the average page time, the average action time, the number of transactions executed successfully, canceled, failed and the number of errors, if any, that occurred.

Summary tables

This section contains summary measurements in a tabular form, that is, aggregate measurements. The first table provides general information, such as the number of transactions that were executed and the number of errors, if any, that occurred. All the following tables provide summary information relevant to the type of application that was tested.

Transactions

This section contains summary measurements in a tabular form, that is, aggregate measurements for all transactions of the specific user. For every transaction, the transaction response time and the transaction busy time are displayed.

The transaction response time is measured from the beginning to the end of the transaction, including all think times.

The transaction busy time is the transaction response time without any think time included.

Page and action timers

This section contains summary measurements in a tabular form for every accessed Web page. For every page, the download time of the whole page, the HTML-document download time, the server busy time, the amount of data downloaded with this page, and the amount of data downloaded for embedded objects are displayed.

Web forms

This section contains summary measurements in tabular form for every used Web form. For every form, the round trip time, the server busy time, the number of HTTP hits, the amount of request data sent and the response data received are displayed.

Parent topic: Viewing Report Files


Output Files

Output files contain the output of write statements that are used in test scripts. An output file is generated for a particular user only if write statements are executed by that user.

Note: Generating output files alters the time measurements of load tests. Therefore, these files should be used for debugging purposes only, and should not be generated for full load tests.
  • Viewing Output Files
    View the output of write statements that are used in test scripts.
Parent topic: Trying Out Scripts
Related reference
Write Statement


Viewing Output Files

Note: Generating output files alters the time measurements of load tests. Therefore, these files should be used for debugging purposes only, and should not be generated for full load tests.
Choose one of the following:
  • From the Silk Performer menu bar, select File > Open > Virtual User Output File and then locate the appropriate file (.wrt).
  • Right-click the line for a virtual user in the Silk Performer Monitor window and select Show Virtual User Output File.
The output file opens.
Parent topic: Output Files


Function and Transaction Declarations

Silk Performer offers GUI tools that assist you in inserting function and transaction declarations into test scripts.

A function is used to encapsulate some tasks that a script requires. Functions can access and change data declared outside themselves, either through variables or parameters. Optionally, a function can return a value of a specific type.

A transaction is a discrete piece of work that is assigned to a virtual user in a test and for which separate time measurements are made.

  • Inserting Function Declarations
    Insert a function declaration into a test script.
  • Inserting Transaction Declarations
    Insert a transaction declaration into a test script.
Parent topic: Customizing Scripts


Inserting Function Declarations

  1. With the test script into which you want to insert a new function open, select Script > New Function from the Silk Performer menu bar. You can also access this dialog by right-clicking within the body of the script and selecting New Function from the context menu. The New Function dialog appears.
  2. In the Name field, enter a name for the function you want to insert into your test script. The name must begin with a character and may consist of any number of letters of the alphabet, digits, and underscores.
  3. From the Return type list box, select the data type of the function's return value. Choose one of the following:
    • none - for the function to return nothing
    • boolean - for the function to return either true or false
    • float - for the function to return any positive or negative floating-point value or zero
    • number - for the function to return any positive or negative whole number or zero
    • string - for the function to return a sequence of characters
  4. In the Parameters list, insert the parameters that you want to pass to the function. For each parameter, enter a name in the Name column and select the data type from the Type list box:
    • boolean - for the parameter to contain either true or false
    • float - for the parameter to contain any positive or negative floating-point value or zero
    • number - for the parameter to contain any positive or negative whole number or zero
    • string - for the parameter to contain a sequence of characters
  5. Use the Preview area to see how the function declaration looks when it is inserted into your script. The declaration contains the parameters you insert into the list as well as the return type. Keep in mind that it is up to you to add the function code after the function declaration has been inserted into the script.
  6. Click OK.
The new function is placed in your script, and appears in the script editor window.
Parent topic: Function and Transaction Declarations


Inserting Transaction Declarations

  1. With the test script into which you want to insert a new transaction open, select Script > New Transaction from the Silk Performer menu bar. You can also access this dialog by right-clicking within the body of the script and selecting New Transaction from the context menu. The New Transaction dialog appears.
  2. In the Name field, enter a name for the transaction you want to insert into your test script. The name must begin with a character and may consist of any number of letters of the alphabet, digits, and underscores.
  3. Click OK.
The new transaction is placed in your script, and appears in the script editor window.
Parent topic: Function and Transaction Declarations


User Groups

User groups are groups of virtual users who share similar, though not identical, behavior. The members of user groups perform slightly different transactions with the goal of simulating real-world client behavior.

User groups are used in conjunction with parameterized user input data and profiles, for example browser types and connection speeds, to simulate typical end-user activity.

User groups are defined by the transactions that they call and the frequency at which they call those transactions. For example, you might have a user group called Searcher that performs a TLogon transaction once, a TSearch transaction five times, and a TLogoff transaction once. You might also have a user group called Updater that performs the TLogon transaction once, the TSearch transaction three times, the TUpdate transaction twice, and the TLogoff transaction once. A third user group called Inserter might perform the TLogon transaction once, the TSearch transaction once, the TInsert transaction three times, and the TLogoff transaction once. Collectively, these user groups can be used to simulate real-world client activity while maintaining load balance, meaning that transactions are distributed in such a way that all users don’t perform the same transaction at the same moment.

When multiple users have the same profile, they can be combined into a user group. The user group list contains the name of the user group, the transactions that are to be invoked by the user group, and the frequency at which the transactions are to be invoked (TransCount). User group descriptions are included in the dcluser sections of Silk Performer test scripts.

  • Customizing User Groups
    Customize a user group or transaction.
Parent topic: Customizing Scripts


Customizing User Groups

  1. Open and activate the BDF script you want to customize
  2. Select Script > Customize User Groups from the Silk Performer menu bar. The Customize User Groups dialog appears.
  3. Right-click a user group or transaction node to open a context menu that lists the available operations:
    • Add a new user group
    • Copy a user group
    • Rename a user group
    • Delete a user group
    • Insert a transaction
    • Copy a transaction
    • Rename a transaction
    • Remove a transaction
    Transactions can be added and removed for each user group. The transaction renaming process renames transactions in all user groups to which they have been assigned.
  4. Select the desired action from the context menu and follow the prompts
  5. Begin and End transactions can be defined for each user group by selecting/deselecting the check boxes in the Begin/End column.
  6. Entries in the Count column, which represent the number of times that transactions are to be called, can be edited directly by clicking them.
  7. When the Choose transactions randomly check box is selected and a user group contains at least two transactions that are neither "begin" transactions nor "end" transactions, the Random Order column shows how the transaction distribution will be weighted, by percentage. For example, if two non-begin and non-end transactions are present, each transaction will have a random order distribution of 50%. If three non-begin and non-end transactions are present, the transactions will have random order distributions of 33%, 33%, and 34%.
  8. Click OK when you’ve completed user group and transaction customization.
The modified data is written to the dcluser section (and dcltrans section if necessary) of your test script.
Parent topic: User Groups


Creating Parameters with the Parameter Wizard

The Parameter Wizard enables realistic functionality to be created for virtual users during tests by replacing recorded or scripted values with constant values, random values, or values pulled from multi-column data files. Each of these value types can be generated using the wizard. This means that you can furnish virtual users with varied personal data for all the information commonly required by Web forms (for example, names, addresses, zip codes, or credit card numbers).

The Parameter Wizard guides you through the process of creating variables and then places the variables in test scripts. A wide range of variable types are provided. Each variable type can generate different value types (strings containing text and/or numbers, serial numbers, whole numbers, and floating-point numbers).

Values can be randomized using different distribution patterns. Comprehensive sets of pre-defined data (for example, names, addresses, or passwords) are also provided.

  • Inserting a Constant Value Into a Script
    Use the Parameter Wizard to replace recorded or scripted values in your script with a single constant value.
  • Inserting Random Values Into a Script
    Use the Parameter Wizard to replace recorded or scripted values in your script with a randomized variable.
  • Inserting Parameters with Values from Multi-Column Data Files
    Use the Parameter Wizard to replace recorded or scripted values in your script with a parameter that pulls values from a multi-column data file.
  • Editing Multi-Column Data Files
    Edit the values or separator type used in multi-column CSV data files.
  • Inserting a Parameter into Your Test Script
    You can insert a pre-existing parameter into your test script.
Parent topic: Customizing Scripts
Related concepts
Customizing User Data
Complex Input/Output Data
Related tasks
Customizing Input Parameters


Inserting a Constant Value Into a Script

  1. In the menu bar, click Script > Create New Parameter . The Parameter Wizard - Create New Parameter dialog box appears.
  2. Click the Create New Parameter icon to open the Parameter Wizard.
  3. Select Constant value.
  4. Click Next.
  5. Select the data type of the variable that you want to insert into your test script from the Data type list box.
  6. In the Name field, enter a name for the new constant value or accept the default name.
  7. In the Value field, enter the value of the new constant value.
  8. Click Finish. The new constant is added to the parameter section of your script. If you opened the wizard via the context menu in your script, the value you selected will be automatically replaced with the newly created variable.

Launch the wizard as often as is required to create more constant values. If you launched the wizard via another method, replace the constant values in your script with the BDL variables you created.

Parent topic: Creating Parameters with the Parameter Wizard
Related reference
Variables Section


Inserting Random Values Into a Script

  1. In the menu bar, click Script > Create New Parameter . The Parameter Wizard - Create New Parameter dialog box appears.
  2. Select Parameter from Random Value.
  3. Click Next.
  4. In the wizard’s Choose the type of random variable window, choose a random variable type from the Random type list box. Use the type description and variable declaration preview provided for each random variable type to choose the required variable and specify its attributes.
  5. Click Next. The Name the variable and specify its attributes window appears.
  6. In the Name field, enter a name for the new constant value or accept the default name.
  7. Specify the attributes of the variable. These vary depending on the type of variable selected. Use the Back button to review the type description of the variable if necessary.
  8. Click Next. The Choose the kind of usage window appears.
  9. Specify how the variable is to be utilized.
    • Per usage: Each use of the random variable generates a new random value.
    • Per transaction: A new value is generated for each transaction call.
    • Per test: The value is the same for the entire test.
  10. Click Finish. The new random variable is then added to the random variables section of your script.

    If you opened the wizard via the context menu in your script, the value you selected will be automatically replaced with the newly created variable.

Launch the wizard as often as is required to create more randomized variables. If you launched the wizard via another method, replace the constant values in your script with the BDL variables you created.

Parent topic: Creating Parameters with the Parameter Wizard
Related concepts
Random Types
Related tasks
Customizing Input Parameters


Inserting Parameters with Values from Multi-Column Data Files

  1. In the menu bar, click Script > Create New Parameter . The Parameter Wizard - Create New Parameter dialog box appears.
  2. Select Parameter from multi-column data file.
  3. Click Next.
  4. In the wizard’s Parameter from multi-column data file window, choose a multi-column data file from the File Name list box.
    1. Select an appropriate separator from the Separator list box, or type a custom separator.
  5. In the Handle name field, type a name for the file handle of the multi-column data file variable or accept the default name.
  6. In the Parameter name field, type a name for the new parameter or accept the default name.
  7. Click Next. The Parameter Wizard - Parameter from Multi-column Data File window appears.
  8. Select a Row selection order and specify the Attribute options.
  9. Specify the attributes of the variable. These vary depending on the type of variable selected. If necessary, use the Back button to review the type description of the variable.
  10. Click Finish.

    The new parameter from a multi-column data file is then added to the parameter section of your script.

    The multi-column data file you selected is also added to your project's data files.

    If you opened the wizard via the context menu in your script, the value you selected is automatically replaced with the newly created variable.

Launch the wizard as often as is required to create more randomized variables. If you launched the wizard via another method, replace the constant values in your script with the BDL variables you created.

Parent topic: Creating Parameters with the Parameter Wizard
Related reference
Variables Section


Editing Multi-Column Data Files

  1. Open the Data Files sub-tree of the Project menu tree.
  2. Double-click the multi-column data file you want to edit. The Edit CSV File window appears.
  3. Choose an appropriate separator for the multi-column data file from the Separator list box or enter a custom separator.
  4. Modify, add, or delete values from the multi-column data files as required.
  5. Click OK to save the changes of the multi-column data file and close the window, or click Save As to save the multi-column data file with a different name.
Parent topic: Creating Parameters with the Parameter Wizard


Inserting a Parameter into Your Test Script

  1. Right-click a customizable value (for example, a string) in your BDL script.
  2. Select Customize Value from the context menu. The Parameter Wizard appears. The Customize Value menu item is disabled if the value in your script is not customizable.
  3. In the wizard’s Customize Value window, select Use existing parameter.
  4. Click Next. The wizard’s Use Existing Parameter window appears.
  5. Select a variable from the list and click Finish. You can choose the data type of the shown parameters from the Show all Parameters of type list box. Silk Performer automatically shows the window with a selected data type that is compatible with the data type of the customized value.
The value you selected is automatically replaced with the existing parameter.
Parent topic: Creating Parameters with the Parameter Wizard


Serialization and Synchronization

There are several Silk Performer functions that allow you to either serialize or synchronize transactions in your test scripts to better control the timing of loads in your simulation. Both serialization and synchronization are implemented using high-level functions that call pre-existing Windows functions.

  • Serialization
    Serialization enables you to test the effects of transactions executed one at a time.
  • Synchronization
    Synchronization is useful in testing the effects of a large number of simultaneously called transactions.
  • Rendezvous Functionality
    Used to create a delay until the specified virtual users reach a certain state, and then to proceed with all the users simultaneously.
  • Multiple Agents
    Silk Performer provides an additional number of functions that extend the use of serialization and synchronization across multiple agents.
Parent topic: Customizing Scripts


Serialization

Serialization enables you to test the effects of transactions executed one at a time. This is useful, for instance in connecting to a server that is not able to handle a large number of concurrent logins.

Serializing users and transactions requires the use of a token or mutex object. Named mutex objects are created by calling the CreateMutex function. The users to be synchronized have to wait until they receive the mutex object. This guarantees that only one user executes a transaction at a time.

After a user has completed the transaction, the user must release the token by calling the ReleaseMutex function. This makes the mutex object available for other users.

Serialization Functions

The following functions are used in serializing transactions and users:

  • CreateMutex
  • CreateMutexEx
  • ReleaseMutex
  • WaitForSingleObject
  • CloseHandle

Serialization Sample Script

The following example is excerpted from a sample script called Mutexlogin.bdf, located in the Samples\Database folder in the Silk Performer installation directory. The script consists of three transactions. TMain waits until the user possesses the token, and then connects to the DBMS; Selling executes the database transaction; and CleanUp closes the connection to the database and releases all the resources.

Initially, a mutex object called MyConnectMutex is created to serialize access to critical sections inside transactions for multiple concurrent users. Calling the WaitForSingleObject function effects a delay until the mutex object is in the signaled state. This means that from that point forward, only the current transaction is executed, and this condition remains until the token is released. During execution time a connection to a database system is established. After successfully connecting, the ownership of the mutex object is released. After these steps have been completed successfully, the transaction is committed. In this example, only connecting to the database system is serialized.

benchmark MutexLogin
use "dbapi.bdh"
var
  gHdbc1 : number; // handle for database connection
  gHMutex : number; // mutex handle
dcluser
  user
    Seller
  transactions
    TMain : begin;
    Selling : 50;
    CleanUp : end;

dcltrans
  transaction TMain
  var
    str: string;
  begin
    // SYNC: serialize connect transaction with mutex object
    // (enter critical section)
    gHMutex := CreateMutex("MyConnectMutex");
    WaitForSingleObject(gHMutex, INFINITE);
    gHdbc1 := DB_Connect("dsn=sqs_purple;uid=u1;pwd=u1");
    Print("Connected!", 1, 1);
    // SYNC: leave critical section and pass control to other user
    ReleaseMutex(gHMutex);
  end TMain;

  // process database transaction
  transaction Selling
  begin
  ...
  end Selling;

  transaction CleanUp
  begin
    DB_Disconnect(gHdbc1);
  end CleanUp;
Parent topic: Serialization and Synchronization


Synchronization

Synchronization is useful in testing the effects of a large number of simultaneously called transactions. It allows you to create stress on your system to test specific concurrency issues. Synchronization works by employing an additional user called an Event Starter, which functions like the starting gun at the beginning of a race. Using the CreateEvent function, you can use the Event Starter user to send an Event object after a specified period of time. You can set up the users in the simulation to wait for this event and thus perform a specified transaction simultaneously when the event is released. Silk Performer provides the PulseEvent function for this purpose.

The other users call the WaitForSingleObject function to wait until the specified event is in the signaled state. Using the WaitFor function, users are able to synchronize themselves without the use of event objects.

Synchronization Functions

The following functions are used in serializing synchronizing and users:

  • CreateEvent
  • PulseEvent
  • WaitFor
  • WaitForSingleObject
  • CloseHandle

Synchronization Sample Script

In the following example, the users create an event object called StarterEvent and establish a connection to an FTP server. The Starter user sets the state of the event object StarterEvent to signaled every ten seconds and resets it after the appropriate number of waiting users process the transaction. In this way, all the Uploader users are forced to execute the TUpload transaction at the same time. The Uploader's wait until the event object is in the signaled state, and then execute their Upload transaction.

dcluser
  user
    Starter
  transactions
    TInit : begin;
    TStartEvent : 20;
  user
    Uploader
  transactions
    TInit : begin;
    TUpload : 20;
var
  hEventGo : number; // handle for starting event
  hFTP : number;

dcltrans
  transaction TInit
  begin
    hEventGo := CreateEvent("StarterEvent");
    WebFtpConnect(hFTP, "standardhost", WEB_PORT_FTP, "username", "password");
  end TInit;

  transaction TStartEvent
  begin
    wait 10.0;
    // every 10 seconds the starter event forces all
    // seller users to execute the selling transaction
    // at the same time
    PulseEvent(hEventGo);
  end TStartEvent;

  transaction TUpload
  begin
    WaitForSingleObject(hEventGo, INFINITE);
    WebFtpPut(hFTP, 4096, "test.dat", true);
  end TUpload;
Parent topic: Serialization and Synchronization


Rendezvous Functionality

This function is used to create a delay until the specified virtual users reach a certain state, and then to proceed with all the users simultaneously. This tests the ability of the system to handle a number of concurrent transactions by making it possible to generate very specific stress on the system. For example, in a transaction that stores a number of files on an FTP server, you may want your script to wait until all the users are logged on, and then to store all the files at the same time.

Rendezvous Functions

Silk Performer includes the following rendezvous function:

  • WaitFor

Rendezvous Sample Script

In this example, the script waits until five virtual users (Buyer) are at the line in the script containing the WaitFor function, and it then proceeds with the transaction.

const
  USERS := 5;
dcluser
  user
    Buyer
  transactions
    TBuy : 10;

dcltrans
  transaction TBuy
  const
    TIMEOUT := 60;
  begin
    // wait for users rendezvousing at this point
    if not WaitFor("Rendezvous", USERS, TIMEOUT) then
      write("timeout"); halt;
    end;
    // proceed with transaction
    print("rendezvous", 1, TEXT_RED);
  end TBuy;
Parent topic: Serialization and Synchronization


Multiple Agents

The serialization and synchronization functionality is available only on a single agent computer. Silk Performer provides an additional number of functions that extend the use of serialization and synchronization across multiple agents.

Serialization across multiple agents is made possible by the GlobalResourceEnter and GlobalResourceRelease functions. GlobalResourceEnter defines a resource that can be occupied by only a limited number of users. The caller has to wait until the number of users who occupy the resource is less than the maximum number of users who are allowed to occupy the resource. The GlobalResourceRelease function releases a resource that was occupied with the GlobalResourceEnter function. If there are users still waiting for the resource, the next user in the queue resumes the simulation.

Synchronization across multiple agents is made possible by the GlobalWaitFor function. This function defines a checkpoint (rendezvous point) and blocks the calling user. The caller waits until a specified number of users (including the caller) have reached or passed the checkpoint, or until a specified timeout occurs. The checkpoint is identified by name and is visible to all the users, including those running on various remote agents. A waiting user continues when the specified timeout is reached or the given number of users have called the function for a checkpoint. A user who has timed out is also regarded as having passed the checkpoint.

The functions GlobalVarGet, GlobalVarInc, and GlobalVarSet are used, respectively, to get, increment, and set the values of global integer variables that are accessible for all the users on all the agents.

For detailed information on these functions, refer to the BDL Function Reference.

Parent topic: Serialization and Synchronization
Related concepts
Synchronization Functions


Check list for building robust scripts

A script that was recorded with the Silk Performer Recorder provides a good starting point for a load test. However, such a raw script usually has two main downsides: It will not produce realistic results and it will not be particularly robust. It is likely to cause errors during replay.

To make your scripts as robust as possible, it is recommended to customize them before you start a load test. When customizing your script, consider the following:

  • Appropriate test data: Most applications require appropriate test data. Make sure to customize your script in a way that makes virtual users employ appropriate user names with correct access rights. If your virtual users execute transactions concurrently, you will probably need to define different user IDs.
  • Dynamic content: Often, the content of an application is dynamic, like link names that change, items being no longer available, products in a web shop being out of stock, and so on. Also, real users usually pursue different paths through an application. A recorded script, however, only contains one specific path. The path may also vary based on time, user, or other conditions.
  • Not available applications: When you start your load test, the application under test might not be available, not yet ready, or a database connection is not yet established. Make sure that your script handles these circumstances appropriately.
  • Timing issues: Some BDL functions use default timeout settings that might not be appropriate for your testing scenario. Adjust these timeout settings to fit your specific needs and to avoid errors.
  • Concurrency issues: Controlling concurrence issues also helps to avoid errors. Your database might be able to respond to only a few virtual users concurrently. Controlling concurrency also helps to make behavior of virtual users more realistic: Real users usually perform one specific task not all at the same time but in a staggered manner. The serialization, synchronization, and rendezvous functionalities of Silk Performer allow you to precisely control the desired behavior of your virtual users.

To make your script even more robust, also consider the following error scenarios. Reflect about how your virtual users are supposed to act when an error occurs. The virtual users can …

  • skip the remaining part of a transaction: This action might be appropriate when a virtual user attempts to buy an item in a web shop that is not in stock at that time. The virtual user could skip that particular transaction and continue with executing the next transaction. Such a behavior can be achieved with a return statement.
  • stop the load test: This action might be appropriate when a database connection cannot be established and the application under test cannot be used without this connection. In such a case, continuing the load test would not be possible. Such a behavior can be achieved with a halt statement.
  • handle an error and continue executing the transaction: This might be useful when a virtual user enters a wrong password on a login page. If the script could handle such a login error, the virtual user could attempt to login with a different password and might be able to continue executing the rest of the transaction. Such a behavior can be achieved with error-handling functions.
Parent topic: Customizing Scripts
Related reference
Halt Statement
Return Statement
Error-Handling Functions


Custom DLLs

In Silk Performer scripts, it’s possible to call functions that are provided in Dynamic Link Libraries (DLLs). This feature allows you to implement functions in any programming language that can generate DLLs and then utilize such external functions in Silk Performer test scripts.

  • External Function Declaration
    In BDL, all external functions called from a script must be declared before they can be used.
  • Function Prototypes
    In the external functions section of scripts, after the name of a DLL has been declared, any number of prototypes of DLL functions can be defined.
  • Parameters in External Functions
    Any type of parameter can be passed to external functions.
  • Structured Data Types in External Functions
    Explains how structured data types can be passed to external functions.
Parent topic: Customizing Scripts


External Function Declaration

Two files are typically required to create a DLL:

  • A source file that contains the implementation of one or more functions
  • A definition file that specifies which functions are to be exported

When developing a DLL using a common C/C++ compiler, the source file (.c, .cpp) and the definition file (.def) must be included in the Visual Studio project.

In BDL, all external functions called from a script must be declared before they can be used. This must be done in the external functions section of Silk Performer scripts.

Note: If a DLL file is not located in the Silk Performer installation directory or a directory included in the path specification, you need to add the DLL file to the project’s data files.
Note: The vb.net dll file is not supported.
The following files contain sample scripts. The files can be found in the following folder and its subfolders: C:\Users\Public\Public Documents\Silk Performer <version>\SampleApps\CustomAPI.
  • DemoFunctions.bdf
  • DemoFunctions.dsp
  • demofunctions.cpp
  • DemoFunctions.dll

Script Example

In the following example, the external functions DemoSum and DemoDiff are declared and then called in the TMain transaction.

dll "DemoFunctions.dll"

  // function without parameters and return value
  "DemoOutput"
    function Output;

  // function declared using C data types
  "DemoSum"
    function Sum(in long, in long): long;

  // function declared using BDL data types
  "DemoDiff"
    function Diff(in number, in number): number;

// DLL is not located in the Silk Performer directory
dll "C:\\Debug\\Functions.dll"

dcltrans

  transaction TMain
  var
    x, y, nSum, nDiff: number;
  begin
    x := 4; y := 5;
    nSum := Sum(x, y); // external function calls
    nDiff := Diff(x, y);
    Output();
  end TransMain;
Parent topic: Custom DLLs
Related tasks
Adding Data Files
Related reference
External Functions Section


Function Prototypes

In the external functions section of a test script, after the name of a DLL has been declared, any number of prototypes of DLL functions can be defined. Each function that is to be used in a Silk Performer script must be declared; these declarations are case-sensitive. Additionally, identifiers that specify the names of all functions that are to be used in BDL scripts must be defined.

When parameters are passed to external functions, it is necessary to indicate whether they are passed into functions by reference or by value (default). Parameters can be declared with BDL data types or basic C data types (long, short, char, float, double, or pointer).

The following table shows the data-type mapping between formal parameters of native functions exported by DLLs, formal parameters of external functions declared in the DLL sections of BDH files, and actual parameters (BDL data types).

Table 1. Data-type mapping
C Data Type | DLL Section (BDH) | BDL Data Type
char | char | Number
unsigned char | unsigned char | Number
short | short | Number
unsigned short | unsigned short | Number
long | long, number, boolean | Number, Boolean
unsigned long | long, number | Number
char* | string | String
*(Pointer) | long, number | Number
float | float | Float
double | double | Float
Ptr (C data type representing a pointer to any data type) | string | String
Parent topic: Custom DLLs


Parameters in External Functions

Any type of parameter can be passed to external functions. While using simple data types is easy, handling arrays and structured data types requires knowledge about the alignment and size of the specific data types in use.

Simple data types allowed as input and output parameters are:
Table 1. Simple data types
C Data Type | BDL Data Type
Char, unsigned char | Number
Short, unsigned short | Number
Long | Number
Double | Float
Float | Float
Char* | String
Note: The unsigned long data type is converted to long when used in Silk Performer scripts.

When a parameter is passed to a function by value, it is declared simply by specifying its type. If a parameter is passed by reference (for example, if it is used as an output parameter), a pointer to the data type must be defined.

The example below illustrates how function parameters are declared in C and how corresponding external functions must be declared in BDL. In addition, an example of an external function call is provided.

C Source Code

In this example, the external function T_PARAM receives the following input parameters: inChar, inShort, inLong, inDouble, inFloat, inUShort, and inUChar. A corresponding output parameter belongs to each: outChar, outShort, outLong, outDouble, outFloat, outUShort, and outUChar. These parameters must be declared as pointers because during function calls references to the variables are passed to the functions. Additionally, a string called inoutString is declared as an input and output parameter.

char* T_PARAM( char            inChar,      // in
               short           inShort,
               long            inLong,
               double          inDouble,
               float           inFloat,
               unsigned short  inUShort,
               unsigned char   inUChar,
               char*           inoutString, // in/out
               char*           outChar,     // out
               short*          outShort,
               long*           outLong,
               double*         outDouble,
               float*          outFloat,
               unsigned short* outUShort,
               unsigned char*  outUChar )
{
  char sBuffer[1000];
  // copy the values of the input parameters to the
  // output parameters and the return value
  return sBuffer;
}

BDL External Function Declarations

To use the above-defined T_PARAM function in BDL, the function must be declared in the external functions section of a Silk Performer script. This is illustrated in the example below. In this case, the parameters are defined as formal data types. The comments attached to each parameter indicate the corresponding BDL data type.

"T_PARAM" function t_param(
  in char,                         // in number
  in short,                        // in number
  in long,                         // in number
  in double,                       // in float
  in float,                        // in float
  in unsigned short,               // in number
  in unsigned char,                // in number
  inout string,                    // inout string
  out char,                        // out number
  out short,                       // out number
  out long,                        // out number
  out double,                      // out float
  out float,                       // out float
  out unsigned short,              // out number
  out unsigned char): string(100); // out number

BDL External Function Calls

The following example illustrates how to call the T_PARAM function. In this example, random values are assigned to the variables and passed to the function as input parameters.

dcltrans
  transaction TMain
  var
    n1, n2, n3, n4, n5, n6, n7, n8, n9, n10 : number;
    f1, f2, f3, f4                          : float;
    s1, sRet                                : string;
  begin
    n1   := 127; n2 := 32000; n3 := 2000000;
    n4   := 64000; n5 := 255;
    f1   := 12345.12345; f2 := 12.99;
    s1   := "Teststring";
    sRet := t_param(n1, n2, n3, f1, f2, n4, n5, s1,
                    n6, n7, n8, f3, f4, n9, n10);
  end TMain;
Parent topic: Custom DLLs


Structured Data Types in External Functions

When using structured data types, it is important to pay attention to the alignment and size of structure elements. The table below shows the size of all conventional data types that can be used within function declarations in Silk Performer scripts.

Simple data types allowed as input and output parameters are:
Table 1. Conventional data type sizes
Data Type | Size
Char, unsigned char | 1
Short, unsigned short | 2
Long | 4
Double | 8
Float | 4
Char[x] | x

C Source Code

The example below clarifies structure composition by showing a data structure that contains all the simple data types.

// declare a demo data structure
#pragma pack(1) // alignment to 1-byte boundaries
typedef struct {
  char           myChar;       // size: 1 byte pos: 1
  short          myShort;      // size: 2 bytes pos: 2
  long           myLong;       // size: 4 bytes pos: 4
  double         myDouble;     // size: 8 bytes pos: 8
  float          myFloat;      // size: 4 bytes pos: 16
  unsigned short myUShort;     // size: 2 bytes pos: 20
  char           myString[10]; // size: 10 bytes pos: 22
  unsigned char  myUChar;      // size: 1 byte pos: 32
} TESTSTRUCT;
#pragma pack()

 char* T_STRUCT(TESTSTRUCT * s)
{
  char sBuf[10000];
  // manipulate values of data structure and generate a
  // return value for demonstration purpose
  ...
  return sBuf;
}

BDL External Function Declarations

To handle structured data types, BDL uses strings of appropriate length and number of type-dependent Get and Set functions. For each structured data type passed to a function, an inout string parameter must be defined. These strings must be exactly as long as the data structures defined in the DLLs.

The first position in a BDL string that can hold a structured data type is one (1). When variables are aligned to one-byte boundaries, the starting position of the next element is derived by adding the current position to the size of the current element. For the data structure declared in the example above, a 32-byte string is required.

"T_STRUCT"
  function t_struct(inout string(32)): string(1000);

BDL External Function Calls

In the following example, arbitrary values are assigned to all the elements of the data structure using the corresponding Set functions. Next, the external function t_struct is called to manipulate the data structure.

dcltrans
  transaction TMain
  var
    n1, n2, n3, n4, n5  : number;
    n6, n7, n8, n9, n10 : number;
    f1, f2, f3, f4      : float;
    sStruct             : string(100);
    sRet                : string(1000);
  begin
    /* one-byte alignment */
    SetChar (sStruct, 1, 127);
    SetShort (sStruct, 2, 32000);
    SetLong (sStruct, 4, 2000000);
    SetDouble(sStruct, 8, 12345.12345);
    SetFloat (sStruct, 16, 12.99);
    SetUShort(sStruct, 20, 64000);
    SetString(sStruct, 22, "123456789", 10);
    SetUChar (sStruct, 32, 255);
    sRet := t_struct(sStruct);
  end TMain;
Parent topic: Custom DLLs
Related concepts
Data Structure Functions


Client IP Address Simulation

This chapter explores the client IP address simulation feature of Silk Performer. The method of configuring network interface cards for multiple IP addresses is explained, as are the script functions used to set up local IP addresses. A brief introduction describes how to activate newly installed/assigned IP addresses.

  • Multiple IP Addresses per NIC
    Describes multi-homed systems.
  • Adding IP Addresses in the System Configuration Wizard
    You can add IP addresses in the System Configuration Wizard. This topic describes step by step how to proceed.
  • Setting Dynamic User IP Addresses Using Automatic Round-Robin
    Describes how to set dynamic user IP addresses in the Profile dialog box.
  • Setting Dynamic User IP Addresses Using Script Functions
    Describes the functions WebSetLocalAddress and WebTcpipConnect, which are used to set up dynamic user IP addresses.
  • Routing Problems Due to Client IP Address Simulation
    Describes possible problems due to client IP address simulation.
  • Solutions for Routing Problems Due to Client IP Address Simulation
    Describes several options to configure servers to send responses to multi-homed clients.
  • Testing Routing Adaptations
    Describes how to use the System Configuration Manager to test if newly added IP addresses and routing adaptations work correctly.
Parent topic: Customizing Scripts


Multiple IP Addresses per NIC

If a computer is configured with more than one IP address, it is referred to as a multi-homed system. Multi-homed systems are supported in one of three ways:
  • Multiple IP addresses per NIC (logical multi-homed): Using the Control Panel, five addresses per card may be configured. However, more addresses may be added to the registry.
    • Requirements: NT4, SP4
    • The total number of IP addresses allowed per NIC depends on the installed NIC. Based on the test results, a 3COM905BTX can handle about 2000 IP addresses.
  • Multiple NICs per physical network (physical multi-homed):
    • No restrictions other than hardware.
  • Multiple networks and media types:
    • No restrictions other than hardware and media support.
Parent topic: Client IP Address Simulation


Adding IP Addresses in the System Configuration Wizard

  1. Disable DHCP and add gateway and DNS addresses.
  2. Select Tools > System Configuration Manager.
  3. Connect to the machine to which you want to add new IP addresses: Click Connect to, select a machine and click Connect.
    Note: By default, you will be connected to the localhost. If you cannot connect to a particular host, make sure that the Silk Launcher Service is running on that host.
  4. Click the IP Address Manager tab and select the network adapter to which you want to add new IP addresses and click Add.
  5. Specify the IP addresses you want to add.
    • Number: The number of sequential IP addresses to be added subsequent to the one specified in the From IP address field.
    • To IP address: Any number of IP addresses will be added until this IP is matched. Addresses must be sequential and can either increase or decrease.
    Note: If you use the From IP address and the To IP address fields, make sure that the To IP address value is higher than the From IP address value. For example: From: 192.12.23.1, To: 192.12.23.108
  6. Reboot the machine.
  7. To verify that the IP addresses you added are valid, either:
    • Call ipconfig.exe (within the shell) to verify that all IP addresses are configured properly.
    • Launch the System Configuration Manager to test that the IP addresses were added correctly.
    Note: By clicking the Check button with the Host name or IP address field blank, the System configuration Manger checks that all added IP addresses are working correctly. If you enter a particular IP address into the Host name or IP address field, only that address will be checked.
During replay you can use a third-party tool to examine the bindings to the local virtual IP address. TCPView can be downloaded from http://www.sysinternals.com.
Parent topic: Client IP Address Simulation


Setting Dynamic User IP Addresses Using Automatic Round-Robin

  1. Select Settings > Active Profile.
  2. On the left side of the Profile dialog box, click Internet.
  3. Check the Client IP address multiplexing check box.
  4. Run your test and use a utility such as TCPView to verify your IP address multiplexing.
Parent topic: Client IP Address Simulation


Setting Dynamic User IP Addresses Using Script Functions

To set up dynamic user IP addresses with functions, use the WebSetLocalAddress and the WebTcpipConnect functions.

For sample applications, review the file WebMultipleClientIpAddresses01.bdf.

Parent topic: Client IP Address Simulation


Routing Problems Due to Client IP Address Simulation

  • Sending packets from multi-homed clients to servers: With multi-homed clients, the destination IP address is always the IP address of the selected server. There are no differences between network operations, and problems usually do not arise when delivering packets from multi-homed clients.
  • Sending packets from servers to multi-homed clients: Problems arise when a server attempts to send back a reply to a multi-homed client using the destination IP address of the sending client application. If the IP address is a local subnet-address, the packet will find its way back to the client because there is already a correct entry in the server's routing table. If the selected IP address does not belong to the local subnet and the server does not find another matching entry in its routing table (this is the normal behavior when entries have not been added) it sends the packet to the default gateway (using the default entry). If it does not find a default entry, it generates a network unreachable error.
Parent topic: Client IP Address Simulation


Solutions for Routing Problems Due to Client IP Address Simulation

There are several options for configuring servers to send responses to multi-homed clients. Here are two options for different network configurations:

Server and agent on the same subnet

If there is no router between the agent and the server, you must add entries to the routing table of the server. If the generated IP addresses of the client begin with the same two numbers (for example 192.200.), you only need to add one entry to the routing table (route add 192.200.0.0 mask 255.255.0.0<your normal IP address>). The server will consider the client as the appropriate router for all addresses beginning with 192.200.

In the example below, server 1 receives a packet from agent 1 and attempts to send its answer from 192.168.20.50 to 192.200.2.1. If you do not modify the server configuration (which means the server does not know that agent 1 is multi-homed), server 1 will send the packet to the default gateway, because there is only one matching entry in the routing table.

Network destination | Netmask | Gateway | Interface | Metric
0.0.0.0 | 0.0.0.0 | 192.168.20.18 | 192.168.20.126 | 1

If you call (at server 1) route add 192.200.0.0 mask 255.255.0.0 192.168.20.21, a new entry will be added. The entry resembles the following:

Network destination | Netmask | Gateway | Interface | Metric
192.0.0.0 | 255.255.0.0 | 192.168.20.21 | 192.168.20.50 | 1

As this entry has a higher priority than the entry of the default gateway, server 1 will send all packets with a destination address type of 192.200.x.x to agent 1 (believing this to be the correct gateway).

Router or load-balancer between the server and the agent

A router or load-balancer is positioned between the server and the agent. In such a case, you must alter the routing table of the router. If agent 1 sends a packet to server 1 (from 192.200.2.1 to 192.168.10.50) and agent 1 is configured correctly, that means it has a routing table entry that resembles the following:

Network destination | Netmask | Gateway | Interface | Metric
192.168.1.0 | 255.255.0. | 192.168.20.70 | 192.168.20.21 | 1

Agent 1 will send the packet to the router, which will in turn forward the packet to server 1. Now server 1 wants to send a response to the request of agent 1 (from 192.168.10.50 to 192.200.2.1). Because of its default entry in the routing table, server 1 sends the packet to the router. However, now problems arise because the router knows nothing of the new IP addresses of agent 1 and will use its default route (shown below) and send the packet to the gateway.

Network destination | Netmask | Gateway | Interface | Metric
0.0.0.0 | 0.0.0.0 | 192.168.20.18 | 192.168.20.70 | 1

If you call (at the router) route add 192.200.0.0 mask 255.255.0.0 192.168.20.21, a new entry will be added, the resembles the following:

Network destination | Netmask | Gateway | Interface | Metric
192.200.0.0 | 255.255.0.0 | 192.168.20.21 | 192.168.20.70 | 1
Because this entry has a higher priority than the entry of the default gateway, the router will send all packets with a destination address type of 192.200.x.x to agent 1 (believing it to be the correct gateway).
Note: You can configure the default gateway of your subnet to forward all packets from the server to the multi-homed agent. However, this might cause problems when a router is forced to send out a packet through the same interface by which the packet is received, the router thinks that the server that originally sent the packet made an incorrect routing decision. The router then generates an ICMP redirect error. This also increases load on the network and server.
Parent topic: Client IP Address Simulation


Testing Routing Adaptations

Use the System Configuration Manager to test if newly added IP addresses and routing adaptations work correctly:
  1. Select Tools > System Configuration Manager. The System Configuration Manager window appears.
  2. Connect to the machine to which you added new IP addresses.
    Note: By default, you will be connected to the localhost. If you cannot connect to a particular host, make sure that the Silk Launcher Service is running on the host.
  3. Click the IP Address Manager tab.
  4. Select the network adapter to which you added new IP addresses.
  5. In the Network section, enter the host name or IP address of the server you want to load test.
  6. Click Check. If no error window appears, all listed IP addresses will have a route is up mark in the Test result section of the list window.
Parent topic: Client IP Address Simulation


User Types

A User type is a unique combination of a script, a user group, and a profile.

Silk Performer automatically generates all possible combinations of user types out of the available scripts, user groups and profiles. To have all user types that you need available, you must add the desired profiles to your test project beforehand. For example, to emulate three different bandwidths during your load test, you must first add a profile for each bandwidth.

The Find Baseline or the Define User Types dialog box allow you to assign user types to the active workload.

You can run a baseline test to establish the baseline performance of your load test for the selected user types. The different user types can be run at the same time.

Only one virtual user per user type is executed for the baseline test. The think times contained in the script are not randomized for comparison reasons.

Parent topic: Defining User Types
Parent topic: Finding Baselines


Baseline Tests

A baseline test enables you to determine your application's ideal performance baseline.

With a baseline test, a customized test is run with just one user per user type. And the results from this unstressed performance of the application form the basis for calculating the number of concurrent users per user type and for setting the appropriate boundaries for the HTML page response times and transaction response times. Additionally, the required bandwidth for running the load test is calculated from the baseline results. The measurements typical of a real load test are used, and report and output files are generated.

Additionally, a baseline test can serve as a trial run of your test script. A trial run can help you verify the following:

  • Customizations have not introduced new errors into the script.
  • The script can accurately and fully reproduce the interaction between the client application and the server.
Note: Baseline tests ignore the Random thinking time option. This makes it easier for you to compare the results of different baseline tests because the think times remain constant between tests.
For baseline test runs, the following settings are configured automatically:
  • A Baseline report file is automatically created.

  • The Stop virtual users after simulation time (Queuing Workload) option is enabled.

  • The Random thinking time option is disabled.
  • The Loadtest description text box is set to Baseline Test.

  • The Display All Errors Of All Users option in the Monitor window is enabled.

  • The Virtual user output files (.wrt) option is enabled.
  • The Virtual user report files (.rpt) option is enabled.
Parent topic: Finding Baselines


Baseline Test Summary

When a baseline test run is complete, the Baseline Test Summary page appears. You can also open this page from the Results tree. You can perform the following actions in the Next Steps area on the right side:

  • Click View baseline test report to view all the metrics of the baseline test run in detail.
  • Click Set as baseline to make the test you have just run your baseline (your reference level) for the upcoming load tests.
  • Click Compare with baseline to compare the results of the test you have just executed with the current baseline. This button is only visible if there is already a baseline set.
  • Click Adjust Workload to perform the next step in the workflow. This button is only visible if you have not yet defined a workload.

You can always return to the Baseline Test Summary page by opening it from the Results tree.

Note: When you click Set as baseline, the Baseline Summary page appears. Do not confuse the Baseline Test Summary page with the Baseline Summary page. The Baseline Test Summary page appears when a baseline test is complete. The Baseline Summary page appears when you have set the baseline test as your baseline or when you click View Baseline on the workflow bar.

You can run one or more user types in a baseline test. If you set the results as baseline, the user types and their results will be added to the baseline. If a baseline with results for a particular user type already exists, these results will be overwritten.

Note: If you want to prevent the summary page to appear each time a test is complete, disable the Show Summary Page button in the toolbar of the Monitor page.
Parent topic: Finding Baselines


Baseline Test Report

After you have run a baseline test, the Baseline Test Summary page appears. Click View baseline test report to view a detailed report with all results and metrics of the baseline test. The detailed test report can be displayed for any test except a Try Script run.

The detailed test report is an XML/XSL-based report that provides you with a summary table, transaction response-time details, timers for all accessed HTML pages, Web forms, and errors that occurred. This information includes the most important test results in a tabular form and is available for all user types involved in the test.

Parent topic: Finding Baselines


Detailed Test Report Content

A detailed test report consists of the following sections:

  • General information

  • User types

    • Summary tables

    • Transaction response times

    • HTML page and action timers

    • Web form measurements

    • Accept Results button

General Information

The General Information section includes administrative information in tabular form.

Administrative information includes the Silk Performer Version information, the project name, a description of the project, the date and time of the baseline test, the workload definition, the workload model, and the number of errors that occurred.

User Types

For each user type involved in the test run, a separate section is available with details on the measured response times. The following information appears in the summary line:

  • Number of virtual users (one for a baseline test)
  • Test duration
  • Session time
  • Session busy time
  • Average page time
  • Average action time
  • The following numbers:
    • Transactions that were executed successfully
    • Canceled transactions
    • Failed transactions
    • Errors

The session time consists of the execution time of all transactions defined in the dcluser section of a test script, without the initial and end transactions. The session busy time is calculated as the session time minus think times, as the following example shows.

dcluser
  user
    Vuser1
  transactions
    TInit  : begin;
    T1     : 1;
    T2     : 3;
    Tend   : end;

The session time is the average response time of T1 + 3 * average response time of T2. The session busy time is the same without any think time.

If you are satisfied with the results, you can set them as baseline results and save them for further processing, such as the calculation of the number of concurrent virtual users and the network bandwidth needed for the load test.

For each user type, detailed results are available in the following sections:

  • Summary tables – Contains aggregate measurements of all virtual users in tabular form. The first table provides general information, such as the number of transactions that were executed and the number of errors that occurred. The remaining tables provide summary information that is relevant to the tested application type.
  • Transactions – Displays the following aggregate measurements in tabular form for all transactions of a specific user type:
    • Transaction response time – Measured from the beginning to the end of the transaction, including all think times.
    • Transaction busy time – The transaction response time without any think time.
  • Page and action timers – Displays the following summary measurements in tabular form for every accessed Web page:
    • Download time of the entire page
    • HTML-document download time
    • Server busy time
    • Amount of data downloaded with the page
    • Amount of data downloaded for embedded objects
  • Web forms – Displays the following measurements in tabular form for every used Web form:
    • Roundtrip time
    • Server busy time
    • Number of HTTP hits
    • Amount of request data that was sent
    • Amount of response data that was received

If the results of an inspected load test are acceptable for use as a baseline, you can store them for further calculations and processing by clicking Accept Results. The results of tests with all user types involved are stored in the file <projectdir>\BaselineResults\baselineReport_<workloadname>.brp. You must define a separate baseline for every workload that is defined in your load test project. If you create a copy of a workload, the baseline results are also copied.

Parent topic: Finding Baselines


Setting a Baseline Test as Baseline

Before you can set a baseline, you must run a baseline test:
  1. Click Find Baseline on the workflow bar. The Workflow - Find Baseline dialog box appears.
  2. Click Run to start the baseline test. For more information on this dialog box, see Finding a Baseline.
  3. When the baseline test run is finished, the Baseline Test Summary page appears.
  4. Click Set as baseline in the Next Steps area on the right side.
  5. Click Yes on the confirmation dialog box.
The baseline test is set as baseline and the Baseline Summary page appears.
Note: The buttons Find Baseline and View Baseline are only visible if the full workflow bar is enabled.
Note: By default, Silk Performer displays the simple workflow bar. To switch between the workflow bar types, right-click on the workflow bar and click Show Simple Workflow Bar, Show Full Workflow Bar, or Show Monitoring Workflow Bar.
Parent topic: Finding Baselines


Baseline Summary

When you have clicked Set as baseline on the Baseline Test Summary page, the Baseline Summary page appears. You can perform the following actions in the Next Steps area on the right side:
  • Click View baseline report to view all the metrics of the baseline in detail.
  • Click Set response time thresholds to configure in what timeframe the subsequent load tests should respond.

You can always return to the Baseline Summary page by clicking View Baseline in the workflow bar.

Note: Do not confuse the Baseline Test Summary page with the Baseline Summary page. The Baseline Test Summary page appears after you have run a baseline test. The Baseline Summary page appears when you set the baseline test as your baseline or when you click View Baseline on the workflow bar.
Parent topic: Viewing Baselines


Response Time Thresholds

With the accepted results from the previous baseline tests, thresholds for response times can be set for subsequent load tests. These thresholds are used in the general overview report of a load test to separate good, acceptable, and unacceptable Web response times.

Set boundaries to identify the following types of response times:

  • Good response times fall below boundary 1.
  • Unacceptable response times fall above boundary 2.
  • Acceptable response times fall between these boundary values.
Set thresholds for the following objects:
  • Transaction response times
  • Custom timers
  • HTML page timers

Specify a multiplier for the calculation of the boundaries from the baseline results. The average response times of the timers are multiplied by these factors, and the boundaries are set accordingly. For example, a multiplier of 3 means that you set a boundary three times higher than the average response time of the timer in the baseline test.

If the measured value in the baseline test is 0, you can specify a minimum value for the boundaries. The load testing scripts connected with the user types is updated to set the thresholds accordingly.

Parent topic: Viewing Baselines


Performance Levels

When a load test is completed, a performance engineer usually has to assess whether the test has been successful or not. This assessment is typically based on a thorough analysis of the load test results.

Performance engineers can use the broad range of analysis tools that the Workbench and Performance Explorer provide. They can use the various reports to analyze a number of metrics, such as the amount of errors or the response time thresholds. They could also compare response times to performance criteria or service levels, which are usually determined prior to the load test execution.

This process can be described as manual load test assessment. However, in many cases an automatic assessment of the load test is useful. For example: In continuous integration environments, users typically want to be notified only in case performance criteria have been violated. In Silk Performer, you can use the so-called performance levels for such scenarios. Performance levels can be defined in two ways: proactively and reactively.

  • Proactive approach: A performance engineer runs a baseline test, then defines performance levels (based on the baseline test results), and assigns the performance levels to the key measures of a test. Now the engineer executes the load test. When the execution is completed, the engineer opens an overview report and checks which performance levels have been missed.
  • Reactive approach: The performance engineer executes the load test first and, only then, defines the performance levels. The load test results are used as a guideline for defining the performance levels.

Of course, these approaches can also be combined. This might be necessary, if performance levels have been defined prior to a load test execution and need to be adapted when the execution is completed, because the reports do not reflect the desired status.

To cover both approaches, you can access the performance level dialogs through the Workbench and Performance Explorer. In the Workbench, click Project > Define Performance Levels or Project > Assign Performance Levels. In Performance Explorer, click the Reports tab and click Define Levels or Assign Levels.

  • Defining and Assigning Performance Levels (Proactive Approach)
    Describes how to set up performance levels using the proactive approach.
  • Defining and Assigning Performance Levels (Reactive Approach)
    Describes how to set up performance levels using the reactive approach.
Parent topic: Viewing Baselines


Defining and Assigning Performance Levels (Proactive Approach)

To assign performance levels to measures, Silk Performer needs to know the measures that will be available after a load test. Therefore, make sure to run a baseline test and set a baseline before you follow the steps described below. If no baseline is set, there are no measures available to assign performance levels to.
  1. In the Workbench, click Project > Define Performance Levels.
  2. The Define Performance Levels dialog displays, containing a table. The table rows represent the performance levels. You can add as many performance levels as you require.
  3. The columns represent the performance indicators. Per column, select one of the following performance indicators:
    • Avg: average value
    • P50: median
    • P90: 90th percentile
    • P95: 95th percentile
    • P99: 99th percentile
  4. Name your performance levels and enter values for each level.
  5. When your performance levels are defined, click Assign Levels.
  6. The Assign Performance Levels dialog shows all measures that were collected during the baseline test. You can assign the defined performance levels manually to each measure. Or you can click Automatically set levels based on baseline. You can also filter the list to quickly find a specific measure, and you can click Reset all levels to none. When you are done, click OK.
Complete modeling your load test and execute it. When the execution is completed, open an overview report and look out for the performance levels. They are color-coded: Performance levels that are met display in green, performance levels that are missed display in red. This allows you to instantly see whether a load test is to be considered as passed or failed. To tweak your settings after the load test execution, follow the reactive approach.
Note: A performance level definition is valid for a particular workload. If you have multiple workloads, you can define performance levels for each workload.
Parent topic: Performance Levels


Defining and Assigning Performance Levels (Reactive Approach)

  1. Model and execute a load test.
  2. When the execution is completed, the Load Test Summary page displays. Click Analyze load test. Performance Explorer opens and the HTML Overview Report displays.
  3. Click the Reports tab and Define Levels.
  4. The Define Performance Levels dialog displays, containing a table. The table rows represent the performance levels. You can add as many performance levels as you require.
  5. The columns represent the performance indicators. Per column, select one of the following performance indicators:
    • Avg: average value
    • P50: median
    • P90: 90th percentile
    • P95: 95th percentile
    • P99: 99th percentile
  6. Name your performance levels and enter values for each level.
  7. When your performance levels are defined, click Assign Levels.
  8. The Assign Performance Levels dialog shows all measures that were collected during the load test. You can assign the defined performance levels manually to each measure. Or you can click Automatically set levels based on baseline. You can also filter the list to quickly find a specific measure, and you can click Reset all levels to none. When you are done, click OK.
Look out for the performance levels in the overview report. They are color-coded: Performance levels that are met display in green, performance levels that are missed display in red. This allows you to instantly see whether a load test is to be considered as passed or failed. To set your performance levels before executing the load test, follow the proactive approach.
Note: A performance level definition is valid for a particular workload. If you have multiple workloads, you can define performance levels for each workload.
Parent topic: Performance Levels


Adjusting Workload

Configuring workload is part of the process of conducting a load test. Silk Performer offers different workload models to be used as a basis for your load test. Before configuring workload, you must select the model that best fits your needs.

You can define more than one workload model in your load test project and save them for further usage, but only one workload model can be active at a time. The accepted baseline results are associated with a workload model. If you copy or rename a workload model, the accepted baseline results are copied or renamed accordingly.

  • Workload Models
    Describes the types of workload models.
  • Workload Tab
    Enables you to configure workload-profile settings related to workload model, start time, and monitoring options.
  • Time Names in Workload Context
    Describes the time values that can be configured in the Select and adjust Workload and Workload Configuration dialogs.
  • Initializing Workload Settings
    Describes how to specify the same workload settings for multiple user types at a time.
Parent topic: Managing Load Tests


Configuring Increasing Workload

  1. Click Adjust Workload on the workflow bar. The Workflow - Select and adjust Workload dialog box appears.
  2. Select the workload model Increasing.
  3. Select a user type and set the following values:
    1. Ramp-up time: Specify the initial number of virtual users (Start VUsers), the maximum number of virtual users (max. VUsers), and the number of virtual users to be added in a specific time interval (Add x per x). Based on these values, Silk Performer calculates the ramp-up time.
    2. Steady time: Specify the steady time.
    3. Ramp-down time: Specify the number of virtual users to be stopped in a specific time interval (Per x stop x).
    4. Warm-up time: During the warm-up time, Silk Performer does not measure the performance. The measuring starts after the warm-up time. Enter zero to start the measuring immediately. You can use the warm-up time to prepare the application under test for the actual load test. If you do not want to take measures during this preparation phase, you can use the warm-up time.
    5. Measurement time: Specify a measurement time. If the measurement time is set to 0, all measures taken between the warm-up time and the end of the simulation time are considered in the reports.
    6. Close-down time: When the close-down time starts, Silk Performer will stop measuring the performance. To stop the load test right after the measurement time, make sure that your warm-up and measurement times sum up to the simulation time. You can use the close-down time to shut down the application under test or to close services if you do not want to take measures during this tidying-up phase.
    Note: The sum of the Ramp-up time and the Steady time must not be shorter than the sum of the Warm-up time and the Measurement time.
    Tip: You can enter the time in the format hh:mm:ss or you can enter for example 1h12m30s. Silk Performer will automatically convert 1h12m30s into 01:12:30. If you just enter 7m, it will be converted into 00:07:00.
  4. Click Next. The Workflow - Assign Agents dialog box appears.
Parent topic: Workload Models
Related concepts
Configuring Monitoring
Assigning Agents


Configuring Steady State Workload

  1. Click Adjust Workload on the workflow bar. The Workflow - Select and adjust Workload dialog box appears.
  2. Select the workload model Steady State.
  3. Select a user type and set the following values:
    1. max. VUsers: The number of virtual users that will be run during the load test.
    2. Steady time: Defines how long the load test will last.
    3. Ramp-down time: Specify the number of virtual users to be stopped in a specific time interval (Per x stop x).
    4. Warm-up time: During the warm-up time, Silk Performer does not measure the performance. The measuring starts after the warm-up time. Enter zero to start the measuring immediately. You can use the warm-up time to prepare the application under test for the actual load test. If you do not want to take measures during this preparation phase, you can use the warm-up time.
    5. Measurement time: Specify a measurement time. If the measurement time is set to 0, all measures taken between the warm-up time and the end of the simulation time are considered in the reports.
    6. Close-down time: When the close-down time starts, Silk Performer will stop measuring the performance. To stop the load test right after the measurement time, make sure that your warm-up and measurement times sum up to the simulation time. You can use the close-down time to shut down the application under test or to close services if you do not want to take measures during this tidying-up phase.
    Tip: You can enter the time in the format hh:mm:ss or you can enter for example 1h12m30s. Silk Performer will automatically convert 1h12m30s into 01:12:30. If you just enter 7m, it will be converted into 00:07:00.
  4. Click Next. The Workflow - Assign Agents dialog box appears.
Parent topic: Workload Models
Related concepts
Configuring Monitoring
Assigning Agents


Configuring Dynamic Workload

  1. Click Adjust Workload on the workflow bar. The Workflow - Select and adjust Workload dialog box appears.
  2. Select the workload model Dynamic.
  3. Select a user type and set the max. VUsers value. This is the maximum number of virtual users that can be run during the load test. It is the upper boundary for upcoming virtual user settings.
  4. Click Next. The Workflow - Assign Agents dialog box appears.
Parent topic: Workload Models
Related tasks
Assigning Agents to Workload


Configuring All Day Workload

  1. Click Adjust Workload on the workflow bar. The Workflow - Select and adjust Workload dialog box appears.
  2. Select the workload model All Day.
  3. Select a user type and set the following values:
    1. max. VUsers: The maximum number of virtual users that can be run during the load test. This is the upper boundary for upcoming virtual user settings.
    2. Simulation time: Defines how long the load test will last.
    Tip: You can enter the time in the format hh:mm:ss or you can enter for example 1h12m30s. Silk Performer will automatically convert 1h12m30s into 01:12:30. If you just enter 7m, it will be converted into 00:07:00.
  4. Click Next. The All Day Workload Configuration dialog box appears.
  5. Select a user type from the list on the left side and configure intervals by entering values into the grid on the right side. Define a start and an end number of virtual users, as well as the duration for each interval. The chart on the top visualizes your settings.
    Note: When a load test was started, you can still change the number of virtual users for intervals that have not yet started, but you cannot exceed the maximum number of virtual users specified for the load test.
  6. Click OK. The Workflow - Assign Agents dialog box appears.
Parent topic: Workload Models
Related concepts
Configuring Monitoring
Assigning Agents


Configuring Queuing Workload

  1. Click Adjust Workload on the workflow bar. The Workflow - Select and adjust Workload dialog box appears.
  2. Select the workload model Queuing.
  3. Select a user type and set the following values:
    1. max. VUsers: The number of virtual users that will be run during the load test.
    2. Steady time: Specify the steady time.
    3. Ramp-down time: Specify the number of virtual users to be stopped in a specific time interval (Per x stop x).
    4. Warm-up time: During the warm-up time, Silk Performer does not measure the performance. The measuring starts after the warm-up time. Enter zero to start the measuring immediately. You can use the warm-up time to prepare the application under test for the actual load test. If you do not want to take measures during this preparation phase, you can use the warm-up time.
    5. Measurement time: Specify a measurement time. If the measurement time is set to 0, all measures taken between the warm-up time and the end of the simulation time are considered in the reports.
    6. Close-down time: When the close-down time starts, Silk Performer will stop measuring the performance. To stop the load test right after the measurement time, make sure that your warm-up and measurement times sum up to the simulation time. You can use the close-down time to shut down the application under test or to close services if you do not want to take measures during this tidying-up phase.
    Tip: You can enter the time in the format hh:mm:ss or you can enter for example 1h12m30s. Silk Performer will automatically convert 1h12m30s into 01:12:30. If you just enter 7m, it will be converted into 00:07:00.
  4. Click Next. The Workflow - Assign Agents dialog box appears.
Parent topic: Workload Models
Related tasks
Assigning Agents to Workload


Configuring Verification Workload

  1. Click Adjust Workload on the workflow bar. The Workflow - Select and adjust Workload dialog box appears.
  2. Select the workload model Verification.
  3. Select a user type and click Next. The Verification Workload Configuration dialog box appears.
  4. Select a Profile and a Script from the lists.
  5. Select a Usergroup.
  6. Select an Agent from the list.
  7. In the TrueLog section, click one of the following options:
    • Click Generate TrueLog to generate a Truelog file for the virtual user group that you are testing.
    • Click Generate TrueLog On Error to generate a TrueLog file only when an error occurs.
  8. Optional: Check the Animated check box to launch the TrueLog Explorer automatically when you start a test.
    Note: You must click Generate TrueLog to enable the Animated setting.
  9. Check the Stress test check box to disable the use of wait periods that are specified in Web functions or are invoked by calling the think-time function. Neither the wait statement nor the transaction scheduling is affected. This feature is equivalent to running a load test with no delays for human interaction.
  10. Click one of the following buttons:
    • Click Connect to initialize the connection to the agents without actually starting the load test. On the Monitor page, you can then click Start All in the toolbar.
    • Click Run to start the load test.
    • Click OK to close the dialog box and save your changes.
    • Click Cancel to close the dialog box and abort your changes.
Parent topic: Workload Models


Workload Tab

The Workload Configuration > Workload tab enables you to configure workload-profile settings related to workload model, start time, and monitoring options.

Item | Description
Increasing | Use this option button to switch to the Increasing workload model.
Steady State | Use this option button to switch to the Steady State workload model.
Dynamic | Use this option button to switch to the Dynamic workload model.
All Day | Use this option button to switch to the All Day workload model. This selection enables the Configure All Day Workload button below.
Queuing | Use this option button to switch to the Queuing workload model.
vUsers-over-time graph | The graph at the top of the dialog box graphically represents the selected workload model and uses the data associated with the user group selected in the UserType table.
UserType table | This portion of the dialog enables you to edit the settings of the user types that are associated with your project. Options vary based on the selected workload mode. (see specific workload-model configuration topics for details on configuring user types.)
Start time | Set the start time for your test in hours, minutes, and seconds.
Relative | Click this option button to start your test after the specified time period has elapsed.
Absolute | Click this option button to start the test at the specified time.
Automatically start monitoring | Check this check box if you have established a monitoring template and want Performance Explorer to start and stop automatically with the test.
TrueLog On Error | Check this check box to generate TrueLog Explorer files for all transactions that generate errors.
Enable real-time measures

When checked, real-time measure data generation is enabled globally for all virtual users across the entire test. This setting overrides preset profile settings.

When unchecked, real-time measure data is disabled for all virtual users globally across the test. This setting overrides preset profile settings.

When checked and grayed out, real-time measure data is generated only for those user types who have this setting activated in their corresponding profiles. In this state a tooltip displays information about the user types for which real-time measures have been enabled.

Note: This check box automatically changes its state when the real-time measure data profile setting option of any virtual user changes.

Note: This setting affects only measures that are configured to provide measurements in real-time through the MeasureSetOption function and the MEASURE_OPT_REALTIME parameter.
Loadtest description | (Optional) Here you can enter a description of the test for project-management purposes.
Configure All Day Workload | (enabled only when the All Day workload model is selected) Opens the All Day Workload Configuration dialog.
Parent topic: Adjusting Workload
Related concepts
Workload Models
Adjusting Workload
Related tasks
Configuring All Day Workload
Configuring Dynamic Workload
Configuring Increasing Workload
Configuring Queuing Workload
Configuring Steady State Workload
Configuring Verification Workload
Related reference
Agent Assignment Tab


Time Names in Workload Context

The following time values can be configured in the Select and adjust Workload and Workload Configuration dialogs:

Measurement | Description
Warm-up time | A load test starts with an optional warm-up time. Measures taken during the warm-up time are not used in the reports. The warm-up time can be used to exclude the start-up tasks of a test (such as allocating and initializing memory or building up caches) from the measured part of the test.
Measurement time

The measurement time is the time between the optional warm-up time and the optional close-down time. During the measurement time, measures are taken and then used in the reports once the test is completed. Typically, the measurement time extends to the end of the simulation time.

If the measurement time is set to 0, all measures taken between the warm-up time and the end of the simulation time are considered in the reports.

Close-down time

A load test ends with an optional close-down time, which is the time between the end of the measurement time and the end of the load test. Measures taken during the close-down time are not used in the reports. The close-down time can be used to exclude the closing tasks of a test (such as shutting down the virtual users) from the measured part of the test.

If the specified simulation time is longer than the sum of the warm-up time and the measurement time, the close-down time starts during the simulation time.

Measurement | Description
Simulation time | The simulation time is the time of the load test excluding the ramp-down time. It can also be described as the sum of the ramp-up time (for increasing workloads) and the steady time.
Ramp-up time

During the ramp-up time, Silk Performer gradually increases the number of virtual users.

The ramp-up parameters can be set in the Select and adjust Workload dialog or in the Workload Configuration dialog.

For example, you can specify to start a load test with 10 virtual users (Start) and add 2 virtual users (Add) every 30 seconds (Interval) until reaching a maximum of 20 virtual users (max. VUsers).

The ramp-up time can only be specified for workloads using the Increasing workload model.

Steady time

During the steady time, no more virtual users are added. The number of virtual users remains steady during this time and equals the specified maximum number of virtual users (max. VUsers).

Ramp-down-time

During the ramp-down time, Silk Performer gradually decreases the number of virtual users to zero. Since the ramp-down happens during the close-down time, it does not influence the reports.

If an end transaction is defined for a virtual user and the profile setting Call end transaction for stopped virtual users is enabled, the end transaction will be executed during the ramp-down time. Specifying a ramp-down time also allows you to gradually stop running virtual users to avoid that all virtual users perform the end transaction at the same time.

The ramp-down parameters can be set in the Select and adjust Workload dialog or in the Workload Configuration dialog. For example, you can specify to stop 10 virtual users (Stop) every 30 seconds (Interval). This translates into a certain ramp-down time depending on the number of virtual users defined in the workload.

If the ramp-down time is set to 0 and the profile setting Call end transaction for stopped virtual users is enabled, all related virtual users execute the end transaction simultaneously. If no end transaction exists, the virtual users stop immediately.

Parent topic: Adjusting Workload


Initializing Workload Settings

Silk Performer allows you to specify the same workload settings for multiple user types at a time.
  1. Click Adjust Workload on the workflow bar. The Workflow - Select and adjust Workload dialog box appears.
  2. Click Initialize. The Initialize Workload Settings dialog appears.
  3. Select a Workload model from the list.
  4. If you want to define one specific value for all user types, use the check boxes: Enable the respective check box and enter the value. To define varying values, enter these directly in the table.
  5. Click OK to save your changes.
Note: The Initialize Workload Settings dialog also allows you to define a duration for the Ramp-up Time and Ramp-down Time. In contrast, the Select and adjust workload dialog allows you to define an increase or decrease value per time. Example for defining the duration: Gradually stop all virtual users within 2 minutes. Example for defining a decrease value: Stop 2 virtual users every 10 seconds.
Tip: The Initialize Workload Settings dialog also allows you to copy and paste values from and to spreadsheet programs like Microsoft Excel. To do so, use the keyboard shortcuts Ctrl+C and Ctrl+V.
Parent topic: Adjusting Workload


Assigning Agents

Explains how to configure and assign individual agents and clusters of agents to your project.

  • Assigning Agents
    Configure the distribution of virtual users in your load testing environment and assign VUsers to specific agents, agent clusters, or cloud agents.
  • Assigning Agents to Workload
    After you define your workload and the replay capabilities of your agents, assign specific agents or agent clusters to deliver the workload.
  • Manually Assigning Agent Computers to User Types
    Assign virtual users manually to agent computers for a particular user type or types.
  • Dynamic Workload-Assignment
    Load-test resource management enables the dynamic allocation of load-test agents to Silk Performer projects.
  • Centralized Management of Load-Test Agent Clusters in Silk Central
    The assign agents feature in Silk Performer supports using multiple load-test agent clusters in combination with Silk Central.
  • Assigning Workload to Cloud Agents
    When load-testing in the cloud, manage your available cloud agents and assign workload to them.
  • Defining Number of VUsers per Cloud Agent
    Explains how to specify number of VUsers using guidelines that show how many VUsers can typically be supported by computer-based agents for the testing of various application types.
  • Evaluating Agent VUser Capacity
    Describes how Silk Performer evaluates the capacity of a specified agent.
Parent topic: Managing Load Tests


Agent Assignment Tab

The Workload Configuration > Agent Assignment tab enables you to configure how agents are assigned to a workload profile to deliver required load, including static or dynamic assignment to specific project agents and dynamic assignment to Silk Central agent clusters.

Item | Description
Agents Lists the agents that are currently available for workload assignment along with the maximum virtual-user capacity that each agent can drive for each capability type (Java, ODBC, SAPGUI, etc.)

Maximum virtual-user capacity depends on the Agent Resource Utilization setting.

This list can assist you with error handling in cases of failed dynamic workload-assignment by displaying agents that can not be connected via the Silk Performer launcher service or are currently locked by other load tests.

When logged in to the cloud, this list displays the available cloud agents side-by-side to other available agents.

Assignment type: Static assignment to project agents | Use this method to statically assign specific agent computers (rather than clusters of agents) to your project. No agent-availability check is performed with this method and agent locking is disabled. Select this method if you want to use Agents deployed in the cloud.
Assignment type: Dynamic assignment to project agents | With this method, workload is delivered using dynamic agent-assignment at execution time against the project's agents. Workload delivery is enhanced with agent-capability specifications to create optimized workload-to-agent assignments based on the capabilities of each agent. Agent locking at execution time is enabled with this method. Only responding agents that are not currently used by another controller are used with this method.
Assignment type: Dynamic assignment to Silk Central agent cluster | Silk Performer workload delivered by way of Silk Central can also use dynamic workload-to-agent assignment. Within Silk Performer you choose the name of the agent cluster (from the drop list) that should deliver your test's workload. Silk Central then provides the list of agent computers that are assigned to the cluster. Workload is then assigned to specific agents at the moment of execution based on the capabilities of the individual agents. After you connect to Silk Central, you are presented with the list of available agent clusters. In the right-most window, you can view the agents that are currently associated with the selected agent cluster. With this approach, the agents of a cluster can be changed without requiring modification of your Silk Performer project. Download of the agent clusters list from Silk Central requires Silk Central logon credentials. If your Silk Performer project is already associated with a Silk Central test definition, login is not required. Agent locking at execution time is enabled with this method. Only responding agents that are not currently in use by another controller are used with this method. If your project is not associated with a test definition in Silk Central, the Silk Central connection parameters from Silk Performer's system settings are used. When neither approach is successful, the Download agent clusters from Silk Central dialog appears. This dialog features the same values as those found at Settings > System Settings , Silk Central. Specify appropriate connection parameters and click Finish.
Even user distribution | This option is enabled when Static assignment to project agents is selected. Use this option to distribute all existing user types evenly across all agents, depending on each agent's general replay capabilities. For example, if you have 50 VUsers and 5 agents, each agent runs ten VUsers. If this option is not enabled, the first agent would run all 50 VUsers if replay capabilities permit. The other agents would rest idle, taking over the workload only if one agent reaches its maximum replay capability.
Use cloud agents | This option is enabled when Static assignment to project agents is selected. Use this option if you want to deploy agents that run as virtual machines in the cloud. When checking this checkbox, the cloud Login dialog box opens, asking for your user credentials (check Save Credentials to not be asked for your credentials again). Contact your sales representative to retrieve valid credentials.
Cloud Agent Manager | Click here to launch the Cloud Agent Manager, which allows you to manage your agents in the cloud.
Agent resource utilization | Check the Agent resource utilization check box to assign a maximum percentage of total virtual users that each agent can run based on the agent's replay capabilities. For example, if an agent can run 50 users of SAPGUI capability, then an Agent resource utilization value of 50% results in 25 available SAPGUI virtual users for the test. This value is reflected in the Agents table.
Balance load across agents This option is especially desirable for increasing or dynamic workloads. Note that this setting does not come into effect until the moment of execution.
  • Without this setting enabled, your user load may be distributed to agents sequentially, as follows:
    • Agent1: VU1, VU2, …, VU17
    • Agent2: VU18, VU19, …, VU34
    • Agent3: VU35, VU36, …, VU50
  • With this setting enabled, virtual user distribution is more uniformly distributed across agents, as follows:
    • Agent1: VU1, VU4, VU7, …
    • Agent2: VU2, VU5, VU8, …
    • Agent3: VU3, VU6, VU9, …
UserType/Agents | This portion of the tab enables you to edit the users-to-agents assignments that are associated with your project. A roll-over tooltip on each usertype shows the capabilities that are required for the usertype. This is useful for error handling in cases when workload assignment fails.
User Distribution Overview | Click the User Distribution Overview button to view a summary of the users-to-agent assignments in your project.
Parent topic: Assigning Agents to Workload
Related concepts
Dynamic Workload-Assignment
Adjusting Workload
Related tasks
Assigning Agents to Workload
Assigning Workload to Cloud Agents
Related reference
Workload Tab


Manually Assigning Agent Computers to User Types

  1. Click Run Test on the workflow bar. The Workflow - Workload Configuration dialog box appears.
  2. Click the Agent Assignment tab.
  3. Define the agents that are to deliver the workload for your test. Click the Static assignment to project agents option button to statically assign specific agent computers (rather than clusters of agents) to your project. Agent locking is disabled with this method.
  4. In the Auto-assign column, uncheck the Auto-assign check box.
  5. Click [...] to the left of the Agents column. The Manual Agent Assignment for Script/Usertype dialog box opens.
  6. Click the agent that you want to assign and click OK. All of the users from the user type must be assigned to agents. The selected agent appears in the Agent column on the Workflow Configuration dialog box.
Parent topic: Assigning Agents


Dynamic Workload-Assignment

Silk Performer's dynamic workload-assignment functionality matches your specific load-test requirements to the replay capabilities of available agent computers at execution time. For example, if your load test requires a workload that can be delivered only by an agent computer with an installed SAPGUI client, dynamic workload-assignment functionality can ensure that your test's workload is assigned only to available agents with installed SAPGUI clients. Further, you can configure the percentage of required workload, in the number of virtual users, that must be allocated to each agent, thereby ensuring that agents are not pushed beyond their load capacities.

Dynamic-workload assignment allows you to account for variations in resource requirements. For example, approximately the same amount of resources is required to drive 2,000 virtual Web users over a Web replay interface as is required to drive 20 virtual SAP users over a SAPGUI replay interface. Based on maximum virtual-user-per-replay-capability settings that you configure, the dynamic-workload assignment algorithm allocates appropriate workload levels to agents. This approach does not necessarily result in each agent continuously driving its maximum supported load. You can define the percentage of maximum-potential workload that must be allocated to each individual agent within the cluster. For example, if an agent can drive 2,000 Web users and you set the agent-resource-utilization setting to 50%, only 1,000 Web users are allocated to that agent. The remaining workload is allocated to other agents that possess the same Web-user capability.

An advantage of dynamic assignment of workload to agent clusters is the manner in which the successful execution of tests is not contingent on your maintaining a static test-execution environment. For example, if an agent's name changes or becomes unavailable, Silk Performer can dynamically assign the unavailable agent's workload to an available agent in the same cluster with the required capabilities. This approach eliminates many of the challenges involved in maintaining a static test environment and is of particular value when Silk Performer load tests are managed and executed based on predefined schedules in Silk Central. Silk Central can run tests against agent clusters rather than individual agents. Issues that do not require consideration from the Silk Central perspective include the health of individual agents and the manner in which workload is balanced across agents.

Agent computers remain available to all workloads until the moment of test execution because they are not reserved or assigned to any one specific workload. When a Silk Performer controller identifies an available agent on which it intends to run a test execution, the controller momentarily locks the agent to prevent conflict conditions with other controllers. After the test completes, the agents are unlocked and made available to other tests.

  • Defining the Capabilities of Agents
    After you add agents to a project's agent pool, adjust each agent's capability values to optimize dynamic-workload assignment.
  • Properties for Agent - Capabilities Tab
    Enables you to configure the maximum number of virtual users per replay interface that the agent is capable of driving to optimize dynamic-workload assignment.
  • Replay Capabilities
    Describes the replay capabilities with which an agent can be tagged.
  • Capability Complexity Configuration
    Explains how complexity values are used to relate sets of capability resource requirements to one another. These values can be overwritten by creating a specialized XML file. Also explains how to define a default number of virtual users for a capability.
Parent topic: Assigning Agents


Defining the Capabilities of Agents

  1. Choose Settings > System . The System Settings dialog box displays.
  2. Click Agents. The Agent Pool tab displays.
  3. Click the agent for which you want to define capabilities.
  4. Click Properties.
  5. Click the Capabilities tab. The Capabilities page is pre-populated with suggested replay-capability values that are based on the specifications of installed hardware.
  6. Adjust the Max. Vuser values per capability type as required by the agent. You are responsible for setting appropriate maximum virtual-user values for your agents. Values from 0 to 9999 are valid.
  7. Click OK to save your settings. Alternatively, you can click Set Default to restore default capability values.
Parent topic: Dynamic Workload-Assignment


Properties for Agent - Capabilities Tab

The Properties for Agent > Capabilities dialog enables you to configure the maximum number of virtual users per replay interface that the agent is capable of driving to optimize dynamic-workload assignment.

The Capabilities page is pre-populated with suggested replay-capability values that are based on the specifications of installed hardware. You are responsible for setting appropriate maximum virtual-user values for your agents. Values from 0 to 9999 are valid.
Capability | Max. Vusers
General | Maximum number of virtual users that the agent is capable of driving against replay interfaces that do not require any specific client installations on the agent. The general capability includes replay interfaces such as Web protocols and IIOP.
Browser-driven | Maximum number of virtual users that the agent is capable of driving against the browser-driven testing replay interface.
Java | Maximum number of virtual users that the agent is capable of driving against replay interfaces that require a Java Runtime installation. The Java capability includes replay interfaces such as Java Framework, OracleForms, Oracle Applications, Jolt, and Jacada.
ODBC | Maximum number of virtual users that the agent is capable of driving against the ODBC replay interface.
Oracle OCI | Maximum number of virtual users that the agent is capable of driving against the Oracle OCI7 or Oracle OCI8 replay interface.
SAPGUI | Maximum number of virtual users that the agent is capable of driving against the SAPGUI replay interface.
Citrix | Maximum number of virtual users that the agent is capable of driving against the Citrix replay interface.
Tuxedo | Maximum number of virtual users that the agent is capable of driving against the Tuxedo replay interface.
.Net | Maximum number of virtual users that the agent is capable of driving against the .Net Framework replay interface.
GuiL Test | Maximum number of virtual users that the agent is capable of driving against the Gui-level testing replay interface.
Default button | Click to reset all values to the suggested replay-capability values.
Parent topic: Dynamic Workload-Assignment
Related concepts
Dynamic Workload-Assignment
Related tasks
Assigning Agents to Workload
Related reference
Replay Capabilities


Replay Capabilities

You can tag each agent with the following replay capabilities:

  • General – Any replay feature that does not require an installation (except browser-driven), including Web and IIOP.
  • Browser-driven - Does not require an installation, but has a higher resource consumption capability than General.
  • Java – A Java run-time environment is available for Java Framework, Oracle Forms, Oracle Applications, Jacada, and Jolt.
  • ODBC – An ODBC client is installed.
  • Oracle OCI – An Oracle client is installed.
  • SAPGUI – A SAPGUI client is installed.
  • Citrix – A Citrix client is installed.
  • Tuxedo – A Tuxedo client is installed.
  • .Net – The .NET Framework is installed.
  • GuiL Test – Terminal Services is installed and running on this agent. Silk Test and the system under test must be installed.

For each capability, you can specify the maximum number of virtual users that the agent is capable of driving. Click the Capabilities tab ( Settings > System > Agents > Agent Pool > Properties > Capabilities to complete this task.

Note: Depending on the hardware resources of the hosting machine, a load-test agent can replay a varying number of virtual users based on the resource demands of each particular replay interface. Therefore, agents are characterized by their hardware specifications, such as their CPU and memory, plus the number of virtual users that can be executed based on a particular replay interface.
Parent topic: Dynamic Workload-Assignment


Capability Complexity Configuration

Capability Complexities

Silk Performer uses abstract values, or complexities, to relate sets of capability resource requirements to one another. A capability is a technology that an agent is able to replay.

With dynamic workload-assignment, this is used for the following operations:

  1. To sort agents by the sum of their capability complexities. This is used to assign user types to agents that have the lowest capability complexity first.
  2. To sort user types by the sum of their associated scripts' capability complexity. This is used to assign user types that have the highest complexity first. Combined with operation 1 (above), this results in user types with the highest complexity being assigned to the agents that best fit the required capabilities.
  3. To compute the default number of virtual users of an agent for each of its capabilities. For an agent, the number of virtual users for the General capability is computed based on the CPU speed, the number of CPUs, and available RAM. Using this value and the list of capability complexities, the number of available virtual users for all other capabilities is computed.

Example XML File

To override capability complexity values, you must create an XML file named CapabilityComplexities.xml and save it to <public user documents>\Silk Performer 21.0.

Such an XML file might look like this:

<Complexities>
  <Capability name="SAPGUI" complexity="150"/>
  <Capability name="ODBC" complexity="65"/>
</Complexities>

This example XML file overrides the complexity values for the SAPGUI and ODBC capabilities. All other values remain unchanged. The file can contain '0-n' Capability tags. The list of capability names is included in the table above.

Please note that specific complexity values are not that important. The important thing is what the values are in relation to each other. This has the consequence that if you were to multiply all complexities by the same factor, the relation of any two capabilities to each other would not change.

Setting a Default Number of Virtual Users

In some situations it is helpful to define a default number of virtual users for a capability (for example, to accommodate a technical constraint of the technology under test). This can be achieved by extending the capabilities defined in CapabilityComplexities.xml with maxVU attributes. For example, <Complexities> <Capability name="GuiLTest" complexity="200" maxVU="30" /> </Complexities>. The value specified in the maxVU attribute overrides the value that would otherwise be computed through the capability complexities. A maxVU value of 0 (which is the default when no maxVU attribute is specified) indicates that the default number of virtual users should be computed through the capability complexities.

Currently, the following fixed maximum VUser values are in effect by default:

  • SAPGUI - 75 VUsers
  • Citrix - 30 VUsers
  • GuiLTest - 30 VUsers
  • Browser-driven - 100 VUsers
Note: The maximum number of browser-driven virtual users is calculated as follows: 5% of capability, up to a maximum of 100.
Parent topic: Dynamic Workload-Assignment


Centralized Management of Load-Test Agent Clusters in Silk Central

Although you have the option of assigning workload to individual agents, assigning workload to clusters of agents is often preferable. Clusters are groups of agents that can share the same capabilities, such as a Java Development Kit (JDK) installation, an ODBC client, or a Citrix client, or can consist of agents that possess entirely heterogeneous capabilities, such as the capability to divide a lab's machines into separate agent groups that can support different teams. With this approach, you select a cluster of agents capable of executing the required workload when you configure your test's workload. Silk Performer then handles the dynamic assignment of workload to specific agents. Only those agents that are required to deliver the workload are actually used.

Agent clusters are managed centrally in Silk Central and are retrieved by Silk Performer when you start a load test—you do not need to configure the availability of agents yourself and conflicts with concurrently scheduled load tests are resolved automatically.

  • Creating a Silk Central Agent-Clusters File
    Once you have output the connection properties, capabilities, and system information of the available agents in your agent pool, you must manually build a Silk Central agent-clusters XML file.
  • Exporting Agent Pool
    Before you can create a Silk Central test-agent cluster file, you need to output the connection properties, capabilities, and system information of the available agents in your agent pool.
Parent topic: Assigning Agents


Creating a Silk Central Agent-Clusters File

Before you can complete this task you must export the Silk Performer agent pool as an XML file (which includes the connection properties, capabilities, and system information of an agent) for each agent in your agent pool.

You only need to create one Silk Central agent-clusters file. The file may contain one or more agent clusters, each of which specifies its associated agents including their capabilities, connection properties and system information. The contents of the file you create will be available to all Silk Performer users on the Workload Configuration dialog when they select the Dynamic assignment to Silk Central agent cluster option.

You must create a Silk Central agent-clusters file if you intend to run your test against a Silk Central agent cluster (this is configured by clicking the Dynamic assignment to Silk Central agent cluster button on the Workload Configuration > Agent Assignment tab). Workloads that use a Silk Central agent cluster can be executed from within the Silk Performer Workbench and they can be scheduled as Silk Central tests.

  1. Create an empty XML file on your local system. This file must be accessible by Silk Central. It can be placed under source control within your Silk Central directory structure.
  2. Use the contents of an exported agent pool file to build the agent-clusters file as structured in the example below. The contents of an exported agent-pool file and the agent-clusters file are nearly identical, so this typically only involves enclosing the <AgentPool/> elements of the exported agent-pool file within a <SctmAgentClusters/> element.

Example of a manually created Silk Central agent-clusters file

This manually created agent-clusters file includes a SctmAgentClusters root element. Within the root element are AgentPool elements, one for each agent pool in the cluster. Within each AgentPool element are Agent elements that convey the connection properties, capabilities, and system information of the individual agents.

<?xml version='1.0' encoding='UTF-8'?>

<SctmAgentClusters>
 <AgentPool name="cluster_1">
  <Agent id="LAB100">
    <ConnProperty name="ConnectPort">19200</ConnProperty>
    <ConnProperty name="ConnectSecurePort">19201</ConnProperty>
    <ConnProperty name="IpAddress">192.168.1.100</ConnProperty>
    <ConnProperty name="LastConnectStatus">5</ConnProperty>
    <ConnProperty name="UseAuthentication">false</ConnProperty>
    <Capability maxVU="390" name=".Net"></Capability>
                <Capability maxVU="100" name="Browser-driven"></Capability>
    <Capability maxVU="39" name="Citrix"></Capability>
    <Capability maxVU="3900" name="General"></Capability>
    <Capability maxVU="39" name="GuiLTest"></Capability>
    <Capability maxVU="390" name="Java"></Capability>
    <Capability maxVU="390" name="ODBC"></Capability>
    <Capability maxVU="390" name="Oracle OCI"></Capability>
    <Capability maxVU="39" name="SAPGUI"></Capability>
    <Capability maxVU="390" name="Tuxedo"></Capability>
    <SysInfo name="AgentRAC">7803300</SysInfo>
    <SysInfo name="AgentVersion">7.8.0.3332</SysInfo>
    <SysInfo name="Memory">2039 MB</SysInfo>
    <SysInfo name="ProcType"></SysInfo>
    <SysInfo name="ProcessorCount">1</SysInfo>
    <SysInfo name="ProcessorSpeed">3200 MHz</SysInfo>
    <SysInfo name="ServicePack"></SysInfo>
    <SysInfo name="SysVersion">5.0</SysInfo>
    <SysInfo name="System">WinNT</SysInfo>
  </Agent>
  <Agent id="lab101">
    <ConnProperty name="AuthPassword"></ConnProperty>
    <ConnProperty name="ConnectPort">19200</ConnProperty>
    <ConnProperty name="ConnectSecurePort">19201</ConnProperty>
    <ConnProperty name="EncryptionSSL">false</ConnProperty>
    <ConnProperty name="HTTPTunnel">:8080</ConnProperty>
    <ConnProperty name="IpAddress">192.168.1.101</ConnProperty>
    <ConnProperty name="LastConnectStatus">5</ConnProperty>
    <ConnProperty name="SOCKSTunnel">:1080</ConnProperty>
    <ConnProperty name="UseAuthentication">false</ConnProperty>
    <ConnProperty name="UseHttpTunnel">false</ConnProperty>
    <ConnProperty name="UseSocksTunnel">false</ConnProperty>
    <Capability maxVU="380" name=".Net"></Capability>
                <Capability maxVU="100" name="Browser-driven"></Capability>
    <Capability maxVU="38" name="Citrix"></Capability>
    <Capability maxVU="3800" name="General"></Capability>
    <Capability maxVU="38" name="GuiLTest"></Capability>
    <Capability maxVU="380" name="Java"></Capability>
    <Capability maxVU="380" name="ODBC"></Capability>
    <Capability maxVU="380" name="Oracle OCI"></Capability>
    <Capability maxVU="38" name="SAPGUI"></Capability>
    <Capability maxVU="380" name="Tuxedo"></Capability>
    <SysInfo name="AgentRAC">7803300</SysInfo>
    <SysInfo name="AgentVersion">7.8.0.3343</SysInfo>
    <SysInfo name="Memory">1983 MB</SysInfo>
    <SysInfo name="ProcType">Intel Pentium IV</SysInfo>
    <SysInfo name="ProcessorCount">2</SysInfo>
    <SysInfo name="ProcessorSpeed">3200 MHz</SysInfo>
    <SysInfo name="ServicePack">Service Pack 2</SysInfo>
    <SysInfo name="SysVersion">5.2</SysInfo>
    <SysInfo name="System">WinNT</SysInfo>
  </Agent>
 </AgentPool>
 <AgentPool name="cluster_2">
  <Agent id="LAB200">
    <ConnProperty name="ConnectPort">19200</ConnProperty>
    <ConnProperty name="ConnectSecurePort">19201</ConnProperty>
    <ConnProperty name="IpAddress">192.168.2.200</ConnProperty>
    <ConnProperty name="LastConnectStatus">5</ConnProperty>
    <ConnProperty name="UseAuthentication">false</ConnProperty>
    <Capability maxVU="390" name=".Net"></Capability>
                <Capability maxVU="100" name="Browser-driven"></Capability>
    <Capability maxVU="39" name="Citrix"></Capability>
    <Capability maxVU="3900" name="General"></Capability>
    <Capability maxVU="39" name="GuiLTest"></Capability>
    <Capability maxVU="390" name="Java"></Capability>
    <Capability maxVU="390" name="ODBC"></Capability>
    <Capability maxVU="390" name="Oracle OCI"></Capability>
    <Capability maxVU="39" name="SAPGUI"></Capability>
    <Capability maxVU="390" name="Tuxedo"></Capability>
    <SysInfo name="AgentRAC">7803300</SysInfo>
    <SysInfo name="AgentVersion">7.8.0.3332</SysInfo>
    <SysInfo name="Memory">2039 MB</SysInfo>
    <SysInfo name="ProcType"></SysInfo>
    <SysInfo name="ProcessorCount">1</SysInfo>
    <SysInfo name="ProcessorSpeed">3200 MHz</SysInfo>
    <SysInfo name="ServicePack"></SysInfo>
    <SysInfo name="SysVersion">5.0</SysInfo>
    <SysInfo name="System">WinNT</SysInfo>
  </Agent>
  <Agent id="lab201">
    <ConnProperty name="AuthPassword"></ConnProperty>
    <ConnProperty name="ConnectPort">19200</ConnProperty>
    <ConnProperty name="ConnectSecurePort">19201</ConnProperty>
    <ConnProperty name="EncryptionSSL">false</ConnProperty>
    <ConnProperty name="HTTPTunnel">:8080</ConnProperty>
    <ConnProperty name="IpAddress">192.168.2.201</ConnProperty>
    <ConnProperty name="LastConnectStatus">5</ConnProperty>
    <ConnProperty name="SOCKSTunnel">:1080</ConnProperty>
    <ConnProperty name="UseAuthentication">false</ConnProperty>
    <ConnProperty name="UseHttpTunnel">false</ConnProperty>
    <ConnProperty name="UseSocksTunnel">false</ConnProperty>
    <Capability maxVU="380" name=".Net"></Capability>
                <Capability maxVU="100" name="Browser-driven"></Capability>
    <Capability maxVU="38" name="Citrix"></Capability>
    <Capability maxVU="3800" name="General"></Capability>
    <Capability maxVU="38" name="GuiLTest"></Capability>
    <Capability maxVU="380" name="Java"></Capability>
    <Capability maxVU="380" name="ODBC"></Capability>
    <Capability maxVU="380" name="Oracle OCI"></Capability>
    <Capability maxVU="38" name="SAPGUI"></Capability>
    <Capability maxVU="380" name="Tuxedo"></Capability>
    <SysInfo name="AgentRAC">7803300</SysInfo>
    <SysInfo name="AgentVersion">7.8.0.3343</SysInfo>
    <SysInfo name="Memory">1983 MB</SysInfo>
    <SysInfo name="ProcType">Intel Pentium IV</SysInfo>
    <SysInfo name="ProcessorCount">2</SysInfo>
    <SysInfo name="ProcessorSpeed">3200 MHz</SysInfo>
    <SysInfo name="ServicePack">Service Pack 2</SysInfo>
    <SysInfo name="SysVersion">5.2</SysInfo>
    <SysInfo name="System">WinNT</SysInfo>
  </Agent>
  <Agent id="lab203">
    <ConnProperty name="ConnectPort">19200</ConnProperty>
    <ConnProperty name="ConnectSecurePort">19201</ConnProperty>
    <ConnProperty name="IpAddress">192.168.2.203</ConnProperty>
    <ConnProperty name="LastConnectStatus">5</ConnProperty>
    <ConnProperty name="UseAuthentication">false</ConnProperty>
    <Capability maxVU="650" name=".Net"></Capability>
                <Capability maxVU="100" name="Browser-driven"></Capability>
    <Capability maxVU="65" name="Citrix"></Capability>
    <Capability maxVU="6500" name="General"></Capability>
    <Capability maxVU="65" name="GuiLTest"></Capability>
    <Capability maxVU="650" name="Java"></Capability>
    <Capability maxVU="650" name="ODBC"></Capability>
    <Capability maxVU="650" name="Oracle OCI"></Capability>
    <Capability maxVU="65" name="SAPGUI"></Capability>
    <Capability maxVU="650" name="Tuxedo"></Capability>
    <SysInfo name="AgentRAC">7803300</SysInfo>
    <SysInfo name="AgentVersion">7.8.0.3371</SysInfo>
    <SysInfo name="Memory">3318 MB</SysInfo>
    <SysInfo name="ProcType"></SysInfo>
    <SysInfo name="ProcessorCount">2</SysInfo>
    <SysInfo name="ProcessorSpeed">3000 MHz</SysInfo>
    <SysInfo name="ServicePack"></SysInfo>
    <SysInfo name="SysVersion">5.2</SysInfo>
    <SysInfo name="System">WinNT</SysInfo>
  </Agent>
 </AgentPool>
</SctmAgentClusters>

Once you have created an agent clusters file, you must configure Silk Central to reference the file. Silk Central will copy the file to the execution servers so that whenever a Silk Performer project with dynamic workload-assignment is executed, the project will read the file to determine how workload should be allocated to the agents within the cluster.

Parent topic: Centralized Management of Load-Test Agent Clusters in Silk Central


Exporting Agent Pool

Before you can create a Silk Central test-agent cluster file, you need to output the connection properties, capabilities, and system information of the available agents in your agent pool.

  1. Navigate to System > Settings > Agents > Agent Pool .
  2. Click the Export Agent Pool button.
  3. Specify an appropriate path and filename to save the contents of your agent pool as an XML file.

Example agent pool file

This XML file includes an AgentPool root element. Within the root element are Agent elements, one for each agent in the agent pool. Within each Agent element are elements that convey the connection properties, capabilities, and system information of that agent.

<?xml version='1.0' encoding='UTF-8'?>
<AgentPool name="LocalPool">
  <Agent id="LAB108">
    <ConnProperty name="ConnectPort">19200</ConnProperty>
    <ConnProperty name="ConnectSecurePort">19201</ConnProperty>
    <ConnProperty name="IpAddress">192.168.1.108</ConnProperty>
    <ConnProperty name="LastConnectStatus">5</ConnProperty>
    <ConnProperty name="UseAuthentication">false</ConnProperty>
    <Capability maxVU="390" name=".Net"></Capability>
    <Capability maxVU="100" name="Browser-driven"></Capability>
    <Capability maxVU="39" name="Citrix"></Capability>
    <Capability maxVU="3900" name="General"></Capability>
    <Capability maxVU="39" name="GuiLTest"></Capability>
    <Capability maxVU="390" name="Java"></Capability>
    <Capability maxVU="390" name="ODBC"></Capability>
    <Capability maxVU="390" name="Oracle OCI"></Capability>
    <Capability maxVU="39" name="SAPGUI"></Capability>
    <Capability maxVU="390" name="Tuxedo"></Capability>
    <SysInfo name="AgentRAC">7803300</SysInfo>
    <SysInfo name="AgentVersion">7.8.0.3332</SysInfo>
    <SysInfo name="Memory">2039 MB</SysInfo>
    <SysInfo name="ProcType"></SysInfo>
    <SysInfo name="ProcessorCount">1</SysInfo>
    <SysInfo name="ProcessorSpeed">3200 MHz</SysInfo>
    <SysInfo name="ServicePack"></SysInfo>
    <SysInfo name="SysVersion">5.0</SysInfo>
    <SysInfo name="System">WinNT</SysInfo>
  </Agent>
  <Agent id="lab116">
    <ConnProperty name="AuthPassword"></ConnProperty>
    <ConnProperty name="ConnectPort">19200</ConnProperty>
    <ConnProperty name="ConnectSecurePort">19201</ConnProperty>
    <ConnProperty name="EncryptionSSL">false</ConnProperty>
    <ConnProperty name="HTTPTunnel">:8080</ConnProperty>
    <ConnProperty name="IpAddress">192.168.1.116</ConnProperty>
    <ConnProperty name="LastConnectStatus">5</ConnProperty>
    <ConnProperty name="SOCKSTunnel">:1080</ConnProperty>
    <ConnProperty name="UseAuthentication">false</ConnProperty>
    <ConnProperty name="UseHttpTunnel">false</ConnProperty>
    <ConnProperty name="UseSocksTunnel">false</ConnProperty>
    <Capability maxVU="380" name=".Net"></Capability>
    <Capability maxVU="100" name="Browser-driven"></Capability>
    <Capability maxVU="38" name="Citrix"></Capability>
    <Capability maxVU="3800" name="General"></Capability>
    <Capability maxVU="38" name="GuiLTest"></Capability>
    <Capability maxVU="380" name="Java"></Capability>
    <Capability maxVU="380" name="ODBC"></Capability>
    <Capability maxVU="380" name="Oracle OCI"></Capability>
    <Capability maxVU="38" name="SAPGUI"></Capability>
    <Capability maxVU="380" name="Tuxedo"></Capability>
    <SysInfo name="AgentRAC">7803300</SysInfo>
    <SysInfo name="AgentVersion">7.8.0.3343</SysInfo>
    <SysInfo name="Memory">1983 MB</SysInfo>
    <SysInfo name="ProcType">Intel Pentium IV</SysInfo>
    <SysInfo name="ProcessorCount">2</SysInfo>
    <SysInfo name="ProcessorSpeed">3200 MHz</SysInfo>
    <SysInfo name="ServicePack">Service Pack 2</SysInfo>
    <SysInfo name="SysVersion">5.2</SysInfo>
    <SysInfo name="System">WinNT</SysInfo>
  </Agent>
  <Agent id="lab125">
    <ConnProperty name="ConnectPort">19200</ConnProperty>
    <ConnProperty name="ConnectSecurePort">19201</ConnProperty>
    <ConnProperty name="IpAddress">192.168.1.125</ConnProperty>
    <ConnProperty name="LastConnectStatus">5</ConnProperty>
    <ConnProperty name="UseAuthentication">false</ConnProperty>
    <Capability maxVU="650" name=".Net"></Capability>
                <Capability maxVU="100" name="Browser-driven"></Capability>
    <Capability maxVU="65" name="Citrix"></Capability>
    <Capability maxVU="6500" name="General"></Capability>
    <Capability maxVU="65" name="GuiLTest"></Capability>
    <Capability maxVU="650" name="Java"></Capability>
    <Capability maxVU="650" name="ODBC"></Capability>
    <Capability maxVU="650" name="Oracle OCI"></Capability>
    <Capability maxVU="65" name="SAPGUI"></Capability>
    <Capability maxVU="650" name="Tuxedo"></Capability>
    <SysInfo name="AgentRAC">7803300</SysInfo>
    <SysInfo name="AgentVersion">7.8.0.3371</SysInfo>
    <SysInfo name="Memory">3318 MB</SysInfo>
    <SysInfo name="ProcType"></SysInfo>
    <SysInfo name="ProcessorCount">2</SysInfo>
    <SysInfo name="ProcessorSpeed">3000 MHz</SysInfo>
    <SysInfo name="ServicePack"></SysInfo>
    <SysInfo name="SysVersion">5.2</SysInfo>
    <SysInfo name="System">WinNT</SysInfo>
  </Agent>
  <Agent id="lab47">
    <ConnProperty name="ConnectPort">19200</ConnProperty>
    <ConnProperty name="ConnectSecurePort">19201</ConnProperty>
    <ConnProperty name="IpAddress">192.168.1.47</ConnProperty>
    <ConnProperty name="LastConnectStatus">5</ConnProperty>
    <ConnProperty name="UseAuthentication">false</ConnProperty>
    <Capability maxVU="180" name=".Net"></Capability>
                <Capability maxVU="100" name="Browser-driven"></Capability>
    <Capability maxVU="18" name="Citrix"></Capability>
    <Capability maxVU="1800" name="General"></Capability>
    <Capability maxVU="18" name="GuiLTest"></Capability>
    <Capability maxVU="180" name="Java"></Capability>
    <Capability maxVU="180" name="ODBC"></Capability>
    <Capability maxVU="180" name="Oracle OCI"></Capability>
    <Capability maxVU="18" name="SAPGUI"></Capability>
    <Capability maxVU="180" name="Tuxedo"></Capability>
    <SysInfo name="AgentRAC">7803300</SysInfo>
    <SysInfo name="AgentVersion">7.8.0.3414</SysInfo>
    <SysInfo name="Memory">1007 MB</SysInfo>
    <SysInfo name="ProcType"></SysInfo>
    <SysInfo name="ProcessorCount">2</SysInfo>
    <SysInfo name="ProcessorSpeed">2593 MHz</SysInfo>
    <SysInfo name="ServicePack"></SysInfo>
    <SysInfo name="SysVersion">5.1</SysInfo>
    <SysInfo name="System">WinNT</SysInfo>
  </Agent>
</AgentPool>

You can now use the XML data in the exported agent-pool file to create a Silk Central test-agent clusters file.

Parent topic: Centralized Management of Load-Test Agent Clusters in Silk Central


Assigning Workload to Cloud Agents

This task can only be performed after you have configured workload for your project.

  1. Click Run Test on the workflow bar. The Workflow - Workload Configuration dialog box appears.
  2. Click the Agent Assignment tab.
  3. Select the Assignment type:
    • Static assignment to project agents : Use this method to statically assign specific agent computers (rather than clusters of agents) to your project. No agent-availability check is performed with this method and agent locking is disabled. Select this method if you want to use Agents deployed in the cloud.
  4. Define the agents that are to deliver the workload for your test.
    • If you selected Static assignment to project agents , you can check the Even user distribution check box to distribute all existing user types evenly across all agents, depending on each agent's general replay capabilities. To use agents that run as virtual machines in the cloud, check the Use cloud agents check box. Click Cloud Agent Manager to manage your agents in the cloud.
    Note: To access Micro Focus CloudBurst services, register on http://cloud.borland.com or contact your sales representative.
  5. Check the Agent resource utilization check box to assign a maximum percentage of total virtual users that each agent can run based on the agent's replay capabilities.
  6. Check the Balance load across agents check box to apportion workload across agents.
  7. If you selected Static assignment to project agents , use the lower window of the Agent Assignment page to define workload assignments for user groups.
    Note: Available options vary depending on the selected workload model.
  8. Click User Distribution Overview to view the assignment of virtual users to the agent computers that are currently available and then click Close.
  9. Click OK to save your settings.
Note: Cloud agents are considered 'unreachable' when the Cloud Agent Manager cannot connect to them. There are a few possible reasons why this may occur:
  • Your network contains a firewall that blocks certain hosts or ports. Agent communication occurs over a secure HTTP tunnel using port 443.
  • Your network uses a proxy server that blocks certain Web sites or ports.
  • The machine that the Cloud Agent Manager runs on has a firewall that blocks certain hosts or ports.
Parent topic: Assigning Agents
Related reference
Agent Assignment Tab


Defining Number of VUsers per Cloud Agent

  1. Click Assign Agents on the workflow bar. The Workflow - Assign Agents dialog box appears.
  2. Click Use Cloud Agents. The Workflow - Prepare Cloud Agents dialog box appears.
  3. Slide the slider to the right to select the number of VUsers that you want to have run on each cloud agent.
    Markers along the slider indicate the number of VUsers that can typically be supported by cloud-based agents when testing various application types. However, the maximum number of VUsers per cloud agent, regardless of application type, is 1,000. The number of VUsers that can actually be supported for your testing scenario may vary of course, depending on the complexity and resource consumption of your specific test. The Workload text field shows the maximum number of VUsers that have been defined for each user type (as defined on the Workflow - Workload Configuration dialog box). The Assignment per region table shows the resulting allocation of agents across all geographic regions based on your selection. For example, with a Workload setting of 100 VUsers and a setting of 20 max VUsers per agent across five geographic regions, each region will run 20 VUsers. The higher the maximum VUsers per agent setting, the fewer agent instances required within each geographic region to support the prescribed workload.
  4. Click Next. The Start Agent(s) dialog box appears showing you the number of agent instances within each geographic region that will be started to deliver the prescribed workload.
  5. Within the Up Time area of the dialog box, specify how long you want the agent instances to remain active. Select Forever or a specific number of days and/or hours. The Company Limit shows the remaining number of agent instances that you can start based on your license type.
  6. Click Start to open Cloud Agent Manager and start the specified number of cloud agent instances.
Parent topic: Assigning Agents
Related reference
Performance and Scalability Matrix


Evaluating Agent VUser Capacity

If you are not sure how many virtual users your agent can handle, you can perform an evaluation run. Once the evaluation run is finished, Silk Performer gives you an estimation of how many virtual users you can run on the specified agent.
On the Evaluate Agent VUser Capacity dialog, click Start. Silk Performer will gradually increase the number of virtual users. The run is automatically stopped if at least one of the following is true:
  • The responsiveness falls below 95%.
  • The CPU usage exceeds 95%.
  • The maximum number of virtual users is reached.
Note: If you want to evaluate the capacity of a cloud agent, you need to have Micro Focus Credits on your cloud account.
Parent topic: Assigning Agents


Try Agents Summary

When a Try Agents run is complete, the Try Agents Summary page appears. You can also open this page from the Results tree. You can perform the following actions in the Next Steps area on the right side:
  • Click Analyze Errors to view the errors in TrueLog Explorer (if any occurred).
  • Click Configure Monitoring to continue with the next step in the workflow bar.
  • Click View debit information to show the amount of Micro Focus Credits that was debited from your account.
  • Click Local Agents or one of the cloud regions in the Analyze Result Files area to get detailed result information about the runs that were executed on the various agents.
Note: If you want to prevent the summary page to appear each time a test is complete, disable the Show Summary Page button in the toolbar of the Monitor page.
Parent topic: Trying Out Agents


Server Monitoring

During a load test, Silk Performer provides for server monitoring by allowing you to view a live, graphical display of the server performance while a test runs.

The monitoring of servers enables the generation of server-side results that can be viewed and correlated with other test measurements at the results exploration stage. Monitoring also helps you learn whether bottlenecks exist on the server and, if so, their exact location. As a result, monitoring lets you examine the performance of both the OS and the server application.

You can set up a template for server monitoring to monitor performance data, or you can use a default template that is already generally configured for the type of application you are testing.

Parent topic: Configuring Monitoring


Setting Up a Template for Server Monitoring

  1. Go to Settings > Active Profile The Profile Settings dialog box opens.
  2. Click the Results icon in the group box.
  3. Click the Monitoring page.
  4. In the Monitoring options area, check the Automatically start monitoring check box to automatically launch Silk Performer's monitoring facility when the test starts.
  5. To automatically use the monitoring template that best suits the project, click the Use default monitoring template option button. For example, if you are creating a Web project, the template specifies the measurements that are useful for Web load tests.
  6. To use a custom monitor template, click the Use custom monitoring template option button and perform one of the following steps:
    • Type the name of the custom template file (.pew) that you want to use to monitor your server. Silk Performer creates a copy of the standard monitor template.
    • Click the folder icon in the name field to select an existing monitoring template.
  7. Optional: Click Edit Custom Monitor Template to add or remove any monitoring performance data. When you click this button, Silk Performance Explorer opens. Perform the following steps:
    1. Add or remove any monitoring performance data.
    2. Save the Silk Performance Explorer workspace to apply your changes to the template.
  8. In the Performance Monitor integration area, check the Compute online performance data check box to compute data for additional performance measurements to be displayed in the Windows Performance Monitor. You can use this data to view concurrent users, transaction throughput, sent and received data, and executed SQL statements.
  9. Click OK. After you start a load test, server monitoring for the load test starts and stops automatically.
  10. To save monitoring results for future exploration, write the server-monitoring results to a monitoring writer file: In Performance Explorer, on the Real-Time Monitoring tab, in the New group, click Monitor Writer.
Parent topic: Configuring Monitoring
Related tasks
Using a Report to Monitor Server Performance
Creating Monitor Writers


Running Load Tests

Part of the process of conducting a Silk Performer load test is to run a full load test.

  • Running Tests
    Describes the procedures that must be run and the options that must be set for executing load tests.
  • Running a Load Test
    Run a test script against a target server to see how workload and multiple virtual users impact server performance.
  • Calculating Virtual Users
    Explains how the values on the Pacing tab of the Workload Configuration dialog are calculated.
  • Pacing
    Describes what pacing is and how it is used to reach a defined number of transactions per second (TPS).
  • Monitoring Load Tests
    Lists all the methods available for monitoring a load test.
  • Starting Silk Performer from the Command Line
    This topic explains how to start Silk Performer load tests directly from a command-line interface. Additionally, it lists the available command line parameters.
Parent topic: Managing Load Tests


Running Tests

In a load test, multiple virtual users are run by means of a test script against a target server to determine the load impact on server performance. A large load test requires an appropriate testing environment on your LAN, including a full complement of agent computers to host the virtual users.

It is essential that you complete the following tasks:
  • Set options for the appropriate type of test that is to be run
  • Accurately define the required workloads
  • Enable the generation of test results to assess server performance

Do not enable complete result-logging during load testing because it might interfere with load-test results. However, the TrueLog On Error logging option writes necessary log files to a disk when errors occur, allowing you to inspect replay errors visually.

Real-time information regarding agent computers, virtual users, and transactions is displayed for you while load tests run. Real-time performance monitoring of the target server is presented in graphical format.

When a test is configured as a verification run, the following options are automatically set to the specified values:
  • A Baseline report file is automatically created.
  • The Stop virtual users after simulation time (Queuing Workload) option is disabled.
  • The Virtual user log files (.log) option is disabled.
  • The Virtual user report files (.rpt) option is enabled.
  • The Virtual user report on error files (.rpt) option is enabled.
  • The Compute time series data (.tsd) option is disabled.
Parent topic: Running Load Tests


Calculating Virtual Users

On the Workload Configuration dialog, on the Pacing tab, you can perform the following actions:
  • You can let Silk Performer calculate the Max. VUsers
  • You can let Silk Performer calculate the Sessions Per Peak Hour
  • You can let Silk Performer calculate the Goal Trans Per Second
  • You can set your own specific Goal Session Time by enabling pacing
Tip: You can copy and paste the values in the Workload Configuration grids by using the keyboard shortcuts Ctrl+C and Ctrl+V or by right-clicking on a value and using the buttons in the context-menu.

Session Pacing

A session is the group of transactions defined for a user in the dcluser section. In the following sample, the session consists of 4 transactions. Note that begin and end transactions are not part of the session. The session time is the time it takes to execute the regular transactions including think times.

// Workload Section
dcluser
  user
    VirtUser
  transactions
    TInit      : begin;
    TLogin     : 1;
    TAddToCart : 2;
    TCheckout  : 1;
    TEnd       : end;

The baseline session time shows how long it took to execute the session in the baseline test.

Session pacing causes Silk Performer to add additional wait time, the so-called pacing wait time, at the end of a session before a new one is started. Session pacing allows you to reach a specified fixed session length, the so-called Goal Session Time.

Typically, you have already defined the number of virtual users in the Adjust Workload workflow step. In this table, you can now see how many sessions the virtual users will manage to execute in one hour. This is reflected by the Sessions Per Peak Hour value. If you adjust this value, Silk Performer will calculate how many virtual users you need to reach the number of sessions. On the other hand, if you adjust the number of virtual users, Silk Performer will recalculate the number of sessions the virtual users will manage to execute.

How the Sessions Per Peak Hour value is calculated

  • Make sure you have set a baseline. See Finding Baselines.
  • Select to Calculate virtual users required to reach a certain number of sessions per hour.
  • The Baseline Session Time [s] column now contains the session time of each user type in the baseline.
  • The Sessions Per Peak Hour is calculated for each user type.

Here is an example of how Silk Performer calculates the values: If the baseline test was executed in 100 seconds and you configured 10 virtual users, these 10 virtual users will be able to execute about 360 sessions within one hour (10 x 3600 seconds / 100 seconds).

Session Per Peak Hour = (Virtual Users x 3600 seconds) / Baseline Session Time

How to set your own specific Goal Session Time

As outlined above, Silk Performer uses the baseline session time to calculate the Sessions Per Peak Hour and the Max. VUsers. If you do not want to use the given baseline session time but want the sessions of a user type to take a different time, you can set your own Goal Session Time by configuring a pacing wait time.

How to configure Session pacing

  • Select sessions per hour to calculate the virtual users required to reach a certain number of sessions per hour.
  • If you have set a baseline previously, the Baseline Session Time [s] column now contains the session time value of each user type in the baseline. Your inputs in the subsequent steps will be validated against the baseline.
  • In the Pacing column, click ... to open the Configure pacing dialog.
  • Click Wait time insertion.
  • Select the relative Pacing wait time or the absolute Goal Session Time and specify the value in the fields beneath the chart.
  • Click OK. Your Goal Session Time displays in the table and the Max. VUsers value is adjusted. The Bandwidth value updates if a baseline has been set.

How to configure Think Time adaption

  • Select sessions per hour to calculate the virtual users required to reach a certain number of sessions per hour.
  • If you have set a baseline previously, the Baseline Session Time [s] column now contains the session time value of each user type in the baseline. Your inputs in the subsequent steps will be validated against the baseline.
  • In the Pacing column, click ... to open the Configure pacing dialog.
  • Click Think time adaptation.
  • Select Static or Dynamic:
    • Static: To reach the goal session time, the think times in the script are multiplied with a constant, static factor.
    • Dynamic: To reach the goal session time, the think times in the script are multiplied with a dynamic factor that is recalculated after each executed session.
  • Define your Goal Session Time and click OK. Your Goal Session Time displays in the table and the Max. VUsers value is adjusted. The Bandwidth updates if a baseline has been set.

Transaction Pacing

While Session Pacing is adding pacing wait time at the end of the session, Transaction Pacing is adding pacing wait time at the end of each individual transaction.

How to get the Goal Transactions Per Second calculation

  • Select transactions per second to calculate the virtual users required to reach a certain number of transactions per second.
  • If you have set a baseline previously, the Avg Transaction Time [s] column now contains the average transaction time value of each user type in the baseline.
  • The Goal Trans Per Second column is calculated for each user type row.

How to set your own specific Goal Transactions Per Second

  • Select transactions per second to calculate the virtual users required to reach a certain number of transactions per second.
  • If you have set a baseline previously, the Avg Transaction Time [s] column now contains the transaction time value of each user type in the baseline.
  • In the Pacing column, click ... to open the Configure pacing dialog.
  • Click Wait time insertion.
  • Select the relative Pacing wait time or the absolute Avg Goal Trans Time and specify the value in the fields beneath the chart.
  • Click OK. Your Goal Session Time displays in the table and the Max. VUsers value is adjusted. The Bandwidth updates if a baseline has been set.
Parent topic: Running Load Tests


Pacing

A commonly used load testing model is to keep transaction rates constant regardless of how loaded the server system is already. In Silk Performer you can define workloads based on transaction or session rates, which Silk Performer tries to meet even when server response times increase due to the increasing load. Consequently, when server response time slows, Silk Performer automatically reduces think times or pacing wait times to keep session times constant.

Silk Performer offers two methods to keep transaction or session rates at a defined level.

  • Think time adaptation modifies the think times in your script so that a certain session time is reached. This option is only applicable if the virtual user script contains at least one ThinkTime() function call.
  • Pacing wait time is the period of time that a virtual user idles after a transaction or session has been completed, so that a certain transaction or session rate is reached.

To modify pacing options, click Run Test on the workflow bar and click the Pacing tab.

To open the Configure Pacing dialog, click ... in the Pacing column.

Several options are available to configure pacing:

  • Think time adaptation: Click this option to determine a Goal Session Time. The think times will be automatically adjusted to match the specified goal session time. You can select between Static and Dynamic. Think time adaptation will only work as expected if the virtual user script contains at least one ThinkTime() function call.
  • Wait time insertion: Specify either the Pacing wait time or the Goal Session Time. If you specify the pacing wait time, it will be added to the execution time of a transaction. If you add up these two times, you will get the goal session time. If you specify the goal session time, the pacing wait time will be automatically determined. You can also specify to randomize the entered values.

To configure pacing wait time directly in a BDL script, use the BDL functions SetPacingTime() and GetPacingTime().

Silk Performer offers pacing for the following workload models:
  • Increasing
  • Steady State
  • All Day
  • Dynamic
Parent topic: Running Load Tests
Related reference
SetPacingTime Function
GetPacingTime Function


Monitoring Load Tests

Detailed real-time information is available to testers while Silk Performer load tests run. Graphic displays and full textual reporting of activity on both the client side and the server side offer intuitive monitoring of the progress of tests as they occur.

Directly from the workbench on which the test is conducted, a tester can view comprehensive overview information about the agent computers and virtual users in the test. A tester can control the level of detail of the displayed information, from a global view of the progress of all the agent computers in the test to an exhaustive detail of the transactions conducted by each virtual user. Progress information for each agent and each user is available in multiple categories. Run-time details for each user include customizable, color-coded readouts on transactions, timers, functions, and errors as they occur.

In addition, real-time monitoring of the performance of the target server is available in graphical form. Charts display the most relevant performance-related information from a comprehensive collection of the Web servers, application servers, and database servers running on all of the OSes most widely used today. Multiple charts can be open at the same time, and these charts can be juxtaposed to provide the most relevant comparisons and contrasts for the tester. A menu tree editor allows for the combination of elements from any data source in the charts. Response times and other performance information from the client application can be placed in the same chart as performance data from the server. This feature enables a direct visual comparison so that one can deterimine the influence of server shortcomings on client behavior.

  • Automatic Monitoring
    Describes the functionality when Automatically start monitoring is enabled in the Silk Performer profile.
  • Monitoring All Agent Computers During Load Testing
    Display performance information for all agents.
  • Monitoring a Specific Agent Computer During Load Testing
    Display information that helps you monitor the performance of a specific agent.
  • Monitoring a Specific Virtual User During Load Testing
    Display detailed run-time information about a selected virtual user.
  • Using a Graph to Monitor Server Performance
    You can generate and view a real-time, color-coded display of server performance.
Parent topic: Running Load Tests


Automatic Monitoring

If Automatically start monitoring is enabled in the Silk Performer profile when a load test begins, Silk Performer launches Performance Explorer with the monitoring template you assigned to the profile.

All monitor writers begin writing and saving generated TSD files to the load-test directory. The writing of these monitor files is automatically stopped after load tests are complete.

The names of generated TSD files are formatted as r@NAMEOFMONITOR@STARTTIME.tsd, where NAMEOFMONITOR is the monitor writers caption. After running the load test, TSD files for each monitor writer are defined in your workspace.

Parent topic: Monitoring Load Tests


Monitoring All Agent Computers During Load Testing

Use the Monitor window to view progress while a load test runs. The top part of the window displays information about the progress of agent computers and user groups.

Among the comprehensive number of information options, you can view the following information:

  • Status of a particular agent
  • Percentage of the test that is complete on an agent
  • Number of executed transactions
Parent topic: Monitoring Load Tests


Monitoring a Specific Agent Computer During Load Testing

In the top part of the Monitor window, select the specific agent to monitor.

The following information about the virtual users running on the selected agent appears in the bottom of the Monitor window:

  • Status
  • Name of the current transaction
  • Percentage of work completed
  • Number of executed transactions
Parent topic: Monitoring Load Tests


Monitoring a Specific Virtual User During Load Testing

In the bottom part of the Monitor window, right-click the virtual user that you want to monitor and choose Show Output of Vuser.
In the Virtual User window, Silk Performer displays detailed run-time information about the selected user, such as the transactions and functions the user executes and the data the user sends to and receives from the server.
Tip: Right-click the virtual user area and choose Select Columns to select the columns you want to view.
Parent topic: Monitoring Load Tests


Using a Graph to Monitor Server Performance

  1. Click Confirm Baseline on the workflow bar. The Workflow - Confirm Baseline dialog box opens.
  2. Click Define monitoring options to specify the settings for receiving online performance data. The Profile Results dialog box opens.
  3. In the Profile Results dialog box, check the Automatically start monitoring check box to automatically start monitoring while running a load test and then choose one of the following options:
    • Click the Use default monitoring template option button.
    • Click the Use custom monitoring template option button to create a customized monitoring template.
  4. Click Create/Edit Custom Monitor Template. Performance Explorer appears.
  5. Close all monitor windows that you are not currently using.
  6. Click Monitor Server on the Performance Explorer workflow bar. Alternatively, you can choose Results > Monitor Server from the menu bar.

    The Data Source Wizard / Select Data Sources dialog box opens.

  7. Perform one of the following steps:
    • If you are certain of the data sources that the server provides, click the Select from predefined Data Sources option button to then select them from the list of predefined data sources.
    • If you are uncertain of the data sources that the server provides, click the Have Data Sources detected option button to let Performance Explorer scan the server for available data sources.
  8. Click Next. In the menu tree, expand the folder that corresponds to the OS on which the server and application are running.
  9. Select the server application you want to monitor from the list that appears. For example, to monitor the OS, select System.
  10. Click Next. The Connection Parameters dialog box opens.
  11. In the Connection parameters area, specify connection parameters such as the host name or IP address of the appropriate server system, the port number, and other data required to connect to the data source. The specified data depends on the OS running on the computer that you are monitoring.
  12. Click Next. The Select Displayed Measures dialog box opens.
  13. Expand the menu tree and select the factors you want to monitor.
  14. Click Finish. A Monitor graph shows the specified elements in a real-time, color-coded display of the server performance. Beneath the graph is a list of included elements, a color-coding key, and performance information about each element.
  • Monitoring Performance for Multiple Servers
    Display a real-time, color-coded display of server performance for multiple servers.
  • Using a Report to Monitor Server Performance
    To have a distributable report of your monitored results, create a Monitor report that contains the same performance factors as selected in the graph.
Parent topic: Monitoring Load Tests
Related tasks
Monitoring Performance for Multiple Servers
Monitoring Server Performance Through SNMP


Monitoring Performance for Multiple Servers

For each server that you want to monitor, follow the procedure for monitoring server performance by using a graph. Separate graphs appear for each server.

  1. Reposition and resize the graphs to facilitate viewing and comparison.
  2. To monitor factors from multiple servers in a single graph, use the menu tree to locate the appropriate factors and drag them onto the selected graph.
Parent topic: Using a Graph to Monitor Server Performance


Using a Report to Monitor Server Performance

Complete the steps for using a graph to monitor server performance.

  1. Choose Monitor > Clone Monitor Report from the Performance Explorer menu bar. A Monitor report displays the performance factors that were selected in the graph. Monitoring information now appears in tabular form in the report.
  2. To save the monitoring report for results exploration along with the load test results, choose Monitor > Write Monitor Data from the Performance Explorer menu bar.
  • Storing Server-Monitoring Data
    Create a file that stores server-monitoring data for a specific time.
Parent topic: Using a Graph to Monitor Server Performance


Storing Server-Monitoring Data

Create a Monitor writer and populate it with the relevant performance factors.
Note: You can store server-monitoring data from a Monitor writer but not from a Monitor chart.
  1. In Performance Explorer, on the Real-Time Monitoring tab, in the New group, click Monitor Writer. The file name appears in the File section of the Monitor information area in the report dialog box. The monitor data is stored in a time series data (.tsd) file.
  2. To view the data in a chart, click Monitor Chart in the New group on the Real-Time Monitoring tab. A new Monitor chart appears.
  3. Drag the appropriate performance factors from the writer onto the chart. The data appears in graphical form.
Parent topic: Using a Report to Monitor Server Performance


Starting Silk Performer from the Command Line

Command Syntax

You can start Silk Performer load tests directly from a command-line interface. This is especially useful when you create a batch file, which executes a number of load tests consecutively.

To start Silk Performer from a command line, use the following syntax:

performer [project file [/Automation [refresh rate] [/WL:workloadname] [/StartMonitor]] [/Resultsdir:directory]]

Here is a sample command with sample parameters:

performer "<my documents>\Silk Performer <version>\Projects\AllDayWorkload\AllDayWorkload.ltp" /Automation 5 /WL:AllDayWorkload10
Note: When files or folders in the project path contain spaces, include quotation marks (") around the project path.
Note: Silk Performer will close immediately if an error (such as a misspelled project path, script error, workload not in the specified project file) occurs during the execution of the command line instruction. Errors can be found in the Event Viewer of the operating system.

Command Line Parameters

Parameter | Description
project file | Name of the project file that defines the load test to be executed.
/Automation | Automatically starts the load test that the specified project file defines. If you omit this parameter, Silk Performer opens the specified project.
refresh rate | Refresh rate, in seconds, at which the Monitor window refreshes. If you omit this parameter, then no refresh occurs.
/WL:workloadname | Name of the workload in the specified project file. If you specify a workload, it is set as the active workload in the project file.
/StartMonitor | Starts Performance Explorer’s monitoring facility when running the test.
/SOA | Launches the Silk Performer SOA Workbench.
/Vision | Specifies to start as Silk Performer Monitor Workbench.
/eCatt | Specifies to start as Silk Performer SAPGUI eCatt Workbench.
/Abort | Aborts running tests.
/? or -? | Displays help about the Silk Performer command-line interface.
/Resultsdir:directory | Specifies the directory where the load test results are stored. The directory path can be absolute or relative to the project file.
/ImportStAsset:asset file?project name | Imports Silk Test assets to Silk Performer. Asset file is the absolute path to the asset. Project name is the name for the new project. This value is optional. When omitted, the default project name is used.
Parent topic: Running Load Tests
Parent topic: Integrating Silk Performer in CI Environments


Exploring Test Results

Usually the final step in conducting a Silk Performer load test is to display and analyze the results of the test to assess the performance of the application and the server under test.

  • Results Overview
    Describes the items that display in the Results menu tree.
  • Silk Central Integration
    Describes how to link Silk Performer data with Silk Central.
  • Exploring Results
    Describes the approaches that are available for displaying, reporting, and analyzing test results.
  • Verification Under Load
    Explains how to use TrueLog On Error to identify errors that only occur under load.
  • Performance Explorer
    Provides an overview of the Performance Explorer functionality.
  • Reports
    Provides an overview of the available reports in Silk Performer , Performance Explorer, and Silk Central .
  • Raw Measure Data Capturing
    Explains when to use raw measure data capturing, how the capturing works in detail, and which raw measure data files are generated.
Parent topic: Managing Load Tests
Related tasks
Exploring Silk Test Results


Results Overview

The Results tab in the bottom left area of the GUI offers full control over your test results. Selecting the Results tab displays a menu tree containing all test results of the currently active project, including Try Script runs, load test results, and Silk Central results (if your Silk Performer project is linked to a Silk Central test definition).

Hovering your mouse over a test in the Results menu tree displays a summary of the test run, including date and time, the selected workload model, agent, VUser and error information.

Depending on the logging options that you have set for test runs, the following items are displayed in the Results menu tree:

  • Baseline Report
  • Time Series
  • TrueLog Files (contains TrueLog files for each virtual user)
  • User Results (contains user profiles, which list all result files per virtual user)
  • Silk Central (displays results from Silk Central, if the project is linked to a Silk Central test definition)
  • Opening Results Files
    View test results to determine the status of your test.
  • Deleting Locally Stored Results Files
    Delete result files that are no longer necessary.
  • Refreshing Displayed Results
    Display the most recent results to determine if your test performed as expected.
Parent topic: Exploring Test Results


Opening Results Files

Choose one of the following methods to open a results file:
  • Double-click a file in the Results menu tree.
  • Right-click a result file and select Open or Explore.
Opening a results file invokes the respective viewing facility.
Note: If the icon of a parent node in the Results menu tree is marked with a red X symbol, an error has occurred during the test execution. If an icon (parent node or result file) is marked with a blue exclamation mark (!), an error log file contains an informational message, a warning, or an error.
Parent topic: Results Overview
Related concepts
Exploring Results
Related tasks
Refreshing Displayed Results


Deleting Locally Stored Results Files

Right-click a top-level results node and select Delete Results.
Note: This does not affect results that are stored in Silk Central.
Parent topic: Results Overview


Refreshing Displayed Results

Right-click a top-level results node and select Update Results. The results that are displayed in the menu tree do not update if they are changed outside of Silk Performer.
Note: If the icon of a parent node in the Results menu tree is marked with a red X symbol, an error has occurred during the test execution. If an icon (parent node or result file) is marked with a blue exclamation mark (!), an error log file contains an informational message, a warning, or an error.
Parent topic: Results Overview
Related concepts
Exploring Results
Related tasks
Opening Results Files


Silk Central Integration

Silk Performer is tightly integrated with Silk Central. If your Silk Performer project is linked to Silk Central, you can store your test results centrally in Silk Central where they can be accessed from both Silk Central and Silk Performer.

To view Silk Central results, your project must be linked to a Silk Central test definition . Once your project is linked to Silk Central, you can view the centrally stored results by clicking Click here to add Silk Central results node in the Results menu tree.

Additionally, you can upload results to Silk Central by right-clicking a top-level results node and selecting Upload Results to Silk Central.

Parent topic: Exploring Test Results
Related concepts
Silk Central Integration
Performance Trend Reports in Silk Central
Related tasks
Downloading Test Results from Silk Central
Uploading Test Results to Silk Central


Exploring Results

Silk Performer offers several approaches to displaying, reporting, and analyzing test results. Defined measurements take place during tests and can be displayed in a variety of graphical and tabular forms. Options include the following:
  • Performance Explorer: This is the primary tool used for viewing test results. A fully comprehensive array of graphic features displays the results in user-defined graphs with as many elements as are required. The results of different tests can be compared. There are extensive features for server monitoring. A comprehensive HTML based overview report that combines user type statistics with time series test result information is also available.
  • TrueLog On Error: Silk Performer provides full visual verification under load capabilities for various application types. It allows you to combine extensive content verification checks with full error drill-down analysis during load tests.
  • Virtual User Report files: When enabled, these files contain the simulation results for each user. Details of the measurements for each individual user are presented in tabular form.
  • Virtual User Output files: When enabled, these files contain the output of write statements used in test scripts.
  • Baseline Reports: A detailed XML/XSL-based report that provides you with a summary table, transaction response-time details, timers for all accessed HTML pages, Web forms, and errors that occurred. This information is available for all user types involved in baseline tests.
  • Silk Central Reports: Silk Performer projects can be integrated into Silk Central (Silk Central) test plans and directly executed from Silk Central. This allows for powerful test-result analysis and reporting. For detailed information on Silk Central reporting, refer to Silk Central Help.
  • Load Test Summary
    On the Load Test Summary page, you can analyze the results of the previous load test.
Parent topic: Exploring Test Results
Related concepts
Results Overview
Silk Central Integration


Verification Under Load

Silk Performer provides full visual verification under load capabilities for Web applications. It allows you to combine extensive content verification checks with full error drill down analysis during a load test. Silk Performer verification checks can be done from all virtual users without major performance loss.

Silk Performer's innovative TrueLog technology makes it possible to collect details regarding the errors of all virtual users that take part in a load test. Traditional probing clients, separated from the load testing tool, are only able to detect content verification errors that occur for users that actually perform verifications. Since a functional testing tool is only able to drive a limited number of concurrent users, the functional test covers only a very small subset of all users that visit your Web application. Such a probing client cannot detect verification errors that occur to users that are not contained within this small subset. Silk Performer has redefined the type of testing that can be done with load testing tools.

With Silk Performer TrueLog technology, you can find errors that usually occur to only a subset of users when your application is under a heavy load. For most applications, this is the type of load that will most likely be experienced once the application is deployed in the real world. Typical errors include incorrect text on a Web page, incorrectly computed and displayed values, or application-related messages, such as Servlet Error or Server Too Busy errors. These are not system-level errors and are displayed on Web pages with HTTP 200 status codes.

TrueLog Explorer provides a view into Silk Performer verification-under-load capabilities with the following features:
  • Visual content verification allows you to visually define the content that is to be verified.
  • TrueLog On Error generation and TrueLog On Error analysis allow you to visually analyze errors to identify their root causes.
  • Viewing Errors in TrueLog Explorer
    View generated log files to verify the cause of errors raised by application servers.
Parent topic: Exploring Test Results


Viewing Errors in TrueLog Explorer

Before you begin, set up the option to generate TrueLog on Error files and run a test that generates errors.

As a foundation for full visual root cause analysis, Silk Performer can save the complete history of errors within a TrueLog. TrueLog On Error can even be generated in large-scale load tests. TrueLog On Error helps you uncover the true source of your application's error output under all possible load conditions.

  1. When an error occurs during a load test, you can view the visual content of the TrueLog by clicking the Explore Results button on the workflow bar. The Workflow - Explore Results dialog opens.
  2. Click the Silk TrueLog Explorer link. TrueLog Explorer opens with the Step Through TrueLog dialog box active. Select Errors.
  3. Navigate from one occurrence of an error to the next.
    Tip: To display the history of an error, click through the preceding API nodes in the menu tree.
Parent topic: Verification Under Load
Related concepts
Performance Explorer
Related tasks
Setting Time-Series Data Options
Setting TrueLog Traffic-Capturing Options


Performance Explorer

Performance Explorer allows you to view measures obtained through real-time monitoring and to analyze results of completed load tests. A variety of tools and features enables exhaustive analysis, reporting, and processing of all captured data.

  • Cloud-Based Region Summary Reports
    Explains how to analyze cloud-based load test measures across geographic regions.
  • Assigning Overview Report Templates to Projects
    Specify an overview report template for your Silk Performer project. The template will be used for automatic and manual generation of HTML overview reports.
Parent topic: Exploring Test Results
Related concepts
Performance Explorer Overview


Cloud-Based Region Summary Reports

Region summary reports gather cloud-based load test measures across geographic regions. When load tests use cloud-based agents, Silk Performer captures region-specific data for each cloud region (and for project agents, if used). Region summary reports are similar to baseline reports. Region summary report files carry the file extension .rsr and are stored in the results directory.

To view region summary result nodes, expand the Region Summary Reports node on the Results tab following a load test.

An overview report (similar to a baseline report) can be created for any individual region by selecting a region node on the Performance Explorer Explore tab and clicking Overview Report.

Parent topic: Performance Explorer


Assigning Overview Report Templates to Projects

You can specify an overview report template for each Silk Performer project. All automatically generated HTML overview reports will use this template and the template will be preselected when you create HTML overview reports manually.

  1. In Silk Performer, expand the Profiles node in the menu tree.
  2. Right-click the profile that you want to configure and choose Edit Profile. Alternative: Choose Settings > Active Profile.

    The Profile - [<profile name>] dialog box opens.

  3. In the shortcut list on the left, click the Results icon.
  4. Click the Time Series tab.
  5. Browse for a template in the Overview report template section and click Open.
  6. Click OK.
Note: Performance Explorer’s command line interface also offers the /OVT:<template> command for assigning overview report templates to Silk Performer projects.
Parent topic: Performance Explorer
Parent topic: HTML Overview Reports


Reports

  • Virtual User Report Files
    Describes the contents of virtual user report files.
  • Virtual User Output Files
    Describes the contents of the output files.
  • Performance Explorer Reports
    Provides an overview of the available reports in Performance Explorer.
  • Performance Trend Reports in Silk Central
    Using Silk Central for load test regression-testing allows you to track performance trends across your product builds.
Parent topic: Exploring Test Results


Virtual User Report Files

Report files contain the simulation results for each virtual user. Details of the measurements for each individual user are presented in tabular form. The many sections in these files include reports on transactions, timers, Web page timers, and counters, and also sections on IIOP, Web form, TUXEDO, and SQL results.

Parent topic: Reports
Related concepts
Virtual User Output Files
Related reference
Overview Report


Virtual User Output Files

Output files contain the output of write statements used in the test script. An output file is generated for a particular user only if write statements are executed by that user.

However, generating output files alters the time measurements of a load test. Therefore, these files should be used for debugging purposes only, and should never be generated for a full load test.

Parent topic: Reports
Related concepts
Virtual User Report Files
Related reference
Overview Report


Performance Explorer Reports

  • Overview Report
    Describes the contents of the overview report.
  • Built-In Measures
    Describes what measures are and provides a list of measures and measure groups.
Parent topic: Reports


Overview Report

The overview report comprises the following sections:

  • General information

  • Summary tables
  • User types
  • Custom charts
  • Custom tables
  • Detailed charts

General information

The general information section includes administrative information in tabular form as well as important load test results in a graphical form.

Administrative information includes the project name, a description of the project, the load test number, a description of the load test, the date of the load test, the duration of the load test, the number of used agent computers, and the number of virtual users that were running.

The charts display the number of active virtual users, response time measurements for transactions, and the number of errors that occur over time. Transaction response times are provided for successfully executed transactions, for failed transactions, and for cancelled transactions.

Additional charts display summary measurements related to the type of load testing project. For example, in the case of Web application testing, response time measurements for Web pages are presented in a graph.

Summary tables

This section contains summary measurements in tabular form, that is, aggregate measurements for all virtual users. The first table provides general information, such as the number of transactions that were executed and the number of errors that occurred. All the following tables provide summary information relevant to the type of application that was tested.

User types

For each user group, this section provides detailed measurements in tabular form. The measurements include transaction response times, individual timers, counters, and response time and throughput measurements related to the type of application that was tested (Web, database, CORBA, or TUXEDO). In addition, errors and warnings for all user groups are listed.

Custom charts

This section contains graphs that you have added manually. You can add charts to and remove charts from this section at any time. You can save your changes as a template to be displayed for every summary report.

Custom tables

This section contains tables that you have added manually. You can add tables to and remove tables from this section at any time. You can save your changes as a template to be displayed for every summary report.

Detailed charts

This section provides enlarged versions of the charts included in the report. Click a reduced version of a chart to jump to the enlarged version, and vice versa.

Parent topic: Performance Explorer Reports
Related concepts
Virtual User Report Files
Virtual User Output Files
Related tasks
Viewing Overview Reports
Assigning Overview Report Templates to Projects


Built-In Measures

A measure is the smallest grouping entity for the values that are collected during a load test or during a monitoring session for a particular measuring point. A measure has a name and type. A set of measured values that are related to the measure is stored as a series in a time series data (.tsd) file.

Measures can be either timers or counters. Timers collect data related to response times, counters collect data on throughput and load test events.

Performance Explorer provides a big amount of measures, which are divided into groups.

  • Summary Measures
    Displays the summarized measurements on a global level.
  • Transaction Measures
    Describes response-time data on the transaction level.
  • Web Form Measures
    Describes scripted measures related to Web forms.
  • Web Page Measures
    Describes the scripted measures related to Web pages.
  • Browser-Driven Measures
    Describes the measures that are used for browser-driven tests.
  • CORBA-Specific Measures
    Describes the measure types that are related to IIOP operations called within a load-testing script.
  • SQL Database-Specific Measures
    Describes the measures that are specific for SQL databases.
  • Middleware-Specific Measures
    Describes the measures that are related to TUXEDO service calls.
  • Citrix-Specific Measures
    Describes the measures related to CItrix.
  • Custom Timer Measures
    Describes the timers that are defined in the load testing script.
  • Custom Counter Measures
    Describes the counters that are defined in the load-testing script.
  • Streaming Measures
    Describes the measures that are specific for HTTP live streaming.
Parent topic: Performance Explorer Reports
Parent topic: Performance Explorer 21.0


Performance Trend Reports in Silk Central

Using Silk Central for load test regression-testing allows you to track performance trends across your product builds. Monitor the evolution of transaction response times, page times, and custom measures across builds to determine how the performance of your application under test is coming along. As new features are being developed in your product, you can react in a timely manner if the application's performance behaves unexpectedly.

The following performance trend reports are available in Silk Central:
Average Page-Time Trend Report
Shows the page times per page for all tests executed for the specified test definition within the specified time range.
Average Transaction Busy-Time Trend Report
Shows the transaction busy time per transaction for all tests executed for the specified test definition within the specified time range.
Custom Measure Trend Report
Shows the average, minimum, and maximum values of the defined measure or measures for all tests executed for the specified test definition within the specified time range.
Overall Page-Time Trend Report
Shows overall page times, aggregated over all user types, for all tests executed for the specified test definition within the specified time range.
Overall Transaction Busy-Time Trend Report
Shows overall transaction busy-time, aggregated over all user types, for all tests executed for the specified test definition within the specified time range.

Refer to Silk Central Help for detailed information.

Parent topic: Reports
Related concepts
Silk Central Integration


Raw Measure Data Capturing

When to use raw measure data capturing

After you have run a load test you can analyze the results in detailed reports in Performance Explorer. If you need data that is even more detailed or if you want to process collected data in another program, you can use Silk Performer to capture raw measure data and store it in CSV files. You can then, for example, import the raw measure data into a spreadsheet program and generate custom graphs.

How does Silk Performer capture raw measure data?

Silk Performer captures raw measure data in three steps:
  1. Raw measure data is collected in u@... files (on the agents).
  2. Raw measure data is merged from the u@... files into i@... files (on the agents).
  3. Raw measure data is merged from the i@... files into m@... files (on the controller).

When you start a Silk Performer test, the Silk Performer controller deploys the test to the agents you have specified. Each agent starts several perfRun.exe processes, and within each process, several virtual users execute the test. During execution, Silk Performer creates one u@... file per process.

The raw measure data is then merged into i@... files and the u@... files are removed. Each i@... file holds the raw measure data of one measure name/measure type combination. The files are stored in the RawData folder: Silk Performer <version number>/Projects/MyProject/RawData.

Once the i@... files have been transferred to the controller, the raw measure data is merged into m@... files (also in the RawData folder). The i@... files remain in the RawData folder. Each m@... file holds the raw measure data of one name/type combination of all agents.

Step one and two of the raw measure data capturing process are executed on the agents, step three is executed on the controller.

What do the file names mean?

These are the full names of the raw measure data files:

  • u@rawdata_processid.csv
  • i@name_type@agent.csv
  • m@name_type@controller.csv

The data is stored in CSV files (comma-separated value files), which allows you to easily process the raw measure data with a spreadsheet program. u stands for user file, i for intermediate file, and m for merged file. Here is an example of some i@... and m@... files:

i@ShopIt+-+Greetings_131@testingserver.csv
i@ShopIt+-+Greetings_132@testingserver.csv
i@SilkPerformer+Test+Site_131@testingserver.csv
i@SilkPerformer+Test+Site_132@testingserver.csv

m@ShopIt+-+Greetings_131@pc-johndoe.csv
m@ShopIt+-+Greetings_132@pc-johndoe.csv
m@SilkPerformer+Test+Site_131@pc-johndoe.csv
m@SilkPerformer+Test+Site_132@pc-johndoe.csv

Note the following from this example:

  • There are no u@... files in this example, since they are removed when their content is merged into the i@... files. They are just temporary files.
  • The measure names are URL-encoded (ShopIt+-+Greetings).
  • The measure type is represented by its number code. 131 is the number code for Page time[s], 132 is the number code for Document download time[s].
  • testingserver is the machine name of the agent.
  • pc-johndoe is the machine name of the Controller.

What does a raw measure data file look like?

Here is an example of what the raw measure data in an m@... file looks like:

;MeasureName:;ShopIt - Greetings
;MeasureType:;Page time[s]
C;Timestamp;Value;VUName
;1381231408198;46;VUser
;1381231431291;31;VUser
;1381231433032;31;VUser
;1381231434120;16;VUser
;1381231436307;15;VUser
...

The data within the CSV files is sorted by the timestamp (which is a Unix timestamp). The timestamp represents the elapsed microseconds since 01.01.1970. Time measure values are logged in seconds, file size values are logged in kilobytes.

  • Enabling Raw Measure Data Capturing
    Describes how to enable raw measure data capturing in the Profile dialog box.
  • Raw Measure Data File Size Statistics
    Provides some examples of how big raw measure data files can become.
Parent topic: Exploring Test Results


Enabling Raw Measure Data Capturing

  1. In Silk Performer, expand the Profiles node in the Project tree.
  2. Right-click the profile that you want to configure and choose Edit Profile.
    Tip: Alternatively, you can choose Settings > Active Profile from the menu bar.

    The Profile - [<profile name>] dialog box opens, and the Replay category is displayed in the shortcut list on the left.

  3. In the shortcut list on the left, click the Results icon.
  4. Click the Measures tab.
  5. Check the Collect raw measure data check box.

To configure raw measure data capturing for particular measure types or single measures, use the BDL function MeasureCollectRawData.

Parent topic: Raw Measure Data Capturing
Related reference
MeasureCollectRawData Function


Raw Measure Data File Size Statistics

The following tables provide some examples of how big raw measure data files can become when you execute load tests with the shown settings.
Note: The size values are approximate values.
Measurements | Duration of load test | Virtual users | Size of raw measure data file
1 measurement per second | 1 hour | 100 | 10 MB
3 measurements per second | 5 hours | 100 | 150 MB
1 measurement every 10 seconds | 3 hours | 100 | 3 MB
Load Test | Duration of load test | Virtual users | Size of all raw measure data files | Agents | Result packaging and download time*
10 pages (with 5 measurements per page), 1 page per second | 1 hour | 100 | 175 MB | 2 | 30s
20 pages (with 5 measurements per page), 1 page every 3 seconds | 5 hours | 100 | 290 MB | 2 | 45s
20 pages (with 5 measurements per page), 1 page every 3 seconds | 10 hours | 400 | 2,25 GB | 4 | 3m 50s
20 pages (with 5 measurements per page), 1 page every 3 seconds | 10 hours | 4000 | 23 GB | 40 | 7m 30s

* To gather these download times, Silk Performer CloudBurst agents and a 100 Mbps internet connection to the Silk Performer controller were used. The times include data processing and compression on the agents and the transfer to the controller.

Note: If you use cloud agents for your load tests, transferring large raw measure data files from the cloud agents to the controller can take a considerable amount of time.
Note: For most load test scenarios it is sufficient to generate raw measure data for only a selected set of measures. To do so, use the BDL function MeasureCollectRawData.
Parent topic: Raw Measure Data Capturing
Related reference
MeasureCollectRawData Function


Load Testing Specific Application Types

Silk Performer supports testing within a variety of computing environments. This section explains Silk Performer’s support of AJAX, SAP eCATT, terminal emulation, GUI-level testing, and much more.

  • Flex/AMF3 Support
    Explains Silk Performer support for the testing of Flex/AMF3 applications, including a technology overview, project setup, and Java configuration issues.
  • Web Applications Support
    Explains how to test Web applications using Silk Performer.
  • Testing Apps for Mobile Devices
    Explains how to test mobile applications with Silk Performer.
  • Responsive Web Design Testing
    Describes what responsive web design is and what it means in terms of load testing.
  • BMC Remedy IT Service Management Support
    Explains Silk Performer's support for the testing of BMC Remedy IT Service Management, including licensing, TrueLogs, and data representation.
  • Citrix XenApp Support
    Explains that Silk Performer provides record and replay support for the testing of applications that are hosted via Citrix XenApp session and application virtualization technologies.
  • .NET Support
    Explains Silk Performer's .NET support, which includes the testing of Web Services, .NET Remoting objects, NUnit, and more.
  • GUI-Level Testing Support
    Explains how GUI-level testing works, when to use it, and how to set up a GUI-level testing environment.
  • Jacada Support
    Explains Silk Performer support for the testing of Jacada applications, including project setup and Java configuration issues.
  • Java Support
    Explains Silk Performer's Java support, which includes the testing of Enterprise JavaBeans (EJB), RMI objects, JUnit, and more.
  • OnWeb Mainframe-to-Web Testing Support
    Silk Performer supports the testing of Micro Focus OnWeb Web-based applications that interact with mainframe systems.
  • Oracle Forms / Oracle Applications Support
    Enter a short description of your concept here (optional).
  • SAP Support
    Explains Silk Performer's support for the testing of SAP applications.
  • Siebel Support
    Explains the testing of Siebel thin client (Web client) installations that utilize front ends comprised of HTML and applets running within a Web browser.
  • Microsoft Silverlight Support
    Explains that the workflow for testing Microsoft Silverlight browser-based applications is the same as the workflow used for testing Web-based applications.
  • Terminal Emulation Support
    Explains Silk Performer support for terminal emulation applications, which enables the recording of terminal-emulator traffic based on the Telnet protocol (“green screen” applications).
  • TCP/IP Based Protocol Support
    This section explains how to develop load test scripts for applications that use legacy or custom TCP/IP based protocols.
  • Load Testing PeopleSoft
  • HLS Support
    Describes what HLS is and how Silk Performer supports recording and replaying media streams using this protocol.
Parent topic: Silk Performer Workbench 21.0


Flex/AMF3 Support

This section explains Silk Performer support for the testing of Flex/AMF3 applications, including a technology overview, project setup, and Java configuration issues.

  • Flex/AMF3 Overview
    Offers a brief introduction to Adobe Flex/AMF3 technology.
  • Flex/AMF3 Project Setup and Testing
    Explains considerations related to the testing of Flex/AMF3 applications with Silk Performer, including project setup, script recording, and XML code examples.
  • Understanding Flex/AMF3 Scripts
    This section explains aspects of the Flex/AMF3 protocol including script elements and XML Representation of Binary AMF.
  • Customizing Flex/AMF3 Scripts
    Explains that Flex/AMF3 scripts are best customized using TrueLog Explorer.
Parent topic: Load Testing Specific Application Types


Flex/AMF3 Overview

AMF3 (Action Message Format, version 3) is a binary protocol developed by Adobe Systems. It is primarily used for remote procedure calls by Flex applications.

A primary goal in the design of AMF3 is that transmitted data be as small as possible. This requirement presents a challenge for protocol customization with Silk Performer. To make the AMF3 protocol customizable and human-readable, Silk Performer transforms AMF3 traffic into XML during script recording, and transforms the XML back into AMF3 format during replay. This means that you do not have to read binary AMF3 data in hex string format. Rather, in recorded scripts and TrueLogs, you see only XML-formatted data.

AMF0 and AMF3 support are tightly integrated (in fact AMF3 uses AMF0’s message structure). Each AMF3 message begins as an AMF0 message (even when they contain the version "3" in the first two bytes of the data stream). A special AMF0 data type marker indicates where AMF0 encoding ends and AMF3 encoding begins.

Understanding Flex

According to Adobe Systems,

"Flex is a free, open source framework for building highly interactive, expressive web applications that deploy consistently on all major browsers, desktops and operating systems. It provides a modern, standards-based language and programming model that supports common design patterns. MXML, a declarative XML-based language, is used to describe UI layout and behaviors, and ActionScript 3, a powerful OO programming language is used to create client logic. Flex also includes a rich component library with over 100 proven, extensible UI components for creating RIAs, as well as an interactive Flex application debugger.

Rich Internet applications created with Flex can run in the browser using the ubiquitous Adobe Flash® Player software or on the desktop on Adobe AIR™. This enables Flex applications to run consistently across all major browsers and across operating systems on the desktop. And using Adobe AIR, the cross-operating system runtime, Flex applications can now access local data and system resources on the desktop.

You can accelerate application development with Adobe Flex Builder 3, a highly productive, Eclipse™ based development environment, and Adobe Live Cycle Data Services ES, a set of advanced data services that can be used in Flex development. Both of these products are available for purchase."

Understanding Advanced Flex Data Services

According to Adobe ,

"Adobe LiveCycle™ Data Services ES provides a comprehensive set of data-enabling features for using data in RIAs. It enables RIAs to talk to back-end data and business logic in a faster, more efficient operating model. LiveCycle Data Services ES also enables seamless integration with LiveCycle ES business processes and document services.

BlazeDS is a free, open source project providing Flex Remoting and Messaging to all developers. Flex Remoting provides a binary, serialized data transport format called the ActionScript Message Format (AMF) to provide a fast, efficient means of transporting data to your RIA which accelerates application performance. Flex Remoting also makes it fast and easy for developers to connect to back-end business logic and data. Flex Messaging adds realtime data push and publish/subscribe, both powerful capabilities now made easy. Using BlazeDS, you can start using these powerful Java server integration features for free, then subscribe to the LiveCycle Data Services Community Edition for certified builds and support, or upgrade to the full LiveCycle Data Services ES Enterprise edition for a complete server solution."

Parent topic: Flex/AMF3 Support


Flex/AMF3 Project Setup and Testing

Prerequisites

For testing Flex/AMF3 applications based on the Adobe or BlazeDS implementation, Java Development Kit 1.5 or later is required.

For testing Flex/AMF3 applications based on the GraniteDS implementation, Java Development Kit 1.6 or later is required.

Transformation is enabled for HTTP requests and responses that have the HTTP header Content-Type set to "application/x-amf". If you need to transform data with a different HTTP Content-Type header, see Transformation of Custom Content-Types.

Setting Up an Adobe Flex/AMF3 Project

For testing Flex/AMF3 applications based on the Adobe or BlazeDS implementation, select the Flex/AMF3 (Adobe) application type on the Outline Project dialog.

The Flex/AMF3 (Adobe) application type supports both AMF0 and AMF3. By selecting the Flex/AMF3 (Adobe) application type, several profile settings are automatically configured for you on the tab Profile > Web (Protocol Level) > Transformation:
  • The Flex/AMF3 (Adobe) transformation DLL is selected in the Type drop list.
  • Transform HTTP Requests is enabled
  • Transform HTTP Responses is enabled
  • Enable Java Virtual Machine usage is enabled. This setting is required because Flex/AMF3 requires a running JVM for accurate transformation of externalizable traits. This setting also causes transformed AMF3 traffic to appear in a readable XML representation that includes fewer AMF3 syntactical tags.

Setting Up a GraniteDS Flex/AMF3 Project

For testing Flex/AMF3 applications based on the GraniteDS implementation, select the Flex/AMF3 (GraniteDS) application type on the Outline Project dialog.

The Flex/AMF3 (GraniteDS) application type supports both AMF0 and AMF3. By selecting the Flex/AMF3 (GraniteDS) application type, several profile settings are automatically configured for you on the tab Profile > Web (Protocol Level) > Transformation:
  • The Flex/AMF3 (GraniteDS) transformation DLL is selected in the Type drop list.
  • Transform HTTP Requests is enabled
  • Transform HTTP Responses is enabled
  • Enable Java Virtual Machine usage is enabled. This setting is required because Flex/AMF3 requires a running JVM for accurate transformation of externalizable traits. This setting also causes transformed AMF3 traffic to appear in a readable XML representation that includes fewer AMF3 syntactical tags.

Configuring a Customized GraniteDS Configuration

If your application under test uses a customized GraniteDS configuration, you may find that an exception is reported in TrueLog Explorer, in the Recorder log or the virtual user log files. These exceptions resemble the following:
WebPagePost(WebEngine: 82 - Content transformation error, RESPONSE: AMF3: Java based XML generation failed,
using fallback, reason: org.granite.messaging.amf.io.AMF3SerializationException
…
Caused by: java.lang.RuntimeException: The ActionScript3 class bound to org.granite.example.addressbook.entity.Person
(ie: [RemoteClass(alias="org.granite.example.addressbook.entity.Person")]) implements flash.utils.IExternalizable but
this Java class neither implements java.io.Externalizable nor is in the scope of a configured externalizer
(please fix your granite-config.xml)
…
To make Silk Performer aware of this custom configuration and to get rid of the exceptions, proceed as follows:
  1. Locate the customized configurations of your application under test. These can usually be found in granite-config.xml or granite-custom-config.xml, which is located in the application's classpath.
  2. In the Project menu tree, locate the granite-custom-config.xml file in the Data Files folder.
  3. Double-click granite-custom-config.xml to open it in the editor.
  4. Copy and paste the customized configurations that you located in step 1 into the granite-custom-config.xml data file and save your changes.

Modeling a Script

Using the JVM requires the configuration of Flex/AMF3 application-specific custom JAR files that contain the classes that are necessary for serialization into correct XML representation. For this reason, when modeling a Flex/AMF3 script, the Model Script dialog includes an Add Custom JAR File(s) button. Click this button to browse to and Add any custom JAR files that are specific to the application under test. Added JAR files are displayed within the Project tree Data Files node.

These required JAR files (or individual .class files) are located on the server to be tested. These files must be prepared manually and copied from the server to the Silk Performer controller machine. It may be that the only required task is to place individual .class files into an archive.

Note: JAR files must be placed in the Project folder.

Clicking Settings on the Model Script dialog links you directly to the current user profile, Java Settings tab. Use this to change Java settings for the currently selected user profile.

The Apache Flex 2, 3, 4 and BlazeDS 3.2.0 base JAR files are installed in the directory C:\Program Files(x86)\Silk\Silk Performer <version>\ClassFiles\Adobe-Flex. These JAR files are automatically added to the classpath. These files may be manually updated by copying new versions of flex-messaging-common.jar and flex-messaging-core.jar into the directory.

Make sure that you have the GraniteDS base JAR files on your machine and then add these JAR files to the classpath.

Note: Do not enable Use system classpath on the Java Settings tab. JAR files set in the system classpath may overrule manually configured JAR files.

Generating a Script from a Capture File

While recording a user transaction, the Silk Performer recorder creates a so-called Silk Performer capture file, which contains the entire traffic of the recorded session. After saving, the capture file is opened in the Workbench for further analysis and processing. Before generating a script from the captured traffic, you can configure recording rules and other settings, which are applied during the script generation process.

If any errors occur, click the buttons in the Resolve Problems area to resolve them. Then, click Generate Script to generate a script from the capture file.

On 64-bit operating systems, both a 32-bit and 64-bit Java installation are required. The 32-bit installation is used for replaying scripts, the 64-bit installation is used for generating scripts. If a 64-bit installation is not available, you can force Silk Performer to use a 32-bit process for script generation by setting the following registry key to 1: HKEY_LOCAL_MACHINE\SOFTWARE\Silk\SilkPerformer\<version>\Force32BitCaptureAnalyzer.
Attention: Using the 32-bit script generator can cause issues with large capture files.

Replaying a Script

If your Java configurations are incorrect (for example, if JAR files are missing), XML responses (only visible in TrueLog Explorer) will not be generated in an easily readable format. Also warnings or errors will be written to the Virtual User Output pane. Typically, errors and warnings indicate whether or not they were caused by requests (client to server) or responses (server to client).

Customizing AMF3 Scripts

Do not change the overall structure of XML objects within AMF3 scripts. It is okay to parse values or insert verification functions, but deleting or rearranging AMF3 XML elements will destroy a call. Also do not change the order of elements within arrays.

Code Examples

Command message example:

<AmfXml version="3">
  <Msg length="203" operation="null" responseURI="/1">
    <StrictArray nrElems="1">
      <Amf3>
        <JavaObject>
          <flex.messaging.messages.CommandMessage>
            <destination></destination>
            <messageId>3EE7E87A-96E6-3272-30F7-FFEF6B9EFE9E</messageId>
            <timestamp>0</timestamp>
            <timeToLive>0</timeToLive>
            <headers>
              <entry>
                <string>DSId</string>
                <string>nil</string>
              </entry>
            </headers>
            <body class="flex.messaging.io.amf.ASObject" serialization="custom">
              <unserializable-parents></unserializable-parents>
              <map>
                <default>
                  <loadFactor>0.75</loadFactor>
                  <threshold>12</threshold>
                </default>
                <int>16</int>
                <int>0</int>
              </map>
              <flex.messaging.io.amf.ASObject>
                <default>
                  <inHashCode>false</inHashCode>
                  <inToString>false</inToString>
                </default>
              </flex.messaging.io.amf.ASObject>
            </body>
            <correlationId></correlationId>
            <operation>5</operation>
          </flex.messaging.messages.CommandMessage>
        </JavaObject>
      </Amf3>
    </StrictArray>
  </Msg>
</AmfXml>

Remoting message example:

<?xml version='1.0' encoding='UTF-8'?>
<AmfXml version="3">
  <Msg length="394" operation="null" responseURI="/4">
    <StrictArray nrElems="1">
      <Amf3>
        <JavaObject>
          <flex.messaging.messages.RemotingMessage>
            <clientId class="string">208F18FC-6F0D-9964-3746-76438D73A6A3</clientId>
            <destination>myextservice</destination>
            <messageId>A98651D4-690D-E530-B744-FFEF866937C7</messageId>
            <timestamp>0</timestamp>
            <timeToLive>0</timeToLive>
            <headers>
              <entry>
                <string>DSId</string>
                <string>208F0A62-A409-8994-08AF-223CD381602C</string>
              </entry>
              <entry>
                <string>DSEndpoint</string>
                <string>my-amf</string>
              </entry>
            </headers>
            <operation>setMyExtClass</operation>
            <parameters>
              <com.borland.silkperformer.flex.samples.MyExt>
                <string>string1</string>
                <string>string2</string>
                <string>string3</string>
                <boolean>true</boolean>
                <date>2009-03-13 14:05:01.545 CET</date>
              </com.borland.silkperformer.flex.samples.MyExt>
            </parameters>
          </flex.messaging.messages.RemotingMessage>
        </JavaObject>
      </Amf3>
    </StrictArray>
  </Msg>
</AmfXml>

Acknowledge message example:

<?xml version='1.0' encoding='UTF-8'?>
<AmfXml version="3">
  <Msg operation="/5/onResult" responseURI="">
    <Amf3>
      <JavaObject>
        <flex.messaging.messages.AcknowledgeMessage>
          <clientId class="string">208F18FC-6F0D-9964-3746-76438D73A6A3</clientId>
          <messageId>20903C27-020C-F5E6-68E7-C8175449798D</messageId>
          <timestamp>1236954453026</timestamp>
          <timeToLive>0</timeToLive>
          <body class="com.borland.silkperformer.flex.samples.MyExt">
            <string>some string</string>
            <com.borland.silkperformer.flex.samples.MyExt>
              <string>string1</string>
              <string>string2</string>
              <string>string3</string>
              <boolean>true</boolean>
              <date>2009-03-13 14:04:58.14 CET</date>
            </com.borland.silkperformer.flex.samples.MyExt>
            <string>GET</string>
            <string>string</string>
            <boolean>true</boolean>
            <date>2009-03-13 14:05:01.545 CET</date>
          </body>
          <correlationId>C4BD7297-67CB-84AB-0C1A-FFEF8DEB3A97</correlationId>
        </flex.messaging.messages.AcknowledgeMessage>
      </JavaObject>
    </Amf3>
  </Msg>
</AmfXml>
Parent topic: Flex/AMF3 Support
Related concepts
Customizing Scripts
Generating Scripts from Capture Files


Understanding Flex/AMF3 Scripts

This section explains aspects of the Flex/AMF3 protocol including script elements and XML Representation of Binary AMF.
  • Flex/AMF Packet-Oriented Protocol
    Explains how AMF packets are sent in the bodies of HTTP POST requests.
  • XML Representation of Binary AMF
    Explains the AmfXml root node and its version attribute.
  • Date Values
    Explains how binary AMF represents date values with a 64-bit floating point value.
  • Out-dated AMF3 Data Types
    Included for backward compatibility purposes only. Lists the out-dated AMF3 data types that are supported for testing by Silk Performer.
Parent topic: Flex/AMF3 Support


Flex/AMF Packet-Oriented Protocol

Flex/AMF uses a binary packet-oriented protocol that is passed with HTTP POST requests. This packet format is called Action Message Format (AMF). The Flex/AMF application sends AMF packets to the server in the bodies of HTTP POST requests. The server responds with AMF packets in the bodies of HTTP responses. Both the HTTP requests and the responses contain the Content-Type HTTP header with the value application/x-amf.

HTTP requests that carry AMF packets are recorded with the function WebPagePost. The URL to be used is recorded as the first parameter of the function, the AMF packet to be sent is recorded as the second parameter.

In scripts, logs, and TrueLogs, Silk Performer does not display binary AMF packets in their original binary format. Instead, an XML based textual representation is used. The conversion from this textual representation to binary AMF and vice versa is done transparently by the recorder and replay. Binary AMF can only be seen in the textual log if the appropriate logging options are enabled.

The advantage of this is that AMF packets are easy to read, understand and customize. AMF packets are also rendered using the XML tree view in TrueLog Explorer, and can be customized there in the same way that all XML data can be customized.

Parent topic: Understanding Flex/AMF3 Scripts


XML Representation of Binary AMF

The root node of Silk Performer XML representation of binary AMF is called AmfXml. Its only attribute is the version attribute, which corresponds to the version field in binary AMF and denotes the AMF protocol specification version. Its value is always zero (0).

AMF packets consist of a list of context headers and a list of messages. Any of these lists may contain zero elements.

The basic structure of an AMF packet in XML is shown below:

<?xml version='1.0' encoding='UTF-8'?>
<AmfXml version=\"0\">
<CtxHeader length="112" mustUnderstand="true"  name="some_name">
     (contents of context header)
  </CtxHeader>
    (more context headers)
  <Msg length="5" operation="some.operation" responseURI="/1">
     (contents of message)
  </Msg>
    (more messages)
</AmfXml>
  • Context Headers
    Explains the attributes of context headers.
  • Messages
    Explains the attributes of Flex/AMF3 messages.
  • Typed Values
    Explains that typed values are serialized actionscript objects included in context headers and messages.
  • Examples of Typed Values
    Includes example Flex/AMF3 transaction and response code samples that use typed values.
Parent topic: Understanding Flex/AMF3 Scripts


Context Headers

Context headers have the attributes length, mustUnderstand, and name.

The value of the length attribute specifies the number of bytes used for this context header in the binary AMF packet. It is for informational purposes only, and need not be adjusted if the XML representation is customized because the transformation from XML to binary AMF automatically calculates the correct value.

The content of a context header is exactly one typed value.

Parent topic: XML Representation of Binary AMF


Messages

Messages have the attributes length, operation, and responseURI. The value of the length attribute specifies the number of bytes used for this message in the binary AMF packet. It is for informational purposes only, and need not be adjusted if the XML representation is customized because the transformation from XML to binary AMF automatically calculates the correct value.

The content of a message is exactly one typed value.

Parent topic: XML Representation of Binary AMF


Typed Values

Typed values are serialized actionscript objects. Each context header and each message contains exactly one typed value.

Typed values can be arbitrary complex, hierarchical data structures.

Each typed value consists of a type, a value, and optionally a name.

The type is specified by the XML node name. The optional name is specified by the name attribute of the XML node.

For simple types, the value is specified in the content of the XML node. For container types, the value is specified by subnodes of the XML node.

Some types may have additional attributes.

Typed values have a name attribute only when they are direct subnodes of an Object, TypedObject, or ECMAArray. Top-level typed objects and subnodes of a StrictArray do not have name attributes.

The following table offers an overview of available types and optional attributes.

XML Nodename | Value location | Additional attributes(except name, see above)
Number | Content of node | ---
Boolean | Content of node | ---
String | Content of node | ---
Object | Subnodes | refId (optional)
Null | no value | ---
Undefined | no value | ---
Reference | Content of node | ---
ECMAArray | Subnodes | nrElems, refId (optional)
StrictArray | Subnodes | nrElems, refId (optional)
Date | Content of node | ---
LongString | Content of node | ---
Unsupported | no value | ---
XMLObject | Content of node | refId (optional)
TypedObject | Subnodes | type, refId (optional)

The optional refId attribute of the types Object, ECMAArray, StrictArray, XMLObject, and TypedObject can be used to assign an arbitrary ID to such a value. Such an ID can then be used to reference the value later with a Reference node.

This technique is commonly used to avoid multiple identical representations of the same object. With this approach, an object is represented only once, and later it is only referenced by a Reference node. This allows you to efficiently serialize complex data structures, which may even contain cyclic references.

Parent topic: XML Representation of Binary AMF


Examples of Typed Values

<Object>
  <Boolean name="coldfusion">true</Boolean>
  <Boolean name="amfheaders">false</Boolean>
  <Boolean name="amf">false</Boolean>
  <Boolean name="httpheaders">false</Boolean>
  <Boolean name="recordset">true</Boolean>
  <Boolean name="error">true</Boolean>
  <Boolean name="trace">true</Boolean>
  <Boolean name="m_debug">true</Boolean>
</Object>

<ECMAArray nrElems="0">
  <Number name="Time">1080677591838</Number>
  <String name="EventType">Information</String>
  <Date name="Date">2004-03-30 20:13:11.838 TZ:-480 [426F73ACED63C000FE20]</Date>
  <String name="Message">CF_DEBUG_DISABLED</String>
  <String name="Source">Server</String>
</ECMAArray>

Example request sent to sample application

<?xml version='1.0' encoding='UTF-8'?>
<AmfXml version="0">
  <CtxHeader length="82" mustUnderstand="false" name="playerInfo">
    <Object>
      <String name="version">WIN 7,0,19,0</String>
      <String name="manufacturer">Macromedia Windows</String>
      <String name="os">Windows 2000</String>
    </Object>
  </CtxHeader>
  <Msg length="13" operation="petmarket.api.catalogservice.getCategories"
       responseURI="/4">
    <StrictArray nrElems="1">
      <String>en_US</String>
    </StrictArray>
  </Msg>
</AmfXml>

Example request received from sample application

<?xml version='1.0' encoding='UTF-8'?>
<AmfXml version="0">
  <Msg operation="/4/onResult" responseURI="null">
    <TypedObject type="RecordSet">
      <ECMAArray name="serverinfo" nrElems="0">
        <StrictArray name="initialData" nrElems="5">
          <StrictArray nrElems="4">
            <Number>5</Number>
            <String>birds</String>
            <String>birds</String>
            <String>D7A91E</String>
          </StrictArray>
          <StrictArray nrElems="4">
            <Number>4</Number>
            <String>cats</String>
            <String>cats</String>
            <String>FFA672</String>
          </StrictArray>
          <StrictArray nrElems="4">
            <Number>2</Number>
            <String>dogs</String>
            <String>dogs</String>
            <String>FF876F</String>
          </StrictArray>
          <StrictArray nrElems="4">
            <Number>1</Number>
            <String>fish</String>
            <String>fish</String>
            <String>4F9FDB</String>
          </StrictArray>
          <StrictArray nrElems="4">
            <Number>3</Number>
            <String>reptiles</String>
            <String>reptiles</String>
            <String>97D76B</String>
          </StrictArray>
        </StrictArray>
        <Number name="version">1</Number>
        <Number name="totalCount">5</Number>
        <String name="serviceName">PageableResultSet</String>
        <Number name="cursor">1</Number>
        <StrictArray name="columnNames" nrElems="4">
          <String>CATEGORYOID</String>
          <String>CATEGORYDISPLAYNAME</String>
          <String>CATEGORYNAME</String>
          <String>COLOR</String>
        </StrictArray>
        <Null name="id"></Null>
      </ECMAArray>
    </TypedObject>
  </Msg>
</AmfXml>
Parent topic: XML Representation of Binary AMF


Date Values

Binary AMF represents date values with a 64-bit floating point value that specifies the number of milliseconds elapsed since January 1, 1970, midnight GMT, and a 16-bit signed integer value that specifies the timezone offset in minutes relative to GMT.

Date values are represented in XML in the following format: YYYY-MM-DD HH:MM:SS.mmm TZ:[+-]tzoffset

YYYY | denotes a 4 digit year
MM | denotes a 2 digit month (range: 01-12)
DD | denotes a 2 digit day (range: 01-31);
HH | denotes a 2 digit hour-of-day (range: 00-23)
MM | denotes a 2 digit minute value (range: 00-59)
SS | denotes a 2 digit seconds value (range: 00-59)
mmm | denotes the 3 digit number of milliseconds value
tzoffset | denotes the timezone offset to GMT in minutes

Because of the rounding of floating point values to the nearest millisecond it is generally not possible to reconstruct an exact binary representation from these string representations. For this reason, the original binary representation is also included in hexadecimal representation in square brackets. As long as such a date value is not customized, the hexadecimal representation can be used to exactly reconstruct the original date value when XML is transformed back to binary AMF.

When customizing a date value, the hexadecimal representation can either be deleted or left untouched. Regardless it is ignored when the XML representation is converted to binary AMF.

Example string representation of a date value: 2004-03-30·16:38:38.260·TZ:-300·[426F73945F768000FED4]

Parent topic: Understanding Flex/AMF3 Scripts


Out-dated AMF3 Data Types

Simple Data Types

Note: This topic is included for backward compatibility purposes only. It describes an out-dated method of XML serialization. If your Java settings are correctly configured and you are using Silk Performer version 2009 or later, you may safely ignore this topic. Usage of the JVM requires the configuration of Flex/AMF3 application-specific custom JAR files that contain classes that are necessary for the serialization of code into correct XML representation. When these JAR files are missing, the translation DLL uses the method of XML serialization described in this topic.

Here are four simple data types that are provided by AMF3. In the binary protocol, each of these data types is transmitted as a 1-byte type marker. The corresponding XML tags for each data type are included in parenthesis.

  • Undefined (<Undefined></Undefined>)
  • Null (<Null></Null>)
  • False (<False></False>)
  • True (<True></True>)

Integer

Integers in AMF3 are serialized as variable-length 29-bit unsigned integers. The variable-length format ensures that integers take up as little space as necessary. In XML format, integers look like this:
<Integer>123456</Integer>

The integer data type is encoded as a 1-byte type marker, followed by up to 4 bytes that encode the integer using the variable length format. Besides their use as a data type, variable-length integers are used in other places within the protocol.

Double

A double stores an 8-byte double precision floating point value as defined in IEEE 754. This is the data type that many programming languages refer to as a double. In XML format, doubles look like this:
<Double>3.14159</Double>

In the binary format, doubles are encoded as 1-byte type markers followed by 8 bytes that contain the double value.

String

Strings are used to store all types of UTF-8-encoded string data. Besides their use as a data type, strings are also used to specify string data, such as classes or member names. All string values in an AMF3 data stream are put into a reference table which is typically generated when AMF3 or XML data is parsed.

A string can either be encoded as a string value or as a string reference. A string reference refers to a previous occurrence of its number in the string reference table. This feature is used to save space when the same string value occurs several times in a single AMF3 data stream.

In XML format, a string looks like this:
<String>Hello, World!</String>
When string references are used, the referenced string is marked with a reference ID (in the form of an attribute), and the string reference refers to the reference ID:
<String val-refId="#0">This string is referenced</String>
<String val-ref="#0"></String>

XML and XMLDocument

AMF3 provides two data types to encode XML data: XMLDocument, which represents a Flash legacy data type, and XML, which is a newer XML type. Both data types encode XML as strings. The difference is that these strings are not registered in the string reference table. They are registered in the object reference table.

Note: With the XML format, the actual XML content must be XML-encoded. Due to a limitation with Silk Performer's XML parser, it is currently not possible to use XML CDATA sections to notate such data.
<Xml>&lt;Data&gt;some data&lt;/Data&gt;</Xml>
<XmlDoc>&lt;Data&gt;some more data&lt;/Data&gt;</XmlDoc>

As with strings, XML data can be referenced to save space:

<Xml refId="data">&lt;Data&gt;foobar&lt;/Data&gt;</Xml>
<Xml ref="data"></Xml>

Date

In AMF3, the date is encoded as the number of milliseconds elapsed since January 1st 1970, 00:00, in the UTC timezone. The number of milliseconds is encoded as a double. Dates also support references, and each date is registered in the object reference table.

<Date>2007-02-18 11:29:00.000</Date>
<Date refId="newmillenium">2000-01-01 00:00:00.000</Date>
<Date ref="newmillenium"></Date>

Array

Arrays in AMF3 cover two types of data structures: standard arrays, where each element is identified by an index number, and associative arrays, where each element is identified by a key (in the case of AMF3, this is always a string). In the binary representation of an array, the associative portion of the array is listed first. This is followed by a separator (an empty string) and finally the dense portion of the array (the standard array elements).

In XML representation, the elements of an associative array are marked by their name attributes. Generally, arrays are not bound to a specific type, which means that you can put any data type in them, including different data types.

    <Array>
        <Integer name="number1">23</Integer>
        <Integer name="number2">42</Integer>
        <String name="username">EMEA\johndoe</String>
        <Date>2008-02-17 13:47:13.000</Date>
        <Undefined></Undefined>
    </Array>

In the above example there is an array with three elements that have a name attribute (meaning they belong to the associative portion of the array) and two elements that do not have a name attribute, which means that they belong to the dense portion of the array.

As with other data types, arrays can be referenced; their elements can be referenced; even their elements’ names can be referenced:

    <Array>
        <String name="foo" name-refId="#0">bar</String>
        <String val-ref="#0"></String>
    </Array>

In this example, there is an array with two string elements. The first element has the name foo and the value bar. The second element has no name, but references the string with the string reference table ID #0 (the string foo).

Arrays themselves are registered in the object reference table.

Object

Objects are the most powerful data type within AMF3. There are several subtypes of classes that you need to be aware of. What all object types have in common is that they bear a class name.

Object Traits

The traits of an object are its member names, plus information indicating if an object is dynamic or externalizable.

An object with traits contains a list of member names followed by the corresponding members. In binary format, member names are encoded as strings without type markers. The number of member names is encoded in an additional field of flags that also contains information about the object’s sub type. Following the members, an optional, additional list of dynamic members, each preceded by their respective member name, is included. The list of dynamic members is only included if the dynamic flag is set to true and terminated by an empty string.

    <Object classname="testclass">
        <Member>strFirstName</Member>
        <Member>strSurname</Member>
        <String>John</String>
        <String>Doe</String>
    </Object>

    <Object classname="testclass2" dynamic="true">
        <Integer name="answer">42</Integer>
    </Object>

Object References

Objects can be directly referenced because they are registered in the objects reference table.

<Object classname="testclass3" dynamic="true" refId="#0">
    <Integer name="answer">42</Integer>
</Object>
<Object ref="#0"></Object>

Traits References

Each object of subtype object traits or externalizable traits is not only added to the objects reference table, but also to the traits reference table. Other objects can then refer to the traits of these objects. This means that such an object does not need to come with the list of members and the object flags by itself, but only with the actual members.

<Object classname="nameclass" traits-refId="name">
        <Member>userid</Member>
        <Member>firstName</Member>
        <Member>lastName</Member>
        <String>jdoe</String>
        <String>John</String>
        <String>Doe</String>
    </Object>
    <Object traits-ref="name">
        <String>mmustermann</String>
        <String>Max</String>
        <String>Mustermann</String>
    </Object>

Externalizable Traits

Externalizable traits contain the binary representation of an object, an indeterminate number of bytes serialized in an unknown format. The format depends on the class that serializes and deserializes this data. The class also has to know how many bytes it has to consume from the byte stream.

Silk Performer provides support for the three most common classes:

  • flex.messaging.io.ArrayCollection
  • flex.messaging.io.ArrayList
  • flex.messaging.io.ObjectProxy

According to Adobe, these three classes are the most common, and are encoded as AMF3. This means that these three classes are parsed like normal arrays or objects, respectively.

In case a class other than these three is found, it is assumed that all bytes up to the end of the stream belong to the externalizable traits. The content of such an unknown externalizable trait is stored as Base64-encoded data.

<Object classname="flex.messaging.io.ArrayCollection" externalizable="true">
<Array>
<Integer>1</Integer>
<Integer>2</Integer>
<Integer>3</Integer>
<Integer>4</Integer>
</Array>
</Object>

<Object classname="flex.messaging.io.ArrayList" externalizable="true">
<Array>
<String>hugo</String>
<String>hugo2</String>
</Array>
</Object>

<Object classname="flex.messaging.io.ObjectProxy" externalizable="true">
<Object classname="" dynamic="true">
<String name="ssnum">555-55-5555</String>
<String name="name">Tyler</String>
<Integer name="age">5</Integer>
</Object>
</Object>

    <Object classname="test" externalizable="true">SGVsbG8sIHdvcmxk</Object>

ByteArray

A ByteArray holds an array of bytes. In XML representation, binary data is encoded in Base64 format.

ByteArrays are registered in the object reference table.

<ByteArray>SGVsbG8sIHdvcmxk</ByteArray>

References

Three different reference tables are used. The following list offers an overview of which data types are registered in which reference table.

String Reference Table:

  • String
  • Class names (not an actual data type)
  • Member names (not an actual data type)
  • Value name of elements of the associative portion of an array (not an actual data type)

Object Reference Table:

  • Object
  • Date
  • Array
  • ByteArray
  • XML
  • XmlDocument

Traits Reference Table:

  • Object traits
  • Externalizable traits

Not registered in any reference table:

  • Undefined
  • Null
  • False
  • True
  • Integer
  • Double

Reference IDs are generated by the AMF3 parser. However in hand-written XML documents, you can use custom reference IDs:

<String val-refId="username">EMEA\johndoe</String>
<String val-ref="username"></String>
Note: Custom reference IDs are lost when an XML document is transformed from XML to AMF3 and back to XML because the AMF3 generator simply looks up the reference table position using the reference ID string and only encodes the position in the AMF3. When parsing such a generated AMF3 data stream, the parser no longer has the information about the custom reference IDs. It generates reference IDs that begin with # and a continuous number that directly reflects the position in the string reference table.
Parent topic: Understanding Flex/AMF3 Scripts


Customizing Flex/AMF3 Scripts

Flex/AMF3 scripts are best customized using TrueLog Explorer.

TrueLog Explorer presents the XML representation of binary AMF3 requests and response bodies in a tree view structure. The HTTP request body is presented in Request view. The HTTP response is presented in Response view. The textual representation of request bodies is shown in Out Header view. The textual representation of response bodies is shown in In Header view.

As with other XML based applications, verification and parsing functions can be inserted visually using TrueLog Explorer.

Parent topic: Flex/AMF3 Support


Web Applications Support

Silk Performer supports testing of all types of Web applications, both on the protocol level (HTTP) as well as on a browser-driven basis.

  • Web Application Communication Overview
    Offers an overview of synchronous and asynchronous Web application processing flow, including the three main asynchronous communication models. Also examines the implications of AJAX on automated load testing and the use of XPATH in identifying DOM elements.
  • Load Testing Web 2.0 Applications (Protocol-Level)
    Explains how to test today's modern Web applications on the protocol level (HTML/HTTP).
  • Load Testing Web 2.0 Applications (Browser-Driven)
    In addition to facilitating testing of today's modern Web applications on the protocol level (HTTP), Silk Performer enables you to use real Web browsers (Internet Explorer, Chrome, and Firefox) to generate load.
Parent topic: Load Testing Specific Application Types


Web Application Communication Overview

The topics in this section offer an overview of synchronous and asynchronous Web application processing flow, including the three main asynchronous communication models. They also examine the implications of AJAX on automated load testing and the use of XPATH in identifying DOM elements.

  1. Understanding Synchronous and Asynchronous Communication
    Explains that in traditional Web-based applications, a user input triggers a number of resource requests. Once the requests have been answered by the server, no further communication takes place until the user's next input.
  2. Asynchronous Communication Models
    Explains that there are three main types of asynchronous request and response sequences: push, poll, and long-poll.
  3. Testing Asynchronous Communication on the Protocol Level
    Explains testing of web applications that use asynchronous communication patterns such as polling, long-polling, and push.
  4. Testing WebSocket Connections
    The WebSocket protocol allows to establish a full-duplex (bidirectional) connection between client and server. This topic explains how to record WebSocket communication and how to script WebSocket BDL functions.
  5. HTTP/2 Support
    Describes what HTTP/2 is, its main characteristics and current limitations, as well as how Silk Performer supports HTTP/2.
  6. Testing AJAX Applications
    Explains that AJAX is a group of interrelated Web development techniques that are used on the client-side (browser) to create interactive Web applications.
Parent topic: Web Applications Support


Understanding Synchronous and Asynchronous Communication

In traditional Web-based applications, a user input triggers a number of resource requests. Once the requests have been answered by the server, no further communication takes place until the user's next input. Such communication between client and server is known as synchronous communication.

Here is an example of traditional synchronous communication passing between a browser and a Web server:

  1. The user clicks a UI control in a browser-based web application.
  2. The browser converts the user's action into one or more HTTP requests and passes them along to the Web-application server.
  3. The application server responds to the user's requests by returning the requested data to the user. At this point the application is updated and the synchronous communication loop is complete. A new synchronous communication loop will begin when the user next clicks a UI control in their browser.

Synchronous communication is limited due to the lapses in application updates that are presented to the user at regular intervals. Even if a synchronous application is designed so that it automatically refreshes information from the application server at regular intervals (for example, every 12 seconds), there will still be consistent periods of delay between data refreshes. For many applications, such update delays don't present an issue because the data they manage don't change often. Some application types however, for example stock-trading applications, rely on continuously updated information to provide optimum functionality and usability to their users.

Web 2.0 web-based applications address this issue by relying on asynchronous communication. Asynchronous applications deliver continuously updated application data to users. This is achieved by separating client requests from application updates. Multiple asynchronous communications between client and server may occur simultaneously or in parallel with one another.

While asynchronous communication delivers tremendous value to users, it presents a serious challenge to software-testing tool vendors who have difficulty emulating it with traditional test scripts.

Parent topic: Web Application Communication Overview
Next topic: Asynchronous Communication Models


Asynchronous Communication Models

There are three main types of asynchronous request and response sequences: push, poll, and long-poll. When building a test script for a web-based application, it is essential that you understand which type of asynchronous communication is in use.

Polling Communication Model

With this model of asynchronous communication, the client sends HTTP requests to the application server at a consistent rate, for example every 8 seconds. The server returns updates to the browser, thereby keeping the application updated with intermittent frequency.

Long-Polling Communication Model

With this model the browser sends an HTTP request to the application server. The server responds with an HTTP response whenever there is an update. The client generates an HTTP request to a known address on the server. Immediately following receipt of the server response, the browser sends out another HTTP request. It is the immediate response by the browser that differentiates this model from the standard polling communication model. The immediate response leads to longer wait time on the server side for a server response.

Push Communication Model

As with the polling and long-polling models, with the push model, communication begins with the browser sending an HTTP request to the application server. The response returned by the server however is kept open. This results in the browser keeping the connection to the server open. The server then sends a sub-message over the open connection whenever it has an update. With this model, communication between browser and server remains open indefinitely.

The server can close the connection at any time or keep it open even in the absence of new updates by sending ping messages that prevent the browser from closing the connection due to time-outs.

Parent topic: Web Application Communication Overview
Previous topic: Understanding Synchronous and Asynchronous Communication
Next topic: Testing Asynchronous Communication on the Protocol Level


Testing Asynchronous Communication on the Protocol Level

The asynchronous testing functionality for protocol-level record/replay is designed for Web applications that use asynchronous communication patterns such as polling, long-polling, and push. The characteristics of such applications is periodic, event-based, or server-triggered content updates without user interaction. Asynchronous web application testing on protocol-level is less resource intensive, but it is more challenging to script as opposed to the BDLT approach, which is resource intensive but automates the scripting process entirely during recording.

Recording Asynchronous Communication

Silk Performer offers a dedicated project type (Web (Async)) to facilitate recording of web applications that make use of asynchronous communication patterns. While recording a user transaction, the Silk Performer recorder creates a so-called Silk Performer capture file, which contains the entire traffic of the recorded session. After saving, the capture file is opened in the Workbench for further analysis and processing. Before generating a script from the captured traffic, you can configure recording rules and other settings, which are applied during the script generation process. Note that it is possible to generate several scripts (with different options) from the same capture file.

Asynchronous Web Functions

For each of the previously mentioned asynchronous communication patterns Silk Performer offers a web API function to create an asynchronous communication channel to the web server:

  • WebAsyncPreparePush
  • WebAsyncPreparePoll
  • WebAsyncPrepareLongPoll

Each WebAsyncPrepare... function call starts a dedicated asynchronous communication channel with the subsequent web function call.

The WebAsyncPrepare... functions take an optional BDL callback function as parameter. The callback function is called to notify the virtual user about certain events. For a detailed description of the events, refer to the BDL reference.

Asynchronous communication channels are active in parallel to normal virtual user activity, whereas callback functions are called by the web replay engine at many but specific occasions during script execution.

Synchronizing Callbacks with Virtual User Activity

Sometimes virtual user activity needs to be synchronized with callback function execution. A typical example is a situation where a virtual user needs to wait for information from the server, which is delivered via an asynchronous communication channel.

At the time where the information is required, the virtual user calls the function UserWaitFor. When the data arrives, the related callback function is called. This function retrieves and stores the awaited information. At this stage, the callback function signals an event to the virtual user by calling the function UserSignal. The virtual user can then safely access the information stored by the callback function.

Parent topic: Web Application Communication Overview
Previous topic: Asynchronous Communication Models
Next topic: Testing WebSocket Connections
Related concepts
Generating Scripts from Capture Files
Related reference
WebAsyncPreparePush Function
WebAsyncPreparePoll Function
WebAsyncPrepareLongPoll Function


Testing WebSocket Connections

The WebSocket protocol is a TCP-based network protocol that allows to establish a full-duplex (bidirectional) connection between client and server. A conventional HTTP connection follows the request-response principle: each client request triggers a server response.

To establish a WebSocket connection, the client sends a WebSocket upgrade request embedded in an HTTP message. Once acknowledged by the server, the open connection can be used for communication by both the server and the client at any time.

Using the WebSocket protocol results in reduced network traffic and latency. It is an alternative to communication models such as polling and long-polling that were used to simulate full-duplex connections.

You can either create a test script by manually scripting the respective functions, or you can use the Silk Performer Recorder to do the scripting for you. To learn about the WebSocket BDL functions, refer to the BDL Reference.

There are two functions you can use to establish a connection to a WebSocket server: Scripting WebSocketConnect establishes an asynchronous communication channel. Scripting WebSocketConnectSync establishes a synchronous communication channel.

Note: The Recorder will always follow the asynchronous scripting model by generating WebSocketConnect functions and associated callback function stubs.

The WebSocket protocol provides for sending and receiving both text and binary messages. Accordingly, Silk Performer offers WebSocketSendTextMessage and WebSocketSendBinaryMessage to support these message types.

Parent topic: Web Application Communication Overview
Previous topic: Testing Asynchronous Communication on the Protocol Level
Next topic: HTTP/2 Support
Related concepts
Asynchronous Communication Functions


HTTP/2 Support

General

HTTP/2 is a major revision of the hypertext transfer protocol (HTTP) used in the World Wide Web. The protocol was derived from an experimental protocol named SPDY, introduced by Google, before it was published as RFC 7540 in 2015.

When designing HTTP/2, the inventors put their focus on efficiency. For that reason, the protocol offers a series of improvements over HTTP/1.1:

  • HTTP/2 uses only one connection between client and server. This single connection supports multiple communication streams in parallel, which reduces the overhead for establishing multiple connections between client and server. In contrast: An HTTP/1.1 connection only allows simple request/response patterns.
  • HTTP/2 is a binary protocol. As such it is not readable as opposed to HTTP/1.x.
  • HTTP/2 uses a compression method that has been specifically designed for HTTP headers. This compression method takes into account that often very similar headers get sent over and over again.
  • HTTP/2 allows a server to push resources to the client without an explicit request from the client.

Configuring HTTP/2

The Silk Performer HTTP/2 support is disabled by default. You can enable and configure HTTP/2 in the Profile Settings: Click Settings > Active Profile > Web (Protocol Level).

Limitations

Currently, Silk Performer supports HTTP/2 for replay only. Scripts recorded using HTTP/1.1 will replay correctly with HTTP/2 unless the server returns specific content that depends on the HTTP version the client uses.

The Silk Performer Recorder does not allow a browser to use HTTP/2, thus HTTP 1.1 is used. In most cases, this does not affect the recorded traffic and content. If, however, the server returns different content depending on the HTTP version used for communication, the HTTP/2 content cannot be recorded.

  • Server Push Support
    Explains what HTTP/2 server push is and how Silk Performer supports server push.
  • HTTP/2 in TrueLog Explorer
    Describes what information TrueLog Explorer displays when an HTTP/2 connection is used.
  • Configuring HTTP/2
    Describes how to enable and disable HTTP/2 and how to enable the server push and fallback options.
Parent topic: Web Application Communication Overview
Previous topic: Testing WebSocket Connections
Next topic: Testing AJAX Applications


Server Push Support

HTTP/2 allows a server to push resources to the client rather than waiting for the client to parse the main HTML document and then request further resources one by one. Typically, HTTP/2 servers push files like style sheets and images to the client. Clients usually require these resources anyway to render a page.

You can enable and disable server push in the Profile Settings: Click Settings > Active Profile > Web (Protocol Level).

  • In TrueLog Explorer pushed resources are represented by nodes with (server push) appended. For these nodes the tabs Out Header and Out Body are disabled. If the resource is required in subsequent pages, cache hits are generated as usual.
  • If you request a page several times, the server will attempt to push the same resources several times. However, Silk Performer stores the pushed resources only once and notifies the server that additional pushes are not required. If the server has already started pushing resources before it receives the notification, the related traffic will not be measured by Silk Performer.
  • If Silk Performer detects a resource that has been pushed by the server but is actually not required during a WebPage* function call, a warning displays in the virtual user output and in TrueLog Explorer. Such a warning indicates a server misconfiguration, because the server pushes resources that are not required. This again produces unnecessary network traffic.

In some cases, the Silk Performer push support might differ from the behavior of real browsers. Browsers have different push cache implementations, because there is no official push cache specification.

Parent topic: HTTP/2 Support


HTTP/2 in TrueLog Explorer

In TrueLog Explorer, you can check the tabs In Header and Out Header to find out whether a request uses HTTP/2. If a request does use HTTP/2, the header tabs display so-called pseudo-headers such as :method, :scheme, :path, :authority, or :status. Note that TrueLog Explorer displays the decompressed version of the headers, because the compressed headers are not human-readable.

When examining the Statistics tab, you might notice some more differences:

  • HTTP/2 uses only one TCP connection to download all content from one host. Because of that, only the first request to a host should contain values for DNS, Connect and SSL Handshake. The following requests to the same host will reuse the existing connection.
  • When you investigate the waterfall diagram for an API node with many embedded resources, you might notice that in an HTTP/2 case the embedded resources can start downloading simultaneously without waiting for an idle TCP connection. While individual requests might take slightly longer, in total the page should be downloaded significantly faster with HTTP/2 compared to previous versions.
  • For HTTP/1.1 traffic, TrueLog Explorer displays the number of bytes transferred including SSL and connection overhead for each web node in the TrueLog tree. For HTTP/2 however, concurrent requests to one host share the same TCP connection, thus portions of multiple concurrent requests or responses might be contained in a single SSL frame. To be able to compare HTTP/1.x with HTTP/2 traffic, TrueLog Explorer displays similar statistics, even though the HTTP/1.1 metrics do not suit well to the new protocol version. In detail this means that TrueLog Explorer distributes the SSL overhead across the corresponding requests and responses. Traffic that does not correspond to a specific request/stream, such as HTTP/2 settings frames, is added to the statistics of the subsequent request/response pair. Some measures can seem small. This is caused by the HTTP/2 header compression feature. Especially when the previous request or response contained many similar headers, this can reduce the number of sent/received bytes for a typical request consisting of mainly headers significantly.
  • Due to the nature of HTTP/2, where one frame can contain portions of multiple streams, TrueLog Explorer cannot associate the compressed frame size with particular request/response pairs. Thus, the size of the uncompressed headers and bodies is displayed in the page drill-down view of the Statistics tab.
Parent topic: HTTP/2 Support


Configuring HTTP/2

HTTP/2 settings can be configured in the Profile Settings.
  1. In the menu, click Settings > Active Profile > Web (Protocol Level).
  2. HTTP/2 is disabled by default. To enable it, set the Preferred HTTP version to HTTP/2.
    Note: Make sure you select a Browser that supports HTTP/2. To find out which HTTP version a certain browser supports, click Details and read the Supported HTTP version. Most current browsers do support HTTP/2.
  3. Allow fallback to HTTP/1.1: You can allow a virtual user to continue with HTTP/1.1 in case the server under test does not support HTTP/2. If the fallback is allowed and actually applied during a test, an informational message will display for each affected server. If the fallback is not allowed, an error message will display.
  4. Allow server push: You can allow an HTTP/2 server to push resources to the client without an explicit request from the client. If server push is allowed but the server under test does not support the push feature, a warning will display.
You can also configure these settings in the BDL script using the WebSetOption Function. Note that the settings defined in the BDL script override the options defined in the profile settings.
Parent topic: HTTP/2 Support


Testing AJAX Applications

Note: Asynchronous testing functionality for protocol-level record/replay is made for Web applications that use few dedicated asynchronous communication channels. Asynchronous testing on the protocol level is less resource intensive, but it is more challenging to script. The browser-driven testing approach is resource intensive, but it automates the scripting process entirely during recording and is therefore often perceived as an easier way to test AJAX applications.

AJAX (Asynchronous JavaScript and XML) is a group of interrelated Web development techniques that are used on the client-side (browser) to create interactive Web applications. With AJAX, Web applications can retrieve data from the server asynchronously in the background without interfering with the display and behavior of the existing page. For data encoding, typically XML or JSON formats are used, although proprietary data encoding formats are also used.

In many cases, related pages on a Web site share a lot of common content. Using traditional methods, that content has to be reloaded upon each page request.

Using AJAX, a Web application can request only the select content that is needed to update the page, thereby dramatically reducing bandwidth usage and load time.

The use of asynchronous requests allows the client Web browser UI to be more interactive and to respond quickly to inputs. In many instances, sections of pages can also be reloaded individually. Users often perceive such applications as being faster and more responsive, even when application state on the server-side has not changed.

Web applications are typically based on AJAX frameworks, such as Ext JS and Ext GWT, though this is not a requirement.

  • AJAX Processing Flow
    Briefly examines how HTTP requests, HTML responses, JavaScript, and additional resources interact to produce Web 2.0 application interactivity.
  • Implications for Automation and Load Testing
    Explains that the major problem that automation and load-testing tools run into in testing Web 2.0 applications is synchronization.
  • Identifying DOM Elements in Browser-Driven Testing
    Explains how Silk Performer uses the concept of object identifiers, so-called locators, to identify one or more elements of the current DOM.
Parent topic: Web Application Communication Overview
Previous topic: HTTP/2 Support


AJAX Processing Flow

With Web 2.0 applications, the entire concept of pages becomes blurred. It is difficult to determine the time when a Web page has finished loading. The initial HTTP request is usually answered with some HTML response including additional resources that the browser loads in subsequent requests. When executing the JavaScript, additional requests may be transmitted via XMLHttpRequest calls. The responses to such asynchronous calls may be reflected by a change/adaption of the initial page.

Some pages are updated frequently without any user interaction. Other events that may trigger asynchronous calls are:

  • Mouse-overs
  • Key strokes
  • Drag and drop operations
  • Timers
  • Network events (on readystatechange)
Parent topic: Testing AJAX Applications


Implications for Automation and Load Testing

As the concept of pages is not applicable with most AJAX applications, it can be difficult to determine when to allow sequential Web page actions. The major problem that automation and testing tools run into is synchronization: Parts of a page may be visible but not yet functional. For example, you might click a button or link and nothing happens, or incorrect behavior occurs. This is usually not an issue for a human user because they can simply perform the action again. Being slower than automation tools, users are often not even aware of such problems.

With the browser-driven approach, Silk Performer uses a sophisticated technique for determining when a Web page is ready for a subsequent action. This AJAX mode synchronization waits for the browser to be in an idle state. This is especially useful for AJAX applications or pages that contain AJAX components. Using the AJAX mode eliminates the need for manual scripting of synchronization functions (for example, such as waiting for an object to appear/disappear, waiting for a specific property value), which dramatically eases the script development process. This automatic synchronization is also the basis for successful record and replay that does not require manual script customization.

Troubleshooting

Because of the true asynchronous nature of AJAX, generally there is no true browser idle state. Therefore, in some situations, it is possible that Silk Performer will not recognize the end of an invoked method call and will throw a timeout error after the specified timeout period.

Parent topic: Testing AJAX Applications


Identifying DOM Elements in Browser-Driven Testing

Within a browser, all visible and invisible elements of a Web page are represented as a hierarchical tree of objects, the Document Objects Model (DOM). To interact with elements of a Web page, Silk Performer uses the concept of object identifiers, so-called locators. Locators are XPath query strings that identify one or more elements of the current DOM. For additional information about XPath, see http://www.w3.org/TR/xpath20/.

All API calls that interact with DOM elements take a locator as an input parameter. For example, the API call BrowserLinkSelect(“//a[@href=’www.companyxyz.com’]”) uses the locator //a[@href=’www.companyxyz.com’] which identifies the first link that has www.companyxyz.com as the value of its href attribute (for example, <a href=”www.companyxyz.com”>My Link</a>).

The following table lists all XPath constructs that are supported by Silk Performer:

Supported XPath Construct | Sample | Description
Attribute | a[@href='myLink'] | Identifies all DOM Links with the given href attribute that are children of the current context. All DOM attributes are supported.
Index | a[1] | Identifies the first DOM link that is a child of the current context. Indices are 1-based in XPath.
Logical Operators: and, or, = | a[(@href='microfocus' or @caption != 'b') and @id='p'] |
. | .//div[@id='menuItem']/. | The" ." refers to the current context (similar to the well known notation in file systems. The example is equivalent to //div[@id='menuItem']/
.. | //input[@type='button']/../div | Refers to the parent of an object. For example, the sample identifies all divs that contain a button as a direct child.
/ | /form | Finds all forms that are direct children of the current object. ./form is equivalent to / form and form.
/ | /form/input | Identifies all input elements that are a child of a form element.
// | //input[type='checkbox'] | Identifies all check boxes in a hierarchy relative to the current object.
// | //div[id='someDiv'//input[type='button'] | Identifies all buttons that are a direct or indirect child of a div that is a direct or indirect child of the context.
/ | //div | Identifies all divisions that are direct or indirect children of the current context.

The following table lists the XPath constructs that Silk Performer does not support.

Unsupported XPath Construct | Example
Comparing two attributes to one another | a[@caption = @href]
Attribute names on the right side are not supported. Attribute names must be on the left side. | a['abc' = @caption]
Combining multiple XPath expressions with and or or. | a [@caption = 'abc'] or .//input
More than one set of attribute brackets | div[@class = 'abc'] [@id = '123'] (use div[@caption = 'abc' and @id = '123'] instead)
More than one set of index brackets | a[1][2]
Wildcards in tag names or attribute names | */@c?ption='abc'
Logical operators: not, != | a[@href!='someValue'], not[@href='someValue']
Any construct that does not explicitly specify a class or the class wildcard. For example, including a wildcard as part of a class name. | //[@caption = 'abc']

The following list shows wildcard examples that match //[@caption ='abc def']:

  • //[@caption ='*c def']
  • //[@caption ='??c def']
  • //[@caption ='ab? ?ef']
  • //[@caption ='ab*ef']
  • //[@caption ='abc?def']
  • //[@caption ='abc d??']
  • //[@caption ='abc d*']
  • //[@caption ='ab? *']
  • //[@caption ='?b? d*']
  • //[@caption ='*c d*']
Parent topic: Testing AJAX Applications


Load Testing Web 2.0 Applications (Protocol-Level)

  • Web Load Testing Overview
    Offers an overview of how Silk Performer is used to test Web applications.
  • Defining a Web Load Test Project
    A project contains all of the resources that are needed to complete a load test including a workload, test script, data files, and more.
  • Creating a Test Script
    Explains how to model Web load-test scripts and try out test scripts using Try Script runs.
  • Analyzing Test Scripts
    Explains the available options for analyzing the results of a Try Script run.
  • Customizing Test Scripts
    Shows how to customize input data and verify page content.
  • Configuring Monitoring
    Explains options for monitoring local and remote computers with Performance Explorer during tests.
  • Adjusting Workload
    Explains how to define the workload for load tests.
  • Running Load Tests
    Explains the tasks involved in running a load test.
  • Exploring Test Results
    Describes the methods available for displaying, reporting, and analyzing test results.
  • Silk Performer Web Context Management
    Explains the concepts that facilitate advanced context management (state information management in Silk Performer).
  • Manual Script Editing
    An effective means of customizing the behavior of virtual users is to manually edit the test scripts.
  • Customization of GZIP or ZLIB POST Data
    Describes how decompression of GZIP or ZLIB POST Data works during script recording.
  • Setting Up Individual IP Addresses
    Set up virtual users with individual IP addresses.
  • Web Forms
    Explains how Web forms are declared and used in a test script.
  • Cookies
    Explains how Silk Performer supports record and replay for cookies used in Web applications.
Parent topic: Web Applications Support


Web Load Testing Overview

The fastest and easiest approach to test today's modern Web applications is to test them on the protocol level (HTML/HTTP). This approach generates simple scripts that incorporate advanced functionality. When testing a Web application with built-in AJAX logic and testing on the protocol level has proved to be unsuccessful we recommend using browser-driven Web load testing.

In addition to facilitating testing of today's modern Web applications on the protocol level (HTTP), Silk Performer now enables you to use real Web browsers (Internet Explorer, Firefox, and Chrome) to generate load. In this way, you can leverage the AJAX logic built into Web applications to precisely simulate complex AJAX behavior during testing. This powerful testing approach provides results that reflect real-world end user browsing experience, including rendering time and protocol-level statistics.

  • Sample Web 2.0 Application
    Explains that Silk Performer offers a modern sample Web application that you can use to learn about Web 2.0 application testing.
Parent topic: Load Testing Web 2.0 Applications (Protocol-Level)
Related concepts
Browser-Driven Load Testing Overview


Defining a Web Load Test Project

  1. Click Start here on the Silk Performer workflow bar.
    Note: If another project is already open, choose File > New Project from the menu bar and confirm that you want to close your currently open project.
    The Workflow - Outline Project dialog box opens.
  2. In the Name text box, enter a name for your project.
  3. Enter an optional project description in Description.
  4. From the Type menu tree, select Web business transaction (HTML/HTTP).
  5. Click Next to create a project based on your settings.
The Workflow - Model Script dialog box appears.
Parent topic: Load Testing Web 2.0 Applications (Protocol-Level)
Related concepts
Outlining Projects
Related tasks
Recording a Test Script


Creating a Test Script

The easiest approach to creating a test script is to use the Silk Performer Recorder, the Silk Performer engine for capturing and recording Web traffic and generating test scripts based on the captured traffic.

  • Recording a Test Script
    Create a test script with the Silk Performer Recorder, Silk Performer's engine for capturing and recording traffic and generating test scripts.
  • Try Script Runs
    Explains that a Try Script run determines if a script accurately recreates the actions that you recorded during script modeling.
  • Trying Out Your Test Script
    Once you have generated a test script, determine if the script runs without error by performing a Try Script run.
Parent topic: Load Testing Web 2.0 Applications (Protocol-Level)
Related concepts
Modeling Scripts


Recording a Test Script

  1. Click Model Script on the workflow bar. The Workflow - Model Script dialog box appears.
  2. Select one of the listed browsers from the Recording Profile list, depending on the browser you want to use for recording.
  3. In the URL field, enter the URL that is to be recorded.
    Note: The InsuranceWeb sample Web 2.0 application is available at http://demo.borland.com/InsuranceWebExtJS/. In the Select a Service or login list, the Auto Quote and Agent Lookup services are available for testing while the other listed services do not provide any functionality.
  4. Click Start recording. The Silk Performer Recorder dialog opens in minimized form, and the client application starts.
  5. To see a report of the actions that happen during recording, maximize the Recorder dialog by clicking the Change GUI size button. The maximized Recorder opens at the Actions page.
  6. Using the client application, conduct the kind of interaction with the target server that you want to simulate in your test. The interaction is captured and recorded by the Recorder. A report of your actions and of the data downloaded appears on the Actions page.
  7. To end recording, click the Stop Recording button.
  8. Enter a name for the .bdf file and save it. The Capture File page displays. Click Generate Script to generate a script out of the capture file.
Parent topic: Creating a Test Script


Try Script Runs

Once you have generated a test script, determine if the script runs without error by executing a Try Script run. A Try Script run determines if a script accurately recreates the actions that you recorded with the Recorder. It also determines if the script contains any context-specific session information that you must parameterize before the script can run error free.

With Try Script runs, only a single virtual user is run and the stress test option is enabled so that there is no think time or delay between the scripted actions.

Parent topic: Creating a Test Script


Trying Out Your Test Script

  1. Click the Try Script button on the Silk Performer Workflow bar. The Workflow – Try Script dialog appears.
  2. Choose a script from the Script list box.
  3. In the Profile list box, the currently active profile is selected (this is the default profile if you have not configured an alternate profile).
    1. To configure simulation settings for the selected profile, click Settings to the right of the list box.
    2. To configure project attributes, select the Project Attributes link.
  4. In the Usergroup list of user groups and virtual users, select the user group from which you want to run a virtual user. Since this is a Try Script run, only one virtual user will be run.
  5. To view the actual data that is downloaded from the Web server during the Try Script in real-time, select the Animated Run with TrueLog Explorer check box. If you are testing anything other than a Web application, you should disable this option.
  6. Click Run. The Try Script begins.
All recorded think times are ignored during Try Script runs. The Monitor window opens, giving you detailed information about the progress of the Try Script run. If you have selected the Animated option, TrueLog Explorer opens. Here you can view the actual data that is downloaded during the Try Script run. If any errors occur during the Try Script run, TrueLog Explorer can help you to find the errors quickly and to customize session information. Once you have finished examining and customizing your script with TrueLog Explorer, your script should run without error.
Parent topic: Creating a Test Script


Analyzing Test Scripts

Silk Performer offers several means of evaluating a test script following the execution of a Try Script run.

  • Visual Analysis with TrueLog Explorer
    Examines the TrueLog Explorer interface and its various components.
  • Viewing a Virtual User Summary Report
    Explains how virtual user summary reports summarize Try Script runs with basic descriptions and timing averages.
  • Finding Errors in a TrueLog
    TrueLog Explorer helps you find errors quickly after Try Script runs. Erroneous requests can then be examined and necessary customizations can be made.
  • Viewing Page Statistics
    Explains how to analyze the performance of the application under "no-load" conditions.
  • Comparing Record and Replay TrueLogs
    You can identify errors in a recorded script by comparing a replay TrueLog with a corresponding recorded TrueLog.
Parent topic: Load Testing Web 2.0 Applications (Protocol-Level)


Visual Analysis with TrueLog Explorer

One of TrueLog Explorer’s most powerful features is its ability to visually render Web content that is displayed by applications under test. In effect, it shows you what virtual users see when they interact with an application.

The TrueLog Explorer interface is comprised of the following sections:

  • The Workflow Bar acts as your primary interface as you work with TrueLog Explorer. The Workflow Bar reflects TrueLog Explorer’s built-in testing methodology by supporting its five primary tasks.
  • The API Node Tree menu on the left of the interface allows you to expand and collapse TrueLog data downloaded during tests. Each loaded TrueLog file is displayed here along with links to all relevant API nodes. You can click a node to display a screen shot in the Screen pane and history details in Information view.
  • The Content pane provides multiple views of all received data.
  • The Information pane displays data regarding testing scripts and test runs, including general information about the loaded TrueLog file, the selected API node, BDL script, and statistics.
Note: To launch TrueLog Explorer from Silk Performer, choose Results > Explore TrueLog.

  • Analyzing a Test Run
    Explains how to get started using TrueLog Explorer to analyze a test run.
Parent topic: Analyzing Test Scripts
Related concepts
Tour of the UI


Analyzing a Test Run

  1. With the TrueLog from a Try Script run loaded into TrueLog Explorer, click the Analyze Test button on the Workflow bar. The Analyze Test dialog box displays.
  2. Proceed with one of the following options:
    • View a virtual user summary report
    • Look for errors in the TrueLog
    • Compare the replay test run to the recorded test run
Parent topic: Visual Analysis with TrueLog Explorer


Viewing a Virtual User Summary Report

Virtual user summary reports are summary reports of individual Try Script runs that offer basic descriptions and timing averages. Each report tracks a single virtual user. Data is presented in tabular format.
Note: Because virtual user summary reports require significant processing, they are not generated by default.

To enable the automatic display of virtual user reports at the end of animated Try Script runs, or when clicking the root node of a TrueLog file in the menu tree, check the Display virtual user report check box at Settings > Options > Workspace > Reports .

Virtual user summary reports include details related to:
  • Virtual users
  • Uncovered errors
  • Response time information tracked for each transaction defined in a test script
  • Page timer measurements for each downloaded Web page
  • Measurements related to each Web form declared in a test script, including response time measurements and throughput rates for form submissions using POST, GET, and HEAD methods.
  • Individual timers and counters used in scripts (Measure functions)
  • Information covering IIOP, Web forms, TUXEDO, SAP, and others
Parent topic: Analyzing Test Scripts


Finding Errors in a TrueLog

TrueLog Explorer helps you find errors quickly after Try Script runs. Erroneous requests can then be examined and necessary customizations can be made.

Note: When viewed in the menu tree, API nodes that contain replay errors are tagged with red “X” marks.
  1. Open the TrueLog you want to analyze or modify.
  2. Click Analyze Test on the workflow bar. The Workflow - Analyze Test dialog box opens.
  3. Click the Find errors link. The Step through TrueLog dialog box appears with the Errors option selected.
  4. Click Find Next to step through TrueLog result files one error at a time. You can select different increments by which to advance through the TrueLog to visually verify that the script worked as intended (Whole pages, HTML documents, Form submissions, or API calls).
Parent topic: Analyzing Test Scripts


Viewing Page Statistics

After verifying the accuracy of a test run, TrueLog Explorer can analyze the performance of the application under “no-load” conditions via the Statistics tab under the Information pane. The Overview page details total page response times, document download times (including server busy times), and time elapsed for receipt of embedded objects.

Detailed Web page statistics show exact response times for individual Web page components. These detailed statistics assist you in pinpointing the root causes of errors and slow page downloads.

Detailed Web page drill-down results include the following data for each page component:
Time | Description
DNS | The time to translate a host name into an IP address.
Connect | The time to establish a connection to a server.
SSL Handshake | The time to establish a secure layer on an existing connection. The client and server exchange certificates and agree on an encryption technology including related keys to secure data transmission.
Send | The time to hand over the request data from Silk Performer to the operating system. This value does not include the time required to send the request data from the operating system to the server.
Server busy | The time to send the request data from the operating system to the server, the time to calculate the response data on the server, and the time to send the first byte of the response data from the server to the client (including network latency).
Receive | The time to receive the entire response data.
Cache statistics |
  • Viewing an Overview Page
    After verifying the accuracy of a test run, you can analyze the performance of your application via Web page statistics on an overview page.
Parent topic: Analyzing Test Scripts


Viewing an Overview Page

  1. From the API Node Tree menu, select the API node for which you would like to view statistics.
  2. Click the Statistics tab to open Statistics view.
  3. Select specific components listed in the URL column for detailed analysis and page drill-down.
Parent topic: Viewing Page Statistics


Comparing Record and Replay TrueLogs

By comparing a TrueLog that has been generated during the script development process alongside the corresponding TrueLog was recorded originally, you can verify that the test script runs accurately.

  1. Click the Analyze Test button on the Workflow Bar. The Workflow - Analyze Test dialog box appears.
  2. Click Compare your test run.
  3. The corresponding recorded TrueLog opens in Compare view and the Step through TrueLog dialog box appears with the Browser Nodes option selected, allowing you to run a node-by-node comparison of the TrueLogs.
  4. Click the Find Next button to step through TrueLog result files one page at a time.
    Note: Windows displaying content presented during replay have green triangles in their upper left corners. Windows displaying content originally displayed during application recording have red triangles in their upper left corners.
  • Synchronizing Record and Replay TrueLogs
    In compare mode you can synchronize corresponding API nodes between replay and record TrueLogs to identify differences between recorded values and replayed values.
Parent topic: Analyzing Test Scripts


Synchronizing Record and Replay TrueLogs

In compare mode you can synchronize corresponding API nodes between replay and record TrueLogs to identify differences between recorded values and replayed values.

Note: This feature is disabled when automatic synchronization of TrueLogs is enabled.
  1. Enable compare mode by doing one of the following:
    • Choose View > Compare Mode .
    • Click the Compare Mode button on the toolbar.
  2. Open a set of corresponding record and replay TrueLogs.
  3. Right-click an API node and choose Synchronize TrueLogs. TrueLog Explorer locates the API node in the matching TrueLog that best correlates with the selected API node.
Parent topic: Comparing Record and Replay TrueLogs


Customizing Test Scripts

Once you have generated a test script with Silk Performer and executed a Try Script run, TrueLog Explorer can help you customize the script in the following ways, among other options:
  • Parameterize input data – With user-data customization, you can make your test scripts more realistic by replacing static, recorded, user-input data with dynamic, parameterized user data that varies with each transaction. Manual scripting is not required to run such data-driven tests. This feature is available for Web, database, XML, Citrix, SAPGUI, terminal emulation, and Oracle Forms applications.
  • Add verifications to test scripts – With the Add Verifications tool, you can gain insight into data that is downloaded during tests, enabling you to verify that content sent by servers is received by clients. Verifications remain useful after system deployment for ongoing performance management. This feature is available for Web, database, XML, SAPGUI, Citrix, terminal emulation, and Oracle Forms applications. TrueLog Explorer supports bitmap and window verification for applications that are hosted by Citrix servers.
  • User-Input Data Customization
    Explains how user-input data customization allows you to make test scripts more realistic by replacing recorded input data with parameterized data.
  • Verifications
    Application errors are often overseen without additional checks, because they do not cause erroneous HTTP responses.
  • Parsing Functions
    Outlines how to parse content returned from a Web server and check if the values meet your testing criteria.
  • Session Handling
    Explains how unique session IDs can be customized in a test script.
  • User Profiles
    Describes how browser types and bandwidths define virtual user profiles.
Parent topic: Load Testing Web 2.0 Applications (Protocol-Level)
Related concepts
Customizing Scripts


User-Input Data Customization

Without user-input data customization, all simulated transactions are identical and do not account for the variables that are typically experienced in real world environments.

For example, you can customize the user-input data that is entered into forms during testing using the Parameter Wizard. The Parameter Wizard lets you specify the values that are to be entered into form fields during testing. This enables test scripts to be more realistic by replacing recorded user-input data with randomized, parameterized user data.

  • Customizing HTML User Data With a New Parameter
    Explains the process of creating a parameter based on a random variable.
  • AJAX and Script Customization
    Explains how Silk Performer can record and replay Web applications that utilize AJAX (Asynchronous JavaScript and XML) requests.
Parent topic: Customizing Test Scripts


Customizing HTML User Data With a New Parameter

Before proceeding, ensure that all static session information has been removed from your test script and that the most recent Try Script run produced a TrueLog that is open in TrueLog Explorer.

With HTML-based applications, the goal of user-data customization is to customize values submitted to form fields.

This task explains the process of creating a parameter based on a random variable.

  1. Click Customize User Data on the workflow bar. The Workflow - Customize User Data dialog box opens.
  2. Click the Customize user input data in HTML forms link. TrueLog Explorer then performs the following actions:
    • Selects the first WebPageSubmit API call node in the menu tree.
    • Opens the Step through TrueLog dialog box (with the Form submissions option button selected).
    • Displays Request view

      Request view shows the page that contains the HTML form that was submitted by the selected WebPageSubmit call. When your cursor passes over a form control, a tool tip shows the control’s name in addition to its initial and submitted values; an orange line indicates the corresponding BDL form field declaration in Form Data view below.

  3. Click Find Next or Find Previous on the Step through TrueLog dialog box to browse through all WebPageSubmit calls in the TrueLog (these are the calls that are candidates for user-data customization).
    Note: Highlighted HTML controls in Request view identify form fields that can be customized.
  4. On the Request page, right-click the form control that you want to customize and choose Customize Value. You can replace the recorded values with various types of input data (including predefined values from files and generic random values) and generate code into your test script that substitutes recorded input data with your customizations. The Parameter Wizard opens.
    With the Parameter Wizard you can modify script values in two ways:
    • Use an existing parameter that is defined in the dclparam or dclrand sections of your script.
    • Create a new parameter based on a new constant value, random variable, or values in a multi-column data file.

    After you create a new parameter, that parameter is added to the existing parameters and is available for further customizations.

  5. Click the Create new parameter option button and then click Next to create a new parameter. The Create New Parameter page opens.
  6. Click the Parameter from Random Variable option button and then click Next. The Random Variable page opens.
  7. From the list box, select the type of random variable that you want to insert into your test script and then click Next. A brief description of the selected variable type appears in the lower window. The Name the variable and specify its attributes page opens.
  8. Enter a name for the variable in the Name text box.
  9. Specify whether the values should be called in Random or Sequential order. The Strings from file random variable type generates data strings that can either be selected randomly or sequentially from a specified file.
  10. In the File group box, select a preconfigured data source from the Name list box and then click Next. The Choose the kind of usage page displays.
  11. Specify the new random value to use by selecting one of the following choices:
    • Per usage
    • Per transaction
    • Per test
  12. Click Finish. Your test script now uses the random variable for the given form field in place of the recorded value. The new random variable function appears on the BDL page.

Initiate a Try Script run with the random variable function in your test script to confirm that the script runs without error.

Parent topic: User-Input Data Customization


AJAX and Script Customization

The Silk Performer Recorder can record and replay Web applications that utilize AJAX (Asynchronous JavaScript and XML) requests. This is possible because Silk Performer recognizes asynchronous AJAX requests and responses that arrive in the form of either XML or JSON within HTML responses. Silk Performer scripts AJAX requests that it encounters as WebPageUrl calls.

Silk Performer and TrueLog Explorer support access to values within AJAX requests. This enables script customizations such as input-data parameterization, verification, parsing, and session-information customization within AJAX responses.
Tip: The InsuranceWeb demo application, available at http://demo.borland.com/InsuranceWebExtJS/, offers the functionality to switch between JSON and XML serialization methods for testing purposes. From the Select a Service or login list, select Agent Lookup for JSON or Agent Lookup (XML) for XML.

Pretty-Format JSON and XML Data

JSON and XML are data-structure formats commonly used in AJAX applications, REST techniques, and other environments. Silk Performer supports pretty-formatted viewing of XML and JSON-formatted byte streams in BDF scripts. Enhanced rendering of JSON formatted data enables easier customization of string values via TrueLog Explorer’s string customization functions.

When JSON-formatted data is recorded or inserted into a BDF script, Silk Performer displays the raw JSON byte stream. Once displayed in JSON format, XML can easily be customized using Silk Performer’s Parameter Wizard.

Silk Performer offers the option of viewing JSON data in either pretty-formatted JSON-rendering view or as a raw JSON byte stream.

Understanding JSON

According to JSON.org (www.json.org), "JSON (JavaScript Object Notation) is a lightweight data-interchange format. It is easy for humans to read and write. It is easy for machines to parse and generate. It is based on a subset of the JavaScript Programming Language...” “JSON is a text format that is completely language independent but uses conventions that are familiar to programmers of the C-family of languages, including C, C++, C#, Java, JavaScript, Perl, Python, and many others. These properties make JSON an ideal data-interchange language."

  • Enabling Pretty-Formatted JSON and XML Viewing in TrueLog Explorer
    Enable pretty-formatted JSON and XML viewing on the Rendered page if TrueLog Explorer is unable to detect JSON or XML data.
  • Enabling Pretty-Formatted JSON and XML Viewing in Silk Performer
    You can specify if Silk Performer should render AJAX data strings in enhanced JSON format or as raw XML.
Parent topic: User-Input Data Customization


Enabling Pretty-Formatted JSON and XML Viewing in TrueLog Explorer

Enable pretty-formatted JSON and XML viewing on the Response page if TrueLog Explorer is unable to detect JSON or XML data. If TrueLog Explorer detects JSON and XML data, it is automatically pretty-formatted on the Response page.

  1. Select a node on the TrueLog menu tree that includes JSON- or XML-formatted data (for example, a HTTP Post command node).
  2. Click the Response tab.
  3. Right-click JSON or XML data and choose Render As > JSON or Render As > XML to pretty-format the data.
Parent topic: AJAX and Script Customization
Parent topic: Working With AJAX-Enhanced Web Applications
Related tasks
Enabling Pretty-Formatted JSON and XML Viewing in Silk Performer


Enabling Pretty-Formatted JSON and XML Viewing in Silk Performer

  1. Within a BDL script that includes JSON- or XML-formatted data, right-click within the screen data that you want to view.
  2. Select your preferred viewing format from the context menu.
    • Select Format As > JSON to format the data in enhanced JSON format.
    • Select Format As > XML to format the data as raw XML.
    You can also select Format As > Auto Format from the context menu to have Silk Performer determine the best formatting option for screen data types. By default, JSON and XML data is pretty-formatted in BDF scripts.
  3. Right-click formatted data strings to access Silk Performer’s standard string customization commands.
    Note: Because formatted JSON data is integrated into the Silk Performer code editor, JSON-formatting can be undone/redone using the Undo/Redo buttons on the toolbar.
    Note: Pretty-formatted JSON and XML data viewing is also available in TrueLog Explorer.
Parent topic: AJAX and Script Customization
Related tasks
Enabling Pretty-Formatted JSON and XML Viewing in TrueLog Explorer


Verifications

Often application errors do not cause erroneous HTTP responses. Instead, the application responds with incorrect data values or with error messages incorporated in the HTML content, such as A Servlet Exception occurred... or Server Too Busy.... A simple check of the HTTP status code will not uncover this class of errors. Therefore, application errors are often overseen if you do not build additional checks into your test script. Verification functions help you to check for application errors that are not simple, standard HTTP errors.

With verification built into your test scripts, your test evolves from being a simple load test to a becoming a combined load and functionality test. You can use these scripts without major performance penalties, even during large load test scenarios. They will, therefore, be able to detect a new class of application errors—errors which only occur under load, but which would be overlooked by a simple load test script without additional verification checks.

Silk Performer offers three means of enhancing your test scripts with verification functionality:

  • Automatically let the Recorder generate verification functions during the recording session.
  • Directly enhance the script by coding verification functions manually.
  • Apply verifications visually via TrueLog Explorer without the need to write a single line of BDL code. TrueLog Explorer will automatically generate verification functions into your script.
    Tip: Refer to TrueLog Explorer Help for detailed information.
  • Automatically Generating Verifications During Recording
    Generate HTML page title verifications and response data digest verifications automatically during recording sessions.
  • Title Verification
    Title verification offers a simple, automatic means of checking to see if applications return correct Web pages.
  • Digest Verification
    Digest verification is useful for verifying the content of relatively static HTML pages.
  • Enabling Verification Checks During Replay
    Enable or disable verification checks during replay via Silk Performer profile settings.
  • Inserting Content-Verification Functions
    Verification functions enable you to verify that content that is received by a client is identical to what was sent by the server under no-load conditions.
Parent topic: Customizing Test Scripts
Related concepts
Adding Verifications
Related tasks
Storing Output Values in Variables


Automatically Generating Verifications During Recording

To enable the automatic generation of verifications during Silk Performer script recording:

  1. Within Silk Performer, choose Settings > Active Profile . The Profile - [<profile name>] - Simulation dialog appears.
  2. Select Record > Web in the shortcut list, then click the Verification tab.
  3. In the Recording section, check the Record title verification and Record digest verification check boxes.
  4. Click OK.
Parent topic: Verifications
Parent topic: Verification Checks


Title Verification

Title verification offers a simple, automatic means of checking to see if applications return correct Web pages. When retrieving HTML documents, the Recorder can automatically generate title verification functions for each page-level Web API call or low-level Web API call.

Note: Title verification does not work when HTML page titles (contents of the <TITLE HTML> tags) are not set, or when they share common names.

Title Verification

transaction TMain
begin
  ...
  WebVerifyHtmlTitle("ShopIt - Greetings", WEB_FLAG_IGNORE_WHITE_SPACE |
    WEB_FLAG_EQUAL | WEB_FLAG_CASE_SENSITIVE, 1,
    SEVERITY_ERROR, bVerifyTitleSuccess1);
  WebPageUrl("http://myHost/shopit");
Parent topic: Verifications
Related tasks
Generating a Title-Verification Function
Related reference
WebVerifyHtmlTitle Function


Digest Verification

Digest verification is useful for verifying the content of relatively static HTML pages. Digest verification is not useful for HTML pages that are dynamic or contain session information in hyperlinks, embedded objects, or hidden form fields—and therefore change with each call.

The function calls WebVerifyDataDigest and WebVerifyHtmlDigest check to see if data that Silk Performer receives during replay differs from the data the Recorder captured during corresponding record sessions. With these function calls, Silk Performer generates digests that contain information about the occurrence of all characters and compares those results with digests generated by the Recorder. This function enables you to see if Silk Performer captures the same data during replay that it captured during recording. The Recorder automatically generates a digest verification function for each page-level Web API call and low-level Web API call that retrieves a document with a content type specified for digest verification (the default content type is text/html).

Digest Verification

const
  gsVerDigest_ShopIt_Greetings := "\h014200000B..."
                                  "\h016000500A..."
                                  "\h030001000A..."
                                  "\h0900410020...";

transaction TMain
begin
  ...
  WebVerifyDataDigest(gsVerDigest_ShopIt_Greetings, 162);
  WebPageUrl("http://myHost/shopit", "ShopIt - Greetings");
  ...
end TMain;
Parent topic: Verifications
Related tasks
Generating an HTML Digest Verification Function
Generating an HTML Data-Digest Verification Function
Related reference
WebVerifyDataDigest Function
WebVerifyHtmlDigest Function


Enabling Verification Checks During Replay

See verification settings options for a list of possible verification checks that you can enable or disable during script replay.

Tip: Profile settings in scripts can be overridden using the WebSetOption BDL function.
  1. Within Silk Performer, choose Settings > Active Profile . The Profile - [<profile name>] - Simulation dialog appears.
  2. Select Replay > Web in the shortcut list, then click the Verification tab.
  3. In the HTML / XML and Data areas, check which verification checks you want to enable during replay.
Parent topic: Verifications
Parent topic: Verification Checks
Related reference
WebSetOption Function


Inserting Content-Verification Functions

  1. Open the TrueLog you want to analyze or modify.
  2. Select a TrueLog API node that includes content that you want to have verified (for example, text or an image).
  3. Select the content that is to be verified on the Source page.
    Note: This step is not required for page-title and page-digest verification functions.
  4. Click Add Verifications on the workflow bar. The Workflow - Add Verifications dialog box opens.
  5. Select a pre-enabled verification:
    • Verify the page title
    • Verify the selected text
    • Verify the selected text in an HTML table
    • Verify the digest
  6. Complete the following dialog box. Specify how verification functions should be inserted into the BDL script.
    Note: Left and right boundaries are automatically identified for you.
  7. Repeat the process for each verification you want to add to the BDL script.
  8. Click Yes on the Workflow - Add Verifications dialog box. A Try Script run is initiated.
  9. Confirm that verifications have passed successfully. API nodes that include verifications are indicated with blue “V” symbols.

Inserting content verification function

Parent topic: Verifications


Parsing Functions

Similar to the verification functions, parsing functions are used to parse content returned from a Web server and check if the values meet your testing criteria. Different from the verification functions, which basically check the occurrence of a specified input value, the parsing functions parse the content of a server response and return the parsed value in a BDL variable. Typically, you will use parsing functions for the following tasks:

  • Parse session IDs and replace static session IDs in the script with parsed, dynamic session IDs to maintain state information in Web applications. This is one of the main fields of application of parsing functions.
  • Build enhanced verifications into your script with parsing functions, which cannot be done with verification functions. For example, if you want to verify that the value of column 2 of row 3 in an HTML table is equal to the sum of the values of column 2 of row 1 and column 2 of row 2. By using parsing functions to parse out the three values and compare them in our script, you can build this enhanced verification check.
  • Conditional execution of parts of your testing script which depends on the data returned from the server. For example, an HTTP request returns an HTML page which includes: Results: <nnn> items found. You want to execute different actions depending on the value of <nnn>. Let's say you want to exit the transaction if <nnn> = 0, and you want to go to link Details if <nnn> = 1, and you want to go to link Next if <nnn> is greater than 0. To accomplish this, you need to parse the value of <nnn> from the HTML page and script the actions, depending on the value you have parsed out.

Silk Performer offers two means to enhancing your test scripts with parsing functionality:

  • Directly enhance your script by coding verification functions manually.
  • Apply parsing functions visually in TrueLog Explorer without the need to write a single line of BDL code. TrueLog Explorer will automatically generate parsing functions in your script.
    Tip: Refer to TrueLog Explorer Help for detailed information.
  • HTML Content Parsing
    HTML content parsing functions parse out portions of the rendered, visible HTML content.
  • Response Data Parsing
    Data parsing functions parse out portions of the response data returned from the server.
Parent topic: Customizing Test Scripts


HTML Content Parsing

HTML content parsing functions parse out portions of the rendered, visible HTML content. The HTML content verification and parsing functions allow you to verify and/or parse the textual content that you see in your browser. Apply HTML content parsing functions in the HTML view of TrueLog Explorer, which includes the following functions:

  • WebParseHtmlBound
  • WebParseHtmlTitle
  • WebParseTable
  • WebParseResponseTag
  • WebParseResponseTagContent
Parent topic: Parsing Functions
Related concepts
HTML Verification Functions
Related reference
WebParseHtmlBound Function
WebParseHtmlTitle Function
WebParseTable Function
WebParseResponseTag Function
WebParseResponseTagContent Function


Response Data Parsing

Data parsing functions parse out portions of the response data returned from the server. In cases in which an HTML document is returned from the server, the complete source code of the HTML document is parsed. Apply data verification functions in the source view of TrueLog Explorer, which includes the following functions:

  • WebParseDataBound (this function replaces the deprecated WebParseResponseData function)
  • WebParseResponseHeader
Parent topic: Parsing Functions
Related concepts
Response-Data Verification Functions
Related reference
WebParseDataBound Function
WebParseResponseHeader Function


Session Handling

Web applications often use a unique Web session ID so that the Web server is able to handle further client requests.

Refer to TrueLog Explorer Help for detailed information.

  • Customized Session Handling
    Explains how session IDs work and how to handle them in Silk Performer.
  • When to Use Customized Session Handling
    If a WebPageUrl call in your script uses a URL that contains a session ID as part of the query string of the URL, you need to customize session handling.
  • Customizing Session Handling
    Outlines the basic steps required in customizing session handling.
Parent topic: Customizing Test Scripts


Customized Session Handling

Web server applications often generate information at runtime that is necessary in order to identify further client requests. In the response to the browser, the server may include a unique string, commonly known as the Session ID. This string is returned by the browser to the server as a part of each subsequent request, allowing the server to identify the unique Web session of which the request is a part. Generally, Session IDs refer to the method the Web server application uses to identify individual users and to associate this identification with the state of the user session information that the application has previously had with those users.

Session IDs can be sent to the client in a number of ways. Most often you will find them included in cookies, or inside HTML as part of URL's used in hyper links or embedded objects, or in hidden HTML form fields. Session IDs are sent back to the server in cookies, URL's, and HTTP post data.

Session Information Inside Cookies

From the server:

Set-Cookie: SessionID=LGIJALLCGEBMIBIMFKOEJIMM; path=/

To the server:

Cookie: SessionID=LGIJALLCGEBMIBIMFKOEJIMM

Session Information in the URL's of HTML Links

From the server:

<html>
  ...
  <a href="/ShopIt/acknowledge.asp?SessionID=LGIJALLCGEBMIBIMFKOEJIMM" >
  Enter Shop
  </a>
 ...
</html>

To the server:

GET /ShopIt/acknowledge.asp? SessionID = LGIJALLCGEBMIBIMFKOEJIMM HTTP/1.1

Session Information in Hidden Form Fields

From the server:

<html>
  ...
  <form action="kindofpayment.asp" method="post" >
  Currently we only accept Credit Cards
  <input type="hidden" name="SessionID" value="LGIJALLCGEBMIBIMFKOEJIMM">
  <input type="text" name="name" value="Jack " >
  <input type="submit" name="paymentButton" value="Submit">
  </form>
  ...
</html>

To the server:

POST /ShopIt/kindofpayment.asp HTTP/1.1
...
SessionId=LGIJALLCGEBMIBIMFKOEJIMM&name=Jack&paymentButton=Submit
Parent topic: Session Handling


When to Use Customized Session Handling

Assuming that a WebPageUrl call in your script uses a URL that contains a session ID as part of the query string of the URL. When replaying the script, this hard coded static session ID is sent to the server. Because the session ID does not correctly identify your replayed session—it still identifies the recording session—the replay won’t work correctly. By not replacing static session IDs in your script with dynamic values that had been generated at runtime, your Web application will usually generate errors such as We are sorry, your session has expired. Please return to the login screen and try again.

The good news is that with Silk Performer, session customization is not often necessary and, even if manual session customization is needed, Silk Performer's TrueLog Explorer will guide you through the process.

Most often when you record a script, it will work without any modifications necessary for the customization of session handling. Silk Performer therefore uses multiple, highly sophisticated methods that prevent the user from manually handling hard coded session IDs:

  • Cookie Management: When your server uses cookies to exchange session information, Silk Performer will automatically handle dynamic session ID values. Because Silk Performer exactly emulates the cookie management of a browser, it will send cookies the same way a browser sends them to your server. No manual interaction is needed for state management.
  • page-level web API: Using the Page-level API when recording (which is the default setting) will generate scripts that mainly generate context-full Web API function calls such as WebPageLink and WebPageSubmit. Context-full Web API calls are working on the HTML level, not the HTTP level, and thus they do not use URL's as parameters. For all context-full API calls, manual session customization is not needed. The page-level API is used if you choose the application type Web business transaction (HTML/HTTP) in the Outline Project dialog. Therefore it is strongly recommended that you use Silk Performer's page-level API instead of the low-level web API.

Due to the heavy use of client side Java Script for dynamically generating HTML, the Silk Performer Recorder sometimes loses the HTML context and scripts context-less Web API calls. Context-less Web API calls, such as WebPageUrl and WebPageForm, contain URL's as parameters. In these rare cases, your script may contain hard coded session IDs. You will find them in the URL parameters of Web API calls and in the form fields declared in the dclform section of your script.

Context-full script (there is nothing to customize)

transaction TMain
  begin
    WebPageUrl("http://lab38/ShopIt/"); // first call is always context-less
    WebPageLink("Join the experience!");
    WebPageSubmit("Enter", SHOPIT_MAIN_ASP001);
    WebPageLink("Products");
  end TMain;

 dclform
 SHOPIT_MAIN_ASP001:
    "SessionID" := "" <USE_HTML_VAL>, // hidden value:
    "LGIJALLCGEBMIBIMFKOEJIMM"
    // recognized as a hidden form
    // field, the value is taken from
    // the actual HTML form field.
    "name" := "Jack", // changed
    "New-Name-Button" := "" <USE_HTML_VAL> ; //unchanged
    value: "Enter"

Script with context-less functions (static session data that needs to be customized is included in the DCLFORM section)

transaction TMain
  begin
    WebPageUrl("http://lab38/ShopIt/"); // first call is always context-less
    WebPageUrl("http://lab38/ShopIt/main.asp", NULL, SHOPIT_MAIN_ASP001);
    WebPageForm("http://lab38/ShopIt/main.asp", SHOPIT_MAIN_ASP002);
    WebPageUrl("http://lab38/ShopIt/products.asp");
  end TMain;

 dclform
 SHOPIT_MAIN_ASP001:
    "from" := "welcome";

    SHOPIT_MAIN_ASP002:
  "SessionID"       := "LGIJALLCGEBMIBIMFKOEJIMM",
    "name"            := "Jack",
    "New-Name-Button" := "Enter";
Parent topic: Session Handling


Customizing Session Handling

The following steps are required to customize session handling.

Refer to TrueLog Explorer Help for detailed information.

  1. Identify the session ID that needs to be customized.
  2. Search for the first response (Web API call in the script) in which the session ID is sent from the server to the client.
  3. Parse out the session ID from the found response of the Web API call into a variable.
  4. Replace all occurrences of the hard coded session ID in the script with this variable.
Parent topic: Session Handling


User Profiles

Browser Types

Virtual users in a test can be customized to use any of a wide choice of Web browsers, and of the functionality they embody. The most popular browsers in use today can be emulated. Lesser-known browsers are also available, as are browsers serving mobile device users. Custom browsers can be defined, using different versions of threading technologies and of HTTP.

Bandwidth

Modems are the means that home users typically use to access the Internet. Since a user’s modem is sometimes the slowest link in the network communication chain, modems can be simulated in a load test.

Virtual users can be customized to use the bandwidth associated with any of the major connection types in wide use among consumers today. Custom settings can be defined where connections use different bandwidth settings for downstream (from the server to the client) and upstream (from the client to the server) traffic.

  • Adding a Profile
    Create a new project-settings profile for your load test project.
  • Configuring Browser Settings
    Configure browser settings for the simulated network environment, including concurrent connections and HTTP version.
  • Configuring Browser-Simulation Settings
    Configure browser-simulation settings to create realistic simulation of virtual users visiting Web sites.
Parent topic: Customizing Test Scripts


Adding a Profile

  1. Select Project > New Profile . The New Profile dialog opens.
  2. Enter a Name for the new profile and click OK. The Profiles folder expands in the Project menu tree and the new profile is available.
Parent topic: User Profiles
Related concepts
Profile Administration


Configuring Browser Settings

  1. In Silk Performer, expand the Profiles node in the Project tree.
  2. Right-click the profile that you want to configure and choose Edit Profile.
    Tip: Alternatively, you can choose Settings > Active Profile from the menu bar.

    The Profile - [<profile name>] dialog box opens, and the Replay category is displayed in the shortcut list on the left.

  3. In the shortcut list, click the Web icon.
  4. Click the Browser tab. Use the Browser type area to specify browser-specific settings.
  5. From the Browser list box, select the Web browser you want to use for your simulation. The selection you make determines the format of the header information included in your HTTP requests and the threading model used for simulation.
    Note: For mobile Web application testing (iPhone, iPad, Android, Windows Phone or Blackberry) you can change the user agent string used for recording.
  6. Click OK to save your settings.
Parent topic: User Profiles


Configuring Browser-Simulation Settings

  1. In Silk Performer, expand the Profiles node in the Project tree.
  2. Right-click the profile that you want to configure and choose Edit Profile.
    Tip: Alternatively, you can choose Settings > Active Profile from the menu bar.

    The Profile - [<profile name>] dialog box opens, and the Replay category is displayed in the shortcut list on the left.

  3. In the shortcut list, click the Web icon.
  4. Click the Simulation tab. Use the Simulation area to set options for realistic simulation of users visiting Web sites.
  5. Check the Simulate user behavior for each transaction check box to have each virtual users reset their browser emulation after each transaction. Depending on the additional option you select, Silk Performer either simulates users who visit a Web site for the first time or users who revisit the site. While users who visit a site for the first time have no persistent cookies stored and no documents cached, users who revisit a page typically have closed their browsers between the Web site visits, have documents cached, and persistent cookies set. Disabling this option lets the virtual user emulate a Web browser that is not closed until the end of the test, thereby reusing cached information throughout multiple transactions.
  6. Click the First time user option button to generate a realistic simulation of users who visit a Web site for the first time. Persistent connections will be closed, the Web browser emulation will be reset, and the document cache, the document history, the cookie database, the authentication databases, and the SSL context cache will be cleared after each transaction. In such instances, Silk Performer downloads the complete sites from the server, including all files.
  7. Click the Revisiting user option button to generate a realistic simulation of users who revisit a Web site. Persistent connections will be closed, and the document history, the non-persistent cookie database, the authentication database, and the SSL context cache will be cleared after each transaction. In such cases, users do not clear the document cache. For more details, review the WebSetUserBehavior function in the BDL Function Reference. Use the User tolerance area to adjust the advanced options of the user tolerance simulation.
  8. Click OK to save your settings on the Profile - [<profile name>] dialog box.
Parent topic: User Profiles


Adjusting Workload

Configuring workload is part of the process of conducting a load test. Silk Performer offers different workload models to be used as a basis for your load test. Before configuring workload, you must select the model that best fits your needs.

You can define more than one workload model in your load test project and save them for further usage, but only one workload model can be active at a time. The accepted baseline results are associated with a workload model. If you copy or rename a workload model, the accepted baseline results are copied or renamed accordingly.

  • Workload Models
    Describes the available workload models.
  • Defining Workload
    Configure a workload model based on the number of concurrent virtual users per user type, duration, and involved agents.
Parent topic: Load Testing Web 2.0 Applications (Protocol-Level)
Related concepts
Calculating Virtual Users
Related reference
Performance and Scalability Matrix


Workload Models

Silk Performer provides the following workload models:
  • Increasing – At the beginning of a load test, Silk Performer does not simulate the total number of users defined. Instead, it simulates only a specified part of them. Step by step, the workload increases until all the users specified in the user list are running.

    This workload model is especially useful when you want to find out at which load level your system crashes or does not respond within acceptable response times or error thresholds.

  • Steady State – In this model, the same number of virtual users is employed throughout the test. Every virtual user executes the transactions defined in the load-testing script. When work is finished, the virtual user starts again with executing the transactions. No delay occurs between transactions, and the test completes when the specified simulation time is reached.

    This workload model is especially useful when you want to find out about the behavior of your tested system at a specific load level.

  • Dynamic – You can manually change the number of virtual users in the test while it runs. After the maximum number of virtual users is set, the number can be increased or decreased within this limit at any time during the test. No simulation time is specified. You must finish the test manually.

    This workload model is especially useful when you want to experiment with different load levels and to have the control over the load level during a load test.

  • All Day – This workload model allows you to define the distribution of your load in a flexible manner. You can assign different numbers of virtual users to any interval of the load test, and each user type can use a different load distribution. Therefore, you can design complex workload scenarios, such as workday workloads and weekly workloads. You can also adjust the load level during a load test for intervals that have not started executing.

    This workload model is especially useful when you want to model complex, long lasting workload scenarios in the most realistic way possible.

  • Queuing – In this model, transactions are scheduled by following a prescribed arrival rate. This rate is a random value based on an average interval that is calculated from the simulation time and the number of transactions per user specified in dcluser section of your script. The load test finishes when all of the virtual users have completed their prescribed tasks.
    Note: With this model, tests may take longer than the specified simulation time because of the randomized arrival rates. For example, if you specify a simulation time of 3,000 seconds and want to execute 100 transactions, then you observe an average transaction arrival rate of 30 seconds.

    This workload model is especially useful when you want to simulate workloads that use queuing mechanisms to handle multiple concurrent requests. Typically, application servers like servlet engines or transaction servers, which are receiving their requests from Web servers and not from end users, can be accurately tested by using the queuing model.

  • Verification – A verification test run is especially useful when combined with the extended verification functionality. This combination can then be used for regression tests of Web-based applications. A verification test performs a specified number of runs for a specific user type.

    This workload is especially useful when you want to automate the verification of Web applications and when you want to start the verification test from the command line interface.

Parent topic: Adjusting Workload


Defining Workload

Prior to the execution of a load test, you must specify the workload model that you want to use and configure its settings. To select a workload model, click Adjust Workload in the workflow bar.

  1. Click Adjust Workload on the workflow bar. The Workflow - Select and adjust Workload dialog box appears.
  2. Select one of the following workload models by clicking the appropriate option button:
    • Increasing
    • Steady State
    • Dynamic
    • All Day
    • Queuing
    • Verification
  3. Click Next.
  4. Configure specific workload types based on the steps outlined in the Help.
Parent topic: Adjusting Workload
Related tasks
Configuring Increasing Workload
Configuring Steady State Workload
Configuring Dynamic Workload
Configuring All Day Workload
Configuring Queuing Workload
Configuring Verification Workload


Running Load Tests

In a load test, multiple virtual users are run by means of a test script against a target server to determine the load impact on server performance. A large load test requires an appropriate testing environment on your LAN, including a full complement of agent computers to host the virtual users.

It is essential that you complete the following tasks:
  • Set options for the appropriate type of test that is to be run
  • Accurately define the required workloads
  • Enable the generation of test results to assess server performance

Do not enable complete result-logging during load testing because it might interfere with load-test results. However, the TrueLog On Error logging option writes necessary log files to a disk when errors occur, allowing you to inspect replay errors visually.

  • Running a Load Test
    Once your testing environment and settings have been configured, you are ready to launch your load test.
  • Monitoring Load Tests
    Details the available options for monitoring servers and virtual users during load tests.
  • Using a Graph to Monitor Server Performance
    You can generate and view real-time, color-coded displays of server performance.
Parent topic: Load Testing Web 2.0 Applications (Protocol-Level)


Running a Load Test

  1. Click Run Test on the workflow bar. The Workflow - Workload Configuration dialog box appears.
  2. Click Run to start the load test.
  3. Click OK on the New Results Files Subdirectory dialog box. (Optional) To specify a name for the results subdirectory, uncheck the Automatically generate unique subdirectory check box and enter a name for the new subdirectory in the Specify subdirectory for results files text box.
Monitor test progress and server activity by viewing the Silk Performer tabular monitor view and the Performance Explorer graphical monitor view.
Parent topic: Running Load Tests


Monitoring Load Tests

Detailed real-time information is available to testers while Silk Performer load tests run. Graphic displays and full textual reporting of activity on both the client side and the server side offer intuitive monitoring of the progress of tests as they occur.

Directly from the workbench on which the test is conducted, a tester can view comprehensive overview information about the agent computers and virtual users in the test. A tester can control the level of detail of the displayed information, from a global view of the progress of all the agent computers in the test to an exhaustive detail of the transactions conducted by each virtual user. Progress information for each agent and each user is available in multiple categories. Run-time details for each user include customizable, color-coded readouts on transactions, timers, functions, and errors as they occur.

In addition, real-time monitoring of the performance of the target server is available in graphical form. Charts display the most relevant performance-related information from a comprehensive collection of the Web servers, application servers, and database servers running on all of the OSes most widely used today. Multiple charts can be open at the same time, and these charts can be juxtaposed to provide the most relevant comparisons and contrasts for the tester. A menu tree editor allows for the combination of elements from any data source in the charts. Response times and other performance information from the client application can be placed in the same chart as performance data from the server. This feature enables a direct visual comparison so that one can deterimine the influence of server shortcomings on client behavior.

  • Monitoring Agent Computers During load Testing
    You can monitor the server performance of all agent computers during a load test.
  • Monitoring a Specific Agent During load Testing
    You can display server performance information for a specific agent during a load test.
  • Monitoring a Specific Virtual User During load Testing
    You can monitor detailed run-time information regarding a specific virtual user.
Parent topic: Running Load Tests
Related tasks
Monitoring Server Performance Through SNMP


Monitoring Agent Computers During load Testing

Use the Monitor window to view progress while a load test runs. The top part of the window displays information about the progress of agent computers and user groups.

Among the comprehensive number of information options, you can view the following information:

  • Status of a particular agent
  • Percentage of the test that is complete on an agent
  • Number of executed transactions
Parent topic: Monitoring Load Tests


Monitoring a Specific Agent During load Testing

In the top part of the Monitor window, select the specific agent to monitor.

The following information about the virtual users running on the selected agent appears in the bottom of the Monitor window:

  • Status
  • Name of the current transaction
  • Percentage of work completed
  • Number of executed transactions
Parent topic: Monitoring Load Tests


Monitoring a Specific Virtual User During load Testing

In the bottom part of the Monitor window, right-click the virtual user that you want to monitor and choose Show Output of Vuser.
In the Virtual User window, Silk Performer displays detailed run-time information about the selected user, such as the transactions and functions the user executes and the data the user sends to and receives from the server.
Tip: Right-click the virtual user area and choose Select Columns to select the columns you want to view.
Parent topic: Monitoring Load Tests


Using a Graph to Monitor Server Performance

  1. Click Confirm Baseline on the workflow bar. The Workflow - Confirm Baseline dialog box opens.
  2. Click Define monitoring options to specify the settings for receiving online performance data. The Profile Results dialog box opens.
  3. In the Profile Results dialog box, check the Automatically start monitoring check box to automatically start monitoring while running a load test and then choose one of the following options:
    • Click the Use default monitoring template option button.
    • Click the Use custom monitoring template option button to create a customized monitoring template.
  4. Click Create/Edit Custom Monitor Template. Performance Explorer appears.
  5. Close all monitor windows that you are not currently using.
  6. Click Monitor Server on the Performance Explorer workflow bar. Alternatively, you can choose Results > Monitor Server from the menu bar.

    The Data Source Wizard / Select Data Sources dialog box opens.

  7. Perform one of the following steps:
    • If you are certain of the data sources that the server provides, click the Select from predefined Data Sources option button to then select them from the list of predefined data sources.
    • If you are uncertain of the data sources that the server provides, click the Have Data Sources detected option button to let Performance Explorer scan the server for available data sources.
  8. Click Next. In the menu tree, expand the folder that corresponds to the OS on which the server and application are running.
  9. Select the server application you want to monitor from the list that appears. For example, to monitor the OS, select System.
  10. Click Next. The Connection Parameters dialog box opens.
  11. In the Connection parameters area, specify connection parameters such as the host name or IP address of the appropriate server system, the port number, and other data required to connect to the data source. The specified data depends on the OS running on the computer that you are monitoring.
  12. Click Next. The Select Displayed Measures dialog box opens.
  13. Expand the menu tree and select the factors you want to monitor.
  14. Click Finish. A Monitor graph shows the specified elements in a real-time, color-coded display of the server performance. Beneath the graph is a list of included elements, a color-coding key, and performance information about each element.
Parent topic: Running Load Tests


Exploring Test Results

Silk Performer offers several approaches to displaying, reporting, and analyzing test results. Defined measurements take place during tests and can be displayed in a variety of graphical and tabular forms. Options include the following:
  • Performance Explorer: This is the primary tool used for viewing test results. A fully comprehensive array of graphic features displays the results in user-defined graphs with as many elements as are required. The results of different tests can be compared. There are extensive features for server monitoring. A comprehensive HTML based overview report that combines user type statistics with time series test result information is also available.
  • TrueLog On Error: Silk Performer provides full visual verification under load capabilities for various application types. It allows you to combine extensive content verification checks with full error drill-down analysis during load tests.
  • Virtual User Report files: When enabled, these files contain the simulation results for each user. Details of the measurements for each individual user are presented in tabular form.
  • Virtual User Output files: When enabled, these files contain the output of write statements used in test scripts.
  • Baseline Reports: A detailed XML/XSL-based report that provides you with a summary table, transaction response-time details, timers for all accessed HTML pages, Web forms, and errors that occurred. This information is available for all user types involved in baseline tests.
  • Silk Central Reports: Silk Performer projects can be integrated into Silk Central (Silk Central) test plans and directly executed from Silk Central. This allows for powerful test-result analysis and reporting. For detailed information on Silk Central reporting, refer to Silk Central Help.
  • TrueLog On Error
    Explains how to use TrueLog On Error to identify errors that only occur under load.
  • Performance Explorer Overview
    Explains the real-time server monitoring and overview report offered by Performance Explorer.
Parent topic: Load Testing Web 2.0 Applications (Protocol-Level)


TrueLog On Error

With Silk Performer TrueLog technology, you can find errors that usually occur to only a subset of users when your application is under a heavy load. For most applications, this is the type of load that will most likely be experienced once the application is deployed in the real world. Typical errors include incorrect text on a Web page, incorrectly computed and displayed values, or application-related messages, such as Servlet Error or Server Too Busy errors. These are not system-level errors and are displayed on Web pages with HTTP 200 status codes.

TrueLog Explorer provides a view into Silk Performer verification-under-load capabilities with the following features:
  • Visual content verification allows you to visually define the content that is to be verified.
  • TrueLog On Error generation and TrueLog On Error analysis allow you to visually analyze errors to identify their root causes.
  • Viewing Errors in TrueLog Explorer
    View generated log files to verify the cause of errors raised by an application server.
Parent topic: Exploring Test Results


Viewing Errors in TrueLog Explorer

  1. When an error occurs during a load test, you can view the visual content of the TrueLog by clicking the Explore Results button on the workflow bar. The Workflow - Explore Results dialog opens.
  2. Click the Silk TrueLog Explorer link. TrueLog Explorer opens with the Step Through TrueLog dialog box active. Select Errors.
  3. Navigate from one occurrence of an error to the next.
    Tip: To display the history of an error, click through the preceding API nodes in the menu tree.
Verification error in TrueLog
Parent topic: TrueLog On Error


Performance Explorer Overview

Performance Explorer offers two main capabilities:
  • Results Analysis
  • Real-Time Monitoring

Results Analysis

With the Results Analysis functionality of Performance Explorer, you can analyze the results of a completed load test by creating charts, tables, and reports. With charts, you can visualize the data that was collected during the load test, and reports as well as tables help you to summarize important data and findings. The basis for all charts, tables, and reports is the data in the .tsd files. During each load test, Silk Performer captures a big amount of data and stores it in several time-series data (.tsd) files. When a load test is completed, you can load the data (the .tsd files) in Performance Explorer and visualize and edit them according to your requirements. All charts are fully customizable, and they can contain as many measures as required. You can open multiple charts using measures from one or multiple tests to show similarities and differences. Performance Explorer provides a variety of templates for charts, tables, and reports. Furthermore, you can place information on client and server performance in a single chart, so that you can directly view the effect of server performance on client behavior. By saving your changes as a template, you can reuse your individual settings.

Real-Time Monitoring

With the Real-Time Monitoring functionality of Performance Explorer, you can monitor a broad range of systems by creating and configuring charts that show the system performance in real-time. It is possible to open multiple charts at the same time, which allows you to watch the performance of two or more systems simultaneously, for example the web server performance and the operating system performance. Adding measures to a chart is easy and intuitive in Performance Explorer: You can drag a single measure or a set of measures from the tree onto the chart.

  • Overview Report Measurements
    Explains the measurement types that are detailed in overview reports.
  • Viewing Overview Reports
    Display and analyze the results of tests to assess the performance of the application and the server under test.
Parent topic: Exploring Test Results
Related concepts
Performance Explorer Reports


Overview Report Measurements

The overview report comprises the following sections:

  • General information

  • Summary tables
  • User types
  • Custom charts
  • Custom tables
  • Detailed charts

General information

The general information section includes administrative information in tabular form as well as important load test results in a graphical form.

Administrative information includes the project name, a description of the project, the load test number, a description of the load test, the date of the load test, the duration of the load test, the number of used agent computers, and the number of virtual users that were running.

The charts display the number of active virtual users, response time measurements for transactions, and the number of errors that occur over time. Transaction response times are provided for successfully executed transactions, for failed transactions, and for cancelled transactions.

Additional charts display summary measurements related to the type of load testing project. For example, in the case of Web application testing, response time measurements for Web pages are presented in a graph.

Summary tables

This section contains summary measurements in tabular form, that is, aggregate measurements for all virtual users. The first table provides general information, such as the number of transactions that were executed and the number of errors that occurred. All the following tables provide summary information relevant to the type of application that was tested.

User types

For each user group, this section provides detailed measurements in tabular form. The measurements include transaction response times, individual timers, counters, and response time and throughput measurements related to the type of application that was tested (Web, database, CORBA, or TUXEDO). In addition, errors and warnings for all user groups are listed.

Custom charts

This section contains graphs that you have added manually. You can add charts to and remove charts from this section at any time. You can save your changes as a template to be displayed for every summary report.

Custom tables

This section contains tables that you have added manually. You can add tables to and remove tables from this section at any time. You can save your changes as a template to be displayed for every summary report.

Detailed charts

This section provides enlarged versions of the charts included in the report. Click a reduced version of a chart to jump to the enlarged version, and vice versa.

Parent topic: Performance Explorer Overview


Viewing Overview Reports

  1. Click the Explore Results button on the workflow bar. The Workflow - Explore Results dialog appears.
  2. Click the Silk Performance Explorer button or link. If you have selected the Generate overview report automatically option in the Settings/Options/Reporting dialog, Performance Explorer opens and displays an overview summary report for the most recent load test. Additionally, you can choose to use a previously stored template for the generation of an overview report in this dialog. This setting is a global setting and will be used with Performance Explorer, regardless of the workload project you are using.
  3. If the overview report does not appear automatically, click the Overview Report button on the workflow bar.
    1. Navigate to the directory of the load test you are working with and select the corresponding .tsd file and then click Open.
    2. Click Next.
    3. Optionally, in the Template field, click [...] to navigate to the template file that you want to use.
    4. Click Finish.
    5. Depending on the load test that you selected, you may be prompted to confirm that you want to load all relevant files into your project.
    The overview report opens.
Parent topic: Performance Explorer Overview


Silk Performer Web Context Management

This section explains the concepts that facilitate advanced context management (state information management in Silk Performer). It covers the benefits of automatic context management in Web load testing and the techniques used by Web applications to transfer context information between browsers and Web/application servers. Also included is an exploration of the techniques used by the Silk Performer Web API to facilitate automatic context management and an explanation of how to optimally configure the Silk Performer Web recorder to generate scripts that automatically maintain state information.

  • Value of Context Management
    Explains some of the techniques that Web applications use to transfer state information.
  • Silk Performer Page-Level API
    Explains that low-level Web API describes network interactions in terms of single HTTP requests.
  • Context-less Functions
    Explains that context-less functions do not refer to previous events or results during script execution.
  • Context-full Functions
    Explains that, in contrast to context-less functions, context-full functions are designed to use results from previous function calls.
  • How the Recorder Loses Context
    Explores scenarios that can lead to loss of context in the absence of advanced context management techniques.
  • Advanced Context Management Techniques
    Explains that t Silk Performer page-level API incorporates advanced techniques that allow the writing of context-full scripts that automatically address context management issues.
  • Web Context Management Settings
    Explains available profile settings for URL parsing, link parsing, and fuzzy form detection.
  • Limitations to Web Context Management
    Explains the reasons why automatic context management may need to be complemented with manual context management techniques.
Parent topic: Load Testing Web 2.0 Applications (Protocol-Level)


Value of Context Management

The HTTP protocol, by its very nature, is stateless. HTTP follows a simple request/response paradigm. The client (the browser or other application/applet that uses HTTP for communication with a server) opens a TCP/IP connection to the server, sends a request, and receives a response from the server. Different requests from the same client to the same server, either on the same TCP/IP connection or on another connection, have no relationship to one another.

Web applications on the other hand need to embed single requests within larger entities such as complete HTML pages, user sessions initiated on Web servers, shopping carts, and registered customers.

To do this there must be some means of transferring state information from the server to the client that allows for the information to be returned back to the server within subsequent HTTP requests so that the server can associate the request with a specific user session (for example, a virtual shopping cart used by a registered customer.) and respond appropriately.

The techniques that Web applications use to transfer state information can be used with any Web browser.

A load-testing project that is to deliver useful results must simulate real users accessing Web servers with real browsers. Otherwise results will be meaningless.

Issues that can arise in the absence of state information

Results may be invalid - Poor context management can result in load-testing scripts in which, amongst other issues, each virtual user logs in to the same session, uses the same account, or uses the same shopping cart. In such cases, the impact on the Web/application server is quite different from a comparable load that might be experienced by a live application. Therefore the test results will be meaningless.

Errors go unnoticed - Web servers often do not use HTTP status codes properly when indicating errors. Instead, HTTP status codes that indicate success are returned within HTML documents describing application-level error conditions (for example, server overloaded and session timed out). If the next instruction in the script does not refer to previous results (for example, by requiring that a link be present), such application level errors may go unnoticed. There is no way for testers to inspect millions of lines of code in thousands of log files to find such errors.

Therefore, context management support contributes directly to improved error detection by providing "auto-verifying" scripts.

Scripts can not be replayed - While replay errors that arise from the auto-verifying functions of advanced context management can be productive, replay errors that arise from improper context management can cause problems, leading to tedious manual customization and debugging of scripts that waste QA resources.

Advanced context management eliminates such annoyances, leading to improved productivity and reduced testing costs.

Parent topic: Silk Performer Web Context Management


Silk Performer Page-Level API

Note: To take advantage of Silk Performer advanced context management techniques, you must use the page-level Web API (the default option when you set up a new Web business transaction Web testing project in Silk Performer).

The basic idea behind page-level API is to describe user actions at a higher level of abstraction.

Low-level API describes network interactions in terms of single HTTP requests. For single Web pages, browsers typically send numerous HTTP requests to servers. Low-level scripts therefore tend to be rather long, with each single function containing a parameter that specifies a URL from which to download. This makes low-level scripts unsuitable for automatic context management. Low-level scripts can also be difficult to read because they do not describe actions from the user perspective.

In contrast, high-level page-level API describes user actions in terms that are familiar to Web users. For example:

  • WebPageUrl - Enter a URL in the address bar
  • WebPageLink - Click a link
  • WebPageSubmit - Submit a form
  • WebPageBack - Click the Back button

One main feature of page-level API that differs from low-level API is that it incorporates an HTML-parser that parses HTML documents and locates embedded objects, frames, links and forms. Embedded objects and frames are downloaded automatically. Links and forms can be used for context-full function calls.

A single function call in a script can download a complete HTML page, even one that includes complex framesets.

Web Page History

Scripts utilizing page-level API emulate histories by logging previously downloaded pages, just as browsers do to enable their Back buttons. The maximum number of pages that are tracked for each virtual user can be limited to manage system resources (the default value is 5).

Note however that this limit does not affect the accuracy of load tests because the history's purpose is to facilitate advanced context management. It has nothing to do with network traffic.

If a page needs to be available for a longer period of time than its life-time in the history allows, it can be locked using the WebPageStoreContext function. While the page will still be dropped from the history if necessary, it will not be deleted from memory and it can be referred to by a handle that is returned by the WebPageStoreContext function. When the page is no longer needed it can be unlocked (and thereby deleted from memory) using the WebPageDeleteContext function.

Parent topic: Silk Performer Web Context Management


Context-less Functions

Context-less functions do not refer to previous events or results during script execution. Therefore they work without requiring information from previous events. For context-less function calls, all information that is required to perform functions must be specified in scripts. Scripting and recording of context-less functions requires that session and other dynamic information be included in some test scripts.

A typical feature of context-less functions is that they include parameters that specify URLs for download.

Context-less functions in Silk Performer page-level API include:
  • WebPageUrl
  • WebPageForm
  • WebPagePost, WebPagePostFile
  • WebPageCustomRequest, WebPageCustomRequestBin, WebPageCustomRequestFile

If any of these functions uses a form from the dclform section of your test script, the form will use a context-less approach because there is not a corresponding HTML form from which unchanged (for example, hidden) values can be taken. All form values must be specified in the script.

Parent topic: Silk Performer Web Context Management


Context-full Functions

In contrast to context-less functions, context-full functions are designed to use results from previous function calls. How results are to be used is specified in a way that does not incorporate dynamic data.

Context-full functions in Silk Performer page-level API include:

  • WebPageLink
  • WebPageSubmit
  • WebPageSubmitBin

The WebPageLink function downloads the target URL of a link.

Example HTML code:
<a href=http://www4.company.com/store/5423/account>Edit Account</a>

The above link contains load balancing information (www4) and a session id (5423) in the target URL.

Assume the user clicks this link. This can be modeled in BDL using the WebPageUrl function:

WebPageUrl("http://www4.company.com/store/5423/account");

The problem with this is that the dynamic components of the URL are hard-coded into the script.

Alternatively, the WebPageLink function can be used: WebPageLink("Edit Account");

This solution is better because the Silk Performer replay engine will, using its HTML parser, use the actual URL that is associated with the link name Edit Account during replay. While it is still possible that a link name can change dynamically, it is far less likely than having a URL change.

The WebPageSubmit function submits a form. By doing so, it combines a form definition from a previously downloaded HTML document with a BDL form defined in the script.

<form action="/cgi-bin/nav.jsp"
      name="frmNav"
      method="post"
      target="basketframe">
  <input type=input  name="quantity"
                     value="1">
  <input type=hidden name="BV_SessionID"
            value="@@@@1245417051.1003814911@@@@">
  <input type=hidden name="BV_EngineID"
            value="dadccfjhgjehbemgcfkmcfifdnf.0">
</form>

Now suppose the user changes the quantity from 1 to 3 and submits the form.

This can be modeled in BDL using the context-less WebPageForm function with a corresponding form definition:

WebPageForm("http://www4.company.com/cgi-bin/nav.jsp", FORM_BASKET_1);
...
dclform
  FORM_BASKET_1:
    "quantity"    := "3",
    "BV_SessionID" := "@@@@1245417051.1003814911@@@@",
    "BV_EngineID"  := "dadccfjhgjehbemgcfkmcfifdnf.0";

The problem with this solution is that everything is hard-coded into the script: the URL, which in this case contains load balancing information, and the form fields, which carry session information.

The better solution is to use the context-full WebPageSubmit function:

WebPageSubmit("frmNav", FORM_BASKET_2);
...
dclform
  FORM_BASKET_2:
    "quantity"     := "3",
    "BV_SessionID" := "" <USE_HTML_VAL>,
    "BV_EngineID"  := "" <USE_HTML_VAL>;

The WebPageSubmit function references an HTML form from a previous server response by name. The Silk Performer replay engine, using its HTML parser, automatically uses the actual action URL and HTTP method (GET or POST) to submit the form. The replay engine then uses the values of the BV_SessionID and BV_EngineID fields from the actual HTML code, so they do not need to be specified in the script.

Form Definitions in BDL

In Silk Performer, the syntax of form definitions in BDL scripts has been enhanced so that it is possible to specify whether individual fields should use values included in scripts, from HTML code, or be suppressed entirely.

Such specification is achieved using syntactical elements called form attributes. Form attributes are also used to specify encoding types for form fields.

For forms that are used context-fully using the WebPageSubmit function, the following usage attributes are allowed:

  • USE_SCRIPT_VAL (default)
  • USE_HTML_VAL
  • SUPPRESS

USE_SCRIPT_VAL means that the field value from the script is to be used for submission. This is the default attribute and can be omitted.

USE_HTML_VAL means that the field value from the HTML form definition is to be used. The value in the script is ignored and set to "". Form fields in the script are matched by name with form fields in the HTML form definition.

SUPPRESS means that even if a field with a specified name is present in an HTML form definition, neither the field's name or its value will be submitted. The field value in the script is therefore meaningless and is ignored.

Parent topic: Silk Performer Web Context Management


How the Recorder Loses Context

Saying that the recorder has "lost context" means that the recorder observes an HTTP request that can not be interpreted as an embedded object, a frame, a link, or a form submission.

This section discusses scenarios that can lead to loss of context in the absence of the advanced context management techniques used by Silk Performer.

  • META Refresh HTML Tag
    Explains that HTML allows for the specification of meta information within META tags.
  • JavaScript and Web Context Management
    Explains that JavaScript offers Web developers many options for doing things that can not be simulated using the Silk Performer replay engine to simply parse HTML.
Parent topic: Silk Performer Web Context Management


META Refresh HTML Tag

HTML allows for the specification of meta information within META tags. A popular use of this technique involves specifying redirections or page reloads within HTML code, rather than relying on HTTP headers to do so (for example, HTTP status code 302 Document moved for redirections).

Example HTML code:

<html>
  <title>Login</title>
  <META http-equiv=refresh
        content="0; URL=http://www4.company.com/user/6543/login.html">
</html>

This example also demonstrates that such non-HTTP redirections can be used (much like standard HTTP redirections) to introduce load balancing and/or session information.

The Silk Performer replay engine does not treat this as a redirection, so the recorder must generate a function call for the resulting HTTP request, thereby losing the context.

Note that this behavior is not a bug, but rather an intentional design feature in Silk Performer replay. To understand why automatically treating this as a redirection would be dangerous (in terms of inaccurate replay), consider the following example:

<html>
  <head>
    <title>Login</title>
    <META http-equiv=refresh
      content="1; URL=http://www.company.com/no_js_login.html">
  </head>
  <body onload="location='http://www.company.com/js_login.html'>
  </body>
</html>

This sample HTML implicitly checks the browser's JavaScript capabilities and redirects to one of two different login pages, based on the JavaScript capabilities of the browser. If the Silk Performer replay engine automatically downloaded the URL specified in the meta tag, it would be demonstrating behavior unlike any Web browser and would therefore be inaccurate.

Parent topic: How the Recorder Loses Context


JavaScript and Web Context Management

JavaScript offers Web developers many options for doing things that can not be achieved through HTML techniques, and therefore can not be simulated using the Silk Performer replay engine by simply parsing HTML. This makes JavaScript a leading cause of context loss.

HTTP requests that result from JavaScript actions often can not be described in terms of WebPageLink or WebPageSubmit functions, therefore the recorder has to generate context-less functions.

This topic offers some examples, but is by no means a complete listing of all scenarios that may be encountered.

JavaScript Redirection and Reload

This example demonstrates how JavaScript can be used to redirect to another URL, thereby introducing state information (load balancing, session IDs, and more).

<html>
  <head>
    <title>Login</title>
  </head>
  <body
    onload="location='http://www4.company.com/usr/6543/login.asp'">
  </body>
</html>

Embedded Objects Loaded by JavaScript

This example shows how JavaScript can be used to load embedded objects. The Silk Performer HTML parser however does not view these URLs as embedded objects, so the recorder has to generate a script function, otherwise the images will not be downloaded by the replay engine.

Note also that the URLs of these embedded objects are specified relatively. The browser resolves these relative URLs to absolute URLs using the base URL of the HTML document that contains them. So resulting URLs may well contain dynamic information (for example, http://www4.company.com/usr/6543/right_arrow.gif.

<html>
  <head>
    <title>Login</title>
  </head>
  <body onload="PreLoadImages('right_arrow.gif', 'left_arrow.gif', 'up_arrow.gif', 'down_arrow.gif')">
  </body>
</html>

Dynamic HTML

The document.write(…) JavaScript function allows you to dynamically change HTML code on the client side. Ad servers commonly use this technique.

Here's an example:

document.write('<script language=javascript
  src="http://ads.com/ad/offer.asp?date=' +
       escape(date) + '"></scr'+'ipt>');

Form Submissions with JavaScript

JavaScript can modify HTML forms before submitting them by:

  • Modifying form field values (even hidden fields)
  • Adding form fields
  • Removing form fields
  • Renaming form fields (equivalent to removing a form field and adding another field in the same position)
  • Changing the action URL

Example HTML code (modified form field names):

<form name="tabform"
      action="/cgi-bin/tabgui.asp"
      method="POST"
      target=_self>
  <input type=hidden name="session" value="6543">
  <input type=hidden name="tabevent" value="">
  <input type=hidden name="tabeventparam" value="">
</form>
<a href="JavaScript:selectTab('3')">Stock Watch List</a>

function selectTab(tabIndex)
{
  // change value of field #2
  document.tabform.elements[1].value = "select";
  // change name of field #3, originally "tabeventparam"
  document.tabform.elements[2].name = "TabIndex";
  // change value of field #3, now "TabIndex"
  document.tabform.elements[2].value = tabIndex;
  document.tabform.submit();
}

The above example demonstrates how JavaScript can submit a form. The form definition in HTML is just a template that is manipulated by JavaScript before it is submitted. The value of the second field ("tabevent", index 1) is changed to "select", the name of the third field ("tabeventparam", index 2) is changed to "TabIndex", and the value is changed to "3".

The following example demonstrates how JavaScript can be used to change the action URL of a form:

function SubmitSearch(linkUrl)
{
  document.searchForm.action = linkUrl;
  document.searchForm.submit();
}
..
<form name="searchForm"
      method="POST"
      target=_self>
  <input type=input name="searchString" value="">
  <input type=hidden name="BV_SessionID"
                     value="@@@@1245417051.1003814911@@@@">
</form>
<a href="JavaScript:SubmitSearch('http://my.server.com/search.asp')">
   Search this site</a>
<a href="JavaScript:SubmitSearch('http://my.mirror.com/search.asp')">
   Search mirror site</a>
Parent topic: How the Recorder Loses Context


Advanced Context Management Techniques

The Silk Performer page-level API incorporates advanced techniques that allow the writing of context-full scripts that automatically address context management issues. The Silk Performer recorder handles this work automatically.

The purpose of this section is to explain the features that are offered by the page-level API and show how they are used by the recorder to generate context-full scripts that do not require manual customization for context management.

This section makes reference to Silk Performer advanced context management settings, which can be configured in Silk Performer at Settings > Active Profile > Web > Recording tab.

  • WebPageAddURL
    The purpose of the WebPageAddUrl function is to specify additional files that should be downloaded during the next page-level API call.
  • Parsed URLs
    Explains that Silk Performer offers an extensible HTML parser that detects parsed URLs.
  • Changed Action URLs on Form Submission
    Explains that JavaScript can be used to change the action URL of a form.
  • Modified Forms
    Explains that JavaScript can modify forms that are defined in HTML before they are submitted.
  • Form Data Encoding
    Explains that the Web API uses form definitions within the dclform section of BDL scripts to specify form data that is to be submitted and query strings to be appended to URLs.
Parent topic: Silk Performer Web Context Management


WebPageAddURL

The purpose of the WebPageAddUrl function is to specify additional files that should be downloaded during the next page-level API call.

Additional files need to be specified when embedded objects will be downloaded by JavaScript or other techniques that are not covered by the Silk Performer HTML parser.

The URL to download can be specified relative to the base URL of the document that is downloaded by the subsequent page-level API call.

Example:

WebPageAddUrl("http://www4.company.com/images/mastercard.gif");
WebPageAddUrl("http://www4.company.com/images/visa.gif");
WebPageLink("Choose payment");
The same script in SilkPerformer, assuming the WebPageLink call downloads the URL http://www4.company.com/user/6543/payment.asp:
WebPageAddUrl("/images/mastercard.gif");
WebPageAddUrl("/images/visa.gif");
WebPageLink("Choose payment");

While WebPageAddUrl is a context-less function, the use of relative URL's minimizes the risk that a URL parameter will contain state information.

Note: The Silk Performer recorder generates WebPageAddUrl calls and relative URL's for WebPageAddUrl calls wherever possible.
Parent topic: Advanced Context Management Techniques


Parsed URLs

Silk Performer offers an extensible HTML parser that detects parsed URLs (also known as custom URLs). In addition to embedded objects, frames, links and forms, parsed URLs are also a category of HTML element that is detected by the HTML parser.

Extending the HTML parser: WebPageParseURL

To enable the HTML parser to parse custom URLs, you need to specify a parsing rule before the page-level custom URL parsing function. The API function for this purpose is WebPageParseUrl. WebPageParseUrl works much like the WebParseDataBound function.

A parsed URL gets a name (this corresponds to the name of the link). The name is specified in the first parameter of WebPageParseUrl. The second and third parameters are the left and right boundaries. The fourth parameter is options (for example, to ignore white spaces when parsing for the boundaries).

A single custom URL parsing specification can result in multiple parsed URLs since parsing does not stop after the first URL is found. More than one WebPageParseUrl statement can be placed before a page-level API call, resulting in multiple parsing rules applied concurrently during page download.

Parsing relative URLs

In parsing custom URLs, the HTML parser applies the same rules that are in effect for resolving relative URLs for links and frames. This means that you can parse, for example, only for a filename and receive a complete absolute URL.

Example: The following HTML document was generated by submitting a login form. It has the base URL http://www4.company.com/user/6543/navigation.asp:

<a href="JavaScript:window.open('account.asp')">Edit Account</a>

When the user clicks this link, the browser opens the URL http://www4.company.com/user/6543/account.asp in a new browser window.

This can be modeled in Silk Performer as:

WebPageParseUrl("Javascript window open", "open('", "'");
WebPageSubmit("login", FORM_LOGIN, "LoginPageTimer");
// now the parsed URL is available under
// the name "Javascript window open" and can be used.

Custom URLs, once parsed, can be used in a variety of ways.

Parsed URLs and WebPageLink

A parsed URL that is parsed using the WEB_FLAG_PARSE_LINK flag can be used anywhere that a link can be used (for example, for the WebPageLink or WebPageQueryLink functions). Note that if you do not specify the WEB_FLAG_PARSE_LINK and WEB_FLAG_PARSE_URL flags, both flags will be in effect by default.

Now the preceding example can be completed:

WebPageParseUrl("Javascript window open", "open('", "'");
WebPageSubmit("login", FORM_LOGIN, "LoginPageTimer");
WebPageLink("Javascript window open");
Note:

The Silk Performer recorder can generate a WebPageParseUrl call and use the parsed URL for a WebPageLink call. The recorder does this automatically whenever possible to avoid context-less function calls.

To enable this feature, select the Dynamic link parsing checkbox on the Advanced Context Management Settings dialog box at Settings > Active Profile > Web > Recording tab.

Parsed URLs and context-less functions: WebPageQueryParsedUrl

Parsed URLs can be retrieved and saved in string variables using the WebPageQueryParsedUrl function.

Such a string variable can then be used as a parameter for all page-level or low-level functions that require URL parameters, in addition to other purposes (for example, diagnostics output and StrSearchDelimited).

The following example HTML document resulted by submitting a login form. It has the base URL http://www4.company.com/user/6543/navigation.asp
<!--
function ShowContent(url, category, vendor)
{
  top.frames["content"].location.href=
    url + "?cat=" + category + "&vendor=" + vendor;
}
// end of script -->
…
<a href="JavaScript:ShowContent('products.asp', 'HD', 'IBM')">
   hard discs by IBM</a>
<a href="JavaScript:ShowContent('products.asp', 'HD', 'WD')">
   hard discs by Western Digital</a>
<a href="JavaScript:ShowContent('products.asp', 'Mon', 'Sony')">
   Monitors by Sony</a>

Assume that the API call that led to this page looks like this:

WebPageSubmit("login", FORM_LOGIN, "LoginPageTimer");

Now when the user clicks the second link, the browser loads the URL http://www4.company.com/user/6543/products.asp?cat=HD&vendor=WD into a frame named content. The parsed URLs and WebPageLink approach will not work for modelling this in BDL. That approach would require that parsing boundaries could be found for one of the following strings:

  • http://www4.company.com/user/6543/products.asp?cat=HD&vendor=WD
  • /user/6543/products.asp?cat=HD&vendor=WD
  • products.asp?cat=HD&vendor=WD

But none of these strings occur in the HTML code. Parsing of the URL does not seem possible. Consider the following:

WebPageSubmit("login", FORM_LOGIN, "LoginPageTimer");
WebPageUrl(
  "http://www4.company.com/user/6543/products.asp",
  "ProductTimer", FORM_PRODUCT_SELECT);
...
dclform
  FORM_PRODUCT_SELECT:
    "cat"    := "HD",
    "vendor" := "WD";

What you get is a context-less function, which, in this example, incorporates dynamic data in the URL. But this can be improved upon. While http://www4.company.com/user/6543/products.asp?cat=HD&vendor=WD can not be parsed, the shorter URL http://www4.company.com/user/6543/products.asp is now in the script and can be used as a parameter for the WebPageUrl function. This URL can be parsed using the boundaries "ShowContent('" and "'". This will parse the string products.asp, which will, after relative URL resolution, yield the required URL. This parsed URL can be copied into a string variable and the variable can be used rather than the hard coded URL parameter in the script. Thereby the following script is generated:

var
  sParsedUrl : string;
..
WebPageParseUrl("ShowContent", "ShowContent('", "'");
WebPageSubmit("login", FORM_LOGIN, "LoginPageTimer");
WebPageQueryParsedUrl(sParsedUrl, sizeof(sParsedUrl),
                  "ShowContent");
WebPageUrl(sParsedUrl, "ProductTimer", FORM_PRODUCT_SELECT);
..
dclform
  FORM_PRODUCT_SELECT:
    "cat"    := "HD",
    "vendor" := "WD";

The advantage here is that a context-less function call has been made, in a sense, "semi-context-full." While the query string is still context-less, the URL is parsed and so the dynamic data in the URL can be handled properly.

Note that in other examples it may happen that a URL won't be dynamic, yet the query string will contain dynamic data. In such instances the technique shown here won't deliver improved context management.

Note: The Silk Performer recorder can automatically generate WebPageParseUrl calls and query the parsed URLs for use with context-less function calls. The recorder does this whenever this technique can be used in conjunction with a context-less page-level API function call. To enable this feature, select the Dynamic link parsing checkbox on the Advanced Context Management Settings dialog box at Settings > Active Profile > Web > Recording tab.
Parent topic: Advanced Context Management Techniques


Changed Action URLs on Form Submission

JavaScript can be used to change the action URL of a form.

function SubmitSearch(linkUrl)
{
  document.searchForm.action = linkUrl;
  document.searchForm.submit();
}
...
<form name="searchForm"
      method="POST"
      target=_self>
  <input type=input name="searchString" value="">
  <input type=hidden name="BV_SessionID"
                     value="@@@@1245417051.1003814911@@@@">
</form>
<a href="JavaScript:SubmitSearch('http://my.server.com/search.asp')">
   Search this site</a>
<a href="JavaScript:SubmitSearch('http://my.mirror.com/search.asp')">
   Search mirror site</a>

Specifying a different absolute action URL

Assume that this page was downloaded by the function call

WebPageLink("Advanced Search");

Using the Silk Performer context-full WebPageSubmit function is a better choice because it automatically handles the hidden field BV_SessionID without having its value in the script.

To facilitate this, Silk Performer has the option of specifying a different action URL to use with the WebPageSubmit function.

The function used to do this is WebPageSetActionUrlAbs. If this function is called before a call to WebPageSubmit, the URL specified in the WebPageSetActionUrlAbs function is used rather than the action URL specified in the HTML code.

Using this function, the BDL code above would be rewritten as:

WebPageLink("Advanced Search");
WebPageSetActionUrlAbs("http://my.mirror.com/search.asp");
WebPageSubmit("searchForm", FORM_SEARCH);
...
dclform
  FORM_SEARCH:
    "searchString"   := "discount",
    "BV_SessionID"   := "" <USE_HTML_VAL>;
Note: The use of WebPageSetActionUrlAbs allows you to use the context-full WebPageSubmit function rather than the context-less WebPageForm function, and so allows you to use the FORM_SEARCH form in a context-full way.

The Silk Performer recorder automatically generates the WebPageSetActionUrlAbs function when it allows for generation of the function WebPageSubmit rather than a context-less function.

To enable this feature, select the Allow modified action URLs checkbox on the Advanced Context Management Settings dialog box at Settings > Active Profile > Web > Recording tab.

Specifying a different parsed action URL

While specifying a different absolute action URL offers an advantage in that it allows for the use of a context-full form, the URL is still context-less and hard coded into the script.

If the action URL also contains state information, the action URL needs to be specified context-fully.

This can be done using the WebPageSetActionUrl function. Unlike the WebPageSetActionUrlAbs function, the WebPageSetActionUrl function receives the name of a parsed URL rather than an absolute URL.

It is possible to parse custom URLs for use with the WebPageSetActionUrl function. To demonstrate, the example above can be rewritten as follows:

WebPageParseUrl("Form Action", "SubmitSearch('", "'");
WebPageLink("Advanced Search");
WebPageSetActionUrl("Form Action", 2);
WebPageSubmit("searchForm", FORM_SEARCH);
...
dclform
  FORM_SEARCH:
    "searchString"   := "discount",
    "BV_SessionID"   := "" <USE_HTML_VAL>;

This example uses the second occurrence of the parsed URL Form Action to set the action URL to http://my.mirror.com/search.asp. The script can handle state information that may be contained in the action URL.

The Silk Performer recorder can automatically generate calls to the WebPageSetActionUrl function and the corresponding call to WebPageParseUrl, rather than calling WebPageSetActionUrlAbs.

To enable this feature, select the Dynamic action URL parsing checkbox on the Advanced Context Management Settings dialog box at Settings > Active Profile > Web > Recording tab.

Parent topic: Advanced Context Management Techniques


Modified Forms

JavaScript can modify forms that are defined in HTML before they are submitted. Removing or renaming individual form fields can be challenging.

Usage attributes for form fields allow for better context management in such situations.

Without form usage attributes, the following example would need to be modeled in a context-less way. When taking advantage of form usage attributes however, it can be modeled context-fully as shown below.

<form name="tabform"
      action="/cgi-bin/tabgui.asp"
      method="POST"
      target=_self>
  <input type=hidden name="session" value="6543">
  <input type=hidden name="tabevent" value="">
  <input type=hidden name="tabeventparam" value="">
</form>
<a href="JavaScript:selectTab('3')>Stock Watch List</a>

function selectTab(tabIndex)
{
  // change value of field #2
  document.tabform.elements[1].value = "select";
  // change name of field #3, originally "tabeventparam"
  document.tabform.elements[2].name = "TabIndex";
  // change value of field #3, now "TabIndex"
  document.tabform.elements[2].value = tabIndex;
  document.tabform.submit();
}

Assume that the page including this HTML code is a response to the following function call:

WebPageLink("My portfolio");

Also assume that the page has the base URL http://www4.company.com/cgi-bin/portfolio.asp.

The user clicks the link Stock Watch List. Without form usage attributes, a corresponding BDL script would look like this:

WebPageLink("My portfolio");
WebPageForm("http://www4.company.com/cgi-bin/tabgui.asp", FORM_001);
...
dclform
  FORM_001:
    "session"   := "6543",
    "tabevent"  := "select",
    "TabIndex"  := "3";

This script uses the context-less WebPageForm function. An absolute URL appears in the script, possibly incorporating state information. The form FORM_001 is context-less, thereby introducing additional state information into the script.

By taking advantage of form field usage attributes, it can be specified that a field with the name tabeventparam must not be sent, but that an additional field with the name TabIndex should be sent. So the form tabform can be submitted in a context-full way using the WebPageSubmit function.

Here is the corresponding BDL code:

WebPageLink("My portfolio");
WebPageSubmit("tabform", FORM_001);
...
dclform
  FORM_001:
    "session"       := "" <USE_HTML_VAL>, // unchanged
    "tabevent"      := "select",   // changed
    "tabeventparam" := "" <SUPPRESS>, // suppressed
    "TabIndex"      := "3";           // added

This version eliminates the state information from the script, thereby providing automatic context management.

The Silk Performer recorder can automatically generate WebPageSubmit calls using HTML forms that do not match submitted form data and then generate appropriate usage attributes for those form fields in scripts. The recorder does this when it allows for a context-full WebPageSubmit call to be generated rather than a context-less function call.

To enable this feature, check the Fuzzy form detection option on the Advanced Context Management Settings dialog box (Settings > Active Profile > Web > Recording tab > View Settings).

Parent topic: Advanced Context Management Techniques


Form Data Encoding

The Silk Performer Web API uses form definitions within the dclform section of BDL scripts to specify form data that is to be submitted and query strings to be appended to URLs.

Unsafe characters must be encoded within query strings and HTTP request bodies. To accommodate the various encoding strategies used by different browsers in different situations, Silk Performer allows for the specification of encoding types for form fields.

This is accomplished using the enhanced syntax for form definitions within BDL, which allows for the specification of attributes for forms and form fields.

Encoding Types

The encoding type ENCODE_FORM encodes unsafe characters according to the mime type application/x-www-form-url-encoded. Blank spaces are encoded with + symbols, unsafe characters are encoded by their hexadecimal values preceded by % symbols.

All popular browsers use this encoding type for form submissions, both for URL query strings (HTTP method GET) and HTTP request bodies (HTTP method POST).

The encoding type ENCODE_FORM is the default when no other encoding type is specified in scripts, and therefore does not have to be specified explicitly.

The encoding type ENCODE_ESCAPE encodes unsafe characters according to the escape JavaScript function. This encoding type is similar to ENCODE_FORM. The main difference is that blank spaces are encoded with %20 rather than +.

The encoding type ENCODE_BLANKS encodes blank spaces with %20. No other unsafe characters are encoded. Most popular browsers use this encoding type for the target URLs of links.

The encoding type ENCODE_NONE does not encode any characters. This encoding type is often used when JavaScript issues HTTP requests without using the escape function.

Examples

dclform
  AD_SERVER_PARAMS <ENCODE_NONE>:
    "~userpref"     := "12|34|56",
    "~requesttime"  := "01/01/2002";
  FORM_REDIR_LOGIN <ENCODE_NONE> :
    "~language"     := "EN",
    "~logingroup"   := "GUEST",
    "~transaction"  := "TEST",
    "~exitUrl"      := "http://www.myserver.com/goodbye.html";
  LOGIN_FORM_001:
    "username"      := "testuser",
    "password"      := "testpassword",
    "hash"          := "%u2e34!\"" <ENCODE_NONE>,
    "platform"      := "OS: Win2000, Browser: IE5.5" <ENCODE_BLANKS>;
  DOWNLOAD_WHITEPAPER <ENCODE_BLANKS>:
    "filename"      := "Context management.pdf",
    "version"       := "V99";
Note: The Silk Performer recorder automatically determines the most suitable encoding type and generates scripts accordingly. The recorder omits the encoding type ENCODE_FORM (the default) to make scripts more readable.
Parent topic: Advanced Context Management Techniques


Web Context Management Settings

General Profile Settings

General Silk Performer Web context management profile settings can be configured at Settings > Active Profile > Web > Recording tab.

Select Page-level Web API (HTML/HTTP) to instruct the recorder to generate a page-level API script.

To have query strings that are part of URL parameters converted into forms for context-less function calls, select Convert URL query strings to forms. It is recommended that you select this option as it makes the Dynamic URL parsing setting applicable in more cases. If this option is not selected, query strings will not be converted into forms, but rather kept as parts of URLs.

Advanced Settings

To configure advanced Web context management settings, go to Settings > Active Profile > Web > Recording tab > View Settings button.

Fuzzy form detection - Selecting this option instructs the recorder to generate forms that use the usage attribute SUPPRESS when required. This may allow the recorder to generate the context-full WebPageSubmit function rather than the context-less WebPageForm (for HTTP POST requests) and WebPageUrl (for HTTP GET requests) functions.

Note: It is recommended that you enable Fuzzy form detection. If the site under test uses JavaScript to modify forms, this option will offer better context management. If the site does not use JavaScript, this option will not cause any harm.

Allowing modified action URLs - Checking this option instructs the recorder to generate the WebPageSetActionUrlAbs function when necessary. This may allow the recorder to generate the context-full WebPageSubmit function rather than the context-less WebPageForm (for HTTP POST requests) and WebPageUrl (for HTTP GET requests) functions.

Note: It is recommended that you enable Allowing modified action URLs. If the site under test uses JavaScript to modify forms, this option will offer better context management. If the site does not use JavaScript, this option will not cause any harm.

Dynamic action URL parsing - Selecting this option instructs the recorder to generate the WebPageSetActionUrl function rather than WebPageSetActionUrlAbs when it is possible to generate a WebPageParseUrl function for the required URL.

Note: It is recommended that you enable Dynamic action URL parsing. If the site under test uses JavaScript to modify forms, this option will offer better context management. If the site does not use JavaScript, this option will not cause any harm.

Dynamic link parsing - Checking this option instructs the recorder to generate the WebPageLink function for HTTP GET requests that do not correspond to a standard HTML link, rather than a context-less function when it is possible to generate the WebPageParseUrl function for the required URL.

Note: It is recommended that you enable Dynamic link parsing. If the site under test uses JavaScript to modify forms, this option will offer better context management. This option also ensures proper context management when the HTML tag <meta http-equiv=refresh …> is used.

Dynamic URL parsing - Selecting this option instructs the recorder to generate the WebPageParseUrl and WebPageQueryParsedUrl functions when possible to pass parsed URLs as parameters to context-less page-level API functions.

Note: The need for generating context-less API functions is greatly reduced when the preceding four advanced context management options are selected.

Enable Dynamic URL parsing if you see context-less API functions in recorded scripts, even if all other advanced context management options are selected and if the context-less functions use URLs that seem to incorporate state information.

Predefined Settings

The Advanced context management settings drop-box combo box (available at Settings > Active Profile > Web > Recording tab > Advanced context management) offers predefined configurations for advanced context management. You can choose a predefined configuration or choose your own custom settings.

The predefined configuration Level 2 is the default for Web business transaction (HTML/HTTP) testing projects.

The other predefined profile settings are detailed in the chart below:

 | Disable | Level 1 | Level 2 (default) | Level 3 | Custom
Fuzzy form detection | - | yes | yes | yes | your choice
Allow modified action URLs | - | yes | yes | yes | your choice
Dynamic action URL parsing | - | - | yes | yes | your choice
Dynamic link parsing | - | - | yes | yes | your choice
Dynamic URL parsing | - | - | - | yes | your choice
Parent topic: Silk Performer Web Context Management


Limitations to Web Context Management

You may encounter situations in which advanced context management techniques do not deliver complete, automatic context management. Common reasons include the following:

  • A URL can not be parsed by WebPageParseUrl. This can happen when a URL is built by JavaScript using string concatenation expressions.
  • Link names, form names, or form field names change dynamically.

In such situations, use TrueLog Explorer to customize context management. TrueLog Explorer supports customization of context management using a point and click interface.

Parent topic: Silk Performer Web Context Management


Manual Script Editing

Silk Performer test scripts are written in the program's proprietary scripting language, the Benchmark Description Language (BDL), which is a high-level language that resembles Pascal. To edit scripts manually, you must be familiar with BDL and be able to create prototypes of user requests. You must also be able to define the typical components of a test script, including modules, functions, workload definitions, transactions, and Web forms.

Verification and Parsing Functions

All parsing and verification functions must be specified before the Web API calls that will offer the response data that is to be parsed/verified. You can specify multiple parse/verification functions before a Web API call. The order of the parse/verification functions is not relevant (Exception: WebParseDataBound and WebVerifyDataBound using the flag WEB_FLAG_SYNCHRON).

WebVerifyHtml("Proper equipment leads to a successful trip", 1, ...);
WebPageLink("ShopIt");
Parent topic: Load Testing Web 2.0 Applications (Protocol-Level)


Customization of GZIP or ZLIB POST Data

GZIP or ZLIB data in requests

If GZIP or ZLIB data is detected in recorded requests, the WebSetEncoding function and the respective parameters are scripted.

GZIP or ZLIB data in responses

If the content encoding header of a response is set to gzip, responses are automatically unzipped with the GZIP algorithm. If the content encoding header is set to deflate, responses are automatically unzipped with either HTTP 1.1 compatible ZLIB algorithm (RFC1950) or raw deflate (RFC 1951).

Legacy GZIP transformation

To ensure backward compatibility, the GZIP transformation DLL is still supported. For more information on how to enable GZIP transformation, see Enabling Customization of GZIP POST Data.

  • Enabling Customization of GZIP POST Data
    Explains how to activate GZIP-transformation functionality to enable transparent decompression of GZIP-compressed POST bodies during script recording.
Parent topic: Load Testing Web 2.0 Applications (Protocol-Level)


Enabling Customization of GZIP POST Data

Silk Performer's GZIP-transformation functionality enables transparent decompression of GZIP-compressed POST bodies during script recording. Upon replay, POST bodies are recompressed into GZIP format. Without this functionality, GZIP compressed data sent by Web applications via http POST method data would be scripted by the Silk Performer recorder in binary format, making customization of the data nearly impossible. Data customization is however facilitated with Silk Performer's GZIP-transformation functionality.

Transformation is enabled for HTTP requests and responses that have the HTTP header Content-Encoding set to gzip. If you need to transform data with a different HTTP Content-Encoding header, see the steps below.

Follow the steps below to activate GZIP transformation.

  1. Navigate to Settings > Active Profile > Record > Web > Transformation .
  2. From the Type drop list, select GZIP Transformation.
  3. Confirm that the Transform HTTP requests option is enabled.
  4. Confirm that the Transform HTTP responses option is disabled.
  5. If you need to transform data with a different HTTP Content-Encoding header, type AdditionalContentEncodings=<mycustomgzip> into the Additional Parameters field. <mycustomgzip> should be the custom Content-Encoding of your application under test.
  6. Navigate to Settings > Active Profile > Record > Web > Recording .
  7. In the Record additional HTTP headers area, click the Add button.
  8. Enter Content-Encoding into the Record additional HTTP headers dialog and click OK. This is required for accurate compression/decompression of GZIP-encoded request bodies.
  9. Back on the Profile dialog, click OK.
Parent topic: Customization of GZIP or ZLIB POST Data


Setting Up Individual IP Addresses

If your application uses a load balancer, you can give the users individual IP addresses by using the System Configuration Manager.

  1. From the Silk Performer menu bar, select Tools > System Configuration Manager . The System Configuration Manager dialog box appears.
  2. Click the IP Address Manager tab. From the Adapter list box, select the network adapter for which you want to configure IP addresses. The list contains all the network adapters to which IP is bound on the computer in question.
  3. Use the IP addresses area to find out information about the current configuration of the network adapter, and to set up IP addresses for the adapter.
  4. To add new IP addresses to the network adapter configuration, click the Add button. The Add IP Addresses dialog opens.
  5. On the Add IP Addresses dialog, specify the following:
    1. In the From IP address field, enter the IP address you want to add to the network adapter configuration. If you specify that you want to add multiple addresses, the System Configuration Manager generates sequential IP addresses, starting with this address.
    2. In the Subnet mask field, enter the subnet mask number for the IP addresses.
      Note: This number, combined with the IP addresses, identifies which network the computers are on.

      To add multiple IP addresses, either select the Number option and enter the number of addresses you want, or select the To IP address option.

      In the latter case, specify the highest IP address you want to add to the network adapter configuration. The System Configuration Manager generates sequential IP addresses, starting with the address you type in the From IP address field and ending with this address.

    3. Select the Do not add conflicting addresses option to only add IP addresses to the network adapter configuration that do not cause conflicts.
    4. When enabling the Allow CIDR addresses check box, the verification of the IP address and subnet mask pair is disabled. Classless Inter-Domain Routing (CIDR) has been adopted as a solution to the scaling problem in the Internet. CIDR is not as restrictive as the "normal" IP-Routing.
    5. Click OK.
    Tip: To edit a selected IP address, click the Edit button.
  6. To save the network adapter configuration to a file, click the Save button. By default, the file is stored in the System Configuration Manager home directory. To load a network adapter configuration from a file, click the Load button and locate the appropriate file.
  7. To remove IP addresses, click the Remove button.
    CAUTION:
    Be cautious about removing multiple IP addresses at once.
    The Remove IP Addresses dialog appears.
  8. On the Remove IP Addresses dialog, specify the following:
    1. In the From IP address field, enter the IP address you want to remove from the network adapter configuration. If you elect to remove multiple addresses, the System Configuration Manager deletes all successive IP addresses, starting with this address.
    2. In the Subnet mask field, enter the subnet mask number for the IP addresses you want to remove.
    3. To remove multiple IP addresses, select either the Number or the To IP address option. Select the Number option to specify the number of IP addresses you want to remove from the network adapter configuration, and enter the number of addresses in the field. The System Configuration Manager deletes that number of successive IP addresses, starting with the address you type in the From IP address field. Select the To IP address option to specify the highest IP address you want to remove from the network adapter configuration. The System Configuration Manager deletes all successive IP addresses, from the address you type in the From IP address field to this address.
    4. Click OK.
  9. If you want to check whether IP routing to a specified computer works for all configured IP addresses, enter the name or IP address of the computer in the Host name or IP address field in the Network area, then click Check. A report from this check will be provided at the bottom of the dialog.
  10. Click OK to exit the dialog and save your changes.
Parent topic: Load Testing Web 2.0 Applications (Protocol-Level)


Web Forms

Web forms are defined in the dclform section of test scripts.

Web Form Declaration Syntax

The form declaration is specified by a form name (for example, FORM_NAME) which can be any valid identifier string and must be followed by a colon. The left side string specifies the name of the field or parameter. An empty string is allowed for nameless URL parameters, such as image map coordinates. The right value specifies the data value of the field or parameter. These can be global constants, global variables and random variables.

The example below illustrates the required syntax for Web form declarations:

dclform
  FORM_NAME:
  "field-name" := R-Value;

Web Form String Encoding

All strings used in the forms declaration will be URL encoded when sent to the server. This means that unsafe characters will automatically be converted into a hexadecimal sequence (%xx). Parameters added directly to the URL will not be encoded (for example, WebUrl("http://host/cgi-bin/doit?MyUnSafeMessage&-?%?-?", 0.0). This allows applications to use non-standard URL parameters.

Web Form Script Example

The following example shows a portion of a Silk Performer script for simulating a form submission. Random variables rsEmail and rsPlatform with two different random functions (RndFile and RndInd) are defined in the random variables section. With each subsequent call to WebFormPost and WebFormGet, the random variables are refreshed and contain new random values. These random values are used to generate the URL encoded form string automatically sent within the request to the Web server. WebFormPost adds the form content string at the end of the HTTP header while WebFormGet adds it at the end of the URL separated by a "?".

dclrand
  rsEmail : RndFile
  ("elname.rnd", 20);
  rsPlatform : RndInd("Windows NT" = 0.3;
  "Windows 2000" = 0.6;
  "other" = 0.1);

dcltrans
  transaction TWebFormPost
  begin
    WebFormPost("http://www.comp.com/cgi/FormMail.pl", CGI_CUST_SUPPORT, nWait);
    WebFormGet("http://www.comp.com/cgi/form", CGI_CUST_SUPPORT, nWait);
  end TWebFormPost;

dclform
  CGI_CUST_SUPPORT:
  "email" := rsEmail,
  "sitetype" := "business",
  "sitelang1" := "english",
  "platform" := rsPlatform;
Parent topic: Load Testing Web 2.0 Applications (Protocol-Level)


Cookies

Silk Performer supports record and replay for cookies used in Web applications.

Overview

Cookies enable Web servers to store and retrieve state information on the client computer. A server, when submitting an HTTP object, may also send a "cookie", a state object that the client will store for a specified amount of time. The cookie includes a description that defines a range of URLs for which it is valid. The next time a client reconnects from within this range of URLs, the contents of the cookie will be submitted to the server in addition to the request. Cookies may either be persistent or non-persistent. Persistent cookies are stored in a cookie database on the client computer and are deleted only after a specified expiration date occurs. Non-persistent cookies are maintained only during a single Web browser session and are deleted when the client Web application is closed. To create as realistic a simulation as possible, only persistent cookies are recorded (and thus replayed) by the Internet Recorder.

Cookie Database Functions

For information about cookie database functions, see Cookie functions. Before you use these functions, you should be familiar with cookies as outlined at http://www.w3.org/Protocols/rfc2109/rfc2109 .

Important Notes

Keep in mind the following when you work with cookies with Silk Performer:

  • The Silk Performer cookie database is non-persistent and therefore only exists while a test is running.
  • Each virtual user has a cookie database of its own and therefore the contents of the cookie database varies from virtual user to virtual user.
  • Although cookies are generally created at server side, you can simulate already existing cookies using the WebCookieSet function.
Parent topic: Load Testing Web 2.0 Applications (Protocol-Level)
Related concepts
Cookie Database Functions Overview


Load Testing Web 2.0 Applications (Browser-Driven)

In addition to facilitating testing of today's modern Web applications on the protocol level (HTTP), Silk Performer enables you to use real Web browsers (Internet Explorer, Chrome, and Firefox) to generate load.
Browser-driven load testing is available in two flavors:
  • Re-using a functional test created with Silk Test. This approach applies best if you already have Silk Test keyword test assets that automate functional tests with one of the supported browsers. When importing such assets, Silk Performer wraps them into a BDL stub script to make it executable as part of a load test. For more information, see Single Session GUI-Level Testing in GUI-Level Testing Support.
  • Creating browser-driven load testing scripts from scratch within Silk Performer. With this approach, the BDL scripting language is used to model the user actions. With this option, no Silk Test installation is required. The user actions are recorded within a purpose-built tool named Browser Application. This application hosts an Internet Explorer component and facilitates recording, including adding verifications, defining Time-to-interact elements and visual debugging.
    Note: Recording within Chrome or Firefox is currently not supported. But once recorded within the Browser Application, you can replay your script in Chrome or Firefox.
Note: In terms of licensing, there are no differences. For both types of browser-driven load testing, the license type SilkPerformerWebVU is required.
  • Browser-Driven Load Testing Overview
    Offers an overview of how Silk Performer is used to test Web 2.0 applications.
  • Web Browser Configuration Settings
    Explains why you may want to change some Internet Explorer settings to maintain stable test executions.
  • Creating a Test Script
    Explains how to model browser-driven Web load-test scripts and try out test scripts using Try Script runs.
  • Analyzing Test Scripts
    Explains the benefits of performing Try Script runs in the Browser Application.
  • Configuring Project Profile Settings
    Explains the browser-driven Web load-testing profile settings that are available with Silk Performer.
  • Advanced Concepts for Browser-driven Tests
    Describes advanced concepts for browser-driven load testing.
  • Troubleshooting Browser-Driven Load Testing Issues
    Learn how to start the perfrun process using an actual user account, handle client certificates, and exclude specific URLs from AJAX synchronization.
Parent topic: Web Applications Support


Browser-Driven Load Testing Overview

In addition to facilitating testing of today's modern Web applications on the protocol level (HTTP), Silk Performer now enables you to use real Web browsers (Internet Explorer, Firefox, and Chrome) to generate load. In this way, you can leverage the AJAX logic built into Web applications to precisely simulate complex AJAX behavior during testing. This powerful testing approach provides results that reflect real-world end user browsing experience, including rendering time and protocol-level statistics.

Unlike other load-testing solutions that only support specific AJAX frameworks (and of those, only specific versions or a subset of controls), Silk Performer supports the full range of Web applications that are developed for (and tested with) Internet Explorer, Firefox, and Chrome.

With the browser-driven load testing support, Silk Performer strives to offer the same functionality and behavior across all supported browsers. This makes it possible to record your scripts in the Internet Explorer-based Browser Application and replay them with Firefox and Chrome.

In some rare cases however, this abstraction might not work as expected due to inherent differences among the browsers. For example: The Browser Application might generate a locator that cannot be resolved by Chrome or Firefox. For more information, see Limitations for Replay with Different Browsers.

Most browsers follow a frequent and silent update policy. For a load testing environment, this is not ideal, because it influences the consistency of the results. Furthermore, Silk Performer might not have been tested with the latest browser versions, especially if these have been published after the latest Silk Performer release. As a general rule: To avoid problems, stick to the tested browser versions listed in the section Tested Software in the release notes and install the latest hotfixes.

  1. Support for Pop-Up Windows
    Explains that Silk Performer browser-driven testing supports sites that utilize pop-up windows.
  2. Sample Web 2.0 Application
    Explains that Silk Performer offers a modern sample Web application that you can use to learn about Web 2.0 application testing.
  3. Pop-Up Window in the Sample Application
    Explains that the sample Web 2.0 application includes pop-up window functionality that you can use to experiment with Silk Performer support for multiple browser windows.
  4. Support for HTML Dialog Boxes
    Lists the dialog types Silk Performer recognizes during browser-driven Web load testing.
  5. Native Replay
    Explains how replaying browser-driven scripts ensures reliability by using Windows API-level events instead of JavaScript events.
Parent topic: Load Testing Web 2.0 Applications (Browser-Driven)
Related concepts
Web Load Testing Overview
Related reference
BrowserSetIEMode Function


Support for Pop-Up Windows

Silk Performer browser-driven testing supports sites that utilize pop-up windows (for example, login dialog boxes). Pop-up browser windows often include input fields in which users enter values that are passed back to the main page (for example, username and password strings). Multiple browser-window support is available by default when you create a Silk Performer project of type Web browser-driven (AJAX).

A new tab is created in the Browser Application each time a pop-up window is generated during application recording. Each pop-up window that is encountered results in a tab being created in the Browser Application. Each time you click a tab in the Browser Application during recording a BrowserActivateWindow function is scripted automatically.

Note: The manual opening of windows and tabs during recording (via menu bars, context menus, or keyboard shortcuts) is not supported.
Parent topic: Browser-Driven Load Testing Overview
Next topic: Sample Web 2.0 Application


Pop-Up Window in the Sample Application

The sample Web 2.0 application includes pop-up window functionality that you can use to experiment with Silk Performer support for multiple browser windows.
  1. To generate the pop-up window, visit the sample Web 2.0 application at http://demo.borland.com/InsuranceWebExtJS/.
  2. From the Select a Service or Log in drop list, select Agent Lookup.
  3. On the Find an Insurance Co. Agent page, click the Open in new window link at the bottom of the page. The Find an Insurance Co. Agent page loads in a new tab within the Browser Application.

Click the Close Window link at the bottom of the page to close the tab.

Parent topic: Browser-Driven Load Testing Overview
Previous topic: Sample Web 2.0 Application
Next topic: Support for HTML Dialog Boxes


Support for HTML Dialog Boxes

Silk Performer recognizes the following dialog types:
JavaScript dialogs | supported in all browsers
Print dialogs | not supported
File Save & File Open dialogs | supported in Internet Explorer
Modal windows and modeless windows (HTML dialogs)* | supported in Internet Explorer

* HTML dialogs display as windows. Note that modal and modeless windows are a specific feature of Internet Explorer, hence they are only supported in Internet Explorer.

Parent topic: Browser-Driven Load Testing Overview
Previous topic: Pop-Up Window in the Sample Application
Next topic: Native Replay


Native Replay

This topic applies to Internet Explorer only. For the other browsers, Silk Performer does not provide native replay capabilities.

The concept of native replay makes replaying a script more reliable. This is achieved by using Windows API-level events instead of JavaScript events for frequently used functions.

In the context of native replay we are using two special terms: native replay and legacy input mode. Note that native replay is the opposite of legacy input mode. If you turn on legacy input mode, native replay is automatically turned off, or the other way around. In this sense, we can also distinguish between native functions and legacy functions.

  • Native functions are using Windows API-level events.
  • Legacy functions are using JavaScript events.
The following functions can be called legacy functions, since they all have a native equivalent. If one of these legacy functions is detected during replay, then ...
  • BrowserClick is replayed like BrowserNativeClick
  • BrowserDoubleClick is replayed like BrowserNativeDoubleClick
  • BrowserSetText is replayed like BrowserTypeKeys
  • BrowserSetPassword is replayed like BrowserTypeKeys
  • BrowserMouseMove is replayed like BrowserNativeMouseMove

If a native function cannot be performed instead of the legacy function, the legacy function is used as fallback and a warning message is logged. This can be the case if, for example, no mouse position can be determined to click the element.

Native replay is enabled by default. You can disable it in the Profile Settings: Click Settings > Active Profile > Web (Browser Driven). On the General tab, enable Legacy input mode. Alternatively, you can add the following function to your script: BrowserSetOption(BROWSER_OPT_LEGACY_INPUT_MODE, true)

Legacy input mode is enabled by default for all project profiles created with Silk Performer 9.0 or earlier.

Parent topic: Browser-Driven Load Testing Overview
Previous topic: Support for HTML Dialog Boxes
Related reference
BrowserClick Function
BrowserNativeClick Function
BrowserDoubleClick Function
BrowserNativeDoubleClick Function
BrowserSetText Function
BrowserTypeKeys Function
BrowserSetPassword Function
BrowserMouseMove Function
BrowserNativeMouseMove Function


Web Browser Configuration Settings

Several browser settings are critical to maintaining stable test executions. Although Silk Performer works without changing any settings, there are several reasons why you may want to change these browser settings in Internet Explorer.

  • Increase replay speed
    • Use about:blank as the home page, rather than a slowly loading Web page
  • Avoid unexpected browser behavior
    • Disable pop-up windows and warning dialog boxes
    • Disable auto-complete features
    • Disable password wizards
    • If Silk Performer runs on a Windows Server operating system, disable Internet Explorer Enhanced Security Configuration (IE ESC).
  • Prevent browser malfunctions
    • Disable third-party plug-ins

The following table explains where you can find these settings within the Internet Explorer GUI.

Note: Browser settings are located at Tools > Internet Options.
Tab Name | Option | Configuration | Comments
General Home page

Set to about:blank

Minimizes start-up time of new tabs.
General Tabs
  • Disable warning for closing multiple tabs
  • Enable switch to new tab when tabs are created
  • Avoids unexpected dialog boxes
  • Links that open new tabs may not otherwise replay correctly
Privacy | Pop-up blocker | Disable pop-up blocker | Ensures that your Website can open new windows.
Content Auto Complete Turn off
  • Avoids unexpected dialog boxes
  • Avoids unexpected data input while typing
Programs Manage add-ons Only enable required add-ons
  • Third-party add-ons may contain defects
  • Third-party add-ons may be incompatible
Advanced Settings
  • Disable Automatically check for Internet Explorer updates
  • Enable Disable script debugging (Internet Explorer)
  • Enable Disable script debugging (other)
  • Disable Display notification about every script error
  • Disable all Warn... settings
Avoids unexpected dialog boxes.
Note: Depending on your browser version, not all settings may be available.
  1. Running Multiple Virtual Users
    Explains that Silk Performer can simulate the behavior of both first-time and revisiting users.
Parent topic: Load Testing Web 2.0 Applications (Browser-Driven)


Running Multiple Virtual Users

When running multiple browser sessions in parallel, Silk Performer must make sure that these sessions operate independently from each other. Cache, cookie data base, and history in particular must not be shared across virtual users to simulate real user load. The separation of virtual users with regards to browsers is called browser sandboxing, meaning each virtual user runs its browser in its own environment.

To run browsers in sandboxed mode, Silk Performer uses different browser-dependent techniques.

Internet Explorer

For performance and resource reasons, Silk Performer does not use a full Internet Explorer browser instance to simulate a virtual user, but an Internet Explorer ActiveX control. The default behavior of the Internet Explorer control is to maintain a single cookie database, cache, and history across browser instances started by a particular Windows user. For load tests, Silk Performer reconfigures an Internet Explorer control to maintain one cookie database, cache, and history for each virtual user.

As each virtual user has its own independent Internet Explorer sandbox, it is possible to accurately simulate first-time and revisiting user behavior, as is used in the protocol-based approach to Web simulation.

Chrome and Firefox

These browsers provide their own mechanism to create independent browser sessions. As a driver engin, Silk Performer uses the corresponding WebDriver interface and some custom enhancements to enable them to run in a load testing environment.

Parent topic: Web Browser Configuration Settings


Creating a Test Script

The easiest approach to creating a test script is to use the Silk Performer Recorder, the Silk Performer engine for capturing and recording Web traffic and generating test scripts based on the captured traffic.

The Silk Performer Recorder captures and records the traffic that moves between the client application and the server under test. When recording is complete, the Silk Performer Recorder automatically generates a test script that is based on the recorded traffic. Scripts are written in the Silk Performer scripting language, Benchmark Description Language (BDL).

  1. Defining a Browser-Driven Web Load Test Project
    A project contains all of the resources that are needed to complete a load test including a workload, test script, data files, and more.
  2. Recording a Test Script
    Create a test script with the Silk Performer Recorder, Silk Performer's engine for capturing and recording traffic and generating test scripts.
  3. Browser Application and Locator Spy Usage
    To enable convenient record/replay, Silk Performer provides its own Browser Application.
  4. Locator Verification in Browser Application
    Explains that the Browser Application offers commands that make it easier to analyze and navigate locator information in the Replay window.
  5. Inserting Mouse Move
    Describes how to fix errors in a script that occur because hovering over an element is not recorded and another UI element cannot be detected.
  6. Inserting a Verification Function
    Use the Browser Application to insert verification functions visually during the browser-driven script recording process.
  7. Including Elements in the TTI
    Describes how to tag elements as TTI-relevant during recording.
  8. Try Script Runs
    Explains that a Try Script run determines if a script accurately recreates the actions that you recorded during script modeling.
  9. Trying Out Your Test Script
    Once you have generated a test script, determine if the script runs without error by performing a Try Script run.
  10. Using Step-by-Step Try Script Replay
    When you enable Step by step execution on the Try Script dialog box, you are given the option of advancing your Try Script replay one step at a time.
  11. Common Replay Errors
    Lists common reasons why scripts do not replay correctly and may require customization.
Parent topic: Load Testing Web 2.0 Applications (Browser-Driven)


Defining a Browser-Driven Web Load Test Project

  1. Click Start here on the Silk Performer workflow bar.
    Note: If another project is already open, choose File > New Project from the menu bar and confirm that you want to close your currently open project.
    The Workflow - Outline Project dialog box opens.
  2. In the Name text box, enter a name for your project.
  3. Enter an optional project description in Description.
  4. From the Type menu tree, select Web browser-driven (AJAX).
  5. Click Next to create a project based on your settings.
The Workflow - Model Script dialog box appears.
Parent topic: Creating a Test Script
Next topic: Recording a Test Script
Related tasks
Recording a Test Script


Recording a Test Script

Recording browser-driven scripts is available for Internet Explorer only.

  1. Click Model Script on the workflow bar. The Workflow - Model Script dialog box appears.
  2. Select Silk Performer Browser Application from the Recording Profile list.
  3. In the URL field, enter the URL that is to be recorded.
    Note: The InsuranceWeb sample Web 2.0 application is available at http://demo.borland.com/InsuranceWebExtJS/. In the Select a Service or login list, the Auto Quote and Agent Lookup services are available for testing while the other listed services do not provide any functionality.
  4. Click Start recording. The Silk Performer recorder opens in minimized form along with the Silk Performer Browser Application (Internet Explorer).
    Note: To specify the dimensions of the browser window for recording, go to View > Resize Browser Window and define Width and Height pixel values.
    To see a report of the actions that occur during recording, maximize the recorder dialog box by clicking [image] on the recorder toolbar.
  5. Using the Browser Application Recorder, interact with the sample application in the same way that you want your virtual users to act during the test (for example, click links, type data into fields, submit data, and open the pop-up window). Your actions will be captured and recorded by the Browser Application Recorder.
    • Click [image] (Pause/Resume Recording) to briefly stop and restart recording.
    • Click [image] (Stop Recording) to end script recording and save your script.
  6. When you are finished, close the browser window and click Stop Recording. The Save As dialog box displays.
  7. Type a meaningful name for the script and click Save.

    A BDL test script that is based on the user actions you performed appears in the Script window.

Parent topic: Creating a Test Script
Previous topic: Defining a Browser-Driven Web Load Test Project
Next topic: Browser Application and Locator Spy Usage


Browser Application and Locator Spy Usage

To enable convenient record/replay, Silk Performer provides its own Browser Application. The application offers the following main parts:

  • Browser Window (the Internet Explorer control)
  • Locator Spy
  • Record/Replay Window

The following image shows the most important elements of the Browser Application.

Note: Tracking of UI elements must be enabled before you can select a DOM object. When tracking is enabled, a green rectangle appears around UI elements as your cursor passes over them. Click Enable Tracking if tracking is not currently enabled.

Record/Replay Window

This window displays logging information during both record and replay. It allows you to start/stop and pause/resume recording during record mode and to pause/resume replay during replay mode.

Browser Navigation Bar

The bar enables standard browser navigation.

Highlighted DOM Element

When you move your mouse over a web page, the DOM elements under the cursor are being highlighted in green. The green rectangles help you to get a feeling for the architecture of the web page and its DOM hierarchy.

Inspected DOM Element

Pressing Pause/Break triggers the following actions:

  • The highlighted DOM element becomes the inspected DOM element.
  • The position of the inspected DOM element is indicated by blue highlighting.
  • The DOM hierarchy tree of the current page is determined and displayed in the Locator Spy by the HTML tags of the DOM elements.
  • The path to the inspected DOM element is expanded and the inspected DOM element is selected.
  • The attributes of the inspected DOM element are displayed.
  • The locator for the inspected DOM element is determined and displayed in the Locator field.

To search within the Locator Spy, press Ctrl+F on your keyboard. Alternatively, select Actions > Find in DOM Tree. You can search for strings within Tags, Property names, or Property values.

To change the inspected DOM element, press Pause/Break on any highlighted DOM element or select another DOM element within the DOM hierarchy tree.

When you select another DOM element in the DOM hierarchy tree, the locator for the DOM element is determined and displayed next to its HTML tag. The locator field is updated and the DOM element is highlighted in blue.

When a page’s DOM becomes invalid after pressing Pause/Break and the locator for the newly selected DOM element can not be found, a red border is displayed around the locator field. Press Pause/Break to refresh the hierarchy tree and to highlight the current DOM object. Locator strings in the DOM hierarchy tree are also removed as they are now invalid.

Locator Field

The locator field shows the locator string of the currently inspected DOM element. Whenever the inspected DOM element changes, the locator string is updated.

The locator field can be used to copy a locator string to another location, for example to a BDL script. Or you can use the field to manually edit locator strings. When you edit a locator, it is automatically being validated. If the locator is invalid, it is highlighted in red. If the locator is valid, it is highlighted in green.

If you want to add a verification during a try script run, pause the replay and click Add Verification. Adding verifications during a try script run works exactly as during recording.

In the right window of the Locator Spy, you can right-click a property and copy the property name, the property value, or both to the clipboard. If you copy both, the string will be saved in the form @name='value'. A real-world example is @hideFocus='false'. This way, you can conveniently exchange properties in the locator field.

Attributes of Inspected DOM Element

This is a list of attributes (name/value pairs) belonging to the currently inspected DOM element. If the current locator string does not fit your needs, you can manually build a specific locator string using some of the listed attributes.

Parent topic: Creating a Test Script
Previous topic: Recording a Test Script
Next topic: Locator Verification in Browser Application


Locator Verification in Browser Application

The Browser Application offers commands that make it easier to analyze and navigate locator information in the Replay window. Right click any API call in the Replay window to access context-sensitive commands for copying that call's locator information, copying the content of the Info column, and displaying the locator of the call in the Locator Spy DOM hierarchy tree.

Such commands can be useful when, for example, a locator verification or an API call fail. You can use the locator of the API call to locate the call in Locator Spy, troubleshoot the issue, and edit the script accordingly. You can also use the Copy command to copy and paste API details into emails and issue reports.

Parent topic: Creating a Test Script
Previous topic: Browser Application and Locator Spy Usage
Next topic: Inserting Mouse Move


Inserting Mouse Move

When you are testing websites where items only appear if you are hovering with your mouse over certain elements (for example a button or a menu item), you will get an error during the replay of the script. Silk Performer cannot detect the item because the hovering event is not recorded. Menus that are built with JavaScript are a good example for such a case. However, with Silk Performer you can fix this problem during the replay of a script.

In the Browser Application, you can click the Troubleshoot button when the error occurs, select Insert Mouse Move from the list, move the mouse over the UI element, press <Pause/Break> on your keyboard, click Insert, and click Rerun Script. Now the script will run without an error.

Parent topic: Creating a Test Script
Previous topic: Locator Verification in Browser Application
Next topic: Inserting a Verification Function


Inserting a Verification Function

  1. During browser-driven script recording using the Browser Application, select a DOM object that contains a value you want to later verify during script replay (press Pause/Break on your keyboard to select a DOM object).
    Note: Tracking of UI elements must be enabled before you can select a DOM object. When tracking is enabled, a green rectangle appears around UI elements as your cursor passes over them. Click Enable Tracking if tracking is not currently enabled.
    The locator of the selected UI object appears in the Locator text box and the DOM hierarchy is displayed in the tree menu.
  2. Click Add Verification. The Add Verification button is enabled when a locator value appears in the Locator field. The Add Verification Function dialog box appears with the locator value preloaded in the Locator field.
  3. Select a DOM Property name (For example, href, class, onmousedown, or textContents). To serve as a meaningful verification function, the selected property name should have a verifiable Property value. For example, property name href should have a property value of a specific URL.
  4. Click Okay to insert a BrowserVerifyProperty verification function for the selected DOM element and its corresponding property name/value pair into the script.

The verification action is recorded in the Record Window and the verification function is inserted into the BDL script.

Parent topic: Creating a Test Script
Previous topic: Inserting Mouse Move
Next topic: Including Elements in the TTI


Including Elements in the TTI

  1. Click File > New Project to create a new browser-driven project. If you want to use an existing project, click Model Sript on the workflow bar and skip to step 3.
  2. Select Web browser-driven (AJAX) in the tree, enter a Name and Description and click Next.
  3. Enter the URL of the application you want to record and click Start recording. The Browser Application launches.
  4. Navigate through the application to record your actions. To tag an element as TTI-relevant, move your mouse over the element, press Pause/Break and click Include in TTI. You can include as many elements as you want. Silk Performer will add a BrowserTtiIncludeElement() function to the script.
    Attention: Make sure to not click the element before you include it. In such a case, the function BrowserTtiIncludeElement() will be tied to the click function, which might result in issues during playback.
  5. Close the Browser Application, stop the recording, and save your script.
Parent topic: Creating a Test Script
Previous topic: Inserting a Verification Function
Next topic: Try Script Runs
Related concepts
Time to Interact
Related reference
Browser-Driven Measures
BrowserTtiIncludeElement Function


Try Script Runs

Once you have generated a test script, determine if the script runs without error by executing a Try Script run. A Try Script run determines if a script accurately recreates the actions that you recorded with the Browser Application-Based Recorder. It also determines if the script contains any context-specific session information that you must parameterize before the script can run error free.

With Try Script runs, only a single virtual user is run and the stress test option is enabled so that there is no think time or delay between transactions.

Note: The default option settings for browser-driven Try Script runs do not include live display of content downloaded during testing (via TrueLog Explorer), though they do include the writing of log files, report files, and replay within the Browser Application Replay window.
Parent topic: Creating a Test Script
Previous topic: Including Elements in the TTI
Next topic: Trying Out Your Test Script


Trying Out Your Test Script

  1. Click Try Script on the workflow bar. The Try Script dialog box appears with the script you created selected in the Script list and the active profile selected in the Profile list. The VUser virtual user group is selected in the Usergroup group box.
  2. Configure settings as follows:
    1. Select a Browser from the list: Internet Explorer, Mozilla Firefox, or Chrome.
    2. Enable the Visible client option so that the browser Replay window will display the web page content. Screenshots of the application state are made before each API function call.
      Note: Simulation settings are not applied when replaying your script with the browser.
    3. Enable the Step by step execution option to run your script step by step. This option is available for Internet Explorer only.
  3. Click Run.
    Note: You are not running an actual load test here, only a test run with a single virtual user to see if your script requires debugging.
    The Try Script run begins. The Monitor window opens, giving you detailed information about the run’s progress.
Parent topic: Creating a Test Script
Previous topic: Try Script Runs
Next topic: Using Step-by-Step Try Script Replay


Using Step-by-Step Try Script Replay

When you enable Step by step execution on the Try Script dialog box, you are given the option of advancing your Try Script replay one step at a time. This option is available for Internet Explorer only.

  1. Execute a Try Script run as explained above. Enable the Step by step execution option on the Try Script dialog box.
  2. Use the buttons in the Replay Window to control replay:
    • Click [image] (Replay Step) to execute the current API call.
    • Click [image] (Replay Run) to execute the remaining API calls without further interruption.
    • Click [image] (Stop Replay) to end the Try Script run.
Parent topic: Creating a Test Script
Previous topic: Trying Out Your Test Script
Next topic: Common Replay Errors


Common Replay Errors

Some typical reasons why scripts do not play accurately after recording are listed below. In such instances you will need to customize your test script.

  • Stateful scripts: Recorded scripts only work when the application under test has the same state during replay that it had during script recording. For example, a script that includes user login can only be run correctly when the application is in a logged-out state. You can work around this issue by either setting the application state by manually adding logic to your script, or you can ensure that your recorded scripts do not change application state in the first place (for example, you could include user log out during the recording of your script).
  • Temporarily generated DOM attributes: Some AJAX frameworks generate attributes that change each time a page is loaded (for example, x-auto values in ext). If a locator relies on such attributes, script replay will fail. You will need to add the attributes to the ignored attributes list to prevent them from being recorded in the future.
  • Missing mouse movements: When you are testing websites where items only appear if you are hovering with your mouse over certain elements (for example a button or a menu item), you will get an error during the replay of the script. Silk Performer cannot detect the item because the hovering event is not recorded. Menus that are built with JavaScript are a good example for such a case. However, with Silk Performer you can fix this problem during the replay of a script. In the Browser Application, you can click the Troubleshoot button when the error occurs, select Insert Mouse Move from the list, move the mouse over the UI element, press <Pause/Break> on your keyboard, click Insert, and click Rerun Script. Now the script will run without an error.
  • Calls that run into the synchronization timeout: Built-in AJAX synchronization waits until the browser is in an idle state before API calls are returned. This is a key factor in reliable testing of AJAX-based applications. However, in some situations there is no idle state (for example, if a page uses polling or keeps connections open for server-push events). In such situations the synchronization waits until it runs into a timeout. You can work around this issue by temporarily setting the synchronization mode back to HTML.
Parent topic: Creating a Test Script
Previous topic: Using Step-by-Step Try Script Replay
Related tasks
Configuring Browser-Driven Replay Settings


Analyzing Test Scripts

In contrast to the Web-protocol approach to load testing, browser-driven Web load testing uses the browser itself for script validation.

The benefits of having Try Script runs performed in the browser are as follows:

  • Live application state is presented in the browser.
  • Locator Spy functionality for advanced script modification and adaption (supported for Internet Explorer only).
  • Scripts can be executed in step-by-step mode (supported for Internet Explorer only).
  • Screenshots are captured before each browser API call and stored in the TrueLog for future analysis.

Once a Try Script run is shown to be successful in the Browser Application, you can analyze the results of the Try Script run with TrueLog Explorer. Test script analysis with TrueLog Explorer involves the following tasks:

  • Viewing Virtual User Summary Reports
  • Finding errors
  • Comparing replay test runs with recorded test runs
  1. Visual Analysis with TrueLog Explorer
    Examines the TrueLog Explorer interface and its various components.
  2. Analyzing a Test Run
    Explains how to get started using TrueLog Explorer to analyze a test run.
  3. Viewing a Summary Report
    Explains that virtual user summary reports are summary reports of individual Try Script runs that offer basic descriptions and timing averages.
  4. Displaying a Virtual User Summary Report
    You can analyze the results of a test run by viewing the run's virtual user summary report.
  5. Enabling Summary Reports
    Explains that virtual user summary reports are not generated by default because they require significant processing resources.
  6. Finding Errors in a TrueLog
    TrueLog Explorer helps you find errors quickly after Try Script runs. Erroneous requests can be examined and necessary customizations can then be made.
  7. Viewing Page Statistics
    Details the various types of Web page statistics that are available on overview pages.
  8. Viewing an Overview Page
    After verifying the accuracy of a test run, you can analyze the performance of your application via Web page statistics on an overview page.
  9. Comparing Record and Replay Truelogs
    You can identify errors in a recorded script by comparing a replay TrueLog with a corresponding recorded TrueLog.
Parent topic: Load Testing Web 2.0 Applications (Browser-Driven)


Visual Analysis with TrueLog Explorer

One of TrueLog Explorer’s most powerful features is its ability to visually render Web content that is displayed by applications under test. In effect, it shows you what virtual users see when they interact with an application.

The TrueLog Explorer interface is comprised of the following sections:

  • The Workflow Bar acts as your primary interface as you work with TrueLog Explorer. The Workflow Bar reflects TrueLog Explorer’s built-in testing methodology by supporting its five primary tasks.
  • The API Node Tree menu on the left of the interface allows you to expand and collapse TrueLog data downloaded during tests. Each loaded TrueLog file is displayed here along with links to all relevant API nodes. You can click a node to display a screen shot in the Screen pane and history details in Information view.
  • The Content pane provides multiple views of all received data.
  • The Information pane displays data regarding testing scripts and test runs, including general information about the loaded TrueLog file, the selected API node, BDL script, and statistics.
Note: To launch TrueLog Explorer from Silk Performer, choose Results > Explore TrueLog.

Parent topic: Analyzing Test Scripts
Next topic: Analyzing a Test Run


Analyzing a Test Run

  1. With the TrueLog from a Try Script run loaded into TrueLog Explorer, click the Analyze Test button on the Workflow bar. The Analyze Test dialog box displays.
  2. Proceed with one of the following options:
    • View a virtual user summary report
    • Look for errors in the TrueLog
    • Compare the replay test run to the recorded test run
Parent topic: Analyzing Test Scripts
Previous topic: Visual Analysis with TrueLog Explorer
Next topic: Viewing a Summary Report


Viewing a Summary Report

Virtual user summary reports are summary reports of individual Try Script runs that offer basic descriptions and timing averages. Each report tracks a separate virtual user and presents data in tabular format.

Virtual user summary reports include details regarding the following:

  • Virtual users
  • Uncovered errors
  • Response time information tracked for each transaction defined in a test script
  • Page timer measurements for each downloaded Web page
  • Individual timers and counters used in scripts (Measure functions)
Parent topic: Analyzing Test Scripts
Previous topic: Analyzing a Test Run
Next topic: Displaying a Virtual User Summary Report


Displaying a Virtual User Summary Report

  1. With the TrueLog generated by your Try Script run loaded into TrueLog Explorer, click the Analyze Test button.
  2. Click the Show the virtual user summary report link.
Parent topic: Analyzing Test Scripts
Previous topic: Viewing a Summary Report
Next topic: Enabling Summary Reports


Enabling Summary Reports

Because virtual user summary reports require significant processing resources, they are not generated by default. To enable the automatic display of virtual user reports at the end of animated TryScript runs (or by clicking the root node of a TrueLog file in the API Node Tree menu) enable the Display virtual user report option ( Settings > Workspace > Reports ).

Note: Virtual user reports can also be viewed within Silk Performer by right-clicking a virtual user name and selecting Show Virtual User Report File.
Parent topic: Analyzing Test Scripts
Previous topic: Displaying a Virtual User Summary Report
Next topic: Finding Errors in a TrueLog


Finding Errors in a TrueLog

TrueLog Explorer helps you find errors quickly after Try Script runs. Erroneous requests can be examined and necessary customizations can be made via TrueLog Explorer.

Note: When viewed in the API Node Tree menu, API nodes that contain replay errors are tagged with red “X” marks.
  1. With the TrueLog generated by your Try Script run loaded into TrueLog Explorer, click the Analyze Test button.
  2. Click the Find errors link. The Step through TrueLog dialog appears with the Errors option selected.
  3. Click Find Next to step through TrueLog result files one error at a time.
Parent topic: Analyzing Test Scripts
Previous topic: Enabling Summary Reports
Next topic: Viewing Page Statistics


Viewing Page Statistics

After verifying the accuracy of a test run, you can analyze the performance of your application under “no-load” conditions via page statistics.

Overview pages detail:

  • Action time: Total page response times, including processing and rendering in the browser.
  • Documents time: Document download times (including server busy times), and time elapsed for receipt of embedded objects.

Detailed action statistics show exact response times for individual Web page components, allowing you to easily pinpoint the root causes of errors and slow page downloads.

Because Try Script runs do not include think times, the measurements they produce cannot be used to predict real-world performance.

Detailed action statistics include the following data for each page component:

  • DNS lookup time
  • Connection time
  • Round-trip time
  • Cache statistics
Note: Compared to the protocol-based approach, browser-driven test statistics do not include certain low-level/protocol-related metrics.
Parent topic: Analyzing Test Scripts
Previous topic: Finding Errors in a TrueLog
Next topic: Viewing an Overview Page


Viewing an Overview Page

  1. From the API Node Tree menu, select the API node for which you would like to view statistics.
  2. Select Browser Nodes on the Step through TrueLog dialog box.
  3. Click the Statistics tab to open Statistics view.
  4. Select specific components listed in the URL column for detailed analysis and page drill-down.
Parent topic: Analyzing Test Scripts
Previous topic: Viewing Page Statistics
Next topic: Comparing Record and Replay Truelogs


Comparing Record and Replay Truelogs

With Web application testing, TrueLog Explorer shows the actual Web pages that are received during tests. Live monitoring of downloaded data is available via TrueLog Explorer animated mode. Data is displayed as it is received during testing.

By comparing a TrueLog that has been generated during the script development process alongside the corresponding TrueLog was recorded originally, you can verify that the test script runs accurately.

  1. Click the Analyze Test button on the Workflow Bar. The Workflow - Analyze Test dialog box appears.
  2. Click Compare your test run.
  3. The corresponding recorded TrueLog opens in Compare view and the Step through TrueLog dialog box appears with the Browser Nodes option selected, allowing you to run a node-by-node comparison of the TrueLogs.
  4. Click the Find Next button to step through TrueLog result files one page at a time.
    Note: Windows displaying content presented during replay have green triangles in their upper left corners. Windows displaying content originally displayed during application recording have red triangles in their upper left corners.
Parent topic: Analyzing Test Scripts
Previous topic: Viewing an Overview Page


Configuring Project Profile Settings

Silk Performer offers a variety of browser-driven Web load-testing profile settings. Web (browser-driven) profile settings are project-specific settings that relate to synchronization and object locator generation. These settings are specified on a per-project basis.

Note: For the purposes of this tutorial, you do not need to change the default settings.
  1. Configuring Browser-Driven Recording Settings
    You must configure active profiles settings before you begin recording.
  2. Configuring Browser-Driven Replay Settings
    Before recording your script you must configure synchronization and simulation settings for the active profile.
Parent topic: Load Testing Web 2.0 Applications (Browser-Driven)


Configuring Browser-Driven Recording Settings

  1. Right-click the Profiles node in the Project tree menu and select Edit Active Profile. The Profile - [Profile1] - Simulation dialog box displays at the Simulation tab (Replay category).
  2. Click Record.
  3. Scroll down and select Web (Browser Driven).
  4. Select the Recording tab.
  5. DOM attribute names to ignore: In this field, type any DOM attribute names that should be ignored during recording. Separate the names with commas. Attribute names that match any pattern in the Ignored DOM attribute names field will be ignored during recording.
  6. DOM attribute values to ignore: In this field, type any DOM attribute values that should be ignored during recording. Separate the values with commas. Attribute values that match any pattern in the Ignored DOM attribute values field will be ignored during recording.
  7. DOM attribute names to prefer: In this field, configure the names of the custom attributes that are recorded.
  8. Maximum length of DOM attribute values: In this field, set the maximal length of an attribute value. If the value is longer than specified, it will be cut off. The cut off part will be replaced by an asterisk (*). For example: The length is set to 10. The textContent value of Some long text content is cut to @textContents='Some long *' in the locator.
  9. Click OK.
Parent topic: Configuring Project Profile Settings
Next topic: Configuring Browser-Driven Replay Settings
Related concepts
Web (Protocol Level) Settings


Configuring Browser-Driven Replay Settings

  1. In the Projects tree menu, right-click the Profiles node and select Edit Active Profile. The Profile - [Profile1] - Simulation dialog box opens at the Simulation tab.
  2. Click the Replay category button.
  3. Scroll down to and select Web (Browser Driven). The Web (Browser Driven) / General tab displays.
  4. Select the browser you want to use for this settings profile from the list.
  5. Use the Simulation group box to set options for realistic simulation of users visiting Web sites:

    • Click the First time user option button to generate a realistic simulation of users who visit a Web site for the first time.

      Persistent connections will be closed, the Web browser emulation will be reset, and the document cache, the document history, the cookie database, the authentication databases, and the SSL context cache will be cleared after each transaction. In such instances, Silk Performer downloads the complete sites from the server, including all files.

    • Click the Revisiting user option button to generate a realistic simulation of users who revisit a Web site. Non-persistent sessions will be closed, but the document history, the persistent cookie database, and the context cache will not be cleared after each transaction. In such cases, pages are not downloaded if they exist in the document cache.

    • Select the IE Compatibility Mode to define the rendering mode that Internet Explorer (IE) uses to display automatic replaying on the user's Web browser. The Default value depends on the user's Internet Explorer browser version.
    Note: Simulation settings are not applied when replaying your script with the Browser Application. However, all caching settings that you configure within Internet Explorer's Internet options will be applied to your browser-driven tests.
  6. Select a replay compatibility to define how locators are generated. Setting this option ensures flawless replay of older scripts with newer versions of Silk Performer and therefor helps to avoid compatibility issues. You can also define the replay behavior for every single script by manually scripting the BrowserReplayCompatibility function.
  7. Ensure that the Legacy input mode setting is disabled.
  8. Click the Synchronization tab.
  9. Configure Synchronization settings as required.
    • The Synchronization mode option configures the algorithm that is used to wait for the ready state of a browser invoke call (pre and post invocation).
    • The Synchronization timeout option configures the maximum time in milliseconds that is used to wait for an object to be ready (pre and post invocation).
    • In the URLs to exclude from synchronization text box, type the entire URL or a fragment of the URL for any service or Web page that you want to exclude. Some AJAX frameworks or browser applications use special HTTP requests, which are permanently open in order to retrieve asynchronous data from the server. These requests may let the synchronization hang until the specified synchronization timeout expires. To prevent this situation, either use the HTML synchronization mode or specify the URL of the problematic request here. Separate multiple entries with a comma.
    • The Object resolve timeout option configures the maximum time in milliseconds to wait for an object to be resolved during replay.
    • The Object resolve retry interval option configures the time in milliseconds after which another replay attempt should be made following an object not resolving.
  10. Click OK.
Parent topic: Configuring Project Profile Settings
Previous topic: Configuring Browser-Driven Recording Settings
Related concepts
Web (Protocol Level) Settings


Advanced Concepts for Browser-driven Tests

  • Defining Browser Window Dimensions for Recording
    Explains that defining specific browser-window dimensions for recording enables you to record screenshots that can be compared alongside comparably sized replay screenshots during TrueLog analysis.
  • Testing Websites That Use Non-system Codepage Characters
    Explains how Silk Performer converts non-displayable characters to enable browser-driven load testing of websites that use such characters.
  • Time to Interact
    Measuring the user experience of AJAX websites can be difficult for a number of reasons. Therefore, Silk Performer provides the Time to Interact.
Parent topic: Load Testing Web 2.0 Applications (Browser-Driven)


Defining Browser Window Dimensions for Recording

Launch the Browser Application for browser-driven load testing .

Note: Browser dimensions can only be defined during script recording.
  1. To define specific browser-window dimensions for recording, go to View > Resize Browser Window. The Resize Browser Window dialog box is displayed.
  2. Specify a Width setting (in pixels).
  3. Specify a Height setting (in pixels).
  4. Click OK.
Parent topic: Advanced Concepts for Browser-driven Tests


Testing Websites That Use Non-system Codepage Characters

Silk Performer is a multibyte character set (MBCS) based application. When you use browser-driven load testing, you must set the correct system codepage. This ensures that the characters displayed on the website are processed correctly.

To enable browser-driven load testing of websites that use non-displayable characters, Silk Performer converts these characters. For example: The following string is converted to a set of numbers:

The numbers represent the Unicode value of each character in the hexadecimal format. When you replay a script, Silk Performer converts the string back and uses it while driving the browser.

Note: Silk Performer applies the conversion only in Browser-Driven API calls. Do not use non-displayable characters in other API calls.
Parent topic: Advanced Concepts for Browser-driven Tests


Time to Interact

Testing AJAX websites is challenging

Measuring the user experience of AJAX websites with the timings the browser provides can be difficult. A user can consider a web page as ready, although the processing in the background is not yet completed. Also, the processing might be completed, but the web page is not yet ready for the user at that point in time. Essential page elements might be loaded asynchronously, that is after the onLoad Function phase and during the Asynchronous Application Logic phase. In such a case, the perceived loading time of a web page can differ considerably from the measured loading time. As a result, Silk Performer introduced the so-called Time to Interact (TTI).

The Time to Interact

In Silk Performer terminology, the Time to Interact is defined as the time from a user interaction (such as navigating to a URL or a click on a link) until all relevant elements a user requires to interact with the page are ready; even if the page has not yet completely loaded. Identifying the relevant elements of a page can not simply be automated, as it heavily depends on the use case and on the perspective which elements to consider relevant. For example: A web shop company can test their website from their own perspective and from the perspective of their customers. From the company-perspective, the elements that contain the special offers might be considered relevant. But from the customer-perspective, just the search field might be considered relevant.

Therefore, the performance engineer has to tag all TTI-relevant elements during recording. The Recorder then generates a BrowserTtiIncludeElement() function for each of these tagged elements. During replay, Silk Performer measures how long it takes to load each TTI-relevant element and reports the maximum as the Time to Interact.

Browser-driven Measures

For browser-driven tests, Silk Performer provides the following measures:

Measure | Description
Dom interactive | Reflects the time span from the request until the browser has completed parsing all HTML elements and constructing the DOM.
Dom complete | Reflects the time span from the request until the browser has completed downloading and processing all resources (images, stylesheets, scripts, and so on).
Load End | Reflects the time span from the request until the browser has completed executing the onLoad function. As a final step in every page load process the browser sends an onLoad event, which triggers the onLoad function. Once the onLoad functions are executed, additional application logic might be executed.
First paint | Reflects the time span from the request until the page begins to display. This measure is available for Internet Explorer only.
Time to interact | Reflects the time span from the request until all TTI-relevant elements are available on the page. At this point in time, the user can interact with the web page.
Action time | Reflects the time span from the request until the browser has completed downloading and processing all resources. The end of this time span varies, depending on the defined synchronization mode: If the synchronization mode HTML is defined, the action time ends when the onLoad function is completed. If the synchronization mode AJAX is defined, the action time ends during the Asynchronous Application Logic phase.
Note: DOM interactive, DOM complete, and Load end can be described as consecutive events. These events all end during the Processing phase. In contrast, First paint and Time to interact are completely website-dependent; they can end in the HTTP Response phase, in the Processing, and in the Asynchronous Application Logic phase.
Important: When the TTI feature is being used, the other measures listed here might not be available or might show incorrect values.
Parent topic: Advanced Concepts for Browser-driven Tests
Related tasks
Including Elements in the TTI
Related reference
Browser-Driven Measures
BrowserTtiIncludeElement Function


Troubleshooting Browser-Driven Load Testing Issues

Learn how to start the perfrun process using an actual user account, handle client certificates, and exclude specific URLs from AJAX synchronization.
Note: Browser-driven load testing is supported for Internet Explorer 11.
  • Browser-Driven Virtual Users on Remote Agents
    Starting the perfrun process with an actual user account rather than the system account avoids the issue of recorded traffic differing from generated traffic.
  • Recommended Internet Explorer settings on agents
    When executing browser-driven load tests using Internet Explorer, make sure that the Internet Explorer installation on your agents is set-up as described in this topic.
  • Handling Client Certificates
    Learn how to handle client certificates for browser-driven load testing.
  • Removing Certificate Errors
    Resolve certificate errors before you can record a Web site browser-driven.
  • Excluding URLs from AJAX Synchronization
    To better facilitate the testing of AJAX-based Web applications, specific URLs can be excluded from browser synchronization.
  • Limitations for Replay with Different Browsers
    Describes a number of areas where you might encounter issues, when you replay browser-driven scripts with different browsers. Many of the described limitations are corner cases and rarely occur.
Parent topic: Load Testing Web 2.0 Applications (Browser-Driven)


Browser-Driven Virtual Users on Remote Agents

Starting a remote agent with an actual user account rather than the system account, which is the default, makes a big difference for browser-driven virtual users. Each virtual user employs its own Internet Explorer instance, which loads the settings stored in the Microsoft Windows user's profile.

Under the system account, Internet Explorer loads different settings than under a user account. Typically Internet Explorer utilizes fewer or different HTTP headers than with user accounts. In order to avoid the issue of recorded traffic differing from generated traffic, it is recommended to run remote agents under a user account.

Note: Ensure that the specified user account is a member of the Remote Desktop Users Windows group on the remote agent.

The required account setting can be configured in System Configuration Manager on the Applications tab or a user account can be set in the System Settings > Agents > Advanced tab if all remote agents should run under the same user account.

Parent topic: Troubleshooting Browser-Driven Load Testing Issues
Related tasks
Using a Particular User Account for All Agents
Using a Particular User Account for a Single Agent


Recommended Internet Explorer settings on agents

When executing browser-driven load tests using Internet Explorer, make sure that the Internet Explorer installation on your agents is set-up as described below. Otherwise, you might experience issues during replay.

  • In Internet Explorer, open the Internet Options and set the home page to about:blank.
  • In the Internet Options, on the Advanced tab, in the Security section ...
    • disable Check for publisher's certificate revocation
    • disable Check for server certificate revocation
    • disable Warn about certificate address mismatch
  • In the Internet Options, on the Security tab, do the following for each zone (Internet, Local intranet, Trusted sites, Restricted sites):
    • uncheck Enable Protected Mode
    • set the lowest possible security level
  • In Internet Explorer, in the Compatibility View Settings ...
    • disable Display intranet sites in Compatibility View
    • disable Use Microsoft compatibility lists
    • remove all added websites
  • On Windows Server operating systems, open the Server Manager and disable the IE Enhanced Security Configuration (IE ESC).
Parent topic: Troubleshooting Browser-Driven Load Testing Issues


Handling Client Certificates

The following applies only, when you use Internet Explorer.

You can select a client certificate during script recording. Client certificates facilitate authentication against certain Web sites. APIs are now available for importing certificates to and deleting certificates from the Microsoft certificate store, which is used by Internet Explorer and the Silk Performer browser-driven load testing feature.

The certificate APIs work with Microsoft Windows 7 or later, Microsoft Windows Server 2008 R2 or later, and Internet Explorer 8 or later.

Certificate handling for browser-based Web load testing works independently of certificate handling for protocol-based Web testing. This means that certificates need to be imported manually via Internet Explorer's Internet Options menu entry (or the management console snap-in certmgr.msc). If authentication works with Internet Explorer 8 it will also work for browser-based load testing.

  1. When importing your certificate, disable strong private key protection:
    1. On the Certificate Import wizard Password page, uncheck the Enable strong private key protection checkbox.
  2. Disable server certificate revocation:
    1. Open Internet Explorer's Tools menu and select Internet Options. The Internet Options dialog opens.
    2. Click the Advanced tab.
    3. Uncheck the Check for server certificate revocation* checkbox.
    4. Click OK.
  3. Activate prompting of the client certificate selection dialog box:
    1. Open Internet Explorer's Tools menu and select Internet Options. The Internet Options dialog opens.
    2. Click the Security tab.
    3. Click Custom Level... The Security Settings page opens.
    4. Scroll down to Don't prompt for client certificate selection when no certificates or only one certificate exists and select the Disable option box.
    5. Click OK.
    6. Restart Internet Explorer.
Parent topic: Troubleshooting Browser-Driven Load Testing Issues
Related tasks
Using a Particular User Account for a Single Agent


Removing Certificate Errors

The following applies only, when you use Internet Explorer.

During recording a Web page may appear with the message There is a problem with this website's security certificate. Additionally the Continue to this website (not recommended) link does not work. Certificate errors can occur due to multiple reasons and you must resolve any certificate errors before you can record a Web site browser-driven. For more information on certificate errors, visit About certificate errors.

One of the more common problems is an address mismatch. To disable address-mismatch warnings:

  1. Open Internet Explorer's Tools menu and select Internet Options. The Internet Options dialog opens.
  2. Click the Advanced tab.
  3. Uncheck the Warn about certificate address mismatch* checkbox.
  4. Click OK.
  5. Restart Internet Explorer.
Parent topic: Troubleshooting Browser-Driven Load Testing Issues


Excluding URLs from AJAX Synchronization

To better facilitate the testing of AJAX-based Web applications, specific URLs can be excluded from browser synchronization.

To illustrate the value of this, imagine that an application displays server time by polling data from the server. This service requires a constant stream of traffic between the client and the server. This presents a challenge to AJAX synchronization because the application never goes into an idle state. By excluding this service from synchronization, other application processes that use different services can be accurately tested.

  1. Right-click a profile in the Project menu tree and select Edit Profile. The Profile - Simulation window opens.
  2. In the Replay group box, click the down arrow to scroll down. Click Web (Browser Driven).
  3. Select the Synchronization tab.
  4. Enter URLs to be excluded into the URLs to exclude from synchronization text field.
  5. Click OK.
Note: When URL exclusion is not feasible due to there being multiple processes running within a single service, you need to disable AJAX synchronization and switch to HTML mode.
Parent topic: Troubleshooting Browser-Driven Load Testing Issues


Limitations for Replay with Different Browsers

Silk Performer uses Internet Explorer to record browser-driven scripts. To replay these scripts, you can use either Internet Explorer, Firefox, or Chrome.

Although these browsers basically resemble each other, they can behave quite differently in a variety of circumstances. This can also result in different behavior, when replaying the very same script with different browsers.

Below you can find a number of areas where you might encounter differences or issues. Note that many of the described issues are corner cases and rarely occur. Also note that the limitations heavily depend on your specific use case and on the application under test, including the underlying frameworks. Therefore, it is not possible to describe every potential limitation in every detail. If you encounter a specific limitation and need more information, contact SupportLine.

Mouse clicks

When replaying scripts, mouse clicks are processed differently in different browsers. Or in other words: The application under test receives different click events, depending on the used browser. For example: Replaying a double-click, raises a click and a double-click event in Internet Explorer and Firefox - this is the default behavior. But replaying a double-click in Chrome, raises just a double-click event.

Here is another example: When replaying a script in Chrome, the right-click event fails when the center of the clicked element is not visible. But in Internet Explorer and Firefox, the right-click event works flawlessly, even if the center of the clicked element is obscured.

Key strokes

Using key strokes within browsers also results in different behavior. For example: When the cursor is placed within a text field within Internet Explorer and you press the Esc key, everything you have typed so far is being removed. Pressing the Esc key in the other browsers has no effect. Another example is that Firefox and Chrome do not differentiate between the Return key and the Enter key on the numpad, while Internet Explorer does.

Locators

A browser might use an element attribute that the other browsers do not use. For example: Internet Explorer uses spellcheck as a generic attribute that exists for every element, while Chrome and Firefox only use the attribute when it is explicitly specified. Since Internet Explorer is used for recording the script, this results in an error when the script is replayed with Chrome or Firefox.

New windows

When your application under test uses a number of short-lived pop-up windows, this might result in unstable behavior. Here is a real-world example that might cause issues: You click a link that opens a pop-up window. This window immediately triggers another window to open, and then it closes again. When you use Firefox or Chrome, the window might be missed during replay. A possible workaround is to use the custom function BrowserWaitForNewWindowWithLocator, which is located in the BrowserAPI.bdh.

Invalid URLs

When you navigate to an invalid URL, Internet Explorer raises an error, while Chrome and Firefox do not. This can be problematic when monitoring a URL. The monitor will never raise an error, although the URL cannot be reached. For such a case, it can be useful to add a verification function to your script.

Measures

Due to the diverse replay technologies and the different architectures of the applications under test, some measures might be missing. For example: Some traffic might not be considered, because the application under test uses redirects or iframes.

Alert handling

When you use Firefox or Chrome to replay scripts, only JavaScript alerts and prompts can be handled. Native dialogs, like the file save or file open dialog, are not supported.

Compatibility mode

Scripts that are created using Silk Performer 18.5 or an earlier version, use a different replay compatibility mode. You can set the compatibility mode in the profile settings or by using the BDL function BrowserReplayCompatibility.

In the past, locators used to be tailored to Internet Explorer, because it was the only supported browser. Thus, the locators used in these older scripts might cause replay issues.

Parent topic: Troubleshooting Browser-Driven Load Testing Issues


Testing Apps for Mobile Devices

  • Mobile Apps Overview
    Provides an overview of Silk Performer's support for testing mobile applications.
  • Recording Mobile Apps Using Mobile Devices
    If your mobile device supports a configurable proxy, record apps directly via your mobile device.
  • Recording Mobile Apps With a Browser
    Have Silk Performer model your test script automatically by recording a mobile application.
  • Recording Mobile Apps With a Mobile Emulator
    Have Silk Performer model your test script automatically by recording a mobile application with a mobile emulator.
  • Replaying Apps for Mobile Devices
    Simulate transactions as virtual mobile device users to test applications for mobile devices.
Parent topic: Load Testing Specific Application Types


Mobile Apps Overview

Due to smaller screen size and different input methods (touch screen) of mobile devices, many Web applications look different when loaded on a mobile device compared to a browser on a PC. From a load testing perspective such applications should be treated as two separate applications, even though they might share some components on the back-end.

Silk Performer fully supports performance testing of mobile Web and native apps. It offers simulation capabilities for a variety of mobile devices, such as iPhone, iPad, Android, Windows Phone, and Blackberry, but other mobile browsers can also be simulated with custom profiles.

An interesting and important simulation parameter for mobile app testing is the bandwidth limitation. This option is not significant for usual Web testing via PCs due to the fast wired (broadband) internet connections, however for real world simulation of mobile devices it makes a real difference to set the bandwidth to particular limits. Silk Performer offers many standard bandwidth limitation settings used in the mobile world, such as EDGE, HSDPA, or LTE.

Parent topic: Testing Apps for Mobile Devices


Recording Mobile Apps Using Mobile Devices

Things to consider when recording via a mobile device:
  • Disable security warnings in the browser of your mobile device
  • Disable "String completion" in the browser of your mobile device, otherwise a Web call will be scripted after each key press
  • Delete your browser's cookies before attempting to record a script
  • Operating system-specific instructions for your specific device are easy to find on the internet using your favorite search engine
To test mobile device apps, the recommended option is to record apps directly via your mobile device if it supports a configurable proxy.
  1. Click Start Here on the workflow bar. The Outline Project dialog box appears.
  2. In the Name text box, enter a name for your project.
  3. Enter an optional project description in Description.
  4. In the Type menu tree, select Web Browser > Mobile Devices.
  5. Click Next to create a project based on your settings.
  6. On the Workflow - Model Script dialog box, click Record via mobile device. The Record via mobile device dialog box appears.
  7. On your mobile device, configure the browser to use the IP address and port of the machine where Silk Performer is installed as proxy. Enter the information as it is displayed in the table on the Record via mobile device dialog box.
    Note: Configuring your mobile device's browser proxy settings depends on the device and operating system that you are using. Instructions for your specific device are easy to find on the internet using your favorite search engine.
  8. When you are done with configuring your mobile device's browser proxy settings: If you have already configured a certificate or if you do not need to record over a secure connection, click Start recording and skip the following step. If you want to record over a secure connection and you have not yet configured the Micro Focus CA (certificate authority) certificate or the certificate of your system under test, click Record over a secure connection on the Workflow - Model Script dialog box and proceed with the following step.
  9. On the Configure secure recording dialog box, select if you want to use the Micro Focus CA (certificate authority) certificate or if you want to use the certificate of your system under test. If you are unsure which approach to use, refer to Secure Connections and Certificates.
    If you selected Configure Micro Focus certificate:
    1. The Silk Performer Recorder dialog opens in minimized form and the Record a secure connection with the Micro Focus CA certificate dialog box appears.
    2. Scan the QR code and install the certificate on your mobile device.
    3. When you are done, click OK on the Record a secure connection with the Micro Focus CA certificate dialog box.
    If you selected Configure server certificate:
    1. In the Server certificate field, locate the server certificate you want to use.
    2. In the Pass phrase field, enter the pass phrase that is to be used, if the server certificate you want the Recorder to use is protected with a pass phrase.
    3. Optional: Check the Send root CA during SSL handshake check box to have the Recorder send the root CA certificate during the SSL handshake. The root CA certificate may be requested by a client to authenticate the certificate authority that signed the Recorder server certificate.
    4. Optional: In the Root CA certificate field, locate the root CA certificate that you want to use.
    5. After you have completed configuring the server certificate, click Start recording.
  10. Now interact with the Web browser or the native app on your mobile device to record a script.
  11. When you are done, click Stop Recording in Silk Performer Recorder and save the recorded script.
Parent topic: Testing Apps for Mobile Devices


Recording Mobile Apps With a Browser

  1. Click Start Here on the workflow bar. The Outline Project dialog box appears.
  2. In the Name text box, enter a name for your project.
  3. Enter an optional project description in Description.
  4. In the Type menu tree, select Web Browser > Mobile Devices.
  5. Click Next to create a project based on your settings.
  6. On the Workflow - Model Script dialog box, type the URL of the application under test in the URL text box. Option: Click Analyze web page to find visual breakpoints for your web application.
  7. Click Certificate... if you want to use the certificate of your system under test. If you are unsure which approach to use, refer to Secure Connections and Certificates.
  8. Click record using customized browser. The Record an application using a customized browser dialog box appears.
  9. Select a Simulation Browser. Due to the multitude of technologies that browser-based applications are based on, different recording types are available for selection.
    Note: Click Settings to change the recording profile used for recording in Silk Performer profile settings (Settings > System > Recorder > Recording Profiles).
  10. Select a predefined mobile device or a custom resolution and click Start recording.
  11. Using the client application, conduct the kind of interaction with the target server that you want to simulate in your test. The interaction is captured and recorded by the Recorder. A report of your actions and of the data downloaded appears on the Actions page.
  12. To end recording, click the Stop Recording button.
  13. Enter a name for the .bdf file and save it. The Capture File page displays. Click Generate Script to generate a script out of the capture file.
Parent topic: Testing Apps for Mobile Devices


Recording Mobile Apps With a Mobile Emulator

Recording mobile apps with an emulator follows the standard workflow, however you need to set up and configure an operating system-specific emulator on your computer where you record your test. Example procedures can be found in the community wiki:
  • Recording Mobile Apps on the Android Emulator with Silk Performer
  • Mobile App Recording with Silk Performer and the Windows Phone Emulator
Parent topic: Testing Apps for Mobile Devices


Replaying Apps for Mobile Devices

Simulate transactions as virtual mobile device users to test applications for mobile devices.
  1. In the menu bar, click Settings > Active Profile . The Profile dialog box appears.
  2. Click Replay and Internet. In the Bandwidth Simulation section, define the required bandwidth configuration. For mobile traffic simulation one of the following might be appropriate:
    • GPRS
    • EDGE
    • UMTS
    • HSDPA
    • HSPA+
    • LTE
  3. Click Web to select a mobile device. The following mobile device settings are available:
    • iPhone
    • iPad
    • Android
    • Windows Phone
    • Blackberry
    Note: If you need a different mobile browser type, you can use the Custom option to specify your browser's parameters.
  4. Follow the remaining workflow steps to define your workload and run the test.
Parent topic: Testing Apps for Mobile Devices


Responsive Web Design Testing

Responsive web design (RWD) is a design paradigm for web applications that allows to dynamically adapt the user interface to the physical conditions of the end user device.

In other words: A web application renders its user interface differently depending on the viewport of the browser. For example, a web page with a three column layout on a desktop monitor might switch to a two column layout on a tablet and a single column layout on a mobile phone. Or the application switches from a one column layout in portrait orientation to a two column layout in landscape orientation.

Nicely applied RWD patterns also allow to optimize a web page in terms of resources. A low resolution viewport makes the application display low resolution images, whereas on a high resolution screen the same application loads a high resolution version of the embedded images.

For load testing, RWD means that testing an application from more than the one usual end user perspective becomes necessary. Beside different user groups, different browsers, and different network conditions, you also need to consider the end user device or viewport, which adds another dimension in test combinations.

Parent topic: Load Testing Specific Application Types


BMC Remedy IT Service Management Support

The workflow for testing BMC Remedy IT Service Management with Silk Performer is the same as the workflow for testing Web-based applications, with the following exceptions:

  • On the Workflow - Outline Project dialog, you must select the Remedy version under test (these settings are grouped under the ERP/CRM node).
  • On the Workflow - Model Script dialog, you enter the commandline path to the Remedy installation under test.
  • Recorded scripts include a number of WebRemedy functions, which are modified WebPagePost and WebPageUrl calls.
  • In the Forms section of test scripts, each Web form contains an XML fragment that is a visualization of the Remedy traffic that was generated by the browser. This XML visualization of the browser traffic is easier to read than actual Remedy traffic. It also facilitates Silk Performer script customization. The actual, originally recorded Remedy traffic is commented at the end of each Web form XML fragment.

BMC Tutorial

BMC has created an excellent tutorial that illustrates how to load test BMC Remedy IT Service Management (ITSM) applications with BMC Remedy Action Request System (AR System). To obtain the tutorial, contact BMC and request the following white paper: Performance Benchmarking Kit: Using Incident Management with Silk Performer .

Licensing

A premium virtual user license is required to test Remedy with Silk Performer.

TrueLog Support

TrueLog functionality is not supported for Remedy testing.

Data Representation in Silk Performer

Remedy uses a proprietary format for data that is sent from the client to the server. This format includes length prefixes and makes customization difficult.

For example:

157/GetTableEntryList/11/smi-web-00126/
SMI:TEL35:SHR:AgentConsole12/Windows_View9/53687098211/
smi-web-00127/SMI:TEL35:SYS:IncomingEmail0/
1/01/02/0/0/2/0/2/0/2/0/

Such data is sent in HTTP requests to the URL http://<hostname>/arsys/BackChannel.

Remedy versions 6.3 patch level 2 and earlier send such data in the body of HTTP POST requests. Versions 6.3 and later send such data in the query string of HTTP GET requests.

The main benefit of Silk Performer’s Remedy add-on is that this proprietary data format is translated into an XML-based representation that eliminates the length prefixes and introduces names to the individual data items. This makes scripts easier to understand and customize. During script replay, this XML-based format is transparently translated back into the original format.

This backward transformation is performed by the functions WebRemedyBackChannelUrl and WebRemedyBackChannelPost.

WebRemedyBackChannelUrl is a replacement for the function WebPageUrl, while WebRemedyBackChannelPost is a replacement for the function WebPagePost.

For example, without the Remedy add-on the following API call would be recorded as:

WebPagePost("http://213.131.176.85/arsys/BackChannel",
    "157/GetTableEntryList/11/smi-web-00126/
SMI:TEL35:SHR:AgentConsole12/W"
    "indows_View9/53687098211/smi-web-00127/
SMI:TEL35:SYS:IncomingEmail0/1"
    "/01/02/0/0/2/0/2/0/2/0/",
    STRING_COMPLETE,
    "text/plain; charset=UTF-8",
    "arsys/BackChannel");

With the Remedy add-on the API call is recorded as follows:

WebRemedyBackChannelPost("http://213.131.176.85/arsys/BackChannel",
"<?xml version='1.0'?>\r\n"
"<SegueRemedyXml
operation=\"GetTableEntryList\">\r\n"
"  <string name=\"table_server\">smi-web-001</string>\r\n"
"  <string name=\"table_schema\">SMI:TEL35:SHR:AgentConsole</string>\r\n"
"  <string name=\"table_vui_name\">Windows_View</string>\r\n"
"  <long name=\"table_field_id\">536870982</long>\r\n"
      "  <string name=\"server\">smi-web-001</string>\r\n"
"  <string name=\"schema\">SMI:TEL35:SYS:IncomingEmail</string>\r\n"
      "  <string name=\"app_name\"></string>\r\n"
      "  <long name=\"start_row\">0</long>\r\n"
      "  <long name=\"num_rows\">0</long>\r\n"
"  <Array name=\"sort_order\"></Array>\r\n"
      "  <string name=\"qualification\"></string>\r\n"
"  <Array name=\"qual_field_ids\"></Array>\r\n"
      "  <Array name=\"qual_field_values\"></Array>\r\n"
      "  <Array name=\"qual_field_types\"></Array>\r\n"
"</SegueRemedyXml>",
      STRING_COMPLETE,
"text/plain; charset=UTF-8",
      "BackChannel - GetTableEntryList");

The key differences are:

  • Use of the function WebRemedyBackChannelPost instead of WebPagePost.
  • Data is in XML format instead of the original format.
  • XML format does not contain length prefixes, which would otherwise have to be considered during script customization.
  • XML format specifies data type and meaningful names for each data item.

Additional Remedy Add-On Benefits

In addition to the different representation of the data there are other benefits to using the Remedy add-on:

  • Remedy.bdh: A bdh file that implements the functions WebRemedyBackChannelPost, WebRemedyBackChannelUrl and WebRemedyInit.
  • The recorder places a call to the function WebRemedyInit() in the TInit transaction.
  • The function WebRemedyInit() installs verifications to catch application-level errors.
  • The recorder detects all timestamps which would otherwise be hard coded into the script, and records the function GetTimeStamp() instead.
  • The recorder records parsing functions for IDs of newly created entities and appropriate substitutions for all occurrences of such IDs in the script with the parsed variable.

Remedy SilkEssential

The Remedy application type is triggered through a SilkEssential package. It contains a set of recording rules and a remedy.bdh. The remedy.bdh wraps the WebPageCalls:

// wrapper function for WebPagePost
// param nDataLength will be ignored
function WebRemedyBackChannelPost(sUrl        : string;
                                  sData       : string;
                                  nDataLength : number optional;
                                  sContent    : string optional;
                                  sTimer      : string optional;
                                  formUrl     : form optional) : boolean <API_FUNCTION>
  begin
    WebRemedyBackChannelPost := WebPagePost(sUrl, RemedyBackChannelData(sData),
    STRING_COMPLETE, sContent, sTimer, formUrl);
  end WebRemedyBackChannelPost;

and

// wrapper function for WebPageUrl for use with BackChannel requests
  function WebRemedyBackChannelUrl(sUrl :    string;
                                   sTimer :  string optional;
formUrl : form optional) : boolean <API_FUNCTION>
  var
sXmlData : string(100000);
sDummy   : string;
begin
WebFormExpand(formUrl, sDummy, 1, true);
WebFormValueGet(formUrl, sXmlData, sizeof(sXmlData), "param");
WebFormValueSet(ARSYS_BACKCHANNEL_INTERNAL_HELPER, "param", RemedyBackChannelData(sXmlData));
WebRemedyBackChannelUrl := WebPageUrl(sUrl, sTimer, ARSYS_BACKCHANNEL_INTERNAL_HELPER);
end WebRemedyBackChannelUrl;
dclform
ARSYS_BACKCHANNEL_INTERNAL_HELPER <ENCODE_URICOMPONENT> :
    "param"                     := "";

Protocol Detection and Conversion

Remedy protocol detection is not available by default. However, it is already built into the Silk Performer recorder and is enabled by choosing the appropriate Remedy application type when creating a new project.

The Remedy data conversion into XML and back out of XML is implemented in the ProxyEngine for recording and in the perfRemedy.dll, which is loaded into the perfRun by the Remedy.bdh.

Parent topic: Load Testing Specific Application Types
Related concepts
Modeling Scripts
Related tasks
Outlining a Project


Citrix XenApp Support

Silk Performer provides record and replay support for the testing of applications that are hosted via Citrix XenApp session and application virtualization technologies.

Citrix facilitates real-time access to shared applications over networks and the Internet. Remote access to Citrix-enabled applications can be over DSL, T1, ISDN, or dial-up. Citrix enables multiple users to run shared applications simultaneously. Communication between Citrix plug-ins (clients) and servers consists of exchange of user inputs (keyboard/mouse) and screen shots.

Silk Performer supports both Citrix server recording and Citrix hosted application recording. Citrix plug-ins offer access to specific applications and multiple desktop windows.

The Citrix Web Interface enables users to access hosted XenApp applications and XenDesktop virtual desktops without connecting directly to host computers. Users access these resources either via a Web browser or the Citrix online plug-in.

Silk Performer offers two Citrix project types:

  • Citrix - Used to test hosted applications that are accessed via Citrix plug-ins (clients)
  • Citrix Web Interface - Used to test Citrix-enabled applications that are published via Citrix Web interface
The PDF-based Citrix XenApp Tutorial walks you through the entire process of testing Citrix-enabled applications. The tutorial is available in Silk Performer at Start > All Programs > Silk > Silk Performer 21.0 > Documentation > Tutorials > Citrix XenApp .
Note: Silk Performer Help includes all of the content that is included in the Citrix XenApp Tutorial.

Citrix Program Neighborhood

Rather than relying on the Web Interface to distribute applications, earlier versions of Citrix use the Windows-based Citrix Program Neighborhood. The Citrix Program Neighborhood allows users to view a listing of all available applications that are by Citrix XenApp on-demand application delivery servers. An enumeration of available resources takes place automatically each time you launch the Citrix Program Neighborhood via the Citrix Browser Service.
Important: When applications are distributed via the Citrix Program Neighborhood you must configure the Citrix published application recording service to start on your system or the Citrix Program Neighborhood will not be able to update your applications list.
  • Defining Projects
    Explains how to create a new Citrix load test project and perform prerequisite XenApp server configurations.
  • Screen Synchronization and Verification
    Explains that screen synchronizations allow for verification of window and screen region appearances (not input values) and are inserted during script recording.
  • Trying Out a Generated Script
    Once you have generated a test script you need to determine if the script runs without error by running a TryScript run. A TryScript run will determine if a script accurately recreates the interactions you recorded.
  • Customizing User Data
    Explains that with user data customization you can make your test scripts more realistic by replacing static recorded user input data with dynamic, parameterized user data that changes with each transaction.
  • Project and System Settings
    Explains that Citrix profile settings are project-specific settings related to Citrix synchronization, logging, virtual user simulation, and client options.
  • Testing Best Practices
    This section explains many of the challenges involved in GUI-based testing.
  • Troubleshooting
    With Silk Performer you have both the record/playback option and the option of coding your test scripts manually. Each approach has its advantages and disadvantages.
Parent topic: Load Testing Specific Application Types


Defining Projects

The first step in conducting a Citrix load test is to define the basic settings for your Silk Performer project. Following that you need to perform prerequisite XenApp server configurations.

  • Configuring the Citrix client software
    Before defining a Citrix project you must install the Citrix client software (Citrix Receiver) and configure how the Citrix server is to handle time-outs.
  • Defining Your Citrix XenApp Project
    You need to specify a name, description, and application type for your Silk Performer project.
  • Creating a Citrix Plug-In Test Script
    Explains how to record user actions via Citrix XenApp plug-ins (clients) that connect directly to Citrix XenApp servers and then generate test scripts based on those actions.
  • Citrix Web Interface Sessions (NFuse)
    Explains that Citrix Web Interface makes applications accessible through a Web browser interface.
  • Citrix Script Functions
    Includes a brief description of some helpful Silk Performer Citrix functions.
Parent topic: Citrix XenApp Support


Configuring the Citrix client software

Before defining a Citrix project you must install the Citrix client software (Citrix Receiver) and configure how the Citrix server is to handle time-outs. To download the Citrix client software, navigate to http://www.citrix.com.

Configuring the Citrix server depends on the version you are using. Following is the procedure for configuring Citrix Server 4.0.

Note: To configure Citrix Server version 4.5 or higher, go to Start > Programs > Administrative Tools > Terminal Services Configuration and double-click the ica-tcp option.
  1. Go to Start > Programs > Citrix > Administration Tools and launch the Citrix Connection Configuration Tool.
  2. Double-click ica-tcp connection.
  3. On the following dialog box, click Advanced. The Advanced Connection Settings dialog box appears.
  4. Set the Disconnection timeout limit. 1 minute is the recommended timeout.
  5. Set the Idle timeout limit. 5 minutes is the recommended timeout.
  6. Select reset from the On a broken or timed-out connection drop list. If this option is not selected, sessions will remain open after replay stops due to broken or timed-out connections. This will generate replay problems when users next log into sessions as scripts will continue from the point where they left off in the previous session. In such instances sessions need to be ended manually.
Parent topic: Defining Projects


Defining Your Citrix XenApp Project

  1. Click Start here on the Silk Performer workflow bar.
    Note: If another project is already open, choose File > New Project from the menu bar and confirm that you want to close your currently open project.
    The Workflow - Outline Project dialog box opens.
  2. In the Name text box, enter a name for your project.
  3. Enter an optional project description in Description.
  4. From the Type menu tree, select Terminal Services > Citrix or Terminal Services > Citrix Web Interface. The Citrix application type uses the Silk Performer Citrix Recorder to test the delivery of Citrix-enabled applications that are accessed via any Citrix online or offline plug-in. The Citrix Web Interface application type is used to test the delivery of Citrix-enabled applications that are accessed via the Citrix Web Interface.
  5. Click Next to create a project based on your settings.
The Workflow - Model Script dialog box appears.
Parent topic: Defining Projects
Related tasks
Creating a Citrix Plug-In Test Script


Creating a Citrix Plug-In Test Script

The easiest approach to recording user actions via Citrix XenApp plug-ins (clients) that connect directly to Citrix XenApp servers and then creating a test script is to use the Silk Performer Recorder, the Silk Performer engine used for capturing and recording traffic and generating test scripts.

The Silk Performer Recorder captures and records the traffic between Citrix XenApp plug-ins and the server under test. When recording is complete, the Silk Performer Recorder automatically generates a test script based on the recorded traffic. Scripts are written in the Silk Performer scripting language, Benchmark Description Language (BDL).

  1. Click Model Script on the workflow bar. The Workflow - Model Script dialog box appears.
  2. In the Recording Profile list, select Silk Performer Citrix Recorder to record a Citrix XenApp-enabled application via the Silk Performer Citrix Recorder application. This recording profile is appropriate for testing Citrix plug-ins that connect directly to Citrix XenApp servers.
  3. Optional: If you have an ICA file that defines your server connection parameters, type the full path of the ICA file into the Command line field.
  4. Click Start recording.
  5. The Silk Performer Recorder then opens in minimized form along with the Silk Performer Citrix Recorder. If correct login credentials are not available at startup, the Connect dialog will open. The Connect dialog is also accessible via the Connect button in the upper left corner of the Silk Performer Citrix Recorder.
    Note: If you have an ICA file that defines your server connection parameters, select ICA File and browse to the ICA file to skip past all of the Login fields.
  6. On the Connect dialog in the Server field, enter the name of the Citrix XenApp server that is to be recorded.
  7. Complete the User name, Password, and Domain fields for the server under test.
  8. Type the name of the hosted application in the Application field.
  9. The Client name field enables you to specify a client name for your session. The default client name for the Citrix recorder is SP_Recorder (the default client name for the Citrix Player is SP_User_x). If you specify a different client name for recording, then a CitrixSetClientName function will be inserted into the script. In such cases you must customize the client name value, otherwise all users will use the same client name, which may lead to replay problems.
  10. Select the desired Color depth for recording.
  11. Select the desired screen Resolution for recording.
    Note: Do not change the resolution after recording your script, as replaying with a different resolution setting may cause mouse actions to fail on repositioned elements.
  12. Click Connect to begin the Citrix XenApp session.
  13. Interact with the shared desktop in the Citrix Recorder in the same way that you want your virtual users to act during the test. For example, you can click links, open applications, and enter data. Your actions will be captured and recorded by the Citrix Recorder. The Citrix Recorder supports session sharing, allowing you to start additional published applications in the existing session (by clicking Run Application on the Citrix Recorder toolbar). Click Select Window to switch between applications. The following example Citrix XenApp session includes simple Excel calculations in which the mouse and keyboard are used to open Excel, enter new data values, insert an AutoSum formula, select a screen region, edit the AutoSum formula, and close Excel.
  14. When you are done recording your Citrix XenApp session, click Stop on the Silk Performer Citrix Recorder. The Generating script progress window opens followed by the Save As dialog.
  15. Save the script with a meaningful name.
  16. A newly generated test script that is based on your recorded actions appears in the Silk Performer script editor window.
Parent topic: Defining Projects


Citrix Web Interface Sessions (NFuse)

Citrix Web Interface software (previously known as NFuse) provides Web access to Java, UNIX, and Windows applications that are hosted via Citrix application server software. While Citrix offers server-side control of hosted applications, Citrix Web Interface makes applications accessible through a Web browser interface (Internet Explorer, version 5.5. or higher).

For technical support and questions regarding Citrix Web Interface, go to http://support.citrix.com

  1. Defining a Citrix Web Interface Project
    Explains the basic steps involved in creating a Citrix Web Interface project.
  2. Creating a Citrix Web Interface Test Script
    Explains how to record user actions via a Citrix Web Interface and then generate test scripts based on those actions.
Parent topic: Defining Projects


Defining a Citrix Web Interface Project

  1. Click Start here on the Silk Performer workflow bar.
    Note: If another project is already open, choose File > New Project from the menu bar and confirm that you want to close your currently open project.
    The Workflow - Outline Project dialog box opens.
  2. In the Name text box, enter a name for your project.
  3. Enter an optional project description in Description.
  4. In the Type menu tree, select Terminal Services > Citrix Web Interface.
  5. Click Next to create a project based on your settings.
The Workflow - Model Script dialog box appears.
Parent topic: Citrix Web Interface Sessions (NFuse)
Next topic: Creating a Citrix Web Interface Test Script


Creating a Citrix Web Interface Test Script

The easiest approach to creating a test script for a Citrix Web Interface session is to use the Silk Performer Recorder, the Silk Performer engine for capturing and recording traffic and generating test scripts.

The Silk Performer Recorder captures and records traffic between a Citrix Web Interface client application (Internet Explorer, version 5.5 or higher) and the server under test. When recording is complete, the Silk Performer Recorder automatically generates a test script based on the recorded traffic. Scripts are written in the Silk Performer scripting language, Benchmark Description Language (BDL).

  1. Click Model Script on the workflow bar. The Workflow - Model Script dialog box appears.
  2. In the Recording Profile list, select Citrix Web Interface. The Citrix Web Interface recording profile is only appropriate for testing Citrix Web Interface/NFuse sessions.
  3. Click Start recording.
  4. The Silk Performer Recorder then opens in minimized form along with Internet Explorer. Enter the name of the Citrix server in the Internet Explorer Address field and click Enter. To see a report of the actions that occur during recording, maximize the Silk Performer Recorder dialog by clicking Change GUI size on the Recorder toolbar.
  5. To log into the Citrix Web Interface, enter your Username, Password, and Domain into the Citrix Web Interface login screen. Contact your system administrator if you do not have this information.
  6. Click Log In.
  7. The application portal appears. This portal contains the applications that have been published for shared use. Select the hosted application you want to record.
  8. The hosted application appears in the Silk Performer Citrix Recorder. Interact with the shared application in the Citrix Recorder in the same way that you want your virtual users to behave during the test. Your actions will be captured by the Citrix Recorder and generated into a BDL script.
  9. When you close the application the Citrix session disconnects and you can save your recorded script.
BDL scripts of recorded Citrix Web Interface sessions are multi-protocol scripts that include a small number of Silk Performer Web functions.
Parent topic: Citrix Web Interface Sessions (NFuse)
Previous topic: Defining a Citrix Web Interface Project


Citrix Script Functions

  • CitrixWaitForWindowCreation, used for screen synchronization, is the most important Citrix function.

    The first parameter that synchronizations consider is window caption. If during replay a window caption is returned that matches the caption of the window that was recorded during replay, then the verification succeeds.

    Note: Wildcards (*) can be specified at the end or beginning of window captions.

    The second parameter considered is the match parameter. Normally this is an exact, case-sensitive comparison of window caption strings.

    The third parameter is the style of the window. If a window caption name is not available, then a portion of the style name is used to identify the window. Styles reflect whether or not windows were maximized during recording.

    The fourth parameter considered is the position of the window. This may be a negative number, as maximized windows have a position of -4, -4. This parameter can be controlled via the Force window position profile setting. When this profile setting is enabled, windows are automatically moved to the exact positions they held during recording.

    The fifth parameter is window size. During replay windows must be resized to the same size they had during recording.

  • CitrixWaitForLogon waits until a Citrix client logs on successfully or a specified timeout period expires.
  • CitrixWaitForScreen captures screen regions and checks them against specified conditions (normally a hash value captured at recording). If a condition does not match and the timeout period expires, the function call fails. CitrixWaitForScreen functions also use screen appearance to synchronize subsequent user actions. Based on provided parameters, this function waits until the image in a specified screen region changes, matches the hash value captured at recording, or does not match the hash value captured at recording.
  • CitrixGetScreen takes a screenshot of a selected region and writes the screenshot to a file in the result directory. If the file name is omitted, it will be automatically generated by the user ID and hash value of the image.
  • CitrixGetScreenHash retrieves the hash value of a selected screen.
  • CitrixSetOption sets particular options, such as network protocol specification, speed screen latency reduction, data compression, image caching, mouse/keyboard timings and event queueing, client disconnect, synchronization time-outs, think times, TrueLog capture, and window position forcing.
  • CitrixWaitForWindow waits until a specified window event (specified with the nEvent parameter) occurs. Such events may be an activation, destruction or caption change for a specified window. If the selected event is a caption change, a matching caption change for the specified window will satisfy the function. Captions can be specified explicitly using the sCaption and nMatch parameters.
  • CitrixKeyString is the standard function for entering printable characters.
  • CitrixMouseClick moves the mouse to a specified position and presses a specified button. Optionally, the mouse can be specified to move while the button is pressed. Key modifiers (such as Ctrl and Alt) can be used.
Parent topic: Defining Projects


Screen Synchronization and Verification

Silk Performer supports bitmap and window verification for applications that are hosted by Citrix XenApp servers. Screen synchronization offers a means of verifying replayed Citrix content. Screen synchronizations differ from standard script verifications in that they allow for verification of window and screen region appearances, not input values. Also, they are inserted during script recording, not during subsequent script customization. Screen synchronizations are particularly useful for synchronizing subsequent user input that is displayed in browsers, or similar interfaces (for example, Citrix application windows), because such applications do not support automatic synchronization through window events such as user input and text display.

Note: Response data verification is not supported for Citrix testing.

Silk Performer relies on hash values to verify replayed bitmaps against recorded bitmaps. Hash values are computer-readable values that reflect bitmap specifications such as size, position, resolution, and color depth.

Note: To verify replay screen regions against hash values that are captured at recording it is necessary that the same color depth that is used during recording be used during replay. Scripts fail when these specifications are not maintained because changes as small as a single pixel can change hash values and result in replay content appearing to be different from recorded content.
Note: Windows maximized during recording must also be maximized during replay. This is because replay cannot change the state of windows (it can only resize and move windows). So if a window state changes (for example, from Maximized to Restored), then it is likely that some user input in the script caused the change (for example the Restore button may have been clicked). On replay the user will click at the same screen position (now the Maximize button) and consequently a different operation will be executed and the subsequent CitrixWaitForWindowRestore function will fail.
  • Text and Screen Synchronizations
    Synchronize your script with the application so that the script waits until the application is ready for additional user input. If you do not use synchronizations, your script may overrun the application.
  • Generating a Screen Region Synchronization During Recording
    Screen region synchronizations compare replay and record bitmaps to determine whether or not they are identical.
  • Verification and Parsing via OCR
    Explains that Silk Performer support for optical character recognition (OCR) simplifies session-dependent verifications and parsing by recognizing text values in the screengrabs of captured application states.
Parent topic: Citrix XenApp Support


Text and Screen Synchronizations

Window synchronizations such as CitrixWaitForWindow() and CitrixWaitForWindowCreation() are well suited to synchronizing with an application. It is important to synchronize with the application so that the script waits until the application is ready for additional user input. If you do not use synchronizations, the script will most likely overrun the application. Also, synchronization gives you point-in-time reference as to when tasks are completed, effectively measuring response times.

Text Synchronization

Many tasks that can be performed on an application do not show, hide, create, or destroy windows, they simply change a section of the screen. In such instances you should use the Silk Performer text synchronization functionality.

After recording your script, you can visually add text synchronization points via the TrueLog Explorer Synchronize Text option. Text synchronization works via built-in OCR (Optical Character Recognition).

Screen Synchronization

Silk Performer offers two types of screen synchronizations: wait for content change and wait for content match. This form of synchronization requires a window reference and two sets of x/y coordinates. However since unplanned events can lead to displaced window coordinates, you should use text synchronization whenever possible, and only use screen synchronization when there is no text to compare.

Wait for content change waits until the selected portion of the screen changes, while wait for content match waits until the selected portion of the screen matches what was defined during recording.

Note: Screen synchronization points must be inserted while you record your test case, whereas text synchronization points can be inserted afterward, via TrueLog Explorer.
Parent topic: Screen Synchronization and Verification


Generating a Screen Region Synchronization During Recording

Screen synchronization is achieved via CitrixWaitForScreen functions, which are not scripted automatically by the recorder. These functions are inserted via the Screen Region dialog box during recording. CitrixWaitForScreen functions compare replay and record bitmaps to determine whether or not they are identical. Hash values, as opposed to actual bitmaps, are used to compare the images. This limits resource consumption during replay.

Note: Screen region synchronization is only available via the Silk Performer Citrix Recorder.
  1. Record a Citrix session and create a test script.
  2. During recording, click Select Region on the Silk Performer Citrix Recorder.
  3. Click and drag your cursor to select the screen region for which you want to generate a bitmap synchronization.
    Note: Because differences as small as a single pixel can cause synchronization processes to fail, it is recommended that for text verifications you select the minimum screen area required. Otherwise unanticipated screen differences (for example, disabled toolbars) may affect verification results.
  4. The Selection dialog box opens. Specify how you want to have screen region coordinates scripted (Script absolute coordinates, Script coordinates relative to window, or No coordinates, use full window). When windows are maximized there is effectively no difference between absolute and relative coordinates. When windows are not maximized, relative coordinates are measured from the top-left corner of the Citrix Recorder window, while absolute coordinates use fixed x/y coordinates.
  5. Specify the Content matching type that the Citrix XenApp player should wait for during replay (content match, content mismatch, or content change).
  6. Click OK to add the synchronization to your Citrix XenApp test script.
Parent topic: Screen Synchronization and Verification


Verification and Parsing via OCR

Silk Performer support for optical character recognition (OCR) simplifies session-dependent verifications and parsing by recognizing text values in the screengrabs of captured application states.

Verification and parsing functions are added via TrueLog Explorer after script recording.

Window Position and State

Window position and state (maximized/minimized) is important for insuring accurate replay as TrueLog Explorer scripts screen coordinates where selected text is to be read from relative to the desktop, not individual windows. So if a window appears in a different position during replay than it did during recording, OCR operations will not be able to locate the specified text. If it is not possible to specify an absolute position, the script must be manually updated using coordinates relative to windows.

Adding OCR Verification Functions

With OCR support Silk Performer enables the storing of recognizable text values in variables, thereby simplifying session-dependent verifications in Citrix tests.

  • Overview
    Explains that string verification via optical character recognition (OCR) is achieved using functions that are inserted via TrueLog Explorer during script customization. CitrixVerifyText functions compare text strings in replay bitmaps to determine if they are identical.
  • Generating an OCR Verification Function
    Insert a verification function that relies on optical character recognition to recognize differences during recorded and replayed text-based content.
  • Generating an OCR Parsing Function
    Generate a parsing function to assist in creating a parameter that can be used for comparison and verification of recorded and replayed text-based content.
Parent topic: Screen Synchronization and Verification


Overview

String verification via optical character recognition (OCR) is achieved using CitrixVerifyText API calls. These functions are inserted via TrueLog Explorer during script customization. CitrixVerifyText functions compare text strings in replay bitmaps to determine if they are identical.

CitrixParseText functions are available for parsing text. These API calls work in the same way as other Silk Performer parsing functions.

Optical character recognition relies on pattern databases to recognize varying fonts and text styles. Font databases must be generated before OCR can be run.

Citrix TrueLogs show verification and parsing API calls in the tree view.

Note: OCR operations must be performed on stable content because when working with frequently changing screen images replay timing is critical. When synchronizing on window events it is possible that screen refresh may be slightly delayed, which will result in timing dependent outcome. Therefore it is good practice to either script a wait or a CitrixWaitForScreen function call before each OCR verification/ parsing function.

The following two screen examples show the output of verification and parsing functions after TryScript runs.

Parent topic: Verification and Parsing via OCR


Generating an OCR Verification Function

  1. From Silk Performer record a Citrix session
  2. Run a TryScript run with the Animation checkbox selected on the TryScript dialog box. This opens TrueLog Explorer.
  3. When the TryScript run is complete, select a CitrixSynchronization API node (or child node) that includes a bitmap screengrab of a page on which you want to verify text.
  4. Click and drag your cursor onscreen to select the page region that includes the text you want to use for verification.
  5. Right-click in the selected area and select Verify Selected Text from the context menu.
  6. The Insert Text Verification Function dialog box opens. The selected text is pre-loaded into the constant value edit box and the constant value radio button is selected by default. In addition to being able to verify against a constant value, you can also verify against an existing parameter or a new parameter. To verify against a parameter, select the parameter radio button. If a parameter already exists, clicking “...” enables you to browse to and select the parameter. If no parameters exist, clicking “...” launches the Parameter Wizard, which you can use to create a new parameter.
  7. From the Verify that the text in the selected rectangle is drop list, select equal or not equal.
  8. Specify whether or not the verification is to be Case sensitive and should Ignore whitespaces.
  9. In the Severity portion of the dialog box, specify the severity that is to be raised if the verification returns a negative result (Error, Warning, Informational, or Custom).
  10. Click OK.
  11. A confirmation dialog box appears. Click OK to add the OCR verification function to your Citrix test script.
Parent topic: Verification and Parsing via OCR


Generating an OCR Parsing Function

  1. From Silk Performer record a Citrix session
  2. Run a TryScript run with the Animation checkbox selected on the TryScript dialog box. This opens TrueLog Explorer.
  3. When the TryScript run is complete, select a CitrixSynchronization API node (or child node) that includes a bitmap screengrab of a page from which you want to parse text.
  4. Click and drag your cursor to select the page region that includes the text you want to parse.
  5. Right-click in the selected region and select Parse Selected Text into a Variable.
  6. The Insert Parsing Function dialog box offers parameters by which the parsing function can be configured. Though the default settings will likely be correct, you can adjust: Parameter name - Enter the name of the parameter that is to receive the result of the parsing function. Informational statement insertion - Select Print statement to insert an informational Print statement into the script after the Web page call. This writes the result of the parsing function to the Silk Performer Virtual User Output window.

    Select Writeln statement (“write line” statement) to write the parsed value to an output file to facilitate debugging (in addition to writing the value to the Virtual User Output window as a Print statement does). Because generating output files alters test measurements, these files should only be used for debugging purposes and should not be generated for full tests.

  7. Click OK.
  8. A confirmation dialog box appears. Click OK to add the OCR parsing function to your Citrix test script.
Parent topic: Verification and Parsing via OCR


Trying Out a Generated Script

With TryScript runs only a single virtual user is run and the stress test option is enabled so that there is no think time or delay between transactions.

Note: Although Citrix TrueLogs do not include live display of data downloaded during testing (via TrueLog Explorer) Citrix Web Interface TrueLogs do include live display of downloaded data. Both TrueLog types include the writing of log files, report files, and replay within the Silk Performer Citrix Player.

If you have configured parsing or verification functions based on Citrix OCR support, you must generate an OCR font database before attempting a TryScript run, otherwise these functions may not operate correctly.

  1. Click Try Script on the Silk Performer Workflow bar. The Try Script dialog box opens.
  2. To view live display of page content within TrueLog Explorer during replay (Citrix Web Interface TrueLogs only), select the Animated Run with TrueLog Explorer check box. The Visible Citrix Client option (Citrix TrueLogs only, not available for Citrix Web Interface TrueLogs) enables visual replay in the Silk Performer Citrix Player during TryScript runs.
  3. Click Run.
    Note: You are not running an actual load test here, only a test run to see if your script requires debugging.
  4. The TryScript run begins. The Silk Performer Monitor window opens, giving you detailed information about the run’s progress.
  • Citrix TrueLogs
    Explains that the Silk Performer Citrix Player opens for Citrix TryScript runs and that TrueLog Explorer opens for Citrix Web Interface TryScript runs
  • Silk Performer Citrix Player
    Explains that the Silk Performer Citrix Player replays all recorded actions in full animation, including mouse movements.
Parent topic: Citrix XenApp Support
Related tasks
Configuring System Settings for OCR


Citrix TrueLogs

The Silk Performer Citrix Player open for Citrix TryScript runs. TrueLog Explorer opens for Citrix Web Interface TryScript runs (when the Animation checkbox on the TryScript dialog box is checked). TrueLog Explorer displays the data that is actually downloaded during TryScript runs.

By selecting a high-level synchronization node you see a bitmap of the window captured during replay just as it appeared after the last synchronization function.

Window synchronization functions are visualized with colored borders. Window creations are indicated with green borders. Window activations are indicated with blue borders. Window destructions are indicated with yellow borders.

TrueLogs work in complement with the Silk Performer Citrix Player by visualizing screen states. For example, if you are not sure which window is indicated by a certain window ID that is listed in the Silk Performer Citrix Player Log window, you can find the corresponding synchronization function in the corresponding TrueLog and thereby access a bitmap that shows the window.

User input nodes (CitrixUserInput and related functions) reflect keyboard and mouse input. CitrixMouseClick functions offer two track vector parameters (X and Y coordinates). Red diamonds indicate mouse-click start points. Red cross-marks indicate mouse release points. A red line between a start and end point indicates the path of the mouse. If there is no move while the button is pressed, then only a red cross is displayed. Onscreen tool tips offer additional information (for example, right-click, left-click, double-click).

Value strings (keyboard input) are visualized onscreen as floating red text until target window captions are identified (in subsequent nodes) to indicate where strings are to be input.

Parent topic: Trying Out a Generated Script


Silk Performer Citrix Player

The Silk Performer Citrix Player opens when TryScript runs begin, replaying all recorded actions in full animation. Mouse movements and operations are simulated with an animated mouse icon.

Note: Silk Performer Citrix Player only opens for the Citrix application type, not the CitrixWeb Interface application type.

Click Toggle Log Window in the upper right corner of the player to open the Log window. The Log window includes three panes that detail different aspects of TryScript runs:

  • Script - This pane lists all of the executed BDL script functions and the currently executing BDL function.
  • Windows - This pane includes a stack of all the client windows of the current session, including window captions, styles, sizes, and positions. Top-level windows carry a window icon and are listed above sub-windows.
  • Log - This pane lists all informational messages and events, including executed BDL functions, and window creation, activation, and destruction.

In all panes, active functions and windows are indicated with a blue arrow icon.

  • Step by Step Replay
    Step-by-step replay mode allows you to advance through replay one function at a time. This is helpful for close analysis and debugging.
  • Skipping Time-Outs
    Explains that you can avoid waiting for time-outs during replay by clicking Skip.
Parent topic: Trying Out a Generated Script


Step by Step Replay

  1. During a Citrix TryScript run, click the Toggle Log Window button in the upper right corner of the Silk Performer Citrix Player to open the Log window.
  2. Click the Step button. Replay stops at the active function. A blue arrow icon indicates the next function in the script.
  3. Click Step to execute the next function.
  4. Continue clicking Step to advance through the script.
    Note: You can also enable step-by-step execution by selecting the Step by step execution checkbox on the TryScript dialog box.
  5. Click Run to resume continuous script processing.
Parent topic: Silk Performer Citrix Player


Skipping Time-Outs

The Silk Performer Citrix Player waits for all time-outs that are encountered during replay. To avoid waiting for time-outs (default time-out is 60 seconds), click Skip to advance past them.

Note: Clicking Skip generates user-break errors in scripts.
  1. During a Citrix TryScript run, click the Toggle Log Window button in the upper right corner of the Silk Performer Citrix Player to open the Log window.
  2. When replay encounters a time-out, click Skip to advance to the next function.
Parent topic: Silk Performer Citrix Player


Customizing User Data

With user data customization you can make your test scripts more realistic by replacing static recorded user input data with dynamic, parameterized user data that changes with each transaction. Manual scripting is not required to create such data-driven tests.

During testing you can customize the user input that is entered into applications that are hosted by Citrix terminal services in two ways:

  • The Parameter Wizard allows you to specify values to be entered with keyboard events, enabling your test scripts to be more realistic by replacing recorded user input data with randomized, parameterized user data.
  • Visual customization allows you to customize mouse events such as clicks, drags, and releases.
  • Using the Parameter Wizard
    Use the parameter wizard to customize user input data in your Citrix test script.
  • Customizing Mouse Events
    You can edit the start and end point of recorded mouse movements.
  • Synchronizing Text
    Explains that TrueLog Explorer offers a synchronization function that pauses the execution of Citrix functions until specified text or a text pattern appears in a specified location.
Parent topic: Citrix XenApp Support


Using the Parameter Wizard

  1. Select an API node that reflects user data input (for example, select a CitrixKeyString node that specifies a keyboard datastring).
  2. Right-click the input datastring (shown as floating red text) and select Customize User Input from the context menu.
  3. The Parameter Wizard opens. Select Create new parameter and click Next.
  4. With the Parameter Wizard you can modify script values in one of two ways. You can either use an existing parameter that’s defined in the dclparam or dclrand section of your script, or you can create a new parameter (based on either a new constant value, a random variable, or values in a multi-column data file). Once you create a new parameter, that parameter is added to the existing parameters and becomes available for further customizations.
    Note: This task explains only the process of creating a parameter based on a new random variable.
  5. The Create New Parameter dialog appears. Select the Parameter from Random Variable radio button and click Next.
  6. The Random Variable Wizard appears. From the drop list, select the type of random variable (for example, Strings from file) you want to insert into your test script. A brief description of the highlighted variable type appears in the lower window.
  7. Click Next.
  8. The Name the variable and specify its attributes page appears. The Strings from file random variable type generates data strings that can either be selected randomly or sequentially from a specified file. Enter a name for the variable in the Name field. Specify whether the values should be called in Random or Sequential order. Then select a preconfigured datasource (for example, Elname which defines last names) from the File/Name drop list.
  9. Click Next.
  10. The Choose the kind of usage page appears. Specify whether the new random value should be used Per usage, Per transaction, or Per test.
  11. Click Finish to modify the BDL form declaration of your test script so that it uses the random variable for the given form field in place of the recorded value. The new random variable function appears below in BDL view.
  12. Initiate a TryScript run with the random variable function in your test script to confirm that the script runs without error.
Parent topic: Customizing User Data


Customizing Mouse Events

  1. Select a CitrixMouseClick node that includes mouse activity. Red diamonds indicate mouse-click start points. Red cross-marks indicate mouse-release points. A red line between a start and end point indicates the path of the mouse. Onscreen tooltips offer additional information (for example, right-click, left-click, and double-click).
  2. Click anywhere on the screen and select Customize User Input from the context menu. The Customize Mouse Event dialog box appears.
  3. Click at the screen position where you want the customized mouse move to begin.
  4. Click at the screen position where you want the customized mouse move to end.
  5. Click the Customize button to accept the customization and modify the BDL script accordingly. Your mouse event customization now appears in the recorded TrueLog bitmaps in green. The mouse customization also appears in the BDL script in green text. CitrixMouseClick functions offer two track vector parameters (X and Y coordinates). The next time this script executes, it will use the new screen coordinates you have specified.
Parent topic: Customizing User Data


Synchronizing Text

TrueLog Explorer offers a synchronization function that pauses the execution of Citrix functions until specified text or a text pattern appears in a specified location. Such synchronization is vital for the accurate execution of verification functions.

Parent topic: Customizing User Data


Project and System Settings

Citrix profile settings are project-specific settings related to Citrix synchronization, logging, virtual user simulation, and client options. Citrix settings are specified on a per-project basis.

This section focuses on Citrix replay settings. Citrix record options are limited to network protocol, encryption level, the Log screen before each user action setting, and the Use RAM disk setting.

  • Configuring Citrix XenApp Options
    Configure Citrix settings, including window-position, mouse-speed, and think-time options to set up a Citrix test.
  • Configuring General Settings
    Explains how to configure basic project options related to window position, logging, time-outs, and more.
  • Configuring Simulation Settings
    Citrix simulation settings enable you to configure the behavior of Citrix virtual users, including keyboard/mouse input and think time.
  • Configuring Client Settings
    Citrix client settings enable you to configure client options such as network protocol, disk cache, data compression, the queuing of mouse movements, speed screen latency reduction, and encryption level.
  • Enabling Citrix Replay on Agents
    To enable Citrix replay on agent workstations you must specify a user account, define the network protocol, and modify the ICA file.
  • System Settings for OCR
    Explains that optical character recognition relies on font databases to recognize fonts and text styles in bitmaps.
Parent topic: Citrix XenApp Support


Configuring General Settings

  1. In the Project tab of the tree-view area of the main SilkPerformer window, right-click the Profiles node and select Edit Active Profile.
  2. The Profile - [Profile1] - Simulation dialog opens at the Simulation tab (Replay category).
  3. Scroll down to and select the Citrix icon. The Citrix General settings tab opens.
  4. In the Options section of the General tab, specify a timeout value in the Synchronization timeout field. You may have to increase this value if your Citrix server is slow.
  5. The Force window position option (enabled by default) automatically moves replayed windows to the coordinates specified in CitrixWaitForWindowCreation functions.
  6. The Disconnect on transaction end option (disabled by default) disconnects the client after each transaction, even init transactions.
  7. In the Logging section of the General tab, the Log screen before each user action option (enabled by default) enables onscreen display of user input (datastring values) for the moment before values are actually input into screens (for example, a user might enter a string value into a spreadsheet cell. The value is not actually input until the user pushes Enter. With this option enabled, in the node just preceding the click of the Enter key, the string value appears onscreen as floating red text). This option requires significant processing and disk storage as it dictates that each user action generate a screengrab. With this option disabled you do not see all user input updates.
  8. The Dump window region on unsuccessful screen synchronization option specifies that screengrabs be generated for all unsuccessful screen synchronizations. These bitmaps, when captured and saved to the current result directory (for example, RecentTryScript) of your Silk Performer installation, can be compared to corresponding recorded synchronizations to assist in debugging efforts. For example, a difference of a single pixel is enough to cause a screen synchronization error. Such a difference might best be detectable visually, by comparing recorded screengrabs with screengrabs captured when synchronization errors occur.
  9. The grabbing, reading, compressing, and writing of screengrabs for TrueLogs involves significant processing resources and can lead to slow replay. The Use RAM disk option (disabled by default) enables faster TrueLog replay by making use of a RAM disk or solid state drive (SSD), rather than writing files to a conventional hard disk. Use the drop list to select the letter of a drive with high read/write rates. Note that this option does not install a RAM disk, but you may use the RAM disk of your choice.
  10. Click OK to save your changes, or click Default to restore the default settings.
Parent topic: Project and System Settings


Configuring Simulation Settings

  1. In the Project menu tree, right-click the Profiles node and select Edit Active Profile.
  2. The Profile - [Profile1] - Simulation dialog opens at the Simulation tab (Replay category).
  3. Scroll down to and select the Citrix icon.
  4. Select the Simulation tab.
  5. In the Mouse section of the Simulation tab, specify virtual user mouse behavior (in milliseconds) such as the length of time that mouse clicks remain pressed, the length of time between the clicks of a double click, and mouse speed. Note that simulated mouse events move at constant speeds. They do not simply jump across the screen.
  6. In the Keyboard section of the Simulation tab, specify virtual user keyboard behavior (in milliseconds) such as the length of time that keys remain pressed, the length of time between keystrokes when entering strings (for example, CitrixKeyString functions), and key repeat time (irepeat parameters of CitrixKeyString functions).
  7. In the Think times section of the Simulation tab, specify virtual user think time behavior (in milliseconds) for delay after successful synchronizations, and delay after each user action. This is a virtual simulation of user reaction time that helps to stabilize replay.
  8. Click OK to save your changes, or click Default to restore the default settings.
Parent topic: Project and System Settings


Configuring Client Settings

  1. In the Project menu tree, right-click the Profiles node and select Edit Active Profile.
  2. The Profile - [Profile1] - Simulation dialog box opens at the Simulation tab (Replay category).
  3. Scroll down to and select the Citrix icon.
  4. Select the Citrix client tab.
  5. Select the network protocol upon which your client will run (TCP/IP or TCP/IP + HTTP). When you specify TCP/IP + HTTP, load balancing is done with the HTTP protocol, using post commands. When you specify TCP/IP, UDP is used. No other network protocols are supported.
  6. Check the Use data compression checkbox to enable data compression (enabled by default).
  7. Check the Use disk cache for bitmaps checkbox to enable the caching of bitmaps on your hard disk (disabled by default).
  8. Check the Queue mouse movements and keystrokes checkbox to queue mouse movements and keystrokes for a specified period of time before they are sent to the server (disabled by default).
  9. SpeedScreen latency reduction enables local echo of mouse and keyboard actions (disabled by default). Local echo means that you do not have to wait for round trips to the server to see the results of your input. Specify Off, On, or Auto.
  10. Specify an encryption level for the client. Options include, Use server default, Basic, 128 Bit for Login Only, 40 Bit, 56 Bit, and 128 Bit.
  11. Click OK to save your changes, or click Default to restore default settings.
Parent topic: Project and System Settings


Enabling Citrix Replay on Agents

  1. From the Silk Performer menu bar, select Tools > System Configuration Manager . The System Configuration Manager dialog box appears.
  2. (applicable to all Citrix XenApp client versions) Click the Applications tab. Click the Silk Performer icon. Enter Account and Password credentials for a user account on the agent workstation that has permission to execute Citrix sessions.
  3. To record a Citrix published application that is accessed using the settings defined on the Citrix Recorder Connect dialog box, perform the following:
    1. Expand the Profiles node on the Project menu tree and right-click the active profile. Select Edit Profile.
    2. Scroll down to and click Citrix.
    3. Click the Citrix client tab.
    4. From the Network protocol list box , select TCP/IP + HTTP.
    To record a Citrix published application utilizing an ICA file: In the [WFClient] section of the ICA file, change TcpBrowserAddress= to HttpBrowserAddress=.
Parent topic: Project and System Settings


System Settings for OCR

To enable optical character recognition (OCR) for parsing and verification functions in TrueLog Explorer, you must generate a font database using Silk Performer system settings.

Optical character recognition relies on font (or pattern) databases to recognize fonts and text styles in bitmaps. The default set of fonts covers most scenarios, however in some situations you may want to add additional fonts or font styles. A new database should be generated whenever new fonts are added or removed from the system.

Including too many fonts in the database can slow down processing and lead to contradictory reading, so it is recommended that you only include those fonts that are used in the bitmaps from which you will be capturing text strings.

  • Configuring System Settings for OCR
    Explains how to specify font size/style characteristics and generate a new font database.
Parent topic: Project and System Settings


Configuring System Settings for OCR

  1. Within Silk Performer, go to Settings/System.../ and select the Citrix icon.
  2. On the OCR tab, use the Add >> and Add All buttons to move those fonts that you wish to have used for OCR from the System Fonts list box to the Chosen Fonts list box.
  3. Use the Remove All and << Remove buttons to delete unnecessary fonts from the Chosen Fonts list box.
  4. In the Sizes field, specify the font size range that should be used (for example, 8-20).
  5. Define which font styles should be included by selecting the Italic, Bold, and Underlined check boxes. Make sure you select the Underlined check box if you want to verify menu entries.
  6. Click Generate Font Database.
  7. The Build Font Base dialog box opens. Click OK to confirm that you want to replace the existing font database with a new database.
    Note: If you encounter problems while generating the font database, it is likely a data execution prevention issue. To resolve the issue, please see the section below.
  8. Click OK on the Silk Performer System Settings dialog box to accept the changes.
Parent topic: System Settings for OCR


Testing Best Practices

While GUI-based testing presents a number of challenges, it can be rewarding as it offers the opportunity to closely simulate a real user experience. GUI-based testing through Silk Performer involves applying load to applications by simulating the terminal services protocol.

At least two physical computers should be used to perform Citrix tests: one computer runs the terminal services environment and the application under test (AUT); the other computer runs Silk Performer and the Citrix client software.

The load generator computer simulates a large number of users by mass producing the terminal services network protocol. The terminal services server (system under test) simulates multiple MS Windows-based desktop sessions simultaneously. This server also hosts the GUI application that is placed under load.

We recommend that you place an isolated network (LAN) between the load generator and the system under test. This allows for network throughput analysis. An isolated network is also less vulnerable to external influence, thereby reducing errors and misleading network throughput results.

  • Test Preparation
    Before conducting GUI-based load tests, it is recommended that you adhere to standard test preparations to avoid common problems.
  • Creating Use Cases
    There are a number of factors to be considered when developing use cases.
  • Ensuring a Stable Environment
    If the UI of the application under test changes after you record your test scripts, the scripts will likely be unusable.
Parent topic: Citrix XenApp Support


Test Preparation

  • User Interface (UI) design - Take advantage of any opportunity to influence the UI design of the application. A solid, consistent UI allows you to create reusable sub-routines. In turn, you can write less test code, and consequently have less code to maintain.

  • Test plan - A thoughtful test plan is a prerequisite of successful GUI-based load testing. In your test plan you should define your goals, objectives, test runs, critical metrics, and others.

  • Use cases - Use cases are step-by-step scenarios that you plan to test. Use cases represent typical user-to-application interaction, for example starting an application, opening a project, editing settings, and others. Your use cases guide you through the recording process.

  • Application expert - Even when equipped with well documented use cases you may not be able to make sense of all of an application’s workflow. It is helpful to have access to someone who has expert knowledge of the application under test, for example a business process owner.

  • Screen resolution - The higher the screen resolution, the higher the system requirements are per terminal session. We recommend you use a screen resolution of no more than 800x600 for record and replay. This approach allows for compatibility with older computers, which you then have the opportunity of including in your load tests.

  • Remote users - If your application is to be available to remote users, consider simulating a slow network during some of your load tests. Slow network connections can have a major impact on the performance of applications, therefore additional tests with simulated network congestion may help improve your test results. You can use the network emulation functionality of Silk Performer for this purpose.

Defining Your Goals

The first thing to do when planning your load test is to define your goals. While testers often assume that their goals are clear to all involved parties, they often are not. It is important that the quality assurance team and management work toward the same goals.

When writing up goals, first consider your highest-level goals:

  1. Discover the baseline performance of your application
  2. Optimize/tune your application
  3. Determine if the application under test is ready for production

Once you have established your high-level goals, you need to break them down into clear, measurable objectives, covering issues such as how you plan to accomplish your goals, how you plan to measure your goals, and what results will be considered acceptable.

Here is an example of how you might break down your testing goals:

Goal #1: Discover and document the baseline performance of your application

  • Use Silk Performer to measure the response times of critical application functions.
  • Place timer functions around window/screen synchronizations (WaitFor events). These measurements will show up in the final report.

Critical timers:

  • Measure how much time it takes from when the OK button is clicked on the Login window until the Welcome window appears.
  • Measure how much time it takes from when the Query results button is clicked until the populated list is displayed.

Goal #2: Optimize/tune the application

  • Optimize/tune the application for 5 days.
  • Document all changes and their impact on the performance of the application under test.

Goal #3: Determine if the application under test is ready for production

  • The application is ready for production if the following condition is met: All response times are under 5 seconds (Silk Performer provides metrics for each window and screen sync).

With a list of measurable objectives, your test results define a definite point at which the application will be ready for production. This also eliminates the risk of endlessly optimizing the application as tuning it to the defined goal is adequate.

Parent topic: Testing Best Practices


Creating Use Cases

A use case is a typical task that a user undertakes when working with the application under test. A use case must use the features of the application that require testing. It is essential that you only test features that are important and working properly. This is not the time to perform functional testing, which should already have been completed. Testing is a long process: the longer the use cases, the more time that will be required for testing.

When stepping through a use case, write down all significant screen events. For example, when entering a formula in Microsoft Excel you should document the changing of cells due to formula processing. Such events will translate into screen synchronizations that will be important during script development. Text synchronizations can be used for text-based screen synchronizations.

Document use cases to a detailed level. You need to document every mouse click, key stroke, and expected result. While this may be tedious initially, it makes things easier when you begin recording your test cases.

The following example, a test that simply locates an existing instance of Microsoft Word and opens a document, displays the level of detail that a use case should have. The square brackets (“[ ]”) indicate an event.

In the “Microsoft Word” window, navigate to the File menu and select Open….
[The “Open” dialog box opens]
Select ‘Test.doc.’
Click Open.
[The “Open” dialog box closes]
[The “Microsoft Word” window has focus once again]

Note that the exact titles of the windows are documented in the above example. This becomes important later during script development as such information is needed to keep the script in sync with the application. Once you have a well documented use case, it is easy to script the application

There are several ways to write use cases. You can use XML notation, numbered notation, or another format that you are familiar with.

XML Use Case Example

<Task Name=”Open a document”>
  In the “Microsoft Word” window, navigate to the File menu  	  and select Open….
  [The “Open” dialog box displays]
  Select ‘Test.doc.’
  Click Open.
  [The “Open” dialog box closes]
  [The “Microsoft Word” window has focus once again]
</Task>

Numbered Use Case Example

100.01 – Open a document
  In the “Microsoft Word” window, navigate to the File menu  	  and select Open….
  [The “Open” dialog box displays]
  Select ‘Test.doc.’
  Click Open.
  [The “Open” dialog box closes]
  [The “Microsoft Word” window has focus once again]
100.02
    …
Parent topic: Testing Best Practices


Ensuring a Stable Environment

Before you start recording, make sure that there will be no additional changes to the UI of the application under test, at least until your tests are complete. This requires good communication with the development team. If the UI changes after you record your test scripts, your scripts will likely be unusable.

Also, make sure that you have the ability to back up and restore any databases that are used in your testing. Because changes to database content often lead to differences in UI content, for example more or different items in lists, different query results, and other, databases need to be returned to a baseline state before the start of each test cycle.

Parent topic: Testing Best Practices


Troubleshooting

Once you have documented your use cases, recording or coding your test scripts should be a relatively simple task. With Silk Performer you have both the record/playback option and the option of coding your test scripts manually. Each approach has its advantages and disadvantages. The most efficient way to create test scripts with Silk Performer is to combine the two approaches, as follows:

  1. With Silk Performer, record the scenario you have outlined in your use case description.
  2. Use TrueLog Explorer to visually customize your script (this is where the “Text synchronization” feature comes into play).
  3. For more complex scripting, edit the generated BDL script manually. Manually editing a script is also the best option for inserting the content of your use case into your test script (in the form of comments). See the example below, which uses numbered notation format:
    100.001 In the “Microsoft Word” window, navigate the menu to File, Open….
100.002 [The “Open” dialog window shows]
100.003 Select Test.doc.
100.004 Click Open.
100.005 [The “Open” dialog window goes away]
100.006[The “Microsoft Word” window has focus again]
  4. You can now copy/paste these contents into your BDL script as follows:.
    // 100.001 In “Microsoft Word" window,
    hwndWordMainWindow := CitrixSearchWindow(“*Microsoft
    Word”, MATCH_Wildcard);
    CitrixWindowBringToTop(hwndWordMainWindow);

// navigate the menu to File, Open….
    CitrixKey(KEY_Alt);
    CitrixKeyString("f");
    CitrixKeyString("o");

// 100.002 [The “Open” dialog window shows]
    hwndOpenDialog := CitrixWaitForWindowCreation(“Open”,
    Match_Exact);

// 100.003 Select Test.doc.
    CitrixMouseClick(150, 100, hwndOpenDialog, MOUSE_
    ButtonLeft);

// 100.004 Click Open
    CitrixMouseClick(300, 200, hwndOpenDialog, MOUSE_
    ButtonLeft);

// 100.005 [The “Open” dialog window goes away]
    CitrixWaitForWindow(hwndOpenDialog, EVENT_Destroy);

// 100.006 [The “Microsoft Word” window has focus again]
    CitrixWaitForWindow(hwndWordMainWindow, EVENT_Activate);
    If the script fails, these comments will help you determine where the script failed in reference to the use case.
  • Recording Tips
    Here are some general tips that will help you avoid the effort of finding and fixing replay errors.
  • Debugging Scripts
    Explains considerations for when windows fail to be activated and screen synchronizations subsequently fail because different values are encountered during replay than were captured during recording.
  • Troubleshooting Scripts
    Here are some tips for avoiding, finding, and fixing timeout and other execution failures.
  • Handling Citrix Dialog Boxes
    Includes suggestions for handling informational dialog boxes.
Parent topic: Citrix XenApp Support


Recording Tips

When recording a terminal services script, you must be aware that unplanned events can change the position and size of target windows during replay, causing test runs to fail. Here are some general tips that will help you avoid the effort of finding and fixing such replay errors.

Try launching the application via the Windows Run command. Launching the application via a desktop icon or mouse click may also work, but consider if you will be moving the application to a different server, or if the GUI will vary between users, in which case a desktop icon might appear in a different location. It is therefore recommended that you type the path to the application’s EXE file in the Windows Run command window.

Keyboard Shortcuts

Mouse clicks require x/y coordinates, a window reference, and the target window must have focus. While GUI testing technologies for tracking mouse clicks have become increasingly reliable, Windows remains a dynamically changing environment, so you must build scripts that can tolerate minor inconsistencies. One way to do this is to use keyboard shortcuts. For shortcuts, the only requirement is window focus.

Note: The Windows Logo key is not supported, as it moves the focus away from the Citrix Recorder.

Almost all menu systems in Windows applications have Alt key combinations that can be used to initiate specific menu commands. To record use of an Alt key shortcut, first give your application focus, then press the Alt key, this gives the menu system focus. Notice that many of the menu items have one of their letters underlined. This indicates which Alt key commands are available for specific menu items. Press appropriate letter keys to gain access to sub-menus until you reach the menu item that you want to initiate. In some cases, a menu item itself will have a key combination. For example, to open a document in Microsoft Word use the Ctrl+O combination. This shortcut does not require that the menu have focus.

Maximizing Windows

If keyboard shortcuts are not available and you must use the mouse, you can reduce the chance of triggering inaccurate mouse clicks by maximizing the window that you are working with. This places the window in a fixed position each time it is used and, in turn, makes mouse clicks more accurate. As a general rule, if a window allows for maximization, it is recommended that you take advantage of it.

Note: Alt-Space, X is the Windows keyboard combination for maximizing an active window

When a window does not allow for maximization, during the recording session, move the window to the upper left-hand corner of the desktop before clicking. When recording, the recorder may not be able to pick up on the window handle that you have in the foreground, so having the coordinates relative to the desktop is a must.

Keeping the System Clean

To eliminate unexpected events during terminal services sessions, ensure that you keep your Windows desktop as uncluttered as possible. Imagine, for example, that while your script is replaying, a Windows network message appears. Your script will break because the subsequent mouse click will go to the Windows network message window instead of your intended application window.

Ensure Correct Focus

Before clicking a window, ensure that the window you intend to click exists and has focus. Here is a sample BDL function that helps automate this process:

function MyCitrixWaitForWindowCreationAndActivation(sCaption:string;
                nMatch    : number optional;
                nStyle    : number optional;
                nX        : number optional;
                nY        : number optional;
                nWidth    : number optional;
                nHeight   : number optional
                ) : number
var
    hwndNewWindow  : number;  // hwnd of the new window created
    nRTT:number;
begin
    //
    // Check if window exists
    //
        hwndNewWindow := CitrixSearchWindow(sCaption, nMatch);
          hwndNewWindow := 0;
    //
    // If window doesn’t exist, wait for creation
    //
        if (hwndNewWindow < 1) then
            hwndNewWindow := CitrixWaitForWindowCreation(sCaption, nMatch,
            nStyle, nX, nY, nWidth, nHeight);
        end;
    //
    // Check if window is already active, wait if it’s not active
    //
        MyCitrixWaitForWindowActivate(hwndNewWindow);
        MyCitrixWaitForWindowCreationAndActivation:=hwndNewWindow;

end MyCitrixWaitForWindowCreationAndActivation;

Using Parameters

If you input the same information more than once, the system under test caches the data in memory rather than repeating the same work. For this reason it is important that you vary input/request data so that the work is as realistic as possible. For example, use different user accounts that have different data ranges. This can be accomplished using a CSV (comma separated values) file as input for a test.

Adding Verifications

Verifications are checks that are added to code to check if the responses that are received from the server are correct. When performing GUI based testing, verifications are automatically added to your script via window synchronizations, however it is recommended that you add additional verifications to your code.

Adding Timers

Custom timers are critically important for tracking an application’s response times. Without custom timers, you cannot determine your end user’s overall experience with an application. Metrics can help determine which aspects of your application are performing well and which are not.

Before you begin adding custom timers to your test script, identify the critical areas of your application and determine where your MeasureStart and MeasureStop calls should be placed. For this effort it is good practice to review the log in TrueLog Explorer.

Here is an example of using timers in a Silk Performer script:

//
// Submit a work order.
//
CitrixMouseClick(27, 31, hwndWorkOrder, MOUSE_ButtonLeft);

//
// Start the response time clock.
//
MeasureStart("202.01: Work Order Submission.");

//
// Wait for the "Order Submission Complete" dialog box.
//
MyCitrixWaitForWindowCreationAndActivation(
    "Order Submission Complete",
    MATCH_Exact
    );

//
// Stop the response time clock.
//
MeasureStop("202.01: Work Order Submission ");
Parent topic: Troubleshooting


Debugging Scripts

Windows may fail to be activated and screen synchronizations may fail when Silk Performer Citrix replay encounters different values during replay than were captured during recording. Sometimes the causes of synchronization problems are not apparent. They may be due to a change in screen position of only a single pixel.

More common than screen synchronization failures are windows not being activated during replay. In such cases the screenshots associated with the corresponding user actions may explain the fault.

Note: Sometimes there is no user fault and a window is activated only sporadically. In such cases you must remove the associated CitrixWaitForWindow function.

Silk Performer Citrix replay captures screengrabs when errors occur (the default setting) and writes the bitmaps to disk. By default, the recorder writes screenshots to the screenshots directory in the project directory. Replay stores screenshots in the current used result directory. Visual comparison of record and replay screens is best achieved using bitmap viewing programs.

The Silk Performer Dump window region of unsuccessful screen synchronizations Citrix option must be activated (the default) to have bitmaps captured and saved.

Parent topic: Troubleshooting


Troubleshooting Scripts

You may encounter timeout errors or other execution failures during load test execution. Here are some tips for avoiding, finding, and fixing such errors.

Using TrueLog Explorer

Test runs often fail due to the appearance of unexpected dialogs, causing scripts to lose focus on the windows they are working on. It is therefore recommended that you enable the TrueLog On Error feature in Silk Performer before you execute tests. Then, if an error occurs, you will be able to visually track it down in TrueLog Explorer.

Clearing Terminal Server Sessions

After a failed test execution, ensure that you reset all terminal server sessions before you execute the test again, otherwise your script will likely fail.

Handling Application Errors

During tests, your application is likely to throw errors due to generated load. Adding event handlers to your script that can handle and report such errors is very helpful.

Here is an example of an event handler that continuously watches for a window with the name Program Error Intercepted and executes an ALT-C to close any such window that appears. The event handler also generates an error message whenever such an error occurs.

dclevent
  handler Handler1 <EVENT_CITRIXINTERRUPT>
  var
    nInterrupt, nWindow : number;
    nStyle              : number;
    sWindowCaption      : string;
    begin
      CitrixGetActInterrupt(nInterrupt, nWindow);
      ErrorAdd(FACILITY_CITRIXENGINE, 47, SEVERITY_INFORMATIONAL);
      print(string(nWindow));
      CitrixGetWindowCaption(nWindow, sWindowCaption);
      if sWindowCaption = "Program Error Intercepted" then
        CitrixKey(67, MOD_Alt); // 'c'
      end;
      ErrorRemove(FACILITY_CITRIXENGINE, 47);
    end Handler1;

Avoiding Think Times

While it may be tempting to use Wait() or ThinkTime statements to avoid having scripts overrun applications under test, this practice is not recommended for two reasons:

  • When load generation increases, application processing speed may slow considerably. The wait statement may eventually be too short and the problem of overrunning the application will again present itself.
  • If you are measuring the response times of window, text, or screen synchronizations, the time in the Wait() statement will artificially bloat response times.

The solution is to use synchronizations.

Re-recording Portions of a Script

Sometimes changes in application behavior result in portions of a recorded script becoming obsolete. Re-recording a portion of a use case is an option, but beware that the recorder may not be able to track the handles of the existing windows, resulting in incorrect window handle numbers. These issues can make the process of integrating newly recorded script with an original script quite tedious. When a use case is small, it is recommended that you re-record the entire use case. Otherwise, follow the process outlined below to integrate a new script with an outdated script:

  1. Comment out the section of code that is to be re-recorded.
  2. Match the location of the code section requiring replacement with the corresponding section in the use case.
  3. Bring a terminal services session up to the corresponding point in the use case.
  4. Begin recording the open terminal services session.
  5. Perform the actions of the use case that require replacement.
  6. Stop the recorder (a script from the recording is then produced).
  7. Replace the window handle variables in the newly recorded script with the respective handles of the original script. You may use functions such as CitrixSearchWindow() to locate correct window handles.
  8. Copy the edited code into the original script.
Parent topic: Troubleshooting


Handling Citrix Dialog Boxes

Depending on how you connect to Citrix terminal services sessions and your licensing setup, you may see one or both of the following dialog boxes:

  • ICA Seamless Host Agent
  • Citrix License Warning Notice

These dialog boxes are informational and may or may not appear when you initially log into terminal services sessions. Following are two ways of handling these dialog boxes.

Handling Citrix dialog boxes (Solution #1)

This solution creates an interrupt that handles the dialog boxes if they appear:

transaction TMain
  var
  begin
    CitrixInit(800, 600);
    CitrixAddInterrupt(INTERRUPT_WindowCreate, "ICA Seamless Host Agent", MATCH_Exact);
    CitrixConnect("lab74", "labadmin", "labpass", "testlab1", COLOR_16bit);
    CitrixWaitForLogon();
    hWnd4 := CitrixWaitForWindowCreation("", MATCH_Exact, 0x96840000, -2, 572, 804, 30);
    CitrixWaitForWindowCreation("Program Manager");
    CitrixMouseClick(36, 17, hWnd4, MOUSE_ButtonLeft, MOD_None, -1, 0);
    hWnd11 := CitrixWaitForWindowCreation("", MATCH_Exact, 0x96400000, 2, 313, 163, 263);
    CitrixMouseClick(62, 247, hWnd11, MOUSE_ButtonLeft);
    CitrixWaitForWindow(hWnd11, EVENT_Destroy);
    hWnd12 := CitrixWaitForWindowCreation("Shut Down Windows", MATCH_Exact, 0x94C808CC, 191, 136, 417, 192);
    CitrixWaitForWindow(hWnd12, EVENT_Activate);
    CitrixMouseClick(203, 170, hWnd12, MOUSE_ButtonLeft);
    CitrixWaitForDisconnect();
  end TMain;

dclevent
  handler Handler1 <EVENT_CITRIXINTERRUPT>
  var
    nInterrupt, nWindow : number;
    nStyle              : number;
  begin
    CitrixGetActInterrupt(nInterrupt, nWindow);

    ErrorAdd(FACILITY_CITRIXENGINE, 47, SEVERITY_INFORMATIONAL);
    print(string(nWindow));
    if CitrixGetWindowStyle(nWindow, nStyle) and (nStyle <> 0xB4000000) then
      CitrixWaitForWindow(nWindow, EVENT_Activate);
      CitrixMouseClick(201, 202, nWindow, MOUSE_ButtonLeft);
      CitrixWaitForWindow(nWindow, EVENT_Destroy);
    end;
    ErrorRemove(FACILITY_CITRIXENGINE, 47);

  end Handler1;

Handling Citrix dialog boxes (Solution #2)

This sample code loops for 30 seconds, waiting for the Citrix dialog boxes to appear. If the dialog boxes appear, this code closes them.

function MyCitrixStartup(nMaxWait: number optional): boolean
    var
        hwndICAHandle              : number;
        hwndFoundLicenseWarning    : number;
        nCount                     : number;
    begin
        hwndICAHandle:=-1;
        hwndFoundLicenseWarning:=-1;
        nCount:=0;

        if (nMaxWait = 0) then
            nMaxWait:=10;
        // if no wait time was passed,
        // use 10 tries (seconds) as a default
        end;

        MeasureStart("MyCitrixStartup");

    //
    // loop until we've handled the conditions or we've tried
    //

        while ((nCount < nMaxWait) and ((hwndICAHandle <=0) or
            (hwndFoundLicenseWarning <=0))) do

    //
    // Just a little feedback, every 10 tries
    //
            if ((nCount MOD 10) =0) then
                print(string(nCount) + ")MyCitrixStartup "
                + " vUser:" + string(GetUserId())
                + " hwndICAHandle=" + string(hwndICAHandle)
                + " hwndFoundLicenseWarning="
                + string(hwndFoundLicenseWarning),
                OPT_DISPLAY_ERRORS , TEXT_GREEN );
            end;
    //
    // if we haven't handled this window yet
    //
            if (hwndICAHandle  <=0) then
                hwndICAHandle := CitrixWaitForWindowCreation
                ("ICA Seamless Host Agent", MATCH_Exact, 0x94C800C4,
                0, 0, 0, 0, false, 1, true);

                if (hwndICAHandle > 0) then
                    if (CitrixWindowBringToTop(hwndICAHandle)) then
                        CitrixKey(KEY_ENTER); // press ok to close the dialog
                        CitrixWaitForWindow(hwndICAHandle, EVENT_Destroy);
                        // wait for the close
                    end; // end waiting for window to top
                end; // end if we have a valid handle
            end; // if window has not been found yet

            if (hwndFoundLicenseWarning  <=0) then
                hwndFoundLicenseWarning := CitrixWaitForWindowCreation
                ("Citrix License Warning Notice", MATCH_Exact, 0x94C800C4,
                0, 0, 0, 0, false, 1, true);

                if (hwndFoundLicenseWarning > 0) then
                    if (CitrixWindowBringToTop(hwndFoundLicenseWarning)) then
                        CitrixKey(KEY_ENTER);  // Press ok
                        CitrixWaitForWindow(hwndFoundLicenseWarning,
                            EVENT_Destroy);
                        // wait for it to go away
                    end; // end waiting for window to top
                end; // end if we have a valid handle
            end; // if window has not been found yet

            nCount :=nCount+1;
            Wait 1.0;
        end; // while nCount

        MeasureStop("MyCitrixStartup");
        //
        // return true if we handled any one of these conditions
        //

        MyCitrixStartup2 := (hwndFoundLicenseWarning > 0)
            or (hwndICAHandle > 0) ;

          print("MyCitrixStartup "
            + " vUser:" + string(GetUserId())
            + " Waited " + string(nCount) + " of " + string(nMaxWait)
            + " hwndICAHandle=" + string(hwndICAHandle)
            + " hwndFoundLicenseWarning=" + string(hwndFoundLicenseWarning),
            OPT_DISPLAY_ERRORS , TEXT_GREEN );

end MyCitrixStartup;
Parent topic: Troubleshooting


.NET Support

Silk Performer's .NET support includes the testing of Web Services, .NET Remoting objects, NUnit, and more.

  • .NET Framework Support
    Silk Performer ships with a .NET Framework that allows you to test Web Services and .NET components.
  • Using .NET Framework Functions Within .NET
    For best results using .NET test code with Silk Performer, call BDL functions from within .NET code.
  • .NET Configuration Files
    Provides an overview of the configuration file settings that affect the .NET runtime environment (e.g., assembly binding and .NET Remoting settings).
  • Testing Web Services and .NET Remoting Objects with .NET Framework
    With the .NET Framework and Silk Performer's Visual Studio .NET Add-On, you can easily test Web services and .NET Remoting objects.
  • Testing SOAP Web Services for .NET
    Explains the basics of SOAP-based Web services and details how you can test them in .NET.
  • Setting Up Silk Performer .NET Projects
    Set up a Silk Performer .NET project to generate a Microsoft Visual Studio project that supports the features offered by the Visual Studio .NET Add-On.
  • Creating Silk Performer .NET Projects in Microsoft Visual Studio
    Provides information about the proper way to create a .NET project in Microsoft Visual Studio.
  • Memory Usage in .NET
    Hosting the .NET CLR and loading .NET objects requires additional memory that is used for virtual user processes (containers).
  • .NET Error Messages
    Lists error messages that may occur during load tests and resolutions for those issues.
  • NUnit Integration
    Provides an overview of the integration of NUnit test scripts into Silk Performer.
  • Silk Performer .NET Explorer
    Provides an overview of Silk Performer .NET Explorer.
Parent topic: Load Testing Specific Application Types


.NET Framework Support

Silk Performer ships with a .NET Framework that allows you to test Web Services and .NET components. This framework includes a set of Benchmark Description Language (BDL) API functions and an Add-On for Visual Studio .NET.

Refer to the Silk Performer .NET Framework Developer Guide for detailed information on Silk Performer .NET Framework support.

Parent topic: .NET Support


Using .NET Framework Functions Within .NET

For best results using .NET test code with Silk Performer, call BDL functions from within .NET code. The .NET assembly perfdotnetfw.dll that comes with Silk Performer implements the Silk Performer.Bdl class, where most BDL functions are implemented.
  1. Add a reference to perfdotnetfw.dll in your .NET project. This DLL can be found in the Silk Performer installation directory.
  2. Import the Silk Performer namespace (see the necessary code below, depending on your implementation language).
    using Silk Performer; // C#
imports Silk Performer // VB.NET
  3. Use the static functions in your .NET Code.

    For example:

    Bdl.Print("This is a message from within a .NET Assembly");
    The functions that are defined by the BDL class can only be used if the .NET assembly runs in a virtual user. This is because perfrun.exe functions (virtual user process) will be called.

    Sample Bdf Script

    dcltrans
  transaction TMain
  var
hObject, hObject2 : number;
hReturn : number;
  begin
    DotNetSetString(hObject, "ConstrValue1");
    hObject := DotNetLoadObject("bin\\Release\\TestDriver.dll", "TestDriver.TestClass");
    hObject2 := DotNetLoadObject("bin\\Release\\TestDriver.dll", "TestDriver.ParamClass");
    DotNetSetFloat(hObject, 1.23);
    DotNetSetInt(hObject, 123);
    DotNetCallMethod(hObject,"TestMethod");
    DotNetGetObject(hObject, hReturnValue);
    DotNetFreeObject(hObject);
    DotNetFreeObject(hObject2);
    DotNetFreeObject(hReturn);
  end TMain;

    Sample .NET Code (C#)

    using System;
using Silk Performer;
namespace TestDriver
{
  public class TestClass
{

public TestClass(string sConstrValue)
{
Bdl.Print("Constructor called with param" + sConstrValue);
}

public TestClass()
{
Bdl.Print("Default Constructor called!");
}

public ParamClass TestMethod(double fParam, int nParam)
{
return new ParamClass(fParam, nParam);
}
}

  public class ParamClass
{
public double mfMember;
public int mnMember;

public ParamClass(double fParam, int nParam)
{
mfMember = fParam;
mnMember = nParam;
}

public ParamClass()
{
mfMember = 0.0;
mnMember = 0;
}
}
}
Parent topic: .NET Support


.NET Configuration Files

Microsoft .NET Framework allows for the specification of configuration files for Windows-, Web- and Internet Explorer-based .NET applications. These configuration files contain settings that affect the .NET runtime environment (e.g., assembly binding and .NET Remoting settings).

When running a .NET test driver with Silk Performer .NET Framework, a configuration file called perfrun.exe.config is created automatically with settings that are required for loading the Silk Performer Framework Assembly and allowing the routing of HTTP traffic over the Silk Performer Web Engine.

You have two options for delivering custom configurations through such configuration files:

  • Load a configuration file at runtime into your .NET test driver.

  • Create a app.config file in your project directory that contains configuration keys that will be merged into the automatically generated perfrun.exe.config file.

Configuration at Runtime

The .NET Class Library provides a class that allows you to configure specific .NET Remoting settings that are loaded from configuration files. If for example you have the following configuration file schema:

<configuration>
<system.runtime.remoting>
<application>
  <channels>
    <channel ref="http" port="2000" />
  </channels>
  <client url="http://remoteserver:2000">
    <activated type="RemoteDll.RemoteClass1, RemoteDll"/>
    <activated type="RemoteDll.RemoteClass2, RemoteDll"/>
  </client>
</application>
</system.runtime.remoting>
</configuration>

…and you store this in a file in your project directory and add it to your data file section you can use the following code to load it at runtime (most likely in the method that corresponds to your init transaction):

RemotingConfiguration.Configure(Bdl.GetDataFilePath("vuser.config"));

Other settings that can be configured in the application configuration file can be changed through other classes of the .NET Framework, for example, System.AppDomain. For a detailed description of the classes that allow for modification of the .NET Runtime Environment, see the MSDN Online Reference.

Own Configuration File

When running a test using the Silk Performer .NET Framework, Silk Performer automatically generates a configuration file that is used to initialize the .NET runtime that is hosted in the virtual user process. This file is called perfrun.exe.config and is stored to the Silk Performer installation directory. The file has a schema like the following:

<configuration>
<system.net>
...
</system.net>
<runtime>
...
</runtime>
</configuration>

When generating this configuration file, Silk Performer looks for an app.config file in your project directory. If there is such a file, the content of the file is merged just after the runtime node. This means that you can define any required configuration XML elements in your app.config file. But you must ensure that the file doesn't have the root configuration tag or one of the tags generated by Silk Performer (system.net or runtime).

Here is a sample configuration file for .NET Remoting components:

<system.runtime.remoting>
<application>
<channels>
  <channel ref="http" port="2000" />
</channels>
<client url="http://remoteserver:2000">
  <activated type="RemoteDll.RemoteClass1, RemoteDll"/>
  <activated type="RemoteDll.RemoteClass2, RemoteDll"/>
</client>
</application>
</system.runtime.remoting>
Parent topic: .NET Support


Testing Web Services and .NET Remoting Objects with .NET Framework

With the .NET Framework and Silk Performer's Visual Studio .NET Add-On, you can easily test Web services and .NET Remoting objects.

The Framework offers the following options for testing Web services/.NET Remoting objects:
  • Writing your test code in Microsoft Visual Studio using a popular .NET Language (C# or VB.NET)
  • Making use of Microsoft Visual Studio's Web Service Client Proxy Generation Wizard
  • Coding your Web service calls in your .NET test driver
  • Running a load test using your .NET test driver
  • HTTP traffic that is generated by .NET to call Web service/.NET Remoting methods is redirected over the Silk Performer Web engine, enabling the advantages of Silk Performer's Web engine (modem simulation, IP-address multiplexing, etc.).
  • Exploring HTTP traffic (SOAP, XML, and binary) with TrueLog Explorer
  • Testing Web Services
    Describes how to test Web Services.
  • Testing .NET Remoting Objects
    Describes how to test .NET Remoting objects.
Parent topic: .NET Support


Testing Web Services

  1. Create a Silk Performer .NET project. Create a project either from within Silk Performer (Project type: Web Services/.NET) or create a new .NET project by launching the Silk Performer Project Wizard from Visual Studio .NET (File > New > Project).
  2. Create a WebService client proxy. Use the Visual Studio .NET Web Service Client Proxy Wizard to generate a client proxy class:
    1. Call Add Web Reference.
    2. Insert the URL to your Web service in the Address field.
    3. Click Add Reference. A proxy class is then generated with the name of your WebService. Namespace is the name of the Web server where the service is hosted. If your URL is, for example, http://localhost/MyWebService/Service1.asmx then the full name of your proxy class would be localhost.Service1.
  3. Code your WebService calls. Instantiate an object of your proxy class and then make calls to the service in one of your transactions. A good design decision would be to define the proxy as a member variable of your test class, instantiate it in your init transaction and make calls in your main transaction. Example (C#):
    using System;
using Silk Performer;
namespace SPProject1
{
[VirtualUser("VUser")]
public class VUser
{
public localhost.Service1 mService;

public VUser()
{
}

[Transaction(ETransactionType.TRANSTYPE_INIT)]
public void TInit()
{
mService = new localhost.Service1();
}

[Transaction(ETransactionType.TRANSTYPE_MAIN)]
public void TMain()
{
int nRetParam = mService.ServiceCall1("Testparam");
Bdl.Print("Return value of ServiceCall1: " +
nRetParam.ToString());
mService.ServiceCall2(nRetParam);
}

[Transaction(ETransactionType.TRANSTYPE_END)]
public void TEnd()
{
}
}
}
  4. Run a TryScript.

    Initiate a Try Script run by calling Silk Performer/Try Script or by pressing the F8 key.The return value is output into the Virtual User Output Window via the Bdl.Print method.

    In the TrueLog, two nodes in the main transaction represent the SOAP HTTP traffic that was responsible for the Web service calls. By default all HTTP traffic is redirected over the Silk Performer Web Engine; therefore output is available in the TrueLog. You can turn off redirection or enable it for specific Web service client proxy classes using the Web Settings dialog.

  5. Continue working in Silk Performer. When you have finished implementing your .NET test driver, you can continue working in Silk Performer and running load tests. With Silk Performer you can run load tests with multiple users distributed over multiple agents. Take advantage of the Web engine features (modem simulation, IP-address multiplexing, etc.) by testing how Web service calls perform when they are called over a slow modem and how your Web server performs when numerous users make service calls simultaneously.
Parent topic: Testing Web Services and .NET Remoting Objects with .NET Framework


Testing .NET Remoting Objects

  1. Reference remote object assembly. To test .NET Remoting objects you must reference the .NET assembly that defines the objects that are remoted. To do this, add a reference to the DLL that defines the classes.
  2. Configure your test driver to be a remoting client. You must tell .NET which classes are remoted. The easiest way to do this is to make the configuration in a .config file. For detailed information about .config files that define a remoting client configuration, see MSDN.

    Here is an example file:

    <configuration>
 <system.runtime.remoting>
 <application>
 <channels>
 <channel ref="http" port="2000" />
 </channels>
 <client url="http://remoteserver:2000">
 <activated type="RemoteDll.RemoteClass1, RemoteDll" />
 <activated type="RemoteDll.RemoteClass2, RemoteDll" />
 </client>
 </application>
 </system.runtime.remoting>
 </configuration>

    This configuration file must be loaded at runtime (ideally in the Init transaction of your test driver). To make sure that this file is available on all agents when running load tests, add it to the project-dependent files (Menu: Silk Performer/Add Dependencies). You can get the correct path using the Bdl.GetDataFilePath method.

    Here is example code that configures remoting and instantiates a remote object:

    using System;
using Silk Performer;
using System.Runtime.Remoting;
using RemoteDll;
namespace SPProject1
{
[VirtualUser("VUser")]
public class VUser
{
public VUser()
{
}

[Transaction(ETransactionType.TRANSTYPE_INIT)]
public void TInit()
{
 RemotingConfiguration.Configure(Bdl.GetDataFilePath("vuser.config"));
 }

[Transaction(ETransactionType.TRANSTYPE_MAIN)]
public void TMain()
{ // .NET Runtime knows that objects of type RemoteDll.RemoteClass1 are remoted
 RemoteClass1 rm1 = new RemoteClass1();
 rm1.SomeMethod("param");
}

[Transaction(ETransactionType.TRANSTYPE_END)]
public void TEnd()
{
}
}
}

    As HTTP was configured as the transporting protocol, you can view the traffic generated for the .NET remoting calls via TrueLog Explorer.

Parent topic: Testing Web Services and .NET Remoting Objects with .NET Framework


Testing SOAP Web Services for .NET

A Web service is an available service on the Web that can be invoked and from which results can be returned. Although other standards exist, the widely accepted standard for Web services, which has been adopted by the W3C, is SOAP (Simple Object Access Protocol).

This section explains the basics of SOAP-based Web services and details how you can test them.

  • Simple Object Access Protocol (SOAP)
    Describes the Simple Object Access Protocol (SOAP).
  • Testing SOAP Over HTTP-Based Web Services
    Explains the three options that are available for testing SOAP over HTTP-based services.
  • Silk Performer .NET Explorer
    Describes how you can use .NET Explorer to test Web services with Silk Performer.
  • Silk Performer .NET Framework
    Silk Performer’s .NET Framework enables developers and QA personnel to coordinate their development and testing efforts while allowing them to work entirely within their specialized environments.
  • External References
    Lists the references that are used for the section.
Parent topic: .NET Support
Parent topic: .NET Testing Support


Simple Object Access Protocol (SOAP)

Simple Object Access Protocol (SOAP) is a lightweight XML-based protocol that is used for the exchange of information in decentralized, distributed application environments. You can transmit SOAP messages in any way that the applications require, as long as both the client and the server use the same method. The current specification describes only a single transport protocol binding, which is HTTP.

SOAP perfectly fits into the world of Internet applications and promises to improve Internet inter-operability for application services in the future. In essence, SOAP packages method calls into XML strings and delivers them to component instances through HTTP.

SOAP XML documents are structured around root elements, child elements with values, and other specifications. First an XML document containing a request (a method to be invoked and the parameters) is sent out. The server responds with a corresponding XML document that contains the results.

SOAP is not based on Microsoft technology. It is an open standard drafted by UserLand, Ariba, Commerce One, Compaq, Developmentor, HP, IBM, IONA, Lotus, Microsoft, and SAP. SOAP 1.1 was presented to the W3C in May 2000 as an official Internet standard. Microsoft is one of the greatest advocates of SOAP and has incorporated SOAP as a standard interface in the .NET architecture.

A SOAP stack, an implementation of the SOAP standard on the client side, is comprised of libraries and classes that offer helper functions. A significant Web service testing challenge is that there are a number of SOAP stack implementations that are not compatible with one another. So although SOAP is intended to be both platform- and technology-independent, it is not. Web services written in .NET are however always compatible with .NET clients—they use the same SOAP stack, or library. When testing a .NET Web service however, you need to confirm if the service is compatible with other SOAP stack implementations, for example Java SOAP stack, to avoid interoperability issues.

SOAP client requests are encapsulated within HTTP POST or M-POST packages. The following example is taken from the Internet draft-specification.

Sample Call

POST /StockQuote HTTP/1.1
Host: www.stockquoteserver.com
Content-Type: text/xml;
charset="utf-8"
Content-Length: nnnn
SOAPAction: "Some-URI"
<?xml version="1.0"?>
<SOAP-ENV:Envelope
  xmlns:SOAP-ENV="http://schemas.xmlsoap.org/soap/envelope/"
  SOAP-ENV:encodingStyle="http://schemas.xmlsoap.org/soap/encoding/">
  <SOAP-ENV:Body>
    <m:GetLastTradePrice xmlns:m="Some-URI">
      <symbol>DIS</symbol>
    </m:GetLastTradePrice>
  </SOAP-ENV:Body>
</SOAP-ENV:Envelope>

The first four lines of code are standard HTTP. POST is the HTTP verb which is required for all HTTP messages. The Content-Type and Content-Length fields are required for all HTTP messages that contain payloads. The content-type text/xml indicates that the payload is an XML message to the server or a firewall capable of scanning application headers.

The additional HTTP header SOAPAction is mandatory for HTTP based SOAP messages, and you can use it to indicate the intent of a SOAP HTTP request. The value is a URI that identifies the intent. The content of a SOAPAction header field can be used by servers, for example firewalls, to appropriately filter SOAP request messages in HTTP. An empty string ("") as the header-field value indicates that the intent of the SOAP message is provided by the HTTP Request-URI. No value means that there is no indication on the intent of the message.

The XML code is straightforward. The elements Envelope and Body offer a generic payload-packaging mechanism. The element GetLastTradePrice contains an element called symbol, which contains a stock-ticker symbol. The purpose of this request is to get the last trading price of a specific stock, in this case Disney (DIS).

The program that sends this message only needs to understand how to frame a request in a SOAP-complient XML message and how to send it through HTTP. In the following example, the program knows how to format a request for a stock price. The HTTP server that receives the message knows that it is a SOAP message because it recognizes the HTTP header SOAPAction. The server then processes the message.

SOAP defines two types of messages, calls and responses, to allow clients to request remote procedures and to allow servers to respond to such a request. The previous example is an example of a call. The following example comes as a response in answer to the call.

Sample Response

HTTP/1.1 200 OK
Content-Type: text/xml;
charset="utf-8"
Content-Length: nnnn
<?xml version="1.0"?>
<SOAP-ENV:Envelope
  xmlns:SOAP-ENV="http://schemas.xmlsoap.org/soap/envelope/"
  SOAP-ENV:encodingStyle="http://schemas.xmlsoap.org/soap/encoding/"/>
  <SOAP-ENV:Body>
    <m:GetLastTradePriceResponse xmlns:m="Some-URI">
      <Price>34.5</Price>
    </m:GetLastTradePriceResponse>
  </SOAP-ENV:Body>
</SOAP-ENV:Envelope>

The first three lines of code are standard HTTP. The first line indicates a response code to the previous POST request, the second and third line indicate the content type and the fourth line the lenght of the response.

XML headers enclose the actual SOAP payloads. The XML element GetLastTradePriceResponse contains a response to the request for a trading price. The child element is Price, which indicates the value that is returned to the request.

  • Java Explorer
    Lists the technologies for which Java Explorer provides support.
  • Java Framework
    Explains that the Java Framework offers a powerful means of simulating virtual users whose behavior is defined with the Java programming language.
Parent topic: Testing SOAP Web Services for .NET
Parent topic: Testing SOAP Web Services for Java


Testing SOAP Over HTTP-Based Web Services

Silk Performer offers three options for testing SOAP over HTTP based services:

  • Recording/replaying HTTP traffic
  • .NET Explorer in combination with Silk Performer .Net Framework
  • Java Explorer in combination with Silk Performer Java Framework

Your environment and prerequisites will determine which of these options is best for your needs.

  • Recording and Replaying HTTP Traffic
    Describes how you can record and replay HTTP traffic to load test SOAP over HTTP-based Web services.
Parent topic: Testing SOAP Web Services for .NET
Parent topic: Testing SOAP Web Services for Java


Recording and Replaying HTTP Traffic

Recording the SOAP protocol over HTTP is as straightforward as recording any Web application that runs in a browser. The application that you record is the application that executes the SOAP Web Service calls. This can either be a client application or a part of the Web application itself.

  1. Creating a New XML/SOAP Project
    Create a new XML/SOAP project to record and replay HTTP traffic.
  2. Creating the Recording Profile
    Create a recording profile for the application to record and replay HTTP traffic.
  3. Recording a Script
    Record a script to replay HTTP traffic.
  4. Script Customization
    Customize a recorded script to replay HTTP traffic.
  5. Replaying a Script
    Replay a script to test SOAP over HTTP-based Web services.
Parent topic: Testing SOAP Over HTTP-Based Web Services


Creating a New XML/SOAP Project

When you want to record and replay HTTP traffic to test SOAP over HTTP-based Web services, you first need to create a new Silk Performer project of the Web Services > XML/SOAP type.
  1. Click Start here on the Silk Performer workflow bar.
    Note: If another project is already open, choose File > New Project from the menu bar and confirm that you want to close your currently open project.
    The Workflow - Outline Project dialog box opens.
  2. In the Name text box, enter a name for your project.
  3. Enter an optional project description in Description.
  4. From the Type menu tree, select Web Services > XML/SOAP. This application type automatically configures its profile settings so that SOAPAction HTTP-headers, that are used by SOAP-based applications when calling Web services, are to be recovered.
  5. Click Next to create a project based on your settings.
The Workflow - Model Script dialog box appears.
Parent topic: Recording and Replaying HTTP Traffic
Next topic: Creating the Recording Profile


Creating the Recording Profile

When you want to record and replay HTTP traffic to test SOAP over HTTP-based Web services, you need to create a recording profile for the client application that you want to record.
  1. Click Model Script on the workflow bar. The Workflow - Model Script dialog box appears.
  2. Click Settings. The System Settings - Recorder dialog box appears.
  3. In the System group box, click Recorder. The Recording Profiles page opens.
  4. Click Add to add a new recording profile to the list. The Recording Profile dialog box opens.
  5. Type a name for the recording profile in the Profile name text box. For example Internet Explorer.
  6. Click Browse ... next to the Application path text box and select the path to the application executable. For example C:\Program Files\Internet Explorer\Explorer.exe.
  7. Define the Working directory. For example C:\Program Files\Internet Explorer.
  8. Define the Program arguments. For example about:blank.
  9. Select the application type from the Application Type list box. For example MS Internet Explorer.
  10. In the Protocol selection area, check the check box that corresponds to the protocol that you want to use. For example, check the Web check box.
  11. To configure the recording profile for WinSock recording click Web Settings, which enables you to select the method that the Recorder is to use to capture Web and TCP/IP-based traffic.
  12. Click OK.
Parent topic: Recording and Replaying HTTP Traffic
Previous topic: Creating a New XML/SOAP Project
Next topic: Recording a Script


Recording a Script

Record a script with your created recording profile. Interact with your client application and the recorder will record all SOAP requests that are executed over HTTP/HTTPS. When you are finished, close the application and save the recorded script.
  1. Click Model Script on the workflow bar. The Workflow - Model Script dialog box appears.
  2. Select one of the listed browsers from the Recording Profile list, depending on the browser you want to use for recording.
  3. In the URL field, enter the URL that is to be recorded.
  4. Click Start recording. The Silk Performer Recorder dialog opens in minimized form, and the client application starts.
  5. To see a report of the actions that happen during recording, maximize the Recorder dialog by clicking the Change GUI size button. The maximized Recorder opens at the Actions page.
  6. Interact with your client application. The recorder records all SOAP requests that are executed over HTTP/HTTPS.
  7. To end recording, click the Stop Recording button.
  8. Enter a name for the .bdf file and save it. The Capture File page displays. Click Generate Script to generate a script out of the capture file.
Parent topic: Recording and Replaying HTTP Traffic
Previous topic: Creating the Recording Profile
Next topic: Script Customization


Script Customization

Each SOAP request that is recorded includes a WebHeaderAdd and a WebUrlPostBin API call.

You can either customize the input parameter of each Web Service call by manually changing the script or you can use the more convenient method of performing customizations within TrueLog Explorer. To do this, run a Try Script. Then use the XML control to customize the XML nodes that represent the input parameters.

Sample SOAP Request

WebHeaderAdd("SOAPAction", "\"http://tempuri.org/Login\"");
WebUrlPostBin(
  "http://localhost/MessageWebService/MessageService.asmx",
  "<?xml version=\"1.0\" encoding=\"utf-8\"?>"
  "<soap:Envelope xmlns:soap=\"http://schemas.xmlsoap.org/soap/envelope/
\"
    "xmlns:xsi=\"http://www.w3.org/2001/XMLSchema-instance\"
    "xmlns:xsd=\"http://www.w3.org/2001/XMLSchema\">"
    "<soap:Body>"
      "<Login xmlns=\"http://tempuri.org/\">"
        "<sUsername>myuser</sUsername>"
        "<sPassword>mypass</sPassword>"
      "</Login>"
    "</soap:Body>"
  "</soap:Envelope>", STRING_COMPLETE, "text/xml; charset=utf-8");
Parent topic: Recording and Replaying HTTP Traffic
Previous topic: Recording a Script
Next topic: Replaying a Script


Replaying a Script

Once you have finished script customization, you can replay your script, either in another Try Script run, as part of baseline identification, or in a test.

Select how you want to replay your script. The following options are available:
  • Start a Try Script run.
  • Replay the script as part of a baseline identification.
  • Replay the script in a test.

As the Web service calls are performed along with Web API functions, you receive the same measures you receive when testing any Web application, including detailed protocol-specific statistics.

Parent topic: Recording and Replaying HTTP Traffic
Previous topic: Script Customization


Silk Performer .NET Explorer

This section offers a brief overview of how you can use .NET Explorer to test Web services with Silk Performer. .NET Explorer is a tool that allows you to create test cases through a point and click interface. .NET Explorer provides support for the following .NET technologies:
  • SOAP Web services
  • .NET Remoting
  • .NET Components (other classes)

You can use the .NET Explorer to create test scenarios. You can then use the test scenarios to run component testing in .NET Explorer or you can export the test scenarios to Silk Performer for testing.

You can also use .NET Explorer to generate test drivers, in either C# or VB.NET, that contain all test logic defined for test scenarios. You can export the test drivers to Visual Studio .NET where you can make further customizations and where you can execute TryScript runs directly in Visual Studio .NET. Once you have completed the customization, you can execute tests with Silk Performer.

.NET Explorer requires permanent projects. This was not the case with previous versions as it was possible to save current projects at any time. When you launch .NET Explorer you are prompted to either create a new project or open an existing project by choosing from a recent file list or by browsing for a .NET Explorer project file, of type .NEF.

For additional details on .NET Explorer, refer to the .NET Explorer Help.

  • Requirements
    Describes the requirements for testing a SOAP-based Web service.
  • Loading a WSDL File
    Describes how you can load a WSDL file.
  • Calling a Web Service
    Describes how you can call a Web service.
  • Final Steps
    Describes how you can finish testing a Web service with .NET Explorer.
Parent topic: Testing SOAP Web Services for .NET


Requirements

The only requirement for testing a SOAP-based Web service is a description of the exposed methods of the Web service. You can find such descriptions in Web Service Description Language (WSDL) files, which are normally generated when you browse a Web-service end point or you specify special HTTP GET parameters for retrieving such files.

In the case of an ASP.NET Web service, appending ?WSDL to the URL end point of the Web service will return the WSDL file for the Web service. Other SOAP-stack implementations may use the same approach or offer WSDL files under separate URLs.

Parent topic: Silk Performer .NET Explorer


Loading a WSDL File

.NET Explorer offers the Load File Wizard that guides you through the steps required to load a WSDL file and invoke Web-service methods. To activate the wizard in .NET Explorer, click Start Here on the toolbar.

You can also load WSDL files, or .NET assemblies that contain .NET Remoting or other .NET classes, through the address bar of your browser. Specify the URL or path to the WSDL file and click Load.

Microsoft .NET Framework offers classes that load WSDL files and generate client proxies for Web services that are defined in WSDL files. .NET Explorer uses this functionality to generate C# or VB.NET code for Web-service proxies and compile the code into temporary .NET assemblies that are displayed as Web Service Proxies in .NET Explorer > Loaded Components > References.

As .NET Explorer uses Microsoft .NET Framework to generate proxies, .NET Explorer shares the drawbacks and limitations of Microsoft .NET Framework. The most significant problem when generating proxies is that not all SOAP stack implementations produced by other vendors comply with the W3C standard. This can lead to problems when you attempt to load WSDL files. You can avoid these problems by manually editing the WSDL files so that they are recognized by Microsoft .NET Framework. To edit the WSDL files you must be familiar to WSDL. For additional information, refer to http://www.w3.org.

.NET Explorer shows a Web-service proxy class, derived from System.Web.Services.Protocols.SoapHttpClientProtocol, in the References menu tree below the Web Service Proxies tree node. Normally, when you write C# or VB.NET code, you must instantiate an instance of the proxy class and call methods on the proxy. .NET Explorer eliminates the need for this by automatically instantiating an instance of the proxy class. You cannot create an instance of a proxy class by calling the constructor. .NET Explorer treats Web services like static objects offering static methods.

If the methods of a Web service take complex objects as parameters, then the classes of those parameters are defined in the WSDL file and loaded by .NET Explorer. Such classes are not Web-service proxy classes. They are simple classes with members and are listed under the Other Classes tree node in the Class menu tree.

You can set several connection-related properties by double-clicking a proxy class in the menu tree and opening the connection wizard in the Input Data Properties pane. These properties are set to the corresponding properties of the internal proxy instance.

When you export a project to either Visual Studio .NET or directly to Silk Performer as a .NET project, the base class of the Web-service proxy is replaced by SilkPerformer.SPSoapHttpClientProtocol. The reason for this is that by exchanging the base class, the Silk Performer .NET Framework is able to generate more detailed timers for Web-service calls that are routed through the Silk Performer Web engine. If you don't want this behavior you can export a project to Visual Studio .NET and either change the base class back manually or use the Web Service dialog box from the Silk Performer menu and deselect the option for routing the proxy class.

You can now either load the WSDL file of the Web service you want to test or select a WSDL file from the list box.

Parent topic: Silk Performer .NET Explorer


Calling a Web Service

After you have successfully loaded a WSDL file you can explore the methods that the Web service offers by expanding the tree node of the Web-service proxy class.

By clicking one of the methods you will see the required input parameters and input header information for the Web-service call. You can customize your input data by either exchanging the default static values for the primitive types or by using global, local, or rendom variables. For additional information, refer to the .NET Explorer Help and the Silk Performer Help.

If a method is called for the first time on a Web service, the internal instance of the proxy class is instantiated. There is a property on the proxy class that holds a cookie container. This property is initialized with a new cookie container so that it can call Web services that handle cookies.

.NET Explorer then sets all the defined values for the SOAP headers to the corresponding member fields of the proxy class. Then a parameter list with all the values that are defined for the input parameters is created. Using this list, the method on the Web-service proxy object is invoked.

Microsoft .NET Framework includes a hooking mechanism that allows .NET Explorer to capture traffic that is passed between the .NET Explorer client and the Web server. You can view the trafic in the Show Traffic dialog box after the method call. You can invoke the dialog box on each Web service and each .NET Remoting call.

This feature is also used to generate BDL Web scripts with a WebPagePost for each Web-service call captured in the traffic moving from the client to the server.

The returned values and SOAP header information are displayed when the method calls return successfully. When exceptions occur, the exception text is displayed in a message box. Currently you cannot add method calls to test scenarios that throw errors because .NET Explorer requires information about the returned values.

Parent topic: Silk Performer .NET Explorer


Final Steps

After calling a Web service you can store the returned values to variables and define verifications for those values.

Once you have finished defining your test scenario you can either remain in .NET Explorer, and use your test scenario for functional testing, or you can export the project to Visual Studio .NET or Silk Performer to further customize the generated code and run regression tests.

You can only export to BDL Web projects when your test scenarios contain only Web-service calls, because only WebPagePost statements are generated for each Web-service call. If you have calls other than Web-service calls, for example calls to other .NET objects, those calls will not be included in Web scripts and therefore your exported scripts may not behave as defined in .NET Explorer, as some method calls will be missing.

Only export to BDL Web projects if you have only Web-service calls and if you only wish to test the SOAP stack of your server, as there is no .NET client SOAP stack involved when executing scripts in Silk Performer. The Silk Performer Web engine posts only those SOAP envelopes that have been used in .NET Explorer.

If you also wish to test the .NET client side, you should export your project to a Silk Performer .NET project. This type of project will compile generated .NET test code into a .NET assembly that can be called from a BDL script, which will also be generated by .NET Explorer.

If you wish to make further customizations to .NET code generated by .NET Explorer you can export your project to Visual Studio .NET. If you export your project you can alter generated test code and run a TryScript within Visual Studio .NET. If you are finished with customizations you can export the project to Silk Performer and proceed with testing.

Parent topic: Silk Performer .NET Explorer


Silk Performer .NET Framework

Silk Performer’s .NET Framework enables developers and QA personnel to coordinate their development and testing efforts while allowing them to work entirely within their specialized environments: Developers work exclusively in Visual Studio while QA staff work exclusively in Silk Performer—there is no need for staff to learn new tools. Silk Performer’s .NET Framework thereby encourages efficiency and tighter integration between QA and development. The Silk Performer .NET Framework (.NET Framework) and .NET Add-On enable you to easily access Web services from within .NET. Microsoft Visual Studio offers wizards that allow you to specify the URLs of Web services. Microsoft Visual Studio can also create Web-service client proxies to invoke Web-service methods.

  • Creating a New Silk Performer .NET Project
    Use Silk Performer or Visual Studio .NET to create a new Silk Performer .NET project.
  • Creating a Web Service Client Proxy
  • Instantiating a Client Proxy Object
    Describes how you can instantiate a client-proxy object.
  • Calling a Web Service Method
    Describes how you can call a Web-service method.
  • Routing Web-Service Traffic
    Explains that the Silk Performer .NET Framework can route Web traffic generated by .NET components through the Silk Performer Web engine.
  • Exploring Results
    Describes where you can find the results of the load tests that you have performed.
  • Testing .NET Components
    Explains how to use Silk Performer’s Visual Studio .NET Add-On for testing .NET Components.
  • Understanding the .NET Framework Platform
    .NET Framework is a powerful programming platform that enables developers to create Windows-based applications.
Parent topic: Testing SOAP Web Services for .NET
Parent topic: .NET Explorer Help
Parent topic: .NET Framework Developer Guide


Creating a New Silk Performer .NET Project

To create a new Silk Performer .NET project, you can either create a new project of type Web Services > .NET Explorer in Silk Performer or you can use one of the Silk Performer .NET project wizards in Visual Studio .NET.
With both approaches you can choose one of the following three implementation languages:
  • C#
  • VB.NET
  • C++

If you choose one of the .NET project wizards in Visual Studio .NET, the result is a new project with a template class that defines three methods, which are the init, main, and end transactions of your Silk Performer virtual user.

To develop a .NET test driver in another language, create an empty project using the language of your choice and perform the following steps:

  1. Add a reference to perfdotnetfw.dll. This DLL is located in the Silk Performer installation directory.
  2. Add a new class to your project.
  3. Add the VirtualUser custom attribute to your class.
  4. Add public member functions to your class to serve as your user transactions.
  5. Add the Transaction attribute to the functions you have created and pass the corresponding transaction type.
    • init
    • main
    • end
Parent topic: Silk Performer .NET Framework


Creating a Web Service Client Proxy

Visual Studio .NET has a wizard that generates a Web-service-client proxy that allows you to call Web-service methods.

You can start the wizard in Project > Add Web Reference.

  1. To start the wizard, click Project > Add Web Reference.
  2. In the corresponding text box, type the URL of your Web service and press Enter. For example, http://demo.borland.com/BorlandSampleService/BorlandSampleService.asmx?WSDL.
  3. If the wizard can load the WSDL document from the URL, click Add Reference. The wizard generates a proxy class in a namespace, which is the reverse of the name of the Web server that hosts the service.
Explore projects to see which classes are generated. Each web service, and all complex data types used by the Web-service methods, are represented as classes. So in the example URL above, there is Service1, which is a Web service, and User, which is a complex parameter.
Parent topic: Silk Performer .NET Framework
Parent topic: Testing Web Services With Microsoft Visual Studio


Instantiating a Client Proxy Object

You can declare a variable of a client proxy class as a public member of the .NET test driver to instantiate a client-proxy object. The variable should be instantiated either in the constructor or in the init transaction. The first part of the namespace where the class is generated, which is the default namespace, is the name of your project.

Example

If you have created a project with the name DotNetProject you would use the following variable declaration:
[VirtualUser("Vuser")]
public class Vuser
{
  public DotNetProject.com.borland.demo.Service1 mService;
  [Transaction(Etranstype.TRANSTYPE_INIT)]
  public void TInit()
  {
    mService = new DotNetProject.com.borland.demo.Service1();
  }
}
Parent topic: Silk Performer .NET Framework
Parent topic: Testing Web Services With Microsoft Visual Studio


Calling a Web Service Method

All methods that are exposed by Web services are also available in proxy objects. The methods that are shared by proxy objects use the same names as their corresponding WSDLs. Web-service method calls should be placed in main transactions.

Example

[Transaction(Etranstype.TRANSTYPE_MAIN)]
public void TMain()
{
  string sReturn = mService.echoString("Test");
  Bdl.Print(sReturn);
}

To customize your Web-service calls from a generated BDL script, you must allow the exchange of data between BDL and .NET with usage of attributes or method parameters.

Example

[Transaction(Etranstype.TRANSTYPE_MAIN)]
[TestAttribute("EchoInput", "Test")]
public void TMain()
{
  string sReturn = mService.echoString(Bdl.AttributeGet("EchoInput"));
  Bdl.Print(sReturn);
}
or
[Transaction(Etranstype.TRANSTYPE_MAIN)]
public void TMain(string sEcho)
{
  string sReturn = mService.echoString(sEcho);
  Bdl.Print(sReturn);
}
Parent topic: Silk Performer .NET Framework
Parent topic: Testing Web Services With Microsoft Visual Studio


Routing Web-Service Traffic

The Silk Performer .NET Framework can route Web traffic generated by .NET components through the Silk Performer Web engine. This means that the Web engine executes the actual Web requests, enabling you to see exactly what is sent over the wire. You can also use features of the Silk Performer Web engine, like modem simulation, IP multiplexing, network statistics, TrueLog, and others.

By default all network traffic is routed through the Web engine. You can switch the routing off and only enable it for specific Web-service client-proxy classes. To switch the routing on for specific Web-service client-proxy classes, you need to change the base class of the proxy classes from SoapHttpClientProtocol to SilkPerformer.SPSoapHttpClientProtocol. Changing the base class allows the Silk Performer .NET Framework to generate more detailed statistical information for each Web-service call. We recommend that you enable this feature for all your Web-service proxy classes. You can enable this feature by using the Web Service dialog box in Microsoft Visual Studio, which is accessible through the Silk Performer menu.

For each Web-service call a node is created in the TrueLog with the SOAP envelope that was passed to the Web service and returned to the client.

If detailed statistical information for Web-service calls is disabled, the .NET HTTP classes process all requests.

Parent topic: Silk Performer .NET Framework
Parent topic: Testing Web Services With Microsoft Visual Studio


Exploring Results

When Web-service-traffic routing is enabled, a TrueLog node is logged for each Web-service call that is executed by the .NET test driver.

In the overview report of the Web-service method that is called, you will find statistical information.

Parent topic: Silk Performer .NET Framework
Parent topic: Testing Your .NET Test Driver


External References

  1. Session, Roger

    SOAP. An overview of the Simple Object Access Protocol, March 2000

    http://www.w3.org/TR/SOAP/

  2. W3C

    Simple Object Access Protocol (SOAP) 1.1, December 2000

    http://www.w3.org/TR/SOAP/

  3. UN/CEFANT, OASIS

    Enabling Electronic Business with ebXML, December 2000

    http://www.ebxml.org/white_papers/whitepaper.htm

  4. Geyer, Carol

    ebXML Integrates SOAP Into Messaging Services Specification, March 2001

    http://www.ebxml.org/white_papers/whitepaper.htm

  5. Open Financial Exchange

    Open Financial Exchange Specification 2.0, April 2000

    http://www.ofx.net/

Parent topic: Testing SOAP Web Services for .NET
Parent topic: Testing SOAP Web Services for Java


Setting Up Silk Performer .NET Projects

  1. Click Start here on the Silk Performer workflow bar.
    Note: If another project is already open, choose File > New Project from the menu bar and confirm that you want to close your currently open project.
    The Workflow - Outline Project dialog box opens.
  2. In the Name text box, enter a name for your project.
  3. Enter an optional project description in Description.
  4. From the Type menu tree, select .NET > .NET Framework using Visual Studio .NET Add-On and click Next. The Workflow - Model Script dialog box opens.
  5. Select the .NET Language (C# or VB.NET) icon for the language you prefer and click OK. The Microsoft Visual Studio Silk Performer Project Wizard opens.
  6. Enter the name of the .NET Testclass in the Name of testclass text box. In the Silk Performer Project text box, enter the name of the project that you created earlier in Silk Performer.
  7. Click Finish.
The following in the files and code are generated in Microsoft Visual Studio:
  • Each generated Testclass becomes a VirtualUser in the BDL script.
  • The first transaction becomes the Init transaction in the BDL script.
  • Files that are generated by the Wizard (code files and Silk Performer project/BDL scripts) are listed on the Solution Explorer page.
  • Handler/clean-up code can be inserted in the stopException method.
  • Custom code for exception handling can be inserted in the testException method.
  • ETransactionType.TRANSTYPE_MAIN becomes the Main transaction in the BDL script.
  • ETransactionType.TRANSTYPE_END becomes the End transaction in the BDL script.

Sample Skeleton Code Generated by the Project Wizard (C#)

using System;
using Silk Performer;

namespace SPProject1
{
  [VirtualUser("VUser")]
  public class VUser
  {
    public VUser()
    {
    }

    [Transaction(ETransactionType.TRANSTYPE_INIT)]
    public void TInit()
    {
      /* You can add multiple TestAttribute attributes to each function defining parameters that can be accessed through Bdl.AttributeGet

      Example of testcode: (Access bdl function through the static functions of the Bdl class Bdl.MeasureStart(...);
      ...
      Bdl.MeasureStop(...);
      */
    }

    [Transaction(ETransactionType.TRANSTYPE_MAIN)]
    public void TMain()
    {
    }

    [Transaction(ETransactionType.TRANSTYPE_END)]
    public void TEnd()
    {
    }
  }
}

As you can see from the skeleton example above, there is a custom attribute called VirtualUser that can be applied to classes. This causes the Add-On's BDL Generation Engine to generate a virtual user definition. You can implement multiple classes that have the VirtualUser attribute applied. The VirtualUser attribute takes the name virtual user as a parameter.

The BDL Generation Engine then parses the methods of the Virtual User class for methods that have a Transaction attribute applied to them. The Transaction attribute takes as a first parameter the transaction type (Init, Main or End). You can only have one Init and one End transaction, but multiple Main transactions.

The Main transaction type takes a second parameter that indicates the number of times that the transaction is to be called during load tests (default: 1).

  • Running a Try Script Test
    Run a Try Script test from Microsoft Visual Studio .NET
  • Custom Attributes
    Explains the VirtualUser attribute and how to apply it to clases.
Parent topic: .NET Support
Parent topic: Load Testing .NET Components


Running a Try Script Test

If you have implemented your .NET test code you can run a Try Script test from within Microsoft Visual Studio .NET.

  1. Choose one of the following:
    • Press F8.
    • Choose Silk Performer > TryScript.
    The .NET Code is compiled to a .NET assembly.

    A BDF script is generated by the BDL Generation Machine based on the meta information of the custom attributes and the settings in the Options dialog.

    The most recent BDF script is overwritten if there have been changes to the meta data of your assembly (changed custom attributes, changed method order, changed generation options, etc.).

    If the meta data has changed but you have altered the latest BDF file manually, you will be prompted to specify whether or not you wish to have the file overwritten, in which case you will lose recent changes. This detection is achieved by comparing the last modified date of the BDF file with the timestamp scripted in the BDF file.

  2. If you have multiple virtual user classes (classes that have the VirtualUser attribute applied) you will be prompted to specify which of the users is to be started. The test begins.

    If you have the Automatic Start when running a Try Script option selected, TrueLog Explorer will start, loaded with the TrueLog generated by the test.

    Virtual user output is displayed in the Virtual User Output tool window.

    Load test controller output is displayed in a separate pane of the Output tool window.

Once the load test is complete you can explore the other results files (log, output, report, and error) by selecting them from the Silk Performer Results menu.

Parent topic: Setting Up Silk Performer .NET Projects
Related concepts
Custom Attributes


Custom Attributes

A custom attribute called VirtualUser can be applied to classes. This attribute instructs the Add-In’s BDL generation engine to generate a virtual user definition. You can implement multiple classes that have the VirtualUser attribute applied to them. The VirtualUser attribute takes the name virtual user as a parameter.

Note: When a BDF file is modified manually, you are prompted to specify whether or not you want to have the file overwritten.

The BDL generation engine parses the methods of the VirtualUser class for methods that have a Transaction attribute applied to them. The Transaction attribute takes the transaction type, Init, Main or End, as a first parameter. You can only have one Init and one End transaction, but multiple Main transactions are allowed.

The Main transaction type takes a second parameter that indicates the number of times that the transaction is to be called during a test (the default is 1).

Following are the available custom attributes and what the BDL generation engine scripts for them.

Attribute Class | Applicable to | Parameters | Description
VirtualUser Class Name of the Virtual User Group

(optional) IsUnitTest

Defines a Virtual User Group.

If you specify true, DotNetUnitTest methods will be scripted instead of the standard DotNet methods (e.g., DotNetUnitTestLoadObject).

Transaction Method Type (Init, Main, End)

If type is Main the number of transaction iterations

(optional) Name

Defines a Transaction for the Virtual User Group.

The transaction implementation will call the method of the .NET Object.

The first script call in the Init transaction is a DotNetLoadObject loading the Object The last script call in the end transaction is a DotNetFreeObject.

Optionally you can define a name that should be used in the generated BDL script for this transaction. By default, the transaction name in BDL is created by combining the VUser name and the method name.

TestMethod Method This will script a call to the method in the current transaction.

The current transaction is the previous method with a Transaction attribute. So a method with this attribute that has no prior method with a Transaction attribute makes no sense.

TestAttribute Method Attribute Name

Attribute Value

(optional) Description

This can be applied multiple times to a method that has either a Transaction or TestMethod attribute.

An AttributeSetString function will be scripted prior to the DotNetCallMethod that calls this method. AttributeSetString will set an attribute with the passed name and value. This is a way how parameters can be passed from the script to the .NET function. The .NET function can read the attributes with Bdl.AttributeGet. Its meant that people (QA) who will receive the finished script only have to change the value passed to the AttributeSetString to customize the script. So there is no need for them to change the .NET Code.

Allows you to define a description for the project attribute. The description can be seen in Silk Performer's project attribute wizard.

VirtualUserInitialize | Method | This method is called for classes that are loaded via DotNetUnitTestLoadObject
VirtualUserCleanup | Method | This method is called for classes that are freed via DotNetUnitTestFreeObject
TestCleanup | Method | This method is called after a method is called via DotNetUnitTestCallMethod
TestInitialize | Method | This method is called before a method is called via DotNetUnitTestCallMethod
TestIgnore | Method | Methods that have this attribute applied to them will not be called via DotNetUnitTestCallMethod
TestException Method Type of exception

Additional log message

Normally, methods that throw exceptions are considered failed. If you want a method to throw an exception, you can use the TestException attribute to tell Silk Performer that this method is supposed to throw an exception.
  • Custom Attributes Code Sample
    Includes a C# test code sample.
  • Generated BDF Script Example
    Includes a sample BDF script.
  • Attributes for Unit Test Standards
    Explains the attributes for methods that are called before and after test methods when working with unit-testing frameworks.
  • Negative Testing
    Explains that Silk Performer offers an attribute that can be applied to test methods to indicate that a specific exception type is expected.
Parent topic: Setting Up Silk Performer .NET Projects
Parent topic: Load Testing .NET Components
Related tasks
Running a Try Script Test


Custom Attributes Code Sample

C# Test Code Sample

using System;
using SilkPerformer;

namespace SPProject1
{
  [VirtualUser("VUser")]
  public class VUser
  {
    public VUser()
{
    }
    [Transaction(ETransactionType.TRANSTYPE_INIT)]
    public void TInit()
    {
    }
    [Transaction(ETransactionType.TRANSTYPE_MAIN)]
    public void TMain()
    {
    }
    [TestMethod]
    [TestAttribute("Attr1", "DefaultValue1")]
    public void TestMethod1()
    {
      string sAttrValue = Bdl.AttributeGet("Attr1");
      Bdl.Print(sAttrValue);
    }
    [Transaction(ETransactionType.TRANSTYPE_END)]
    public void TEnd()
    {
    }
  }
}
Parent topic: Custom Attributes


Generated BDF Script Example

benchmark DOTNETBenchmarkName

use "dotnetapi.bdh"

dcluser
 user

    VUser
 transactions
   VUser_TInit : begin;
   VUser_TMain : 1;
   VUser_TEnd  : end;
var
 hVUser : number;

dcltrans
 transaction VUser_TInit
 begin
   hVUser:= DotNetLoadObject("\\SPProject1\\bin\\release\\SPProject1.dll", "SPProject1.VUser");
   MeasureStart("TInit");
   DotNetCallMethod(hVUser, "TInit");
   MeasureStop("TInit");
 end VUser_TInit;

 transaction VUser_TMain
 begin
   MeasureStart("TMain");
   DotNetCallMethod(hVUser, "TMain");
   MeasureStop("TMain");
   AttributeSetString("Attr1", "DefaultValue1");
   MeasureStart("TestMethod1");
   DotNetCallMethod(hVUser, "TestMethod1");
   MeasureStop("TestMethod1");
 end VUser_TMain;

 transaction VUser_TEnd
 begin
   MeasureStart("TEnd");
   DotNetCallMethod(hVUser, "TEnd");
   MeasureStop("TEnd");
   DotNetFreeObject(hVUser);
 end VUser_TEnd;
Parent topic: Custom Attributes


Creating Silk Performer .NET Projects in Microsoft Visual Studio

When you create a Silk Performer .NET project from within Microsoft Visual Studio, ensure that the created solution file (.sln) is placed in the same directory as the created project file (.csproj, .vbproj, etc). In Microsoft Visual Studio’s Create Project wizard, there is a Create directory for Solution check box. Do not select this option (i.e., leave it unchecked). Otherwise you may experience problems when opening the project from Silk Performer’s Model Script dialog.

Parent topic: .NET Support


Memory Usage in .NET

When you run BDL scripts with .NET method calls, Silk Performer needs to host the Microsoft .NET Common Language Runtime (.NET CLR). Hosting the .NET CLR and loading .NET objects requires additional memory that is used for virtual user processes (containers).

Silk Performer allows you to specify whether each virtual user should run in its own application domain or if all virtual users in a virtual user container should share an application domain. One application domain per user means that all objects from individual virtual users are isolated from the objects of the other users in the same virtual user container.

One application domain per virtual user container means that all objects exist in the same domain and may influence one another. This setting can be changed via your project’s profile settings.

Each additional application domain requires additional memory and administrative overhead by the .NET CLR.

Memory consumption (in MB) is listed below, based on the number of users running in a virtual user process and the application domain setting. This is initial memory consumption when starting a load test (for example, no .NET objects have been loaded).

 | 1 VUser | 2 VUser | 3 VUser | 4 VUser | 10 VUser | 20 VUser | 50 VUser
No .NET Calls (normal BDL Script) | 1.668 | 1.760 | 1.836 | 1.904 | 2.352 | 3.124 | 5.484
App Domain/User | 5.268 | 6.644 | 6.828 | 6.940 | 7.916 | 9.364 | 13.868
App Domain/Container | 5.268 | 5.404 | 5.488 | 5.564 | 6.036 | 6.852 | 9.368

The next table shows memory consumption after loading a simple .NET object. The object defines three methods, but no members.

 | 1 VUser | 2 VUser | 3 VUser | 4 VUser | 10 VUser | 20 VUser | 50 VUser
App Domain/User | 5.680 | 7.404 | 7.816 | 8.296 | 11.000 | 15.300 | 28.664
App Domain/Container | 5.688 | 5.812 | 5.900 | 6.012 | 6.620 | 7.628 | 10.240

As you can see from the tables above, having one application domain per virtual user requires more memory than does having one application domain per container. The default setting in the project file is one application domain per user. The reason for this is that the objects created by a user cannot influence the objects of other users. Ensure that you won’t run into problems if objects access global resources from within their application domain.

The initial amount of memory needed to host the .NET CLR is about 3.5 MB. The .NET CLR is hosted only once per virtual user container -- this is not influenced by application domain setting.

Memory consumption when loading objects depends on the size of the objects. In the table above, the example loaded object has no members. If you are loading objects with members, memory consumption will be different.

To free up memory from objects that are no longer referenced, call DotNetFreeObject.

Parent topic: .NET Support


.NET Error Messages

The following issues may occur during .NET load tests.

  • Cannot Start .NET Language Runtime
    Lists the possible cause and resolution for the "Cannot start .NET Language Runtime" error message.
  • Invalid Handle
    Lists the possible cause and resolution for the "Invalid handle" error message.
  • Loading Object Throws an Exception
    Lists the possible cause and resolution for the "Loading Object Throws an Exception" error message.
  • Object Does Not Implement This Public Method
    Lists the possible cause and resolution for the "Object Does Not Implement This Public Method" error message.
  • Method Execution Failed
    Lists the possible cause and resolution for the "Method Execution Failed" error message.
  • .NET Common Language Runtime Not Started
    Lists the possible cause and resolution for the ".NET Common Language Runtime Not Started" error message.
  • Cannot Load mscoree.dll (.NET Runtime)
    Lists the possible cause and resolution for the "Cannot Load mscoree.dll (.NET Runtime)" error message.
  • Initialize .NET Application Domain Failed
    Lists the possible cause and resolution for the "Initialize .NET Application Domain failed " error message.
  • .NET Common Language Runtime Is Not Running
    Lists the possible cause and resolution for the ".NET Common Language Runtime is not running" error message.
  • .NET Assembly With the Given Name Could Not Be Found
    Lists the possible cause and resolution for the ".NET Assembly with the given name could not be found" error message.
  • Perfrun.Exe.Config Could Not Be Written Successfully
    Lists the possible cause and resolution for the Perfrun.Exe.Config could not be written successfully error message.
  • Your .NET DLL References Wrong perfdotnetfw.dll
    Lists the possible cause and resolution for the "Your .NET DLL references wrong perfdotnetfw.dll" error message.
  • Verification Failed
    Lists the possible cause and resolution for the "Verification failed" error message.
  • Exception Has Been Logged
    Lists the possible cause and resolution for the "Exception has been logged" error message.
  • Could Not Find or Load a Specific Class
    Lists the possible cause and resolution for the "Could not find or load a specific class" error message.
  • An Exception Was Thrown by a Type's Initializer (.cctor)
    Lists the possible cause and resolution for the "An exception was thrown by a type's initializer (.cctor)" error message.
  • An Exception Was Thrown by the Called Method
    Lists the possible cause and resolution for the "An exception was thrown by the called method" error message.
  • Invalid Number of Parameters
    Lists the possible cause and resolution for the "Invalid number of parameters" error message.
Parent topic: .NET Support


Cannot Start .NET Language Runtime

Possible Cause | Resolution
Silk Performer couldn't host the .NET Common Language Runtime. | Make sure you have installed the .NET Common Language Runtime.
Parent topic: .NET Error Messages


Invalid Handle

Possible Cause | Resolution
You passed an invalid .NET object handle to the DotNet API function. | Object handles can be acquired by a call to DotNetLoadObject or they can be received with DotNetGetObject if the last called method returns an object.
Parent topic: .NET Error Messages


Loading Object Throws an Exception

Possible Cause Resolution
This error occurs if:
  • Referenced assemblies cannot be loaded/found
  • Your perfdotnetfw.dll has a different version than the perfrun.exe
 Ensure that the assembly files are in the location being referenced and that the versions match for perfdotnetfw.dll and perfrun.exe.
Parent topic: .NET Error Messages


Object Does Not Implement This Public Method

Possible Cause | Resolution
You attempted to call a method that is not a public method of the .NET object. | Only public methods can be called with the DotNetCallMethod function.
Parent topic: .NET Error Messages


Method Execution Failed

Possible Cause | Resolution
Method execution failed because of an unhandled exception. | Examine the method that failed.
Parent topic: .NET Error Messages


.NET Common Language Runtime Not Started

Possible Cause | Resolution
This error occurs when you attempt to call a DotNet function before the .NET CLR has been started. | Ensure that the .NET CLR starts before you call a DotNet function.
Parent topic: .NET Error Messages


Cannot Load mscoree.dll (.NET Runtime)

Possible Cause | Resolution
Silk Performer couldn't host the .NET Common Language Runtime. | Make sure you have installed the .NET Common Language Runtime. The runtime can be installed from the Microsoft Download Center.
Parent topic: .NET Error Messages


Initialize .NET Application Domain Failed

Possible Cause | Resolution
A .NET application domain couldn't be started. | Check to see if your user has the privilege to run .NET applications.
Parent topic: .NET Error Messages


.NET Common Language Runtime Is Not Running

Possible Cause | Resolution
This error occurs when you attempt to call a DotNet function before the .NET CLR has been started. | Ensure that the .NET CLR starts before you call a DotNet function.
Parent topic: .NET Error Messages


.NET Assembly With the Given Name Could Not Be Found

Possible Cause | Resolution
The assembly file passed as the first parameter to DotNetLoadObject cannot be found. | If you passed a relative path, the path should be relative to the project directory.
Parent topic: .NET Error Messages


Perfrun.Exe.Config Could Not Be Written Successfully

Possible Cause | Resolution
Before Silk Performer hosts the .NET CLR the file perfrun.exe.config will be written to set configuration settings for the loaded .NET objects. | Confirm that this file is write-enabled and that the executing user has appropriate privileges.
Parent topic: .NET Error Messages


Your .NET DLL References Wrong perfdotnetfw.dll

Possible Cause | Resolution
Your perfdotnetfw.dll has a different version than the perfrun.exe | Ensure that the version of your perdotnetfw.dll is the same as the perfrun.exe.
Parent topic: .NET Error Messages


Verification Failed

Possible Cause | Resolution
This error is raised when a verification with one of the verification functions provided by perfdotnetfw.dll fails. | Examine the verification function that failed.
Parent topic: .NET Error Messages


Exception Has Been Logged

Possible Cause | Resolution
This error is raised when you log an exception with the Bdl.LogException method provided by perfdotnetfw.dll. | Examine the exception that was logged.
Parent topic: .NET Error Messages


Could Not Find or Load a Specific Class

Possible Cause | Resolution
The class with the name you passed as the second parameter to DotNetLoadObject cannot be found in the assembly. | Check the spelling and ensure that you defined the full name (including namespace).
Parent topic: .NET Error Messages


An Exception Was Thrown by a Type's Initializer (.cctor)

Possible Cause | Resolution
Constructor of the object has thrown an exception. | Examine the object constructor that threw the exception.
Parent topic: .NET Error Messages


An Exception Was Thrown by the Called Method

Possible Cause | Resolution
The method called with DotNetCallMethod has thrown an exception. | Examine the method that threw the exception.
Parent topic: .NET Error Messages


Invalid Number of Parameters

Possible Cause | Resolution
You passed an invalid number of parameters to the DotNetCallMethod function. | Check the parameters used by the DotNetCallMethod function.
Parent topic: .NET Error Messages


NUnit Integration

Silk Performer facilitates smooth integration of existing NUnit and Microsoft Unit test scripts into Silk Performer for the support of remote-component testing under realistic concurrent-access server conditions.

Silk Performer provides an import tool that enables you to import existing NUnit assemblies and other .NET assemblies. Methods may have parameters and return values; code for setting the in-parameters of these functions is generated automatically.

Silk Performer’s Unit Import Tool offers you the option of selecting specific test case methods. It automatically generates BDL stub code (a benchmark description file) that calls those selected test case methods. Existing NUnit test classes can be called from Silk Performer without requiring modification of the test classes.

Note: Silk Performer’s NUnit import utility supports NUnit versions 2.1.4 and higher.
  • Setting Up an NUnit or .NET Testing Silk Performer Project
    Create an NUnit or .NET testing project in order to import your NUnit test scripts.
  • Importing an NUnit or .NET Assembly
    Import existing NUnit or .NET test assemblies into Silk Performer for the support of remote-component testing under realistic concurrent-access server conditions.
  • Filter Options for NUnit Methods
    Lists the filters that are available in the Methods area when you import a test class.
  • Example NUnit BDL Script
    Provides an example BDL script that includes timer parameter information for NUnit.
Parent topic: .NET Support


Setting Up an NUnit or .NET Testing Silk Performer Project

  1. Click Start here on the Silk Performer workflow bar.
    Note: If another project is already open, choose File > New Project from the menu bar and confirm that you want to close your currently open project.
    The Workflow - Outline Project dialog box opens.
  2. In the Name text box, enter a name for your project.
  3. Enter an optional project description in Description.
  4. From the Type menu tree, expand Unit Testing and select NUnit or .NET Testing.
  5. Click Next.
    Note: If you need to add additional resources to the project, right-click the project icon in the Project menu tree view. It is particularly important that all the user data files (.csv), random data files (.rnd), and .idl files needed by Silk Performer are set up for your project.
The Workflow - Model Script dialog box appears.
Parent topic: NUnit Integration
Related tasks
Recording a Test Script


Importing an NUnit or .NET Assembly

  1. Click Model Script on the workflow bar. The Workflow - Model Script dialog box appears.
  2. In the File field, specify the archive that is to be tested. The archive is automatically added to the profile classpath. The available classes are then retrieved and displayed, sorted alphabetically in the Class field.
  3. From the Class list, select one of the available classes for testing.
    When you do not specify a specific archive for testing, the Model Script dialog enables you to specify a class that is available in the profile classpath. Type the fully qualified class name into the Class field. The available constructors and methods are automatically retrieved and displayed.
  4. From the Constructor list, select the appropriate constructor for instantiating the imported class. If a constructor is not selected (entry <No Instance Required – Only Static Calls>), only static methods will be displayed in the method list.
  5. In the Methods area, select the methods that you want to call.
  6. To filter the methods that are shown in the Methods area, perform the following steps:
    1. Click the Advanced Settings button (the funnel icon above the Methods area).
    2. Once you have customized filter settings, click OK to update the Methods area.
  7. To change general NUnit settings including traffic redirection values such as routed web service proxy classes, click the Active Profile Settings link. The Profile dialog opens to the General page for .NET projects (NUnit and .NET Testing project types).
    Note: Changes made to these settings may lead to different results. Selections made in the Class, Constructor, and Methods fields will be updated with the new results.
  8. Click OK.
Parent topic: NUnit Integration


Filter Options for NUnit Methods

This table lists the filters that are available in the Methods area when you import a test class.

NUnit Method | Description
Parameterless Functions Only | Ignore all functions that expect parameters
Unit Test Functions Only (selected by default) | Ignore all functions that are not NUnit
Member Functions Only | Ignore all non-member functions
Public Functions (selected by default) | Include public functions
Protected Functions | Include protected functions
Private Functions | Include functions with private access
Package Functions | Include functions with package access
Declared Functions Only | Ignore functions from the base classes
Complex Functions (selected by default) | Show functions that take complex parameters. In Java, complex parameters are scripted by DotNetSetObject with NULL as the default value.
Autodetect Unit Test Functions (selected by default) | Automatically detect and script functions. Functions must not have parameters or return values. Methods marked with [SetUp] and [TearDown] (for NUnit) respectively [TestInitialize] and [TestCleanup] (for Microsoft Unit Tests) are invoked prior to and following each method.
Parent topic: NUnit Integration


Example NUnit BDL Script

Script Example

The following script is generated by importing NUnit Money and selecting the three methods BagMultiply, BagNegate, and BagSimpleAhdd.

transaction TInit
var
  sFileName : string;
begin
  DotNetSetOption(DOTNET_OPT_REDIRECT_CONSOLE, 1);
  // ==============================================
  // Unit Test TestClass Information:
  // Used Framework: NUnit Test Framework
  // Initialize method: SetUp
  // Class contains 21 test methods!
  // ==============================================
  GetDataFilePath("nunitmoneysample.dll", sFileName);
  ghTestObj := DotNetUnitTestLoadObject(sFileName, "NUnit.Samples.Money.MoneyTest", "NUnit.Samples.Money.MoneyTest");
end TInit;

transaction TMain
begin
  // BagMultiply
  DotNetUnitTestCallMethod(ghTestObj, "BagMultiply", "BagMultiply");
  // BagNegate
  DotNetUnitTestCallMethod(ghTestObj, "BagNegate", "BagNegate");
  // BagSimpleAdd
  DotNetUnitTestCallMethod(ghTestObj, "BagSimpleAdd", "BagSimpleAdd");
end TMain;

transaction TEnd
begin
  DotNetUnitTestFreeObject(ghTestObj, "NUnit.Samples.Money.MoneyTest");
end TEnd;

DotNetUnitTestLoadObject loads the NUnit assembly and creates an instance of the test class. If the test class has a global initialize function implemented (marked with TestFixtureSetup - ClassInitialize), this function will be called right after the object is created.

DotNetUnitTestFreeObject in the TEnd transaction frees the reference to the test object. If the test class has a global uninitialize function implemented (marked with TestFixtureTearDown - ClassCleanup), this function will be called prior to release of the object.

DotNetUnitTestCallMethod calls the TestMethod in the same way that the NUnit Microsoft Unit Test Engine does. If there is a SetUp - TestInitialize method implemented, it will be called before the test method is called.

If there is a TearDown - TestCleanup method implemented, it will be called after the test method is called.

Test methods that expect an exception to be thrown (those marked with ExpectedException) are only considered successful when an exception is actually thrown.

When a test method writes information to the error or out console, the information can be viewed in the TrueLog. A separate element is logged as child node of the DotNetUnitTestCallMethod.

The same applies for unexpected exceptions. Stack trace and exception messages are logged to the TrueLog.

Timers

A new optional timer parameter has been introduced for the original DotNet API calls and the new DotNetUnitTest API calls. When this parameter is specified, the execution times of the constructor, test method, set up method, and tear down method are measured. For the example above you would receive the following measures:

  • For the constructor: NUnit.Sample.Money.MoneyTest
  • For the methods: BagMultiply, BagNegate, BagSimpleAdd
  • For the setup methods: BagMultiply_Setup, BagNegate_Setup, BagSimpleAdd_Setup
Parent topic: NUnit Integration


Silk Performer .NET Explorer

Silk Performer .NET Explorer, which was developed using .NET, and the Silk Performer .NET Framework allow you to test Web Services, .NET Remoting objects, and other GUI-less .NET objects. .NET Explorer allows you to define and execute complete test scenarios with different test cases without requiring manual programming because tasks are completed visually by way of mouse-based operations. Test scripts are visual and easy to understand, even for individuals who are unfamiliar with .NET programming languages.

Test scenarios created with .NET Explorer can be exported to Silk Performer for immediate reuse in concurrency and load testing and exported to Microsoft Visual Studio .NET for further customization.

For more information about .NET, visit http://msdn.microsoft.com/net.

  • Starting .NET Explorer
    Launch .NET Explorer to define and execute complete test scenarios with different test cases without requiring manual programming.
  • Using the .NET Explorer SilkEssential
    Use the SilkEssential to hook .NET Explorer to produce a BDL script with tested Web Services.
  • Using the .NET Message Sample
    Includes concepts and tasks that describe the .NET message sample, which allows you to experiment with the testing of .NET technologies using Silk Performer.
  • .NET Explorer Samples
    Includes topics that explain how to access the .NET Remoting and Web service samples that ship with .NET Explorer.
Parent topic: .NET Support


Starting .NET Explorer

Perform one of the following steps to launch .NET Explorer:
  • Click Start > All Programs > Silk > Silk Performer 21.0 > Development Tools > Silk Performer .NET Explorer .
  • Click Start > All Programs > Silk > Silk Performer 21.0 > Silk Performer Workbench and create a new project with the application type .NET/.NET Explorer or Web Services/.NET Explorer.

By default, the executable file is located at C:\Program Files\Silk\Silk Performer 21.0\DotNET Explorer\NetExplorer.exe.

Refer to Silk Performer .NET Explorer Help for detailed information.

Parent topic: Silk Performer .NET Explorer


Using the .NET Explorer SilkEssential

Before you begin this task, create and save a .NET Explorer test scenario. Refer to Silk Performer .NET Explorer Help for detailed information.

Silk Performer ships with a SilkEssential that allows you to hook .NET Explorer to produce a BDL script with tested Web Services.

  1. Create a new project based on the SilkEssential, as follows:
    1. Click Start here on the Silk Performer workflow bar.
      Note: If another project is already open, choose File > New Project from the menu bar and confirm that you want to close your currently open project.
    2. In the Name text box, enter a name for your project.
    3. Enter an optional project description in Description.
    4. From the Application menu tree, expand Web Services and click .NET Explorer.
    5. Click Next.
      Note: If you need to add additional resources to the project, right-click the project icon in the Project menu tree view. It is particularly important that all the user data files (.csv), random data files (.rnd), and .idl files needed by Silk Performer are set up for your project.
  2. Model the script.
  3. While the recorder is running, start .NET Explorer.
  4. Load a test scenario that you have defined in a previous.NET Explorer session.
  5. Execute an animated run of the scenario. A BDL script is generated while the recorder and .NET Explorer run.
  6. Close .NET Explorer and the recorder.
  7. Perform a Try Script run of the recorded BDL script.
  8. Perform XML customization and verification in the TrueLog, as required. Refer to TrueLog Explorer Help for detailed information.
Parent topic: Silk Performer .NET Explorer
Related concepts
Modeling Scripts
Try Script Overview


Using the .NET Message Sample

This section includes concepts and tasks that describe the .NET message sample, which allows you to experiment with the testing of .NET technologies using Silk Performer.

The message sample implements a message server that allows users to log in, view their message store, and send messages to other users. The sample is comprised of the following .NET technologies:
  • .NET Remoting
  • Web services
  • ASP.NET
  • .NET Message Sample Overview
    Describes the .NET components and technologies that are used by the message sample.
  • MessageLib Interfaces
    Describes how the MessageLib works and lists its interfaces.
  • Sample .NET Web Service
    Describes how the sample .NET Web service works and lists the functions that are defined in the interfaces.
  • Working With the .NET Message Sample
    Explains how to install and configure the .NET message sample and provides a detailed description of the clients and the server components.
  • Testing the .NET Message Sample
    Lists the options that are available to you for testing the .NET components of the message sample using Silk Performer.
Parent topic: Silk Performer .NET Explorer


.NET Message Sample Overview

The message sample implements a message server that allows users to log in, view their message store, and send messages to other users. The sample is comprised of the following .NET technologies:
  • .NET Remoting
  • Web services
  • ASP.NET
The sample contains the following components:
Component | Description
MessageLib | .NET library that defines the interfaces that are implemented by the server library.
MessageImpl | Implementation of the MessageLib interfaces.
MessageServer

A simple console application that hosts the .NET Remoting objects that are implemented in MessageImpl.

An object that implements IObjectManager which can be activated at http://localhost:1999/ObjectManager.rem. You can change this setting in the config file.

MessageServerIIS | The ObjectManager remoting object hosted by IIS.
MessageWebService | This Web service exposes Web service methods for most of the methods implemented in the MessageImpl. The Web service does not host the objects of the MessageImpl directly. The Web service communicates with the .NET Remoting server.
MessageSimpleClient | This simple client console application acquires the IObjectManager from the server application and calls methods on the object.
MessageWin32Client | Win32 application that either connects to the .NET Remoting server or to the Web service. It provides an interface for logging in, checking messages, and sending messages.
MessageWebClient | ASP.NET application that connects to the Web service and provides an interface for logging in, checking messages, and sending messages.

Component Interaction Example

The .NET Remoting server hosts a Singleton SAO (Server Activated Object) that client applications (Web Service, Win32 Client, Simple Client) can aquire by way of http://localhost:1999/ObjectManager.rem.

Image that shows the Components Interacting

Parent topic: Using the .NET Message Sample


MessageLib Interfaces

The MessageLib library defines several interfaces that are implemented by the MessageImpl library, which is hosted on the .NET Remoting server. IObjectManager is the core interface that can be acquired from the server. This interface offers access to other objects such as users, the message store, and messages. A separate interface assembly is required because when a client application accesses a remote object, it requires the type information of the object it acquires. By implementing a library that only defines the interfaces, the implementation remains on the server side. It would be possible to ship the MessageImpl to the client, but that would imply that the implementation exists on both the client and the server side, which is not the preferred approach.

Some methods return an integer value that indicates the success of the method call. 0 indicates a successful call. Values other than 0 indicate errors. The method GetErrorMsg on the IObjectManager interface returns an error description of the error code.

  • ObjectManager Interface
    Describes the methods that are available from the ObjectManager interface.
  • IUser Interface
    Describes the methods that are available from the IUser interface.
  • IMessageStore Interface
    Describes the methods that are available from the IMessageStore interface.
  • IMessage Interface
    Describes the methods that are available from the IMessage interface.
Parent topic: Using the .NET Message Sample


ObjectManager Interface

Login Method

int Login(string sUsername, string sPassword,
    ref IUser user)

This method executes a user login with a given password. If the login is successful, the user holds a valid reference to the user’s object. If the login is not successful, check the return value.

Logout Method

int Logout(IUser user)

Logs out the user.

CreateUser Method

int CreateUser(string sUsername, string sPassword);
Creates a new user.
Note: This method does not login the user.

DeleteUser Method

int DeleteUser(IUser user);

Deletes the user. The user is no longer valid after this call.

GetErrorMsg Method

string GetErrorMsg(int errNo);

Returns a description for the error number.

Parent topic: MessageLib Interfaces


IUser Interface

ChangePassword Method

int ChangePassword(string sOldPwd, string sNewPwd);

Changes the user password.

ChangeName Method

int ChangeName(string sNewName);

Changes the username.

GetMessageStore Method

IMessageStore GetMessageStore();

Returns the user’s message store.

SendMessage Method

int SendMessage(string sRecipient, string sMsgText);

Sends a message to another user.

Username Method

string Username

User’s name (read-only property).

Parent topic: MessageLib Interfaces


IMessageStore Interface

GetMessage Method

int GetMessage(int nMsgId, ref IMessage msg);

Returns the message with the given message ID (1 based).

DeleteMessage Method

int DeleteMessage(int nMsgId);

Deletes the message with the given message ID (1 based).

Count Method

int Count

Number of messages in the store (read-only property)

Parent topic: MessageLib Interfaces


IMessage Interface

Sender Method

string Sender

Sender (read-only property)

MessageText Method

string MessageText

Message text (read-only property).

Parent topic: MessageLib Interfaces


Sample .NET Web Service

The sample Web service exposes most of the functions that are defined in the interfaces. When there is a successful login, the user object is stored in the ASP.NET session object. As a result, it is possible to call methods on the user object without passing a reference to the object back to the client of the Web service. The session state information is held in the server memory and the session key is passed back to the client in a cookie. So, if you are using a generated Web proxy client class, be sure to create a CookieContainer object and assign it to the CookieContainer property of the proxy object.

Exposed functions include:
  • Login
  • Logout
  • CreateUser
  • DeleteUser
  • GetMessageCount
  • GetMessage
  • DeleteMessage
  • SendMessage
  • GetErrorMsg

The Web service defines a separate message class. The class contains two public members (Sender and MessageText).

Parent topic: Using the .NET Message Sample
Related tasks
Configuring the Web Service


Working With the .NET Message Sample

This section explains how to install and configure the .NET message sample. Also included is a detailed description of the clients and the server components. The section concludes with an explanation of how to test the .NET message sample with Silk Performer.

  • Installing the .NET Message Sample
    Install the .NET message Remoting server to enable testing of the .NET message sample.
  • Configuring the .NET Message Sample
    Includes tasks that explain how to set up the .NET message sample clients, the sample Web service, and IObjectManager.
  • Exploring the .NET Message Sample
    Guides you through the components of the .NET message sample.
Parent topic: Using the .NET Message Sample


Installing the .NET Message Sample

Note: If you only need to test the .NET Remoting component of the message sample, skip this task and simply start the message server.
  1. Create virtual directories for the Web service, Web client, and message server hosted on IIS by performing the following steps:
    1. Open the Internet Service Manager from the Administrative Tools folder.
    2. Create three virtual directories: MessageWebService, MessageWebClient, and MessageServerIIS.
    3. Open the sample application directory and set the base directory to the MessageWebService, MessageWebClient, and MessageServerIIS directories. By default, the sample application directory is <public user documents>\Silk Performer 21.0\SampleApps\DOTNET\Message Sample.
    4. Right-click the virtual directory entry in the tree and choose Properties. The Properties window opens.
    5. Click Create to create an application for the virtual directory. If there is no Create button on the Properties page, this step has been executed automatically by IIS during the creation of the virtual directory.
    6. Repeat the preceding two steps ('d' and 'e') for both virtual directories.
  2. To ensure that the binaries of the sample application are compiled against the latest version of the .NET Framework, perform the following steps:
    1. Open the MessageLib.sln solution in the <public user documents>\Silk Performer 21.0\SampleApps\DOTNET\Message Sample\MessageLib directory.
    2. Perform either a release or debug build of the solution.
    3. Copy the output files of the MessageImpl (either debug or release) project to the MessageServerIIS\bin directory.
Parent topic: Working With the .NET Message Sample
Related concepts
Testing the .NET Message Sample
Related tasks
Configuring the .NET Message Sample
Exploring the .NET Message Sample


Configuring the .NET Message Sample

  • Configuring the IObjectManager Object Properties
    Configure the port, whether to use a TCP channel instead of HTTP, or the URL for the IObjectManager object.
  • Configuring the Simple Client
    If you changed the ObjectManagerURL value in MessageServer.exe.config, then you also need to edit the simple client config file.
  • Configuring the Web Service
    To enable access to the sample Web service you need to specify the Object Manager URL.
  • Configuring the Web Client
    To enable the Web client, you need to specify the URL of the Web service.
Parent topic: Working With the .NET Message Sample
Related concepts
Testing the .NET Message Sample
Related tasks
Installing the .NET Message Sample
Exploring the .NET Message Sample


Configuring the IObjectManager Object Properties

By default the message server exposes the IObjectManager object on http://localhost:1999/ObjectManager.rem. Proceed with this task only if you need to change the default setting.

  1. Navigate to <public user documents>\Silk Performer 21.0\SampleApps\DOTNET\Message Sample\MessageServer and double-click MessageServer.exe.config.
  2. Enter the port number. Ensure that the port is not already in use by another service on your machine.
  3. To use a TCP channel instead of HTTP, change the ref attribute to TCP.
  4. To change the URL of the object, edit the objectUri attribute.

If you change any of the these properties, ensure that you also change the configuration of the client applications, as explained in the following tasks.

Parent topic: Configuring the .NET Message Sample


Configuring the Simple Client

If you changed the ObjectManagerURL value in MessageServer.exe.config, then you also need to edit the simple client config file.

  1. Navigate to <installation path>\Sample Apps\Message Sample\MessageSimpleClient.
  2. Double-click MessageSimpleClient.exe.config.
  3. Change the value of the key ObjectManagerURL to the required URL.
Parent topic: Configuring the .NET Message Sample
Related tasks
Running the Simple Client


Configuring the Web Service

  1. Navigate to <public user documents>\Silk Performer 21.0\SampleApps\DOTNET\Message Sample\MessageWebService and double-click Web.config.
  2. Change the value of the key ObjectManagerURL to the required URL.
You can now access the Web service at http://<server>/MessageWebService/MessageService.asmx.
Parent topic: Configuring the .NET Message Sample
Related concepts
Sample .NET Web Service
Related tasks
Testing a .NET Web Service


Configuring the Web Client

When the Web service is installed on a different machine than the Web client, or if you have selected a different virtual directory name, you must specify the URL of the Web service in the file Global.asax.

  1. Navigate to <public user documents>\Silk Performer 21.0\SampleApps\DOTNET\Message Sample\MessageWebService and double-click Global.asax.cs.
  2. Locate the Session_Start method.
  3. Define your Web service’s URL.
  4. Rebuild the application.
You can now access the Web client at http://<server>/MessageWebClient/Default.aspx.
Parent topic: Configuring the .NET Message Sample
Related tasks
Working with the Web Client


Exploring the .NET Message Sample

This section guides you through the components of the message sample. The sample uses the message server that is implemented by the console application. You can use the message server running in IIS by changing the remoting URL in the configuration files of the client applications.

  • Starting the .NET Remoting Server
    Start the .NET Remoting server to access ObjectManager object data.
  • Running the Simple Client
    The simple client creates two users that can be interacted with by both the sample Win32 client and the sample Web client.
  • Working With the Win32 Client
    The sample Win32 client allows you to perform basic operations such as logging in, creating users, and sending messages.
  • Working with the Web Client
    The Web client allows you to perform basic interactions with the sample Web service, such as logging in, creating users, and sending messages.
Parent topic: Working With the .NET Message Sample
Related concepts
Testing the .NET Message Sample
Related tasks
Installing the .NET Message Sample
Configuring the .NET Message Sample


Starting the .NET Remoting Server

The .NET Remoting server hosts the ObjectManager object that is accessed by all client applications. The server is a simple console application that runs when you press any key. Some of the methods of the remoting objects print information to the console, such as which users have logged in or out, and who sent messages to whom.

Note: The server holds all the information about the users and messages in memory. So if you stop the server, the current state is lost. This means that each time you start the server you have an empty environment with no users or messages.
  1. Navigate to <public user documents>\Silk Performer 21.0\SampleApps\DOTNET\Message Sample\MessageServer.
  2. Double-click MessageServer.exe.

The message server console window displays. The console window logs information about the methods that are called during tests. Press any key to stop the server.

Parent topic: Exploring the .NET Message Sample
Related tasks
Testing a .NET Web Service


Running the Simple Client

The simple client connects to the .NET Remoting server, creates two users (User1 and User2) with passwords (Pass1 and Pass2). The simple client also sends a message from User1 to User2.

  1. Navigate to <public user documents>\Silk Performer 21.0\SampleApps\DOTNET\Message Sample\MessageSimpleClient.
  2. Double-click MessageSimpleClient.exe.
The message server console window opens. Two users are created and a message is sent from User1 to User2.
Parent topic: Exploring the .NET Message Sample
Related tasks
Configuring the Simple Client


Working With the Win32 Client

Before working with the Win32 client, run the simple client. The simple client automatically creates system users with which the Win32 client can interact.

The Win32 client does not require any configuration outside the application.

The Win32 client can either connect directly to the ObjectManager object of the remoting server or it can perform all the method calls through the Web service. The Web service forwards the method calls to the ObjectManager object on the remoting server.

Once you connect to the Win32 client, you can either create a new user or log in as an existing user. You can also delete the current user. Any messages sent to the active user are listed in the message store, including any messages sent using the sample Win32 client or the simple client. You can delete messages or send new messages to other users in the system.

The Last Error box shows the error text of the last error that occurred when a method was executed.

Note: When errors occur while calling methods on remote objects, you see error descriptions in the Error Text box.
  1. Navigate to <public user documents>\Silk Performer 21.0\SampleApps\DOTNET\Message Sample\MessageWin32Client and double-click MessageWin32Client.exe. The sample Win32 client starts.
  2. Connect to either the Remoting server or the Web service.
    • To log into the .NET Remoting message server, enter the server's URL (for example, http://localhost:1999/ObjectManager.rem) in the Message Server field and click Connect.
    • To log into the sample Web service, enter the Web service URL (for example, http://localhost/MessageWebService/MessageService.asmx) in the Web Server field and click Connect.
  3. Login using one of the users that the simple client application created. By default, the simple client application creates User1 with password Pass1 and User2 with password Pass2.
  4. Create a new user.
  5. Login using the newly created login credentials.
  6. Send a message to another user.
    Note: User names are case-sensitive.
  7. Review the server console output. Logging information related to all methods that were called is listed there.

Be sure to log out after you finish your work.

  • Creating a New User
    Create a new user in your Message Sample client.
  • Sending a Message
    Send a message to another user in your Message Sample client.
Parent topic: Exploring the .NET Message Sample


Creating a New User

  1. Enter unique Username and Password values.
  2. Click Create User.
Parent topic: Working With the Win32 Client
Parent topic: Working with the Web Client


Sending a Message

  1. Enter an existing username in the To User field.
  2. Enter sample text in the Message field.
  3. Click Send.
Parent topic: Working With the Win32 Client
Parent topic: Working with the Web Client


Working with the Web Client

Before you can use the Web client, you must configure the Web client by specifying the URL of the Web service.

Before working with the Web client, run the simple client. The simple client automatically creates system users with which the Web client can interact.

The Web client communicates with the Web service. The Web client allows you to login to the system and create new users. When you login, you can view your message store, delete your messages, or send new messages to other users in the system. Usernames are case-sensitive. If an error occurs while you are executing a method, the error will be displayed in red.

  1. Start your browser and load the URL http://localhost/MessageWebClient/default.aspx. A login page is displayed.
  2. Enter login credentials for an existing user account or create a new user account (see instructions in the task below). The first time you login, use User1 for the Username and Pass1 for the Password.
  3. Click Login. When you log in you are redirected to the Your Message Store page where you can see any messages that are in the active user's message store, including any messages that have been sent using the sample Win32 client or the simple client.

    You can send messages to other users in the system, same as you can with the sample Win32 client (see instructions in the task below).

  4. Review the server console output window. The window displays information related to the activities you performed with the Web client, including user creation, sent messages, and logins.

Be sure to log out after you finish your work.

  • Creating a New User
    Create a new user in your Message Sample client.
  • Sending a Message
    Send a message to another user in your Message Sample client.
Parent topic: Exploring the .NET Message Sample
Related tasks
Configuring the Web Client


Testing the .NET Message Sample

You have several options for testing the .NET message sample with Silk Performer:
  • Hook into the Win32 client application and record Web traffic.
  • Record a Web session with the Web client.
  • Use .NET Explorer to test the Web service and generate a Silk Performer .NET project.
  • Create a new .NET Framework project and write a .NET test driver that either tests the Web service or the .NET Remoting server directly.
  • Hooking a Win32 Client Application
    Explains how to create a Win32 client-application project, add a recording profile, and record a script.
  • Recording a Web-Client Session
    Explains how to create a new Web project, record a script, and execute a Try Script run.
  • Testing a .NET Web Service
    Explains how to create a Web service project, load a WSDL, define a usage scenario, and record a test script.
  • Creating a .NET Framework Project
    Explains how to create a .NET Framework project in Silk Performer, record a script, and code a .NET test driver.
Parent topic: Using the .NET Message Sample
Related tasks
Installing the .NET Message Sample
Configuring the .NET Message Sample
Exploring the .NET Message Sample


Hooking a Win32 Client Application

Before proceeding, start the message server.

  1. Create a new Silk Performer project of type Web Services > XML/SOAP.
  2. Add a new recording profile for MessageWin32Client.exe.
    1. From the Silk Performer Application type list box, select Custom Application.
    2. In the Protocol selection area, check the Web check box. The Silk Performer Recorder intercepts all function calls and displays the results.
  3. Begin recording a script.
  4. Perform actions using MessageWin32Client (for example, connect, login, send, and logout).
  5. End recording. For each call made in the Win32 client application there is a WebUrlPostBin call and a SOAP envelope.
  6. Review the recorded script.
  7. Execute a Try Script run using the recorded script. Monitor details of the test run in the Server Console window.
Parent topic: Testing the .NET Message Sample


Recording a Web-Client Session

.NET Explorer

Before proceeding, start the message server.

  1. Create a new Silk Performer project of type Web Browser > Web business transaction.
  2. Begin recording: http://localhost/MessageWebClient/Default.aspx.
  3. Perform actions using the sample Web client (for example, connect, login, send, and logout).
  4. End script recording.
  5. Review the recorded script.
  6. Execute a Try Script run using the recorded script. Monitor details of the test run in the Server Console window.
Parent topic: Testing the .NET Message Sample


Testing a .NET Web Service

Before proceeding, start the message server.

Note: This scenario is stored within your Silk Performer installation. You can access it at <public user documents>\Silk Performer 21.0\SampleApps\DOTNET\Message Sample\NetExplorer_TestingWebService.
  1. Launch Silk Performer and create a new project.
  2. Load the WSDL from the Web service: http://localhost/MessageWebService/MessageService.asmx?WSDL
  3. Invoke the login method using User1 and Pass1 as input values.

    You can also use random variables or global variables mapped to attributes (see .NET Explorer Help for details).

  4. Send a message with some text from User1.
  5. Logout the current user and login as User2 (username: User2; password: Pass2).
  6. Invoke GetMessageCount and store the result in a variable called mCount.
  7. Call GetMessage with the message count variable as input. You will receive the last message that was sent.
  8. Add the remaining logout method call.
  9. Execute an animated run. The failed verification can be ignored (or you can remove the default verification of the GetMessageCount call).
  10. Export a Silk Performer .NET project or a Visual Studio .NET project (exported projects can be found at <public user documents>\Silk Performer 21.0\SampleApps\DOTNET\Message Sample\NetExplorerExportedProject).
  11. Execute a Try Script run via Silk Performer or Visual Studio .NET.
  12. Explore the TrueLog. You will see a node for each Web service call.
Parent topic: Testing the .NET Message Sample
Related tasks
Configuring the Web Service
Testing a .NET Web Service
Starting the .NET Remoting Server


Creating a .NET Framework Project

Before proceeding, start the message server.

For full details about the Silk Performer .NET Framework, see .NET Framework Help.

  1. Create a new Silk Performer project of type .NET > .NET Framework using Visual Studio .NET Add-On.
  2. Use the Model Script dialog to bring up Visual Studio .NET.
  3. Code a .NET test driver.
  4. A sample test driver implementation that tests the .NET remoting server and the Web service can be found at <public user documents>\Silk Performer 21.0\SampleApps\DOTNET\Message Sample\SPVNetTestDriver.
  5. Open the project in Visual Studio .NET and execute a Try Script run.
  6. After the run, review the TrueLog and open the user's WRT file.
The sample sends a message from User1 to User2 (where User1 is connected to the remoting server and User2 is connected to the Web service).
Parent topic: Testing the .NET Message Sample


.NET Explorer Samples

This section includes topics that explain how to access the .NET Remoting and Web service samples that ship with .NET Explorer. It also includes a list of helpful Web resources.

  • .NET Remoting Support
    Explains that RemotingLib implements one remotable object (MarshalByRefObject) and defines an interface.
  • .NET Remoting Testing
    Use .NET Explorer to test the .NET Remoting sample.
  • .NET Component Testing Overview
    Explains that netexptestdll.dll implements base classes that can be tested.
  • Sample Web Services
    Several sample Web services are available for testing with .NET Explorer.
  • Order Web Service
    The sample Order Web service offers a number of methods for testing with .NET Explorer.
  • Web References
    Includes additional online resources that can assist you with the testing of Web services and getting the most from .NET Explorer.
Parent topic: Silk Performer .NET Explorer


.NET Remoting Support

RemotingLib implements one remotable object (MarshalByRefObject) and defines an interface. The interface is available at <public user documents>\Silk Performer 21.0\SampleApps\DOTNET\RemotingSamples\RemotingLib.

RemServerConsole is the server application that hosts the remotable object and implements one object that implements the defined interface of RemotingLib. It is available at <public user documents>\Silk Performer 21.0\SampleApps\DOTNET\RemotingSamples\RemServerConsole.

All source code is available. Code is already compiled into a debug version.

Parent topic: .NET Explorer Samples


.NET Remoting Testing

  1. Start the remoting server application via .NET Explorer. Choose Help > Start Remoting Sample.
  2. Manually start RemServConsole.exe, which is available at <public user documents>\Silk Performer 21.0\SampleApps\DOTNET\RemotingSamples\RemServerConsole\bin\debug\RemServConsole.exe.
  3. Load RemotingLib.dll, which is available at <public user documents>\Silk Performer 21.0\SampleApps\DOTNET\RemotingSamples\RemServerConsole\bin\debug\RemotingLib.dll.
  4. Create an instance of the class RemoteObject. Right-click RemoteObject and choose Create Remote Object. You will be prompted for the activation URL. Enter tcp://localhost:2000.
  5. Connect to the remoted interface.
  6. Invoke a method of the RemoteInterface interface. The first time you do this you will be prompted for the activation URL. The activation URL is either tcp://localhost:2000/RemoteInterface.rem or tcp://localhost:2000/RemoteInterfaceSCall.rem (single call object).
Parent topic: .NET Explorer Samples


.NET Component Testing Overview

netexptestdll.dll implements base classes that can be tested. This file is available at <public user documents>\Silk Performer 21.0\SampleApps\DOTNET\netexptestdll\bin\debug\netexptestdll.dll.

You can instantiate one of the loaded objects via the context menu on the class or by invoking a constructor. Following that, store the created object in a variable and call methods on the created object.

Parent topic: .NET Explorer Samples


Sample Web Services

Several sample Web services are available for testing with .NET Explorer.

  • The .NET sample Web service SampleService.asmx offers simple method calls.
  • Testing ASP.NET Data Types (DataTypes.asmx) is a sample Web service provided by Microsoft that allows you to test different data types that are provided by the ASP.NET Framework.
  • Order Web service (OrderService.asmx) is a sample Web service that allows you to simulate the ordering of books and DVDs.
  • Other free accessible Web services are available at http://www.xmethods.net and http://www.mssoapinterop.org.
Parent topic: .NET Explorer Samples


Order Web Service

The sample Order Web service offers a number of methods and is available for testing with .NET Explorer at http://demo.borland.com/OrderWebService/OrderService.asmx. The following methods are available:

  • SearchArticles: Searches for articles by a name pattern.
  • GetArticleByName: Searches for an article by the full name.
  • GetArticleById: Searches for an article by its ID.
  • CreateUser: Creates a new user in the database.
  • Login: Logs in an existing user. The return value is the user ID that is needed for other method calls (store this return value in a global variable).
  • Logout: Logs the user out of the system.
  • CreateOrder: Creates a new order for the currently logged in user.
  • AddOrderItem: Adds an item to the order.
  • GetOrder*: Returns information about an order.

All order related methods take the userid as a header parameter. This is why you should store the user ID that is returned by the Login method in a global variable and use the variable as input for all order-related methods.

Some of the methods may throw SOAP exceptions (for example, if you are not logged in and try to create an order).

Parent topic: .NET Explorer Samples


Web References

Here are some additional online resources that can assist you with the testing of Web services and getting the most from .NET Explorer.

  • (Web service) http://demo.borland.com
  • (Web service) http://www.mssoapinterop.org/asmx/simple.asmx
  • (Web service) http://www.mssoapinterop.org/asmx/simpleB.asmx
  • (.NET resource) http://msdn.microsoft.com/net
Parent topic: .NET Explorer Samples


GUI-Level Testing Support

When to Use GUI-Level Testing

Suppose you have an application that implements a traditional client/server architecture. You want to test what happens when multiple instances of the client application access the server simultaneously. An example would be a proprietary time-tracking system that stores the working hours of employees on a server. However, you cannot use any of the existing Silk Performer application types for testing, because the application uses an exotic protocol to communicate between client and server. In such instances, you may want to use GUI-level testing. With GUI-level testing, you can find out how many employees can concurrently access the server and use the time-tracking system without overloading the server.

How GUI-Level Testing Works

As shown in the graphic below, the process begins with the Silk Performer Controller. When you start a load test, the Silk Performer Controller connects to an agent running on a Microsoft Windows Server operating system and has Remote Desktop Service (formerly known as Terminal Services) running. The Silk Performer agent then creates runtimes and within the runtimes the virtual users are created. Each virtual user creates a new session on the agent machine and starts Silk Test within this session. Silk Test then performs the previously recorded steps on the application, or in other words: Silk Test drives the application. The application accesses the server and generates the load, while the virtual users measure the response times.

Sometimes you cannot run more than one instance of an application on a machine or within a single session. This is why each virtual user creates a new session on the agent machine. With this approach, Silk Performer creates several instances of your application, all of which access the system under test simultaneously.

Setting Up a GUI-Level Testing Environment

  1. Set up at least one agent machine that has one of the Microsoft Windows Server editions installed on it.
  2. Install Silk Performer Agent on the machine.
  3. Install Silk Test.
  4. Install your client application.
  5. Use Silk Test to model one or more test cases using the application.
  6. Create a Silk Performer GUI-level testing project that uses the Silk Test project to run the defined test cases against the system under test.

Once you have performed all these steps, you can start the load test in Silk Performer.

Note: You can use the following Silk Test clients for GUI-level testing: Silk Test Classic, UFT Developer (Silk4J), and UFT Developer (Silk4NET). Make sure that you meet all requirements when you use UFT Developer (Silk4J) and UFT Developer (Silk4NET) for GUI-level testing. See Requirements for GUI-Level Testing with UFT Developer (Silk4J) and UFT Developer (Silk4NET) for details.

Why is it Called GUI-Level Testing?

Silk Test performs testing directly on the graphical user interface, or in other words, on the GUI-level. With this approach you can watch how Silk Test performs the recorded test steps, for example mouse clicks and keyboard entries, if you connected to one of the sessions on the agent machine.

GUI-Level Testing Functions

Refer to the Silk Performer BDL Reference for full details on the BDL functions that are offered by Silk Performer.

Note: Silk Test can be started in local host mode. With this approach, virtual users use a console session rather than a separate Windows session.
Note: GUI-level testing only works on Windows Server edition platforms. Windows Home or Professional editions can only be used as agents for a single GUI-level testing VUser.

Single Session GUI-Level Testing

For tests against web applications using Google Chrome or Mozilla Firefox, Silk Performer allows you to run all virtual users within a single Windows session. The benefits are that no remote desktop licenses are required and that resource consumption per virtual user is considerably lower compared to the conventional GUI-level testing approach.

  • Configuring Windows for GUI-Level Testing
    Before you can execute GUI-level tests, you must configure your Windows operating system and install Silk Test.
  • GUI-Level Test Execution
    Explains how to execute GUI-level testing using Silk Performer and Silk Test.
  • Requirements for GUI-Level Testing with UFT Developer (Silk4J) and UFT Developer (Silk4NET)
    Lists the requirements for using UFT Developer (Silk4J) and UFT Developer (Silk4NET) for GUI-Level testing.
  • GUI-Level Testing Scalability Scenarios
    Includes information about the scalability of a GUI-Level load test executed in Silk Performer when run on a series of scenarios using different VUser counts and time periods in the same system environment.
  • Troubleshooting GUI-Level Testing Issues
    Identifying and rectifying GUI-Level testing issues requires familiarity with the three components involved: Silk Performer, Silk Test, and Windows/Terminal Services/Remote Desktop Services.
Parent topic: Load Testing Specific Application Types
Related concepts
Silk Test Automation Functions Overview
GUI-Level Testing Functions
Related tasks
Exploring Silk Test Results
Configuring Windows for GUI-Level Testing
Setting GUI-Level Testing Options


Configuring Windows for GUI-Level Testing

Before you can execute GUI-level tests, you must configure your Windows operating system. Additionally, Silk Test needs to be installed on the agent computer (refer to the Silk Test Help for details).

  • Configuring Windows 2008 R2 for GUI-Level Testing
    Explains several settings that must be configured to enable testing for Windows 2008 R2 machines.
  • Configuring Windows 2012 - 2019 for GUI-Level Testing
    Explains several settings that must be configured to enable testing for Windows 2012, 2016, and 2019 machines.
  • Obtaining More Licenses for Windows Server Edition
    Windows Server Edition offers multiple licenses for remote desktop sessions, which means that you can connect multiple times during a single session.
Parent topic: GUI-Level Testing Support


Configuring Windows 2008 R2 for GUI-Level Testing

Before you can perform this task, make sure that the Remote Desktop Services server role is installed.

  1. Enable Remote Desktop Protocol (RDP). RDP is disabled by default.
    1. Open Windows Control Panel > System and Security > System.
    2. Click the Remote Settings link.
    3. Check the checkbox Allow connections from computers running any version of Remote Desktop (less secure).
    4. Click OK.
  2. Allow RDP users to launch applications remotely.
    1. Navigate to Administrative Tools > Remote Desktop Services > RemoteApp Manager.
    2. Click Change next to RD Session Host Server Settings.
    3. In the Access to unlisted programs group box, check the checkbox Allow users to start both listed and unlisted programs on initial connection.
    4. Click OK.
  3. Allow RDP users to run multiple sessions.
    1. Navigate to Administrative Tools > Remote Desktop Services > Remote Desktop Session Host Configuration.
    2. Double-click Restrict each user to a single session. The Properties dialog box displays.
    3. Uncheck the checkbox Restrict each user to a single session.
    4. Click OK.
  4. Configure Remote Desktop settings.
    1. Navigate to Administrative Tools > Remote Desktop Services > Remote Desktop Session Host Configuration.
    2. Right-click Remote Desktop Protocol-TCP (RDP-Tcp) in the Connections list and click Properties.
    3. Click the Log on Settings tab and make sure that Always prompt for password is disabled.
    4. Click the Sessions tab and make sure that Override user settings is selected and that End a disconnected session is set to 1 minute. Make sure that all other settings are disabled or left blank.
    5. Click the Environment tab and make sure that Run initial program specified by user profile and Remote Desktop Connection or client is enabled.
    6. Click the Remote Control tab and make sure that Use remote control with default user settings is enabled.
    7. Click the Network Adapter tab and make sure that All Network adapters configured with this protocol is selected in the Network adapter list.
    8. Click OK.
  5. User Account Control (UAC) is enabled by default, but is not required for GUI-level testing. If you want to leave UAC turned on, the agent must run under a user account. To configure UAC settings:
    1. Navigate to Control Panel > User Accounts > User Accounts > Change User Account Control Settings.
    2. Modify the UAC notification level as desired.
    3. Click OK.
  6. Using the Windows user and group administration functionality, select the local users that can execute GUI-level tests. Ensure that this user is a member of the Administrators and/or Remote Desktop Users group.
Parent topic: Configuring Windows for GUI-Level Testing


Configuring Windows 2012 - 2019 for GUI-Level Testing

Before you can perform this task, make sure that Remote Desktop Services is enabled and that you are logged in with a domain user with administrative privileges on the machine.

  1. Set a time limit for disconnected users.
    Note: The time limit can be set on two levels: either through a Windows group policy or through the Remote Desktop Services Collection. The group policy setting has priority over the Remote Desktop Services Collection setting.
    Group Policy:
    1. Start the Windows Local Group Policy Editor and navigate to Local Computer Policy > Computer Configuration > Administrative Templates > Windows Components > Remote Desktop Services > Remote Desktop Session Host > Session Time Limits.
    2. Double-click Set time limit for disconnected sessions.
    3. Click Enabled.
    4. For End a disconnected session, select 1 minute.
    Remote Desktop Services Collection:
    1. Start the Windows Server Manager and navigate to Remote Desktop Services > Collections > <name of the collection>. In the Properties area, select Edit Properties from the Tasks menu.
    2. On the Session Collection dialog, select Session.
    3. For End a disconnected session, select 1 minute.
    4. Click OK.
  2. Allow RDP users to run multiple sessions and launch all programs.
    1. Start the Windows Local Group Policy Editor and navigate to Local Computer Policy > Computer Configuration > Administrative Templates > Windows Components > Remote Desktop Services > Remote Desktop Session Host > Connections.
    2. Double-click Restrict Remote Desktop Services users to a single Remote Desktop Services session.
    3. Click the Disabled option.
    4. Click OK.
    5. Double-click Allow remote start of unlisted programs.
    6. Click the Enabled option.
    7. Click OK.
  3. User Account Control (UAC) is enabled by default, but is not required for GUI-level testing. If you want to leave UAC turned on, the agent must run under a user account. To configure UAC settings:
    1. Navigate to Control Panel > User Accounts > User Accounts > Change User Account Control Settings.
    2. Modify the UAC notification level as desired.
    3. Click OK.
  4. Add users to the Remote Desktop Users group.
    1. In Server Manager > Tools > Computer Management > Local Users and Groups > Groups, double-click the Remote Desktop Users group and add the local users that shall be able to execute GUI-level tests.
    2. In case the GUI-level test users require administrative privileges during test execution, you can add them to the Administrators group here.
Parent topic: Configuring Windows for GUI-Level Testing


Obtaining More Licenses for Windows Server Edition

Windows Server Edition offers multiple licenses for remote desktop sessions, which means that you can connect multiple times during a single session.

Windows Server Edition offers two free licenses for remote desktop sessions. Windows Home and Professional editions can only be used as agents for a single GUI-level testing VUser.

  1. Navigate to Start > ... > Control Panel > Add or Remove Programs .
  2. Click the Add/Remove Windows Components button.
  3. Within the Windows Components Wizard, scroll to and check the Terminal Server check box.
  4. Click Next to enable application mode for your Windows system.
    Note: A license server is required for application mode. Contact Microsoft for information about obtaining a license server.
  5. Restart your computer.
Parent topic: Configuring Windows for GUI-Level Testing


GUI-Level Test Execution

  • Modeling GUI-Level Tests - Keyword-driven
    Describes how to import a Silk Test keyword-driven test asset.
  • Modeling GUI-Level Tests - UFT Developer (Silk4J)
    Describes how to import a UFT Developer (Silk4J) test asset.
  • Modeling GUI-Level Tests - UFT Developer (Silk4NET)
    Describes how to import a UFT Developer (Silk4NET) test asset.
  • Modeling GUI-Level Tests - Silk Test Classic
    Describes how to import a Silk Test Classic test asset.
  • Exporting Silk Test Tests to Silk Performer
    Describes how to export UFT Developer (Silk4J) tests from Eclipse and UFT Developer (Silk4NET) tests from Visual Studio to Silk Performer.
  • User Credentials for GUI-Level Testing
    You must configure login credentials for the virtual users in your test.
  • Timers in GUI-Level Testing
    You can add timers in your Silk Test Classic, UFT Developer (Silk4J), and UFT Developer (Silk4NET) scripts, which will be reported to Silk Performer’s test results.
  • GUI-Level Testing Result Files
    TrueLogs and other result files are generated by Silk Test and Silk Performer during GUI-level testing.
  • Exploring Silk Test Results
    You can launch Silk Test directly from Silk Performer to analyze Silk Test .res result files.
Parent topic: GUI-Level Testing Support


Modeling GUI-Level Tests - Keyword-driven

  1. Click File in the menu and click New Project. In the tree, click GUI-Level Testing and Silk Test. Enter a Name and a Description and click Next.
  2. In the File field, specify the Silk Test asset you want to use for a performance test. Silk Performer automatically detects the file type and enables the appropriate button below.
  3. Click Import Keyword-Driven test.
  4. In the Tests area, select the keyword-driven tests you want to import.
  5. Specify the Import Options:
    • Ignore parameters: Does not include any of the parameters that are part of the keyword-driven test.
    • Script parameters as static strings: The parameters are directly added to the script, which means that they are static strings within the script.
    • Script parameters as values from CSV file: The parameters are stored within a .csv file and referenced in the script. The .csv file is added to the project and displays within the Project tree.
  6. Specify the Row selection order:
    • Random: Adds the BDL function FileGetRndRow to the script.
    • Sequential - machine-wide: Adds the BDL function FileGetNextRow to the script.
    • Sequential - test-wide: Adds the BDL function FileGetNextUniqueRow to the script.
  7. Select a Web Browser from the drop-down list. This list is only enabled when the file that is to be imported is based on a Silk Test web project. Silk Test web projects can make use of the single-session concept for GUI-level testing.
  8. Enable Use project attributes for session login to let Silk Performer use credentials from the Project Attributes to login into sessions. To edit the project attributes, click Project > Project Attributes . The credentials will be added to the TInit transaction of your script.
    Note: Silk Test web projects can make use of the single-session concept for GUI-level testing, thus login credentials are not required at all. Nevertheless, for further script customization it might be useful to enable Use project attributes for session login.
  9. Click OK and save the .bdf file.
Silk Performer imports the test assets and generates an appropriate .bdl stub.
Parent topic: GUI-Level Test Execution


Modeling GUI-Level Tests - UFT Developer (Silk4J)

  1. Click File in the menu and click New Project. In the tree, click GUI-Level Testing and Silk Test. Enter a Name and a Description and click Next.
  2. In the File field, specify the Silk Test asset you want to use for a performance test. Silk Performer automatically detects the file type and enables the appropriate button below.
  3. Click Import UFT Developer (Silk4J) test.
  4. In the File field, specify the archive that is to be tested. The archive is automatically added to the profile classpath. The available classes are then retrieved and displayed, sorted alphabetically in the Class field.
  5. From the Class list, select one of the available classes for testing.
    When you do not specify a specific archive for testing, the wizard enables you to specify a class that is available in the profile classpath. Type the fully qualified class name into the Class field, for example java.lang.String. The available constructors and methods are automatically retrieved and displayed.
  6. In the Methods area, select the methods that you want to call.
  7. To filter the methods that are shown in the Methods area, perform the following steps:
    1. Click the Advanced Settings button (the funnel icon above the Methods area).
    2. Once you have customized filter settings, click OK to update the Methods area.
  8. To change general Java settings including the Java version, Java home directory, or JVM DLL, click the Active Profile Settings link. The Profile Settings dialog opens to the Java/General page for Java projects (JUnit project type).
    Note: Changes made to these settings (for example Java Classpath) may lead to different results. Selections made in the Class, Constructor, and Methods fields will be updated with the new results.
    Note: If you change the Java version, Java home directory, or JVM DLL, you must restart Silk Performer for the changes to take effect.
  9. Select a Web Browser from the drop-down list. This list is only enabled when the file that is to be imported is based on a Silk Test web project. Silk Test web projects can make use of the single-session concept for GUI-level testing.
  10. Enable Use project attributes for session login to let Silk Performer use credentials from the Project Attributes to login into sessions. To edit the project attributes, click Project > Project Attributes . The credentials will be added to the TInit transaction of your script.
    Note: Silk Test web projects can make use of the single-session concept for GUI-level testing, thus login credentials are not required at all. Nevertheless, for further script customization it might be useful to enable Use project attributes for session login.
  11. Click OK and save the .bdf file.
Silk Performer imports the test assets and generates an appropriate .bdl stub.
Parent topic: GUI-Level Test Execution


Modeling GUI-Level Tests - UFT Developer (Silk4NET)

  1. Click File in the menu and click New Project. In the tree, click GUI-Level Testing and Silk Test. Enter a Name and a Description and click Next.
  2. In the File field, specify the Silk Test asset you want to use for a performance test. Silk Performer automatically detects the file type and enables the appropriate button below.
  3. Click Import UFT Developer (Silk4NET) test.
  4. In the File field, specify the archive that is to be tested. The available classes are retrieved and displayed, sorted alphabetically in the Class field.
  5. From the Class list, select one of the available classes for testing. Type the fully qualified class name into the Class field. The available methods are automatically retrieved and displayed.
  6. In the Methods area, select the methods that you want to call.
  7. To filter the methods that are shown in the Methods area, perform the following steps:
    1. Click the Advanced Settings button (the funnel icon above the Methods area).
    2. Once you have customized filter settings, click OK to update the Methods area.
  8. To change general .NET settings, click the Active Profile Settings link. The Profile Settings dialog opens to the .NET/General page.
  9. Select a Web Browser from the drop-down list. This list is only enabled when the file that is to be imported is based on a Silk Test web project. Silk Test web projects can make use of the single-session concept for GUI-level testing.
  10. Enable Use project attributes for session login to let Silk Performer use credentials from the Project Attributes to login into sessions. To edit the project attributes, click Project > Project Attributes . The credentials will be added to the TInit transaction of your script.
    Note: Silk Test web projects can make use of the single-session concept for GUI-level testing, thus login credentials are not required at all. Nevertheless, for further script customization it might be useful to enable Use project attributes for session login.
  11. Click OK and save the .bdf file.
Silk Performer imports the test assets and generates an appropriate .bdl stub.
Parent topic: GUI-Level Test Execution


Modeling GUI-Level Tests - Silk Test Classic

  1. Click File in the menu and click New Project. In the tree, click GUI-Level Testing and Silk Test. Enter a Name and a Description and click Next.
  2. In the File field, specify the Silk Test asset you want to use for a performance test. Silk Performer automatically detects the file type and enables the appropriate button below.
  3. Click Import Silk Test Classic test.
  4. If the test case file you want to import is located within a Silk Test package file (.stp), select Open a Silk Test package file and specify the file in the Silk Test Package field.
  5. If you want to import a test case file, select Open a Silk Test script file and specify the file in the Script File field.
  6. Select a specific Testcase from the list.
  7. (optional) You can add Silk Test Classic test data to the selected test case, if required. Enter test data into the Test Data field using the format "<test case name>",<test data> (For example, "test", 10).
  8. Click Add. The selected test case appears below in the Testcase field.
  9. Add more test cases to your project as required by repeating this procedure.
  10. Select a Web Browser from the drop-down list. This list is only enabled when the file that is to be imported is based on a Silk Test web project. Silk Test web projects can make use of the single-session concept for GUI-level testing.
  11. Enable Use project attributes for session login to let Silk Performer use credentials from the Project Attributes to login into sessions. To edit the project attributes, click Project > Project Attributes . The credentials will be added to the TInit transaction of your script.
    Note: Silk Test web projects can make use of the single-session concept for GUI-level testing, thus login credentials are not required at all. Nevertheless, for further script customization it might be useful to enable Use project attributes for session login.
  12. Click OK and save the .bdf file.
Silk Performer imports the test assets and generates an appropriate .bdl stub.
Parent topic: GUI-Level Test Execution
Related tasks
Setting GUI-Level Testing Options


Exporting Silk Test Tests to Silk Performer

Before you start the export, make sure that Silk Performer is installed on your computer.
  1. You can export your Silk Test test from Eclipse and Visual Studio:
    • Start Eclipse and open or create a UFT Developer (Silk4J) test.
    • Start Visual Studio and open or create a UFT Developer (Silk4NET) test.
  2. Use the Export as Performance Tests feature:
    • In Eclipse, click the Silk Test icon in the toolbar and click Export as Performance Tests.
    • In Visual Studio, click UFT Developer (Silk4NET) in the menu and click Export as Performance Tests.
Silk Performer launches and the Model Script dialog displays. Set the required options and complete the import process. Silk Performer then creates a .bdf file and adds all necessary files to the project.
Parent topic: GUI-Level Test Execution


User Credentials for GUI-Level Testing

User credentials for GUI-level testing can be specified in the following areas:

  • Profile settings
  • Project attributes (username and password project attributes are automatically defined when you create a GUI-level testing project)
  • Plain text specified in the BDL script
  • Imported from data files
Note: Ensure that the user accounts used for GUI-level testing are members of the Remote Desktop Users Windows group on the remote agent.

If you want each VUser to connect using different login credentials, specify the credentials using project attributes or use script customization through data files.

If you want each VUser to connect with identical login credentials, specify the credentials using profile settings or with plain text in the BDL script.

Note: User credentials specified in profile settings are used only when the other options listed above are not used. When no user credentials are specified in any of the areas listed above, Silk Performer connects to the console session without using the remote desktop protocol. In such instances you can only run one VUser per agent.
Parent topic: GUI-Level Test Execution
Related concepts
Data Files
Project Attributes
Related tasks
Setting GUI-Level Testing Options


Timers in GUI-Level Testing

Timers are central to GUI-level load testing. You can add timers to your Silk Test Classic, UFT Developer (Silk4J), and UFT Developer (Silk4NET) scripts which will be reported to Silk Performer’s test results. Refer to the Silk Test Help for detailed information about creating timers within Silk Test scripts.

Silk Performer automatically generates names for Silk Test timers that do not have names.

When executing keyword-driven tests, the execution time for each keyword is logged automatically.

Parent topic: GUI-Level Test Execution


GUI-Level Testing Result Files

You can find the most recent Try Script TrueLog files in the RecentTryScriptTest directory within your Silk Performer project directory. During GUI-level testing, temporary Silk Test TrueLog files with the extension .xlgs are written. After each Silk Test test case execution, the results of the Silk Test .xlgs and the results of the Silk Performer .xlgs files are merged into the Silk Performer .xlgs files (per VUser) and the temporary .xlgs files are deleted.

The RecentTryScriptTest directory within your Silk Performer project directory also includes Silk Test .xlgs result files. These are the files that are displayed in Silk Test when you initiate the Explore Silk Test results command.

Parent topic: GUI-Level Test Execution


Exploring Silk Test Results

  1. Within Silk Performer, right-click a virtual user profile.
  2. Select Explore Silk Test Results from the context menu. Silk Test launches, allowing you to analyze the corresponding Silk Test .res result file. You can also select Explore TrueLog from the context menu to view a Try Script’s TrueLog in TrueLog Explorer. Click the Results tab to view test results directly in Silk Performer.
Parent topic: GUI-Level Test Execution
Related concepts
Exploring Test Results
GUI-Level Testing Support


Requirements for GUI-Level Testing with UFT Developer (Silk4J) and UFT Developer (Silk4NET)

Make sure to meet the following requirement when you use UFT Developer (Silk4J) for GUI-Level testing:
  • You must have Silk Test 15.0 or higher installed.
Make sure to meet the following requirements when you use UFT Developer (Silk4NET) for GUI-Level testing:
  • You must have Silk Test 15.0 or higher installed.
  • You must have Test Agent from the .NET Framework installed.
  • You need the same version of MSTest that was used to build the test file.
    Note: Silk Performer will always use the latest MSTest version that is installed on the test machine. If the version you used for building the test file differs from the latest version that is installed on the test machine, the UFT Developer (Silk4NET) information in the TrueLog file will be missing.
Parent topic: GUI-Level Testing Support


GUI-Level Testing Scalability Scenarios

System Test Environment

  • Silk Performer 2019
  • Silk Test 21.0
  • 4 GB RAM
  • BroadCom 57xx Gigabit Controller
  • Dual (2 x 2.4 GHz) processors
  • 167 GB free space hard disk
Note: The results below should be used as a guideline only and your results will differ depending on the application under test and the available resources of specific Silk Performer agent machines.

Test Scenario

The following table lists the memory consumption of virtual users navigating through a web application such as the Insurance demo application using different GUI-level testing technologies of Silk Test. As the memory consumption per virtual user depends heavily on the AUT (browser, application), only the processes of the corresponding driver technology are listed.

 |  | Private Memory
Silk Test Type | VUser(s) | PerfRun.exe | openAgent.exe | PerfSm.exe | Supplementary processes
Silk Test Classic | 1 | 15,5 MB | 861 MB | 2 MB | partner.exe - 19 MB
Silk Test Classic | N | N x 15,5 MB | N x 861 MB | N x 2 MB | N x 19 MB
UFT Developer (Silk4J) | 1 | 15,5 MB | 861 MB | 36,5 MB |
UFT Developer (Silk4J) | N | N x 15,5 MB | N x 861 MB | N x 36,5 MB |
UFT Developer (Silk4NET) | 1 | 15,5 MB | 680 MB | 2,5 MB | vstest.console.exe - 25 MB testhost_x86.exe - 35 MB
UFT Developer (Silk4NET) | N | N x 15,5 MB | N x 680 MB | N x 2,5 MB | N x 60 MB

Additional Information

Additional information on executing the load test on machines which use Multiple Processors:

As long as you have more replay engines (PerfRun.exe) running than you have CPUs available on the machine, the current implementation of GUI-level support in Silk Performer does not have any limitations regarding the number of processors that can be used on a Silk Performer agent installation. During a load test scenario, each Silk Performer replay engine (PerfRun.exe) will be bound to a particular processor in a round robin method, for example: PerfRun.exe1 to CPU1, PerfRun.exe2 to CPU2, PerfRun.exe3 to CPU3, perfRun.exe4 to CPU4, and so on.

Parent topic: GUI-Level Testing Support


Troubleshooting GUI-Level Testing Issues

When troubleshooting GUI-Level issues it is important to note that there are three separate components (Silk Performer, Silk Test, and Windows/Terminal Services/Remote Desktop Services) that play integrated roles during the execution of GUI-Level tests; each of these components should be considered when attempting to isolate the root causes of errors.

Step 1: Windows test-environment configuration

Note: For resolutions to issues outlined in this section, please visit the Micro Focus Knowledge Base and enter the referenced Resolution ID.

The first thing to consider is that Silk Performer can only execute multiple GUI-level virtual users on Microsoft Windows operating systems that have Terminal Services/Remote Desktop Services installed, licensed and configured. If you attempt to execute more than one GUI-level virtual user from a Microsoft Windows machine you will encounter the following error message: StInitSession(GUI-Level Testing Replay: 10 - Virtual user information, Silk Test Connection timeout reached.

Resolution ID: 17256, 17231

The next, and perhaps most important, step is to configure Windows Terminal Services/Remote Desktop Services to allow each Silk Performer virtual user to execute a Silk Test test case within a separate terminal session. Therefore it is of the vital importance that each of the settings below be configured exactly as specified in the resolution listed below.

Resolution ID: 17255

Please note that failure to configure Windows Terminal Services/Remote Desktop Services as recommended above can result in error messages such as GUI-Level Testing Replay: 10 - Virtual user information, RDP not connected.

Resolution ID: 20117

Once you have configured Terminal Services/Remote Desktop Services, the final configuration check is to ensure that you are using the correct version of Silk Test (for test case generation) and that you have the correct Silk Performer licenses available for a GUI-level load testing.

Resolution ID: 17168, 17148

Step 2: Proxy Server Configuration

In some situations, when recording a Silk Performer script via the Silk Test interface, the resulting BDF file contains no Silk Performer functions. To resolve this issue, perform the following:

  1. Launch Internet Explorer and navigate to Tools > Internet Options.
  2. Select the Connections tab.
  3. Click LAN settings. The Local Area Network (LAN) Settings dialog box opens.
  4. Check the Use a proxy server for your LAN check box.
  5. In the Address field, type localhost.
  6. In the Port field, type 8080.
  7. Click OK.

Step 3: Silk Test configuration and test-case generation

Note: For resolutions to issues outlined in this section, please visit the Micro Focus Knowledge Base and enter the referenced Resolution ID.

When using Silk Test to generate a test case for execution in Silk Performer it is important that you consider that the test case will eventually be executed by Silk Performer within a Terminal Services/Remote Desktop Services/Remote Desktop Services environment. This means that certain considerations need to be made, such as ensuring that a full version of Silk Test is installed on the Silk Performer Agent otherwise Silk Performer will report the error message GUI-Level Testing Replay: 7 - Application could not be launched.

Resolution ID: 17181

Ensure that any directory paths that have been configured for Silk Test are still available when the Silk Test project is exported to Silk Performer; otherwise the Silk Performer runtime engine may be unable to can locate the directory path used to launch the application under test. Failure to set a global path can result in an error message such as Error: Directory XXXX does not exist".

Resolution ID: 17204

Finally, before exporting the Silk Test project to Silk Performer it is imperative that you export the project using the correct settings. Otherwise you may see the following error: GUI-Level Testing Replay:11 SilkTest reported. Project failed to open. The resolution below describes both the consequences of not doing this and the correct way to export a project from Silk Test.

Resolution ID: 17200

Step 4: Silk Performer configuration and common GUI-level replay errors

Note: For resolutions to issues outlined in this section, please visit the Micro Focus Knowledge Base and enter the referenced Resolution ID.

The final component to look at when troubleshooting GUI-level issues is Silk Performer. The first thing an end user should consider before they replay a GUI-level BDF script in Silk Performer is that there are major differences between executing a Silk Test testcase within Silk Performer using a normal console session and executing a Silk Test test case using a terminal server session. The major differences between running a BDF script as a console session and terminal server session are detailed in the following resolution.

Resolution ID: 17258

Failure to understand the differences between the types of sessions that can be executed in Silk Performer and failure to instruct Silk Performer that you wish to execute a terminal server session can lead to the common replay error GUI-Level Testing Replay: 10 - Virtual user information, More than 1 user per Session is not allowed. Refer to the resolution listed below to learn how to avoid this error during replay in Silk Performer.

Resolution ID: 17257

Other errors that commonly occur during replay are related to the Terminal Services/Remote Desktop Services session in which the Silk Test test case runs. For example is it important to consider that when a Silk Test test case is initially recorded it is often within an operating system environment that uses different user credentials than the environments in which the Silk Test test case will be executed within the terminal server environment. This can result in unexpected windows being generated during replay within the terminal server session and as a result the Silk Test agent will report an error message during replay within Silk Performer such as Log Error: *** Error: Window 'window name' was not found. The following resolution provides a good example of one such error and explains how you can avoid it.

Resolution ID: 17236

Before you execute an actual GUI-level test it is important to consider that there are limitations in regards to the number of virtual users that can be executed within a Terminal Server environment. The resolution below outlines the typical number of GUI-level virtual users that can be executed from a single Silk Performer installation.

Resolution ID: 17202

Parent topic: GUI-Level Testing Support


Jacada Support

This section explains Silk Performer support for the testing of Jacada applications, including project setup and Java configuration issues.

Jacada is a J2EE-based solution that covers both the agent desktop and the back end. Jacada is mainly used to wrap applications and present a Web UI to clients.

  • Creating Jacada Projects
    To test a Jacada application you must set up a project with the appropriate Jacada application type.
  • Configuring Jacada Recording Profiles
    Before recording a Jacada application, you must set up a Web-based recording profile.
  • Configuring Java Profile Settings for Jacada
    Before replaying a Jacada application, you must define the Java Virtual Machine (JVM) and provide Jacada's clbase.jar file.
  • Recording Jacada Applications
    Record your Jacada application like a standard Web application.
  • Structure of a Jacada BDL Script
    Explains the structure of a BDL script of a recorded Jacada application.
Parent topic: Load Testing Specific Application Types


Creating Jacada Projects

  1. Click Start here on the Silk Performer workflow bar.
    Note: If another project is already open, choose File > New Project from the menu bar and confirm that you want to close your currently open project.
    The Workflow - Outline Project dialog box opens.
  2. In the Name text box, enter a name for your project.
  3. Enter an optional project description in Description.
  4. In the Type menu tree, select Application Server/Component Models > Jacada.
  5. Click Next to create a project based on your settings.
The Workflow - Model Script dialog box appears.
Parent topic: Jacada Support
Related tasks
Recording Jacada Applications


Configuring Jacada Recording Profiles

  1. In the Silk Performer menu, click Settings > System .
  2. Click the Recorder icon. The Recording Profiles page opens.
  3. In the Application list, select the listed recording profile and click Edit. The Recording Profile dialog box opens.
  4. In the Protocol selection area, check the Web check box, if it is not already selected.
  5. Click Web Settings. The Web Settings dialog box opens.
  6. Click the WinSock option button, then click OK.
  7. In the Java API list box, check the Jacada check box.
  8. Click OK to close the Recording Profile dialog box.
  9. On the System Settings dialog box, click the Proxies tab to edit the recording proxy configuration. The Proxies page opens.
  10. In the Proxies list box, select the SOCKS protocol and click Edit. The Proxy Settings dialog box opens.
  11. In the Suppress recording (only forward data) area, type 1100-1200 in the Within port range text box to suppress the recording of forward data.
  12. Click OK to close the Proxy Settings dialog box.
  13. Click OK to close the System Settings dialog box.
Parent topic: Jacada Support


Configuring Java Profile Settings for Jacada

  1. In Silk Performer, expand the Profiles node in the Project tree.
  2. Right-click the profile that you want to configure and choose Edit Profile.
    Tip: Alternatively, you can choose Settings > Active Profile from the menu bar.

    The Profile - [<profile name>] dialog box opens, and the Replay category is displayed in the shortcut list on the left.

  3. In the shortcut list, click Java.
  4. From the Jacada server on which you want to test your Jacada application, copy the file clbase.jar to your local working directory. The default location of clbase.jar on the Jacada server is \classes\cst\.
  5. Click File to locate clbase.jar on your local machine and add it to the Classpath.
  6. Click OK to save your profile settings.
Parent topic: Jacada Support
Related tasks
Configuring Java Version and Classpath Settings


Recording Jacada Applications

Record your Jacada application like a standard Web application.

  1. Click Model Script on the workflow bar. The Workflow - Model Script dialog box appears.
  2. In the URL text box, enter the URL of the Jacada application that you want to test. Example: http://my.jacada.server:9999
  3. Click Start recording to begin recording the session.
  4. Perform the required interactions with the application under test.
  5. When recording is complete, close the application, close the recorder, and save the test script.
  6. To confirm that your test script runs as expected, execute a Try Script run in animated mode; you will then be able to view the results of the test run in TrueLog Explorer.
Parent topic: Jacada Support


Structure of a Jacada BDL Script

When recording a Jacada application with Silk Performer, the resulting BDL script contains a mix of both Web/HTTP as well as Jacada protocol entries. The script is structured into HTTP traffic and user interactions:
  • HTTP traffic
    • JacCreateUser(…)
    • JacConnectUsing…(…)
  • User Interactions
    • JacDestroy(…)

Jacada Functions

A number of functions are provided to handle Jacada function calls from within Silk Performer. These functions are one-to-one wrappers of Jacada's own API. Refer to Jacada documentation for detailed information.

Following is a sample of Jacada user interactions:
  • Enter Data
    • JacSetTextData(...)
    • JacSetTableData(...)
  • Screen Transition
    • JacSendWindowData(...)
    • JacSendCommand(...)
    • JacChangeCellValue(...)
  • Verifications
    • JacCheckScreen(...)
    • JacCheckFieldValue(...)
    • JacCheckTableCell(...)
Parent topic: Jacada Support


Java Support

Silk Performer's Java support includes the testing of Enterprise JavaBeans (EJB), RMI objects, JUnit, and more.

  • Java Framework Support
    As a powerful extension to Silk Performer’s Benchmark Description Language, the Java Framework enables you to implement user behavior in Java.
  • Testing SOAP Web Services for Java
    Explains the basics of SOAP-based Web Services and details how they can be tested in Java.
  • Java Over HTTP Support
    This section explains Silk Performer support for the testing of applications that rely on Java over HTTP.
  • JUnit Integration
    Provides an overview of the integration of JUnit test scripts into Silk Performer.
  • Java RMI Support
    Explains Silk Performer's support for the record and replay of Java RMI applications, including project setup and Java configuration issues.
  • Eclipse Plug-In
    Describes how the Eclipse plug-in works with Silk Performer.
  • Silk Performer Java Explorer
    Provides an overview of Silk Performer Java Explorer.
Parent topic: Load Testing Specific Application Types


Java Framework Support

As a powerful extension to Silk Performer’s Benchmark Description Language, the Java Framework enables you to implement user behavior in Java. When testing an existing Java application you do not need to spend much time creating test scripts. The only effort required is embedding existing Java source code into the framework. Refer to the Java Framework Developer Guide for detailed information.

To generate a benchmark executable and run a test with the help of the Java framework, two source files are typically required:

  • Java class that implements the behavior of a virtual user
  • Silk Performer test script that invokes Java method calls

Both source files need to have the same name, with extensions indicating the file types (.bdf for the Silk Performer test script and .java for the Java source file).

With Silk Performer it is possible to call Java functions on any Java object from a BDL context with any number and type of parameter and return parameter. When a Java function returns a complex object, a handle for the Java object is returned in its place. The handle can be passed to other function calls as an input parameter, or public methods may be invoked on the object. There is also support for static methods, cast operations, and exception handling.

  • Creating Java Projects
    Setting up a Java project involves specifying the Java Framework application type and identifying any additional resources that your project requires.
  • Generating Java Framework Files
    To test a Java class, your project needs both a BDL file and a Java file containing a class.
  • Generating Java Files Without a BDL File
    You have the option of generating Java files for your project without using a BDL file.
  • Compiling Java Files
    Before a Java file can be compiled it is necessary to ensure that a valid path to a Java SDK and a valid classpath are specified.
  • Switching between 32-bit and 64-bit Java
    Explains how to switch between 32-bit and 64-bit Java and what the Java architecture effects during test execution.
Parent topic: Java Support
Related concepts
JUnit Integration
Java Framework Functions


Creating Java Projects

  1. Click Start here on the Silk Performer workflow bar.
    Note: If another project is already open, choose File > New Project from the menu bar and confirm that you want to close your currently open project.
    The Workflow - Outline Project dialog box opens.
  2. In the Name text box, enter a name for your project.
  3. Enter an optional project description in Description.
  4. From the Type menu tree, select Java/Java Framework.
  5. Click Next to create a project based on your settings.
The Workflow - Model Script dialog box appears.

If you need to add additional resources to the project, right-click the project icon in the menu tree. It is particularly important that all the user data files (.csv), random data files (.rnd), and .idl files needed by Silk Performer are set up for the project.

Parent topic: Java Framework Support


Generating Java Framework Files

  1. Click File > New > Java Framework Scripts (.bdf/.java) . The New Java Framework Script dialog box opens.
  2. Type a name for your Java class.
  3. Click OK. A Java file containing a class with the specified name is generated and opened along with a BDL file, which is used to test the Java class.
  4. If you save your files, you are asked whether you want to add them to your project.
Parent topic: Java Framework Support


Generating Java Files Without a BDL File

  1. Select File > New... > Java Script (.java) from the main menu bar. The New Java Script dialog appears.
  2. Enter a name for your Java class.
  3. Click OK. A Java file containing a class with the given name is generated and opened.
  4. When saving a new Java file for the first time, you are asked if you want to add the file to the current project. Click Yes. There are two other ways you can add Java files to your project:
    • Right-click the Scripts subnode of the project and select Add Existing Script... to open the Select Script(s) dialog. Change the File of type list box selection to Java files (*.java). Select your file, which will be added to the project when you click Open.
    • Right-click in Java file view to open the context menu. Click Add to Project to add the file to the project.
Parent topic: Java Framework Support
Related concepts
JUnit Integration


Compiling Java Files

  1. Select Settings > Active Profile .
  2. Select the Java icon in the left-hand scroll window. The General page appears.
  3. Click the folder icon next to the Java home text box to select the directory where the Java SDK is installed.
  4. Add any required entries to the classpath in the Classpath text box.
    Note: Alternatively, you can use the JavaSetOption function with the appropriate option number to set the Java version, home directory, and classpath.
  5. Click OK.
  6. Perform manual compilation using one of the following methods:
    • Open a Java file and press F7.
    • Open a Java file and right-click in the view to open the context menu. Select the Compile command.
    • Right-click a Java file on the Project page to open the context menu. Select the Compile command.
Initiating Try Scripts, finding baselines, and running tests will also automatically launch compilation for all Java and BDL files.

During compilation, all output from the Java Compiler is redirected to the Compiler page. Resulting class files are generated in the current project directory.

Parent topic: Java Framework Support
Related concepts
Java Framework Functions


Switching between 32-bit and 64-bit Java

  1. In the menu, click Settings > Active Profile.
  2. Click the Java icon and then the Advanced tab.
  3. Select 32-bit Java (default) or 64-bit Java.
  4. If you use 64-bit Java, specify an Execution timeout for the communication between the Silk Performer runtime and the JVM.
The specified Java architecture determines whether your Java test code is running in-process or out of process. This results in the following behavior:
  • 32-bit Java is enabled: When you execute a test, the jvm.dll and the required .jar files are loaded dynamically into the perfrun.exe. Note that this increases the memory usage of the perfrun.exe. Also be aware that during the early phase of a load test, the memory usage might be volatile. This can be misunderstood as a memory leak, but is in fact expected due to the Java garbage collector at work. By default, up to 50 virtual users share the same JVM, which helps reduce memory usage. However, this feature requires that your Java test code is thread-save (especially the static variables).
  • 64-bit Java is enabled: When you execute a test, the Java test code is running in a separate process - it is not loaded into the perfrun.exe.

You can also use the BDL function JavaSetOption to switch between 32-bit and 64-bit Java. Note that the settings defined in the BDL script override the options defined in the profile settings.

Parent topic: Java Framework Support
Parent topic: Java Framework


Testing SOAP Web Services for Java

A Web service is an available service on the Web that can be invoked and from which results can be returned. Although other standards exist, the widely accepted standard for Web services, which has been adopted by the W3C, is SOAP (Simple Object Access Protocol).

This chapter explains the basics of SOAP-based Web Services and details how they can be tested.

  • Simple Object Access Protocol (SOAP)
    Describes the Simple Object Access Protocol (SOAP).
  • Testing SOAP Over HTTP-Based Web Services
    Explains the three options that are available for testing SOAP over HTTP-based services.
  • External References
    Lists the references that are used for the section.
Parent topic: Java Support
Parent topic: Java Testing Support


Java Explorer

Java Explorer allows users to create test cases using point and click operations. Java Explorer provides support for the following technologies:

  • SOAP Web Services
  • RMI
  • EJB
  • General GUI-less Java objects

Java Explorer can be used to export complete Silk Performer projects that make use of the Silk Performer Java Framework. Java Explorer itself can only run previously defined test scenarios in animated mode. With exported projects however, Silk Performer can perform real tests with multiple virtual users.

Note: Java Explorer currently uses the Axis SOAP stack (http://www.apache.org) to generate Web Service client proxy classes.
Parent topic: Simple Object Access Protocol (SOAP)


Java Framework

With the Java Framework, Silk Performer offers a powerful means of simulating virtual users whose behavior is defined with the Java programming language. Arbitrary Java classes can be instantiated within the framework and methods defined within classes may be invoked.

The behavior of virtual users running in the Java framework can be scripted manually using Silk Performer or another Java IDE. A more convenient method however is to use Java Explorer to define virtual user behavior through its point and click interface.

Parent topic: Simple Object Access Protocol (SOAP)


Java Over HTTP Support

This section explains Silk Performer support for the testing of applications that rely on Java over HTTP.

  • Java Over HTTP Overview
    Offers a brief introduction to Java over HTTP technology.
  • Java Over HTTP Project Setup and Testing
    Explains considerations related to the testing of Java over HTTP applications with Silk Performer, including project setup, script modeling, verifications, and parsing statements.
  • Customizing Java Over HTTP Scripts
    This section explains how to customize scripts using both Silk Performer and TrueLog Explorer.
  • Adding Verification and Parsing Statements
    This section explains how to use TrueLog Explorer to add verification statements using both rendered XML view and plain-text source view.
Parent topic: Java Support


Java Over HTTP Overview

Some applications make use of Java Object Serialization to transfer objects between client and server over the HTTP protocol. This communication, based on the exchange of serialized Java objects, uses data in binary format. Therefore Java Object Serialization is effectively object representation in binary format.

JAVA Object Serialization has been used by many applications for many years. For full details, see the Java specification for object serialization.

A popular framework that enables the use of Java over HTTP as a remoting technology is Spring Framework and its HTTP Invoker.

Parent topic: Java Over HTTP Support


Java Over HTTP Project Setup and Testing

Prerequisites

For testing Java over HTTP applications, Java Development Kit 1.6 or later is required.

Transformation is enabled for HTTP requests and responses that have the HTTP header Content-Type set to "application/octet-stream" or "application/x-java-serialized-object". If you need to transform data with a different HTTP Content-Type header, see Transformation of Custom Content-Types.

Setting Up a Java Over HTTP Project

When outlining your project, be sure to select the Java over HTTP application type (Web browser/Java over HTTP on the Outline Project dialog).

By selecting the Java over HTTP application type, several profile settings are automatically configured for you on the tab Profile > Web Protocol Level > Transformation:

  • The Java over HTTP transformation DLL is selected in the Type drop list.
  • Transform HTTP Requests is enabled
  • Transform HTTP Responses is enabled
  • Enable Java Virtual Machine usage is enabled. This setting is required because Java over HTTP requires a running JVM for accurate transformation of serialized/externalizable Java objects. This setting also causes transformed binary Java traffic to appear in readable XML representation.

Modeling a Script

Using the JVM requires the configuration of Java over HTTP application-specific custom JAR files that contain the classes that are necessary for deserialization and transformation into correct XML representation. For this reason, when modeling a Java over HTTP script, the Model Script dialog includes an Add Custom JAR File(s) button. Click this button to browse to and Add any custom JAR files that are specific to the application under test. Added JAR files are displayed within the Project tree Data Files node.

Note: If your application is based on Spring Framework HTTP Invoker, you must add spring.jar to the classpath.

These required JAR files (or individual .class files) are located on the server to be tested. These files must be prepared manually and copied from the server to the Silk Performer controller machine.

Note: It is recommended that JAR files be placed in the Project folder.

Clicking Settings on the Model Script dialog links you directly to the current user profile, Java Settings tab. Use this to change Java settings for the currently selected user profile.

Note: Do not enable Use system classpath on the Java Settings tab. JAR files set in the system classpath may overrule manually configured JAR files.

Generating a Script from a Capture File

While recording a user transaction, the Silk Performer recorder creates a so-called Silk Performer capture file, which contains the entire traffic of the recorded session. After saving, the capture file is opened in the Workbench for further analysis and processing. Before generating a script from the captured traffic, you can configure recording rules and other settings, which are applied during the script generation process.

If any errors occur, click the buttons in the Resolve Problems area to resolve them. Then, click Generate Script to generate a script from the capture file.

On 64-bit operating systems, both a 32-bit and 64-bit Java installation are required. The 32-bit installation is used for replaying scripts, the 64-bit installation is used for generating scripts. If a 64-bit installation is not available, you can force Silk Performer to use a 32-bit process for script generation by setting the following registry key to 1: HKEY_LOCAL_MACHINE\SOFTWARE\Silk\SilkPerformer\<version>\Force32BitCaptureAnalyzer.
Attention: Using the 32-bit script generator can cause issues with large capture files.

Replaying a Script

If your Java configurations are incorrect (for example, if JAR files are missing), XML responses (only visible in TrueLog Explorer) will not be generated in an easily readable format. Also warnings or errors will be written to the Virtual User Output pane. Typically, errors and warnings indicate whether or not they were caused by requests (client to server) or responses (server to client).

Customizing Java Over HTTP Scripts

Do not change the overall structure of XML objects within Java over HTTP scripts. It is okay to parse values or insert verification functions, but deleting or rearranging Java over HTTP XML elements will destroy a call. Also do not change the order of elements within arrays.

Parent topic: Java Over HTTP Support
Related concepts
Generating Scripts from Capture Files
Related tasks
Configuring Java Version and Classpath Settings


Customizing Java Over HTTP Scripts

You can use either Silk Performer or TrueLog Explorer (Response tab) to customize Java over HTTP scripts.

  • Customizing Input Data Using Silk Performer
    Use the string customization wizard to customize user input data in your script.
  • Customizing Input Data Using TrueLog Explorer
    Upon opening a Try Script TrueLog, TrueLog Explorer offers a rendered XML view that facilitates the customization of XML strings.
Parent topic: Java Over HTTP Support
Related concepts
Customizing Scripts


Customizing Input Data Using Silk Performer

  1. Search for the original value in the script, this is typically an XML node value.
  2. Select the string you want to customize.
  3. Right click and chose Customize Selected String.
  4. Follow the steps outlined by the string customization wizard.
Note: Do not change the overall structure of XML objects within Java over HTTP scripts. It is okay to customize input, parse values and insert verification functions, but deleting or rearranging Java over HTTP XML elements can destroy a call. Also, do not change the order of elements within arrays.
Parent topic: Customizing Java Over HTTP Scripts
Related concepts
Customizing Scripts


Customizing Input Data Using TrueLog Explorer

  1. Run a Try Script.
  2. Open the resulting TrueLog (XLG) file. To do this, from within TrueLog Explorer, click Open TrueLog, open the related project folder, and double click the XLG file.
  3. Expand the TrueLog node in the tree menu and select a request.
  4. Select the Request tab.
  5. Select the XML node value you want to customize.
    Tip: Right-click in the rendered XML view and choose Find to search for an XML node value. The global find option is not able to search rendered XML view.
  6. Right click and choose Customize Selected String.
  7. Follow the steps outlined by the string customization wizard.
Parent topic: Customizing Java Over HTTP Scripts
Related concepts
Customizing User Input Data
Working With XML Applications


Adding Verification and Parsing Statements

This section explains how to use TrueLog Explorer to add verification statements using both rendered XML view and plain-text source view.

  • Adding Verification Statements Using Rendered XML View
    TrueLog Explorer offers rendered XML view for all supported content types.
  • Adding Verification Statements Using Plain-Text View
    For unsupported content types, TrueLog Explorer offers plain-text source view to facilitate string customization.
Parent topic: Java Over HTTP Support
Related tasks
Adding Verification Statements Using Rendered XML View
Adding Verification Statements Using Plain-Text View


Adding Verification Statements Using Rendered XML View

  1. Run a Try Script.
  2. Open the resulting TrueLog (XLG) file. To do this, from within TrueLog Explorer, click Open TrueLog, open the related project folder, and double click the XLG file.
  3. Expand the TrueLog node in the tree menu and select a request.
  4. Select the Response tab.
    Note: XML can only be rendered when an appropriate content type is sent from the server. Use plain-text source view for unsupported content types.
  5. (Optional) If you are sure that an unknown application type (for example, octet-stream) can be rendered as XML, you may do the following to render it:
    1. Run regedit.
    2. Select HKEY_CURRENT_USER\Software\Silk\TrueLog Explorer\...\TreatAsXmlAlways
    3. Add application/octet-stream to the list of values. Use a semi-colon (;) as a separator.
    4. Restart TrueLog Explorer.
  6. Right-click an XML node value and choose Verify Element Value… or Parse Element Value….
    Tip: Right-click in the rendered XML view and choose Find to search for an XML node value. The global find option is not able to search rendered XML view.
  7. Follow the steps outlined by the wizard.
Parent topic: Adding Verification and Parsing Statements
Related concepts
Adding Verifications
Verification Functions for XML Applications


Adding Verification Statements Using Plain-Text View

  1. Run a Try Script.
  2. Open the resulting TrueLog (XLG) file. To do this, from within TrueLog Explorer, click Open TrueLog, open the related project folder, and double click the XLG file.
  3. Expand the TrueLog node in the tree menu and select a request.
  4. Select the Response tab.
  5. Search for and select the value to be verified.
  6. Right-click an XML node value and choose Verify Element Value… or Parse Element Value….
  7. Follow the steps outlined by the wizard.
Parent topic: Adding Verification and Parsing Statements
Related concepts
Adding Verifications
Verification Functions for XML Applications


JUnit Integration

Silk Performer facilitates smooth integration of existing JUnit test scripts (version 3.8.x and 4.x) into Silk Performer for the support of remote-component testing under realistic concurrent-access server conditions.

Silk Performer provides an import tool that enables you to import existing JUnit test classes and other Java classes. Tested Java methods may have parameters and return values; code for setting the in-parameters of these functions is generated automatically. By definition, JUnit test methods cannot have parameters.

Silk Performer’s Unit Test Import tool offers you the option of selecting specific test methods. It automatically generates BDL stub code (a benchmark description file) that calls those selected test methods. Existing JUnit test classes can be called from Silk Performer without requiring modification of the test classes.

Prerequisites

JUnit 4.x testing requires Java version 1.5 or higher.

The respective JUnit libraries must be available in the classpath of the Java settings of the active profile.

  • Setting Up a New JUnit Silk Performer Project
    Create a JUnit project in order to import your JUnit test scripts.
  • Importing a JUnit or Java Test Class
    Import existing Java test classes into Silk Performer for the support of remote-component testing under realistic concurrent-access server conditions.
  • Java Profile Settings
    Describes how Silk Performer maintains the profile classpath.
  • Filter Options for JUnit Methods
    Lists the filters that are available in the Methods area when you import a test class.
  • Example BDL Script for JUnit 3.8.x (legacy)
    Provides an example BDL script that includes timer parameter information for JUnit 3.8.x.
  • Example BDL Script for JUnit 4.x (legacy)
    Provides an example BDL script that includes timer parameter information for JUnit 4.x.
  • Example BDL Script for JUnit
    Provides an example BDL script for JUnit.
  • Exception Handling for JUnit 4.x and newer
    Describes how JUnit exceptions are validated and provides an example of a method that throws an exception.
  • Importing a JUnit Test Suite
    Import existing JUnit test suites into Silk Performer for the support of remote-component testing under realistic concurrent-access server conditions.
  • Executing a JUnit Test Suite
    In order to invoke methods that have a return value, you must uncomment the code used to retrieve the return value before you can successfully execute a test suite.
Parent topic: Java Support
Related concepts
Java Framework Support


Setting Up a New JUnit Silk Performer Project

  1. Click Start here on the Silk Performer workflow bar.
    Note: If another project is already open, choose File > New Project from the menu bar and confirm that you want to close your currently open project.
    The Workflow - Outline Project dialog box opens.
  2. In the Name text box, enter a name for your project.
  3. Enter an optional project description in Description.
  4. From the Type menu tree, expand Unit Testing and select JUnit.
  5. Click Next.
    Note: If you need to add additional resources to the project, right-click the project icon in the Project menu tree view. It is particularly important that all the user data files (.csv), random data files (.rnd), and .idl files needed by Silk Performer are set up for your project.
The Workflow - Model Script dialog box appears.
Parent topic: JUnit Integration
Related tasks
Recording a Test Script


Importing a JUnit or Java Test Class

Modify your Java profile settings accordingly before importing JUnit 4.x module tests.
  1. Click Model Script on the workflow bar. The Workflow - Model Script dialog box appears.
  2. In the File field, specify the archive that is to be tested. The archive is automatically added to the profile classpath. The available classes are then retrieved and displayed, sorted alphabetically in the Class field.
  3. From the Class list, select one of the available classes for testing.
    When you do not specify a specific archive for testing, the wizard enables you to specify a class that is available in the profile classpath. Type the fully qualified class name into the Class field, for example java.lang.String. The available constructors and methods are automatically retrieved and displayed.
  4. From the Constructor list, select the appropriate constructor for instantiating the imported class. If a constructor is not selected (entry <No Instance Required – Only Static Calls>), only static methods will be displayed in the method list.
  5. In the Methods area, select the methods that you want to call.
  6. To filter the methods that are shown in the Methods area, perform the following steps:
    1. Click the Advanced Settings button (the funnel icon above the Methods area).
    2. Once you have customized filter settings, click OK to update the Methods area.
  7. To change general Java settings including the Java version, Java home directory, or JVM DLL, click the Active Profile Settings link. The Profile Settings dialog opens to the Java/General page for Java projects (JUnit project type).
    Note: Changes made to these settings (for example Java Classpath) may lead to different results. Selections made in the Class, Constructor, and Methods fields will be updated with the new results.
    Note: If you change the Java version, Java home directory, or JVM DLL, you must restart Silk Performer for the changes to take effect.
  8. Click OK.
Parent topic: JUnit Integration


Java Profile Settings

The JUnit or Java test class you want to import and all third-party libraries needed by the test class must be available in the profile classpath. Silk Performer automatically adds all archives entered in the File field to the profile classpath. Also, all test classes compiled in Silk Performer are compiled to the project directory, which is also automatically included in the profile classpath.

Parent topic: JUnit Integration


Filter Options for JUnit Methods

This table lists the filters that are available in the Methods area when you import a test class.

JUnit Method | Description
Parameterless Functions Only | Ignore all functions that expect parameters
Unit Test Functions Only (selected by default for JUnit import) | Ignore all functions that are not JUnit
Member Functions Only | Ignore all non-member functions
Public Functions (selected by default) | Include public functions
Protected Functions | Include protected functions
Private Functions | Include functions with private access
Package Functions | Include functions with package access
Declared Functions Only | Ignore functions from the base classes
Complex Functions (selected by default) | Show functions that take complex parameters. In Java, complex parameters are scripted by JavaSetObject with NULL as the default value.
Autodetect Unit Test Functions (selected by default) Automatically detect and script JUnit functions according to the following rules:
  • JUnit 3.8.x scripts are derived from junit.framework.TestCase class.
  • JUnit 3.8.x functions must not have parameters or return values.
  • setUp() and tearDown() are invoked prior to and following each JUnit 3.8.x method.
  • JUnit 4.x scripts no longer require to be derived from junit.framework.TestCase class.
  • JUnit 4.x functions are recognized by the @Test annotation and added to the script, unless the @Ignore annotation is used.
  • Methods having @BeforeClass and @AfterClass annotation are invoked once per test class.
  • Methods having @BeforeClass and @After annotation are invoked prior to and following each JUnit 4.x method.
Parent topic: JUnit Integration


Example BDL Script for JUnit 3.8.x (legacy)

Script Example

The following script is generated by importing a sample JUnit 3.8.x test case and selecting the three methods testRound, testSqrt, and testMax:

Note: The following script is a legacy script, which is generated within older Silk Performer versions. For Silk Performer 19.5 and newer, a JUnit import creates a slightly different script, which is documented in Example BDL Script for JUnit .
transaction TInit
var
    hPerf : number;
begin
    JavaCreateJavaVM();
    JavaSetString(JAVA_STATIC_METHOD, "TestCaseName");
    ghTestObj := JavaLoadObject("JUTestClass", "JUTestClass.<init>");
end TInit;

transaction TMain
begin
    JUnitCallMethod(ghTestObj, "testRound", "testRound");
    JUnitCallMethod(ghTestObj, "testSqrt", "testSqrt");
    JUnitCallMethod(ghTestObj, "testMax", "testMax");
end TMain;

transaction TEnd
begin
    JavaFreeObject(ghTestObj);
end TEnd;

JavaLoadObject in the TInit transaction instantiates the JUnit test class, JUTestClass.

JUnitCallMethod in the TMain transaction calls one of the three test methods in the same way that a JUnit test runner would. First the setUp() method is invoked, then the test method itself (e.g., testSqrt()), finally the tearDown() method is invoked.

Timers

When an optional timer parameter is specified for a Java method call, the execution times of the constructor, test method, setup method, and teardown method are measured. For the example in this topic, you receive the following measures:

  • For the constructor: JUTestClass.<init>
  • For the methods: testRound, testSqrt, testMax
  • For the set up methods: testRound_setup, testSqrt_setup, testMax_setup
  • For the tear down methods: testRound_tearDown, testSqrt_tearDown, testMax_tearDown
Parent topic: JUnit Integration


Example BDL Script for JUnit 4.x (legacy)

Script Example

The following sample JUnit test script contains several annotations for test setup and teardown and is generated by importing a sample JUnit 4.x test case and selecting the methods doFoo and doFoo2.

Note: The following script is a legacy script, which is generated within older Silk Performer versions. For Silk Performer 19.5 and newer, a JUnit import creates a slightly different script, which is documented in Example BDL Script for JUnit .
var
  ghTestObj :number;
dcluser
  user
    JavaUser
  transactions
    TInit :begin;
    TMain :1;
    TEnd :end;

dclfunc
  function JUnit4Before
  begin
    // @Before
    JavaCallMethod(ghTestObj, "myBefore", "myBefore");
  end JUnit4Before;

  function JUnit4After
  begin
    // @After
    JavaCallMethod(ghTestObj, "myAfter", "myAfter");
  end JUnit4After;

  function JUnit4CallFunc(hJavaObj :number; sName :string; sTimerName :string optional; sExceptionBuffer :string optional) : boolean
  begin
    JUnit4Before();
    // @Test
    JUnit4CallFunc := JavaCallMethod(hJavaObj, sName, sTimerName);
    if not StrIsNull(sExceptionBuffer) then
      JavaGetLastException(hJavaObj, sExceptionBuffer);
    end;
    JUnit4After();
  end JUnit4CallFunc;

dcltrans
  transaction TInit
  var
    hPerf : number;
  begin
    JavaCreateJavaVM();
    ghTestObj := JavaLoadObject("JU4ImporterTest", "JU4ImporterTest.<init>");
    // @BeforeClass
    JavaCallMethod(JAVA_STATIC_METHOD, "JU4ImporterTest.myBeforeClass", "myBeforeClass");
  end TInit;

  transaction TMain
  var
    sBuffer :string;
  begin
    JUnit4CallFunc(ghTestObj, "doFoo", "doFoo");
    JUnit4CallFunc(ghTestObj, "doFoo2", "doFoo2");
  end TMain;

  transaction TEnd
  var
    sBuffer :string;
  begin
    // @AfterClass
    JavaCallMethod(JAVA_STATIC_METHOD, "JU4ImporterTest.myAfterClass", "myAfterClass");
    JavaFreeObject(ghTestObj);
  end TEnd;

In the dclfunc section, the helper functions for test setup, teardown, and exception handling are defined. These functions are used in the transactions.

JavaLoadObject in the TInit transaction instantiates the JUnit test class JU4ImporterTest. All JUnit methods that use the @BeforeClass annotation are called in the TInit transaction.

JUnit4CallFunc in the TMain transaction calls all the test methods that were selected for the JUnit test import. First, the methods that use the @Before annotation are invoked, and then the test method itself, such as doFoo(), is invoked. Finally, the methods that use the @After annotation are invoked.

Timers

When an optional timer parameter is specified for a Java method call, the execution times of the constructor, test method, setup method, and teardown method are measured. For the example in this topic, you receive the following measures:

  • Constructor – JU4ImporterTest.<init>
  • For the methods – doFoo, doFoo2
  • For the test setup – myBeforeClass, myBefore
  • For the test teardown – myAfterClass, myAfter
Parent topic: JUnit Integration


Example BDL Script for JUnit

Script Example

The following sample script is generated by importing a sample JUnit test case.

var
  hTestClass : number;

dcltrans
  transaction TInit
  begin
      // Load and start the JVM.
      JavaCreateJavaVM();

      // instantiate the java class
      hTestClass := JUnitLoadClass("com/microfocus/Test");
  end TInit;

  transaction THello
  begin
    JUnitExecuteTest(hTestClass, "doHello", "doHello_timer");
    JUnitExecuteTest(hTestClass, "", "Test_timer");
  end THello;

  transaction TEnd
  begin
    JavaFreeObject(hTestClass);
  end TEnd;
  • JUnitLoadClass in the TInit transaction instantiates the Java object and returns a handle of the runtime class. The handle is assigned to hTestClass.
  • JavaFreeObject in the TEnd transaction releases the Java runtime class.
  • JUnitExecuteTest in the THello transaction starts the JUnit test execution.
Parent topic: JUnit Integration


Exception Handling for JUnit 4.x and newer

JUnit 4.x and newer versions allow the definition of methods that throw exceptions. Throwing such exceptions is validated by JUnit. Silk Performer imports JUnit methods that throw exceptions including the validation of the thrown message.
//@Test(expected=java.lang.IllegalArgumentException)
    JavaRegisterException(500,"java.lang.IllegalArgumentException", JAVA_OPTION_MATCH_SUBSTRING);
    ErrorAdd(FACILITY_NATIVE_JAVA, 500, SEVERITY_INFORMATIONAL);
    JUnit4CallFunc(ghTestObj, "doFoo", "doFoo", sBuffer);
    ErrorRemove(FACILITY_NATIVE_JAVA, 500);
    if (StrSearch(sBuffer, "java.lang.IllegalArgumentException", STR_SEARCH_FIRST) = 0) then
          RepMessage("method did not throw: java.lang.IllegalArgumentException", SEVERITY_ERROR);
    end;

The sample above tests a JUnit method that is expected to throw a java.lang.IllegalArgumentException. The function JavaRegisterException assigns the BDL error code 500 to the exception. The function ErrorAdd sets the error severity to informational because the error is expected. After that, the JUnit method doFoo is invoked, where the parameter sBuffer retrieves the error message. The ErrorRemove function sets the error handling back to its original state. It also verifies that the expected exception occurred, and throws a BDL error if this is not the case.

Note: When modifying the BDL script manually, make sure that you do not map a Java exception to different BDL error numbers, or vice versa.
Parent topic: JUnit Integration


Importing a JUnit Test Suite

Modify your Java profile settings accordingly before importing JUnit 4.x module tests.

  1. Select Project > Import Unit Test > JUnit Test Class . The Import Unit Test - JUnit Test Class dialog opens.
  2. Cick the Advanced Settings button (the funnel icon above the Methods area). The Advanced Settings dialog opens.
  3. Perform the following steps:
    1. Uncheck the Unit Test Functions Only check box.
    2. Check the Declared Functions Only check box.
    3. Uncheck the Member Functions Only check box.
    4. Click OK.
  4. In the File field, specify the archive that is to be tested. The archive is automatically added to the profile classpath. The available classes are then retrieved and displayed, sorted alphabetically in the Class field.
  5. From the Class list, select one of the available classes for testing.
    When you do not specify a specific archive for testing, the wizard enables you to specify a class that is available in the profile classpath. Type the fully qualified class name into the Class field, for example java.lang.String. The available constructors and methods are automatically retrieved and displayed.
  6. From the Constructor list, select the appropriate constructor for instantiating the imported class. If a constructor is not selected (entry <No Instance Required – Only Static Calls>), only static methods will be displayed in the method list.
  7. In the Methods area, select the suite() method, then click OK.
Parent topic: JUnit Integration


Executing a JUnit Test Suite

When JUnit Import Tool ( Project > Import Unit Test > JUnit Test Class ) script code is used to invoke a method that has a return value, the code used to retrieve the return value is scripted, but commented out.

If a Java method returns a junit.framework.Test method, additional commented-out code is scripted, which allows the FRunTestSuite function from junit.bdh to execute the test suite. junit.bdh is automatically added to the include section of the BDL script.

Uncomment the code for retrieving the return value. For example:
transaction TMain
begin
  // junit.framework.Test suite()
  JavaCallMethod(JAVA_STATIC_METHOD, "JU4ImporterTestSimple.suite", "suite");
  // hObj := JavaGetObject(JAVA_STATIC_METHOD);
  // use the following function to execute JUnit test suites
  // FRunTestSuite(hObj);
  // JavaFreeObject(hObj);
end TMain;

Parent topic: JUnit Integration


Java RMI Support

This section explains Silk Performer's support for the record and replay of Java Remote Method Invocation (Java RMI) applications, including project setup and Java configuration issues. It also shows usage of Product Manager, which is the sample Java RMI application that ships with Silk Performer.

Java Remote Method Invocation (Java RMI) enables the programmer to create distributed Java technology-based applications, in which the methods of remote Java objects can be invoked from other Java virtual machines.

  • Creating Java RMI Projects
    To record and replay a Java RMI application you must set up a project with the appropriate Java RMI application type.
  • Configuring Java RMI Recording Profiles
    Before recording a Java RMI application, you must set up a Web-based recording profile.
  • Configuring Java Profile Settings for the IBM JVM
    Before recording a Java Virtual Machine (JVM), you must define the Java settings and provide a customized startup file.
  • Recording Java RMI Applications
    Record your Java RMI application like a standard Web application.
  • Java RMI Recording Results
    Describes the results of a recorded Java RMI application.
  • Replaying a Java RMI Application
    Replay a recorded Java RMI application.
  • Java RMI Sample Application
    Shows how to use the sample RMI application that ships with Silk Performer.
Parent topic: Java Support


Creating Java RMI Projects

  1. Click Start here on the Silk Performer workflow bar.
    Note: If another project is already open, choose File > New Project from the menu bar and confirm that you want to close your currently open project.
    The Workflow - Outline Project dialog box opens.
  2. In the Name text box, enter a name for your project.
  3. Enter an optional project description in Description.
  4. In the Type menu tree, select Java > Java RMI/EJB (recording).
  5. Click Next to create a project based on your settings.
The Workflow - Model Script dialog box appears.
Parent topic: Java RMI Support


Configuring Java RMI Recording Profiles

  1. From the Silk Performer menu bar, choose Settings > Active Profile.
  2. Click Java and configure Java version, classpath settings, and classpath elements. The recorder uses the JDK internally and the Silk Performer Java Framework uses the JDK for replay.

    In the Version list box, select a JDK version that is later than version 1.2.

  3. In the Silk Performer menu, click Settings > System .
  4. Click the Recorder icon. The Recording Profiles page opens.
  5. Click Add to define a recording profile for the application that you want to record. The Recording Profile dialog box opens.
  6. Type a name for the new recording profile in the Profile name text box.
  7. Type the full path to the executable or startup script, that starts your Java RMI client, in the Application path text box. Specify the working directory, followed by a path separator. Or browse for the executable, in which case the working directory is inserted automatically.
  8. Optional: If the executable that hosts the Java Virtual Machine (JVM) is located in another directory than the application, check the Record executable is different from application path check box. In the Record executable list box, select the executable.
  9. In the Protocol selection area, check the Java APIs that you want to record in the Java API list box.
  10. Click OK to close the Recording Profile dialog box.
  11. Click OK to close the System Settings dialog box.
Parent topic: Java RMI Support
Related tasks
Configuring Java Version and Classpath Settings


Configuring Java Profile Settings for the IBM JVM

  1. In the Silk Performer menu, click Settings > System .
  2. Click the Recorder icon. The Recording Profiles page opens.
  3. In the Application list, select the listed recording profile and click Edit. The Recording Profile dialog box opens.
  4. Click Java Settings and select the Manual option button.
  5. Click OK to close the Java Settings dialog box.
  6. Customize the startup script.
    1. Open the startup-script file, for example startMyApp.cmd, in an editor.
    2. Rename the startup-script file, for example to startMyAppForRecording.cmd.
    3. Insert a call to perfPrepareJavaRecording.cmd in the Silk Performer home directory. For example call C:\Program Files\Silk\Silk Performer 21.0\perfPrepareJavaRecording.cmd.
    4. In the startup-script file, replace java my.rmi.application <parameters> with java %PERFREC_OPTIONS% my.rmi.application <parameters>, where my.rmi.application is an example. Thus you add the command-line parameter %PERFREC_OPTIONS% to the java execution.
Parent topic: Java RMI Support


Recording Java RMI Applications

Record your Java RMI application like a standard Web application.

Important: When you record applets, use a JVM by Sun Microsystems instead of one provided by Microsoft.
  1. Click Model Script on the workflow bar. The Workflow - Model Script dialog box appears.
  2. In the Recording Profile list box, select the profile for the application that you plan to test, for example My Rmi Application. If a profile has not yet been set up for the application you want to use, click Settings to the right of the list box to set one up.
  3. Click Start recording to begin recording the session.
  4. Perform the required interactions with the application under test.
  5. When recording is complete, close the application, close the recorder, and save the test script.
  6. To confirm that your test script runs as expected, execute a Try Script run in animated mode; you will then be able to view the results of the test run in TrueLog Explorer.
Parent topic: Java RMI Support


Java RMI Recording Results

When you record a Java RMI application, Silk Performer generates two result files, x.java and x.bdf.

The Java source file x.java contains the recorded actions. This file is compiled automatically from within Silk Performer. You have to specify the classpath needed to compile this file in Settings > Active Profile > Java.

The file x.bdf contains the BDL stub code that launches the Java virtual user.

Parent topic: Java RMI Support


Replaying a Java RMI Application

  1. Remove the recorded API calls JavaSetOption(JAVA_CLASSPATH) and JavaSetOption(JAVA_CMDLINE_OPTIONS) from the BDL script.
  2. Obtain the JAR and CLASS files from the server. Use the recorded comments in the recorded Java source code to find the JAR and CLASS files.

    The comments look as described in the following example.

    // ###ClassPath###
// ###Applet CodeBase###
// ###Applet parameters queried by the Applet###
  // codebase=...
  // archives=...
  // code=...
  3. Copy these files to your local machine.
  4. Add the path to these files to the classpaths in Settings > System > Java.
Parent topic: Java RMI Support


Java RMI Sample Application

The sample application that ships with Silk Performer to demonstrate how to record and replay Java RMI applications is called Product Manager.

To launch Product Manager, navigate to <public user documents>\Silk Performer 21.0\SampleApps\RMILdap\Web, and click ProductManager - DemoVersion.htm.

  • Recording and Replaying the Sample Application
    Demonstrates how to record and replay a Java RMI application.
  • Modifying the Internet Explorer Profile
    Modify the Internet Explorer profile to record the sample application.
Parent topic: Java RMI Support


Recording and Replaying the Sample Application

  1. Create a new Java RMI project.
  2. Modify the existing Internet Explorer recording profile. See Modifying the Internet Explorer Profile.
  3. Specify the script generation details in Settings > Active Profile > Record > Script > Java.
  4. Go to Settings > Active Profile > Record > Java, and add the JAR file ProductManager.jar from the Silk Performer samples directory, <public user documents>\Silk Performer 21.0\SampleApps\RMILdap\Web\ProductManager.jar, to the classpath.
  5. Start the RMI and LDAP servers. To start the servers, open the Product Manager sample HTML page, <public user documents>\Silk Performer 21.0\SampleApps\RMILdap\readme.htm, and follow the instructions in the Starting up servers section.
  6. Click Model Script in the workflow bar.
  7. Type the location of the RMI sample-application HTML page in the Command line text box. The default path of the HTML page is <public user documents>\Silk Performer 21.0\SampleApps\RMILdap\Web\ProductManager - DemoVersion.htm.
  8. Click OK to launch the applet. The applet loads and the recorder starts to record the JNDI and RMI activities of the applet. You can now perform searches for products, change products, add new products, and so on.
  9. Click OK when you have performed all the desired actions. The Save As dialog box opens.
  10. Specify a valid Java identifier for the script name and click Save to save the recorded script.
  11. Click Yes twice to close the recorder and to confirm the closing.
  12. Comment out or delete the recorded API calls JavaSetOption(JAVA_CLASSPATH, ... and JavaSetOption(JAVA_CMDLINE_OPTIONS, ....
You can now replay the recorded script. Click Try Script on the workflow bar for a try run of the script.
Parent topic: Java RMI Sample Application
Related tasks
Creating Java RMI Projects
Modifying the Internet Explorer Profile


Modifying the Internet Explorer Profile

  1. Click Model Script on the Silk Performer workflow bar.
  2. Click Settings next to the Recording Profile list box.
  3. Select Internet Explorer from the recording profiles.
  4. Click Edit.
  5. Uncheck the Web check box.
  6. Check the Java RMI and Java JNDI check boxes. This sample uses the Java Naming and Directory Interface (JNDI) for the bootstrapping of remote object references.
Parent topic: Java RMI Sample Application


Eclipse Plug-In

Silk Performer is packaged with a plug-in for Eclipse, the popular Java IDE that is based on plug-in technology. The plug-in enables Eclipse users to be supported with Silk Performer load testing features.

The structure of the Silk Performer test class supports Java developers in creating test cases for Silk Performer. The test class implements the ITestClass interface that is packaged with the Eclipse plug-in. It contains a Silk Performer object that represents the interface to Silk Performer’s Java Framework.

The test class includes two basic methods:

  • testInit - This method initializes the interface. It is called at the beginning of test runs.
  • testEnd - This method closes the interface. It is called at the end of Try Script runs and load tests.

Between testInit and testEnd there may be one or more test methods invoked by a running load test. Each method that has a signature void testXY() throws Silk Performer Exception.

Example:

public void testMyMethod() throws
 silk.performer.SilkPerformerException

Using the JavaSetOption BDL Function

For debugging Java framework projects, some debug parameters must be set as command line arguments. This is done by the Eclipse plug-in automatically when you run a Try Script.

In most cases, running and debugging Try Script tests without modifications is possible. However, when you override the default value of a JVM option in a BDL script using JavaSetOption, additional configuration is required to enable debugging in Eclipse.

You must also define an Eclipse debug Remote Java application configuration. After these options are set, you can then launch a Try Script run. Afterwards, you must start the Eclipse debug configuration to start a debugging session.

  • Eclipse Project Restrictions
    Describes the restrictions on concurrent use of Eclipse and Silk Performer.
  • Installing the Eclipse Plug-In
    Install the Eclipse plug-in to use Silk Performer with Eclipse.
  • Configuring Eclipse Plug-In Settings
    Configure the settings for default project name, test class name, Java debugger timeout, shutdown after finish delay, log level, installed JREs, and Java runtime profiles.
  • Projects
    Explains how to set up and work with Silk Performer projects in Eclipse.
  • Try Script Runs
    Describes how to configure and execute try script runs for test classes.
  • Results
    Describes the types of results that you can view after a test or Try Script run.
Parent topic: Java Support


Eclipse Project Restrictions

There are restrictions on concurrent use of Eclipse and Silk Performer. Projects are locked from use by Eclipse while Silk Performer works on them. If you attempt to open a project from Eclipse that is currently in use by Silk Performer, you will receive an error message. You must close Silk Performer to pass project control back to Eclipse.

Parent topic: Eclipse Plug-In


Eclipse Plug-In does not work on Microsoft Windows 8 and Microsoft Windows Server 2012

Problem:

The Silk Performer Eclipse Plug-In does not work on Microsoft Windows 8 and Microsoft Windows Server 2012

.

Resolution:

On Microsoft Windows 8 and Microsoft Windows Server 2012, run Eclipse in compatibility mode. To do this, perform the following steps:
  1. Right-click eclipse.exe and select Properties.
  2. On the Properties dialog box, select the Compatibility tab.
  3. In the Compatibility mode section, check Run this program in compatibility mode for: and select Windows 7.
Parent topic: Installing the Eclipse Plug-In


Configuring Eclipse Plug-In Settings

  1. In Eclipse, select Window > Preferences . The Preferences dialog opens.
  2. Select the Silk Performer node on the menu tree to display Silk Performer settings.
  3. Confirm that the installation directory of your Silk Performer installation is listed in the Install directory text box. If it is not listed, click Browse to browse for and select your Silk Performer installation directory.
  4. Edit the Default project name as required.
  5. Edit the Default test class name as required.
  6. (experienced users only) Edit the default Timeout for connecting to Java debugger setting as required. This is the amount of time allowed (in milliseconds) for connecting to a Silk Performer process during tests.
  7. (experienced users only) Edit the default Shutdown after finish delay setting as required. This is the amount of time (in milliseconds) that Eclipse waits before retrieving results after the completion of Silk Performer tests.
  8. Select a Log level to specify when logs are to be written. Selecting None results in no log files being written. Selecting Errors results in log files being written only when errors are encountered. Selecting Debug results in all activity being logged.
  9. In the menu tree, expand Java and select the Installed JREs node. The Installed JREs page opens and lists the Java runtimes that are used by Eclipse on your local system.
  10. Confirm the Location and Type settings for your Java runtime environment.
  11. To add a Java runtime profile, perform the following steps:
    1. Click the Add button. The Add/Edit JRE dialog opens.
    2. Click [...] to browse to and select the directory that contains your JDK installation (specifically, your Java compiler), then click OK. The fields on the Add/Edit JRE dialog are automatically populated with values derived from your JDK installation.
      Note: You must select a JDK (version 1.5 or higher), rather than a JRE, because Silk Performer attempts to recompile Java files in its test classes.
    3. Click Finish to save your settings.
  12. To edit an existing Java runtime profile, perform the following steps:
    1. Click the Edit button. The Add/Edit JRE dialog opens.
    2. Click [...] to browse to and select the directory that contains your JDK installation (specifically, your Java compiler), then click OK. The fields on the Add/Edit JRE dialog are automatically populated with values derived from your JDK installation.
      Note: You must select a JDK (version 1.5 or higher), rather than a JRE, because Silk Performer attempts to recompile Java files in its test classes.
    3. Click Finish to save your settings.
  13. On the Installed JREs page, click OK to save your settings.
Parent topic: Eclipse Plug-In


Projects

  • Setting Up a New Eclipse Project
    Create an Eclipse project that links the Eclipse project to your Silk Performer project.
  • Importing Projects
    Describes the differences between creating a project with Silk Performer Eclipse Plug-In and importing a project from Silk Performer or Silk Performer Java Explorer.
  • Importing a Silk Performer Project into Eclipse
    Import the selected project, settings, and classpaths into your Eclipse workspace.
  • Customizing a Silk Performer Project to Use the Required Eclipse Notation
    Customize a Silk Performer Java Framework project that has been created with Silk Performer or Silk Performer Java Explorer manually so that it fulfills the required Eclipse notation used by the Silk Performer Eclipse Plug-In.
  • Configuring Silk Performer Project Properties from Eclipse
    Define project attributes for the project including Name, value Type, Value, Default value, and Description.
  • Configuring Silk Performer System Settings in Eclipse
    Define system settings for your project.
  • Configuring Silk Performer Project Settings in Eclipse
    The project settings that you define in Eclipse overrule the settings defined in Silk Performer.
  • Redirecting Java Build Paths
    From the moment that Silk Performer projects are controlled from Eclipse, the classpaths of projects are controlled from the Eclipse environment. For this reason you may want to adjust the Java build path of your Eclipse projects.
  • Adding a Silk Performer Test Class to an Eclipse Project
    Generate multiple Java classes for the testing of Silk Performer-enabled Eclipse projects.
Parent topic: Eclipse Plug-In


Setting Up a New Eclipse Project

  1. Within a Silk Performer-enabled Eclipse workbench, select File > New > Project . The New Project wizard opens.
  2. Expand the Silk Performer node in the menu tree.
  3. Select the Java Project node and then click Next. The New SilkPerformer load testing capable Java project page opens.
  4. Edit the name of your new project as required.
  5. Edit the Test class name (the name of the initial test class template) as required.
  6. Click Finish. The plug-in generates the test class template in your Eclipse workspace and links the test classes to a test case in your Silk Performer project.
A class path links the new test class into Silk Performer’s workspace so that it works with both the Eclipse editor and Silk Performer. Behind each test class is BDF stub code. This code is generated each time a test class is compiled, so any changes you make to BDF stub code will be overwritten the next time the test class is compiled.
Parent topic: Projects


Importing Projects

Another way of linking your Eclipse and Silk Performer workspaces is to import an existing Silk Performer project into your Eclipse workspace.

A Silk Performer Java Framework project that has been created using the Silk Performer Eclipse Plug-In fulfills the required Eclipse notation, used by Eclipse Plug-In projects. A Silk Performer Java Framework project that has been created with Silk Performer or Silk Performer Java Explorer does not fulfill the required Eclipse notation.

When importing a Silk Performer Java Framework project into Eclipse, the result differs as follows:
Project created with Silk Performer Eclipse Plug-In | Project created with Silk Performer or Silk Performer Java Explorer
Running and debugging try script tests without modifications is possible | Limited execution and debugging functionality available
Automatic bdf stubfile generation for changes to the test class or test methods | No automatic bdf stubfile generation
New test methods can be added to project | No introduction of new test methods possible
Changing existing test class and test method names is possible | Changing existing test class and test method names is not possible
Note: Modifications to Java test code are possible for either imported project type.

Before you can import a Silk Performer Java Framework project that has been created with Silk Performer or Silk Performer Java Explorer into Eclipse, the test class must have the same name as the bdf file, for example TestClass.java and TestClass.bdf.

Tip: Java Explorer allows you to specify the test class and the script file name. Refer to Silk Performer Java Explorer Help for detailed information.

You can customize a Silk Performer Java Framework project that has been created with Silk Performer or Silk Performer Java Explorer manually so that it fulfills the required Eclipse notation used by the Silk Performer Eclipse Plug-In.

Parent topic: Projects


Importing a Silk Performer Project into Eclipse

  1. Select File > Import . The Import dialog box opens.
  2. Expand the Other node in the menu tree.
  3. Select Import Existing Silk Performer Java Project.
  4. Click Next to view all available Silk Performer projects in your Silk Performer projects directory.
  5. Check the check boxes of the projects that you want to import.
  6. Click Finish. The selected project, settings, and classpaths are imported into your Eclipse workspace.
Parent topic: Projects


Customizing a Silk Performer Project to Use the Required Eclipse Notation

Before you begin this task, import your Silk Performer project into Eclipse.

You can customize a Silk Performer Java Framework project that has been created with Silk Performer or Silk Performer Java Explorer manually so that it fulfills the required Eclipse notation used by the Silk Performer Eclipse Plug-In.

  1. Open the test class in Eclipse and modify it according to the following rules:
    1. The test class must implement the silk.performer.ITestClass interface.
    2. The method for test initialization must be named testInit and take a single parameter of type Silk Performer.
    3. The method for test finalization must be named testEnd.
    4. All test methods must start with the prefix test and may not have any parameters.
  2. Save your changes.
Parent topic: Projects


Configuring Silk Performer Project Properties from Eclipse

  1. In Eclipse, select Project > Properties .
  2. Select the Silk Performer Project Properties node in the menu tree. At the top of the Silk Performer Project Properties dialog box, the path to the targeted Silk Performer project is displayed.
  3. If required, edit the Name that has been specified for the project when opened in Silk Performer.
  4. Edit the Description that has been defined for the project, as required.
  5. You can define Silk Performer project attributes for the project (Name, value Type, Value, Default value, Description). See Project Attributes for full details regarding configuring Silk Performer project settings.
  6. Click Apply to apply your changes.
  7. Click OK.
    Note: Silk Performer project attributes can also be accessed directly by selecting Project Attributes from Eclipse’s Silk Performer menu.
Parent topic: Projects
Related concepts
Project Attributes


Configuring Silk Performer System Settings in Eclipse

  1. In Eclipse, select Silk Performer 21.0 > System Settings .
  2. Set the configuration options as needed.
  3. Click OK to save your changes.
Parent topic: Projects
Related tasks
System Settings


Configuring Silk Performer Project Settings in Eclipse

Note: When Eclipse controls a Silk Performer project, all Java settings defined in Silk Performer are overruled by the settings you defined in Eclipse.
  1. In Eclipse select Silk Performer 21.0 > Profile Settings . You will be directed to the General page for your project profile Java settings, where you can view the Java home and classpaths that have been set up for your newly created project.
  2. Set the profile options as needed.
  3. Click OK to save your changes.
Parent topic: Projects
Related concepts
Project Profile Settings


Redirecting Java Build Paths

There are restrictions for classpaths of Eclipse projects that are used within Silk Performer. To enable the distribution of libraries during a test, all libraries must be located either in the Silk Performer project directory (<my documents>\Silk Performer 21.0\Projects) or they must be available on a UNC path.

  1. Right-click a Silk Performer-enabled project in Eclipse’s Package Explorer and select Build Path > Configure Build Path from the context menu.
  2. Click the Libraries tab. All of the user libraries that are required for running tests are displayed.
  3. Click Add Library. The Add Library page opens.
  4. Select User Library from the list and click Next.
  5. Click User Libraries. The User Libraries page opens.
  6. Click New. The New User Library dialog opens.
  7. Specify a name for the new library and click OK. The User Libraries page opens.
  8. Click Add JARs.
  9. Browse to and select one or more Java libraries that are available to your local system. Press the Shift or Ctrl keys to select multiple libraries.
  10. Click Open to add the JAR files to your new user library. The User Libraries page opens.
  11. Click OK. The Add Library page opens.
  12. Click Finish. These settings are migrated to the classpaths of both your Silk Performer Workbench project and your Silk Performer-enabled Eclipse project.
Parent topic: Projects


Adding a Silk Performer Test Class to an Eclipse Project

You can generate multiple Java classes for the testing of Silk Performer-enabled Eclipse projects.

Note: Silk Performer can handle user-defined JAR libraries. It can only launch classes that are within the root package of Java projects within Silk Performer. Only external libraries such as JARs can be used.
  1. In the Eclipse SDK, choose File > New > Other . The New dialog box opens.
  2. Choose Silk Performer > Silk Performer Test Class from the menu tree and then click Next. The New Silk Performer Test Class dialog box opens.
  3. Edit the Project name and Test class values as required.
  4. Click [...]. The Silk Performer Enabled Projects dialog box opens.
  5. Select the Silk Performer-enabled Eclipse project to which you want to append this new test class template and then click OK.
  6. Click Finish. The test class template is appended to your Eclipse project.
Parent topic: Projects


Try Script Runs

  • Executing Try Script Runs for Test Classes
    Perform a Try Script run to determine if your test class generates errors or leads to a failed test.
  • Defining a Launch Configuration for Silk Performer Try Scripts
    Associate a project with a launch configuration.
  • Running Baseline Tests
    Pass your test project from Eclipse to Silk Performer to run a baseline test.
Parent topic: Eclipse Plug-In


Executing Try Script Runs for Test Classes

  1. In Eclipse’s Package Explorer menu tree, select the test class for which you want to run a Try Script.
  2. Select Silk Performer 21.0 > Try Script . Eclipse automatically switches to the Debug perspective and initiates a Try Script run. The bottom pane of the Debug page includes Silk Performer views that monitor the status of the test.
  3. If your test class generates errors or leads to a failed test, edit your test class in the Eclipse Editor.
  4. If your Try Script run is successful, you can view the results of the test in the Silk Performer log files and result files, including TrueLog files.
Parent topic: Try Script Runs
Related concepts
Results


Defining a Launch Configuration for Silk Performer Try Scripts

  1. In Eclipse main toolbar, select Run > Debug Configurations . The Debug Configurations dialog opens.
  2. Select the Silk Performer Try Script node in the menu tree.
  3. Click the New button on the toolbar. The Create, manage, and run configurations page opens and the currently active Silk Performer project and its first test class are pre-selected.
  4. Click [...] next to the Project box. The Silk Performer Enabled Projects dialog opens.
  5. Select the Silk Performer-enabled project that you want to associate with this launch configuration.
  6. Click OK.
  7. Select the Test class that you want to launch with this launch configuration.
  8. (optional) Edit the parameters of any pre-defined project attributes in the Project Attributes section of the page.
  9. Click Apply to apply your changes.
  10. Click Debug to run a Try Script run based on your launch configuration settings.
Parent topic: Try Script Runs


Running Baseline Tests

Once you are satisfied with the Try Script results generated by your TestClass, it is time to pass your test project from Eclipse to Silk Performer and run a baseline test.

  1. In Eclipse, select Silk Performer 21.0 > Open in Silk Performer . Silk Performer workbench launches with your Eclipse project loaded in the Project menu tree. All TestClasses are appended to the project under the Scripts node.
  2. Define and run a baseline test.
Parent topic: Try Script Runs


Results

Following a successful test or Try Script run, you can choose to view a Virtual User Report file, a Virtual User Log file, a Virtual User Output file, a Virtual User Error File, or a TrueLog.

  • Viewing Virtual User Reports
    Display the virtual user report in Eclipse’s Silk Performer Report File Viewer tab.
  • Viewing Virtual User Log Files
    Display the log file for the most recent test run.
  • Viewing Virtual User Output Files
    Display the output file of the TestClass code for the most recent test run.
  • Viewing Virtual User Error Files
    Display the error file for the most recent test run.
  • Viewing TrueLogs
    Display the TrueLog file of the most recent Try Script run to analyze the test results.
Parent topic: Eclipse Plug-In
Related tasks
Executing Try Script Runs for Test Classes


Viewing Virtual User Reports

In Eclipse, select Silk Performer 21.0 > Virtual User Report File .

The report is then displayed in Eclipse’s Silk Performer Report File Viewer tab. This view displays virtual-user status messages that are passed from the latest Try Script test.

Parent topic: Results


Viewing Virtual User Log Files

In Eclipse, select Silk Performer 21.0 > Virtual User Log File .

The log file of the most recent test run is displayed.

Parent topic: Results


Viewing Virtual User Output Files

In Eclipse, select Silk Performer 21.0 > Virtual User Output File .

The output file of the TestClass code for the most recent test run is displayed.

Parent topic: Results


Viewing Virtual User Error Files

In Eclipse, select Silk Performer 21.0 > Virtual User Error File .

The error file of the most recent test run is displayed.

Parent topic: Results


Viewing TrueLogs

In Eclipse, select Silk Performer 21.0 > Show TrueLog . The TrueLog file of the most recent Try Script run is then displayed in TrueLog Explorer.
Parent topic: Results
Related concepts
Understanding TrueLog


Silk Performer Java Explorer

Silk Performer Java Explorer, which was developed using Java, and the Silk Performer Java Framework allow you to test Web Services, Enterprise JavaBeans (EJB), RMI objects, and other GUI-less Java objects. Java Explorer allows you to define and execute complete test scenarios with different test cases without requiring manual programming because tasks are completed visually by way of mouse-based operations. Test scripts are visual and easy to understand, even for individuals who are unfamiliar with Java programming languages.

Test scenarios created with Java Explorer can be exported to Silk Performer for immediate reuse in concurrency and load testing.

Note: Java Explorer is compatible only with JDK versions 1.2 and higher (v1.4 or higher is recommended).

For information about Java, visit the following Web sites:

  • http://java.sun.com
  • http://www.javaworld.com
  • http://www-106.ibm.com/developerworks/java/
  • Starting Silk Performer Java Explorer
    Launch Java Explorer to define and execute complete test scenarios with different test cases without requiring manual programming.
Parent topic: Java Support


Starting Silk Performer Java Explorer

Perform one of the following steps to launch Java Explorer:
  • Click Start > All Programs > Silk > Silk Performer 21.0 > Development Tools > Silk Performer Java Explorer .
  • Click Start > All Programs > Silk > Silk Performer 21.0 > Silk Performer Workbench and create a new project with the Java/Java Explorer or Web Services/Java Explorer application type.
Parent topic: Silk Performer Java Explorer
Related concepts
Java Explorer Help


OnWeb Mainframe-to-Web Testing Support

Silk Performer supports the testing of Micro Focus OnWeb Web-based applications that interact with mainframe systems. OnWeb Web-based applications can easily be tested using standard Silk Performer Web-application recording, scripting, and playback features. When creating a script to test an OnWeb application, choose Web business transaction (HTML/HTTP) as the application type to be recorded. Beyond that, the testing of Micro Focus OnWeb Web-based applications is identical to that of standard Web applications. Silk Performer automatically handles any dynamic values that need to be parameterized. Additionally, using .NET Explorer and Java Explorer, OnWeb Web services can be tested in the same way that standard SOAP Web services are tested.

About Micro Focus OnWeb

Micro Focus OnWeb offers a comprehensive development and deployment platform that transforms your host applications into Web applications. OnWeb aggregates and composes data from multiple screens across multiple host systems and presents them as Web pages.

OnWeb® and its wide array of application connectors can help you bring together both host systems and enterprise applications to create standards-based Web-enabled composite applications, leveraging your existing IT investment and helping you move towards a service-oriented architecture (SOA).

Parent topic: Load Testing Specific Application Types


Oracle Forms / Oracle Applications Support

This section explains how to use Silk Performer to run load tests against Oracle Forms and Oracle Applications. It briefly outlines possible server configurations and discusses how they can be tested. It also provides guidelines for customizing scripts, including verification functions.

  • Basic Concepts
    Explains Silk Performer's support for testing Oracle Forms and Oracle Applications.
  • Installation and Requirements
    Explains the configuration requirements for setting up Oracle client and server software.
  • Managing Oracle Forms/Oracle Applications Load Tests
    Lists the tasks that must be completed to prepare for, run, and analyze the results of an Oracle Forms/Oracle Applications load test.
  • Recording Concepts
    Explains how Oracle Forms applications are recorded by Silk Performer.
  • Oracle Forms / Oracle Applications TrueLogs
    Explains how TrueLog Explorer can be used to explore the results of Oracle Forms / Oracle Applications tests and how to visually customize your scripts.
  • Replay Concepts
    Explains how Silk Performer drives Oracle Forms clients during replay.
  • Oracle Forms Performance Monitoring
    Explains that Performance Explorer is used to retrieve performance metrics from Oracle Forms Dynamic Monitoring System (DMS).
  • Root Cause Analysis
    Explains how errors can be analyzed using the log files.
  • Tips and Tricks
    Explains issues that need to be considered when testing Oracle Forms applications with Silk Performer.
Parent topic: Load Testing Specific Application Types


Basic Concepts

This section explains Silk Performer's support for testing Oracle Forms and Oracle Applications, including a technology overview, project setup, and configuration issues.

The following versions are supported:
  • Oracle Forms 6i, 9i, 10g, 11g, 12c
  • Oracle EBS 11i, 12.x
  • Oracle Fusion 10g, 11g, 12c
  • Architecture
    Provides an introduction to the architecture of Oracle Web Forms.
  • Oracle Forms Client Types
    Explains the differences between the available versions of Oracle Forms client types and which JVM they use.
  • Oracle Forms/Oracle Applications Versions
    Lists the supported Oracle client versions and which Java version they use.
Parent topic: Oracle Forms / Oracle Applications Support


Architecture

Oracle Web Forms allows you to run your existing Oracle Forms applications in a browser. In previous versions, the user interface and complete client/business logic where executed on the client machine in the Oracle Forms runtime. The move to Web technology split these components: There is still an Oracle Forms runtime that performs the client/business logic on an application server. However, the runtime has been separated from the user interface by sending/ receiving user interface actions to an applet that runs in a browser.

The following illustration offers a basic overview of the architecture:

Oracle Forms Architecture

When a client connects to an Oracle Forms server a HTTP-listener process returns the initial HTML page that contains information regarding the hosting of the applet. If a Java Virtual Machine (JVM) has not yet been installed, this page redirects your browser to download a JVM.

The applet connects to a listener process during initialization. This listener spawns a new process that hosts the runtime engine for the client. The client applet and the runtime engine then have a direct connection, via HTTP, HTTPS, or Socket mode.

Note: Socket mode is not available for Oracle Forms 6i patch 4, 10g, 11g, and 12c.

Oracle Forms 9i has introduced a test interface that can be used to retrieve all messages during recording and send those messages to the server during replay.

Parent topic: Basic Concepts


Oracle Forms Client Types

The Oracle Forms Web client is a Java applet hosted within a browser. Oracle Forms 11g or later uses the standard Java Virtual Machine (JVM), while for version 10g or earlier, Oracle provides its own JVM, which is called JInitiator.

A JVM or JInitiator is installed automatically when you access an Oracle Forms Web application for the first time. There are different versions of JInitiator, where the version numbers reflect the Java Runtime Environment version numbers that are used, for example JInitiator 1.1.8 uses Java Runtime Environment 1.1.8).

For detailed information on Oracle Forms and Oracle Applications, visit the Oracle Technology Network.

Parent topic: Basic Concepts


Oracle Forms/Oracle Applications Versions

There are different versions of Oracle Forms and, depending on the version you use, Silk Performer utilizes different approaches for recording. The following table illustrates the supported Oracle client versions and which Java version they use:
Oracle client version | Java version in Oracle client | Java version in Silk Performer profile settings
Oracle Forms 6 | JInitiator 1.1.x | Java 1.4
Oracle Forms 9i | JInitiator 1.3.x | Java 1.4
Oracle Forms 10g | JInitiator 1.3.x | Java 1.4
Oracle Forms 11g | JVM 1.6 | Java 1.6
Oracle Forms 12c | JVM 1.7 | Java 1.7
Oracle Applications 11i (operates on Oracle Forms 6i) | JInitiator 1.1.x | Java 1.4
Oracle Applications 12i (operates on Oracle Forms 10g) | JVM 1.6 | Java 1.6
Parent topic: Basic Concepts


Installation and Requirements

Oracle Forms applications require a Java Runtime Environment (JRE) on the client side. Silk Performer's record/replay mechanism also requires a JRE to test Oracle Forms applications.

  • Configuring Oracle Forms Client Software
    Explains the necessary Oracle Forms client software configurations.
  • Configuring Oracle Applications Server Software
    Modify the configuration of your Oracle Applications server if Silk Performer Recorder records IDs instead of names.
Parent topic: Oracle Forms / Oracle Applications Support


Configuring Oracle Forms Client Software

Oracle Forms clients run in Web browsers as applets. By default, a Web browser will download and install a JRE when loading an Oracle Forms application for the first time. For Oracle Forms 10g or earlier, Oracle's JRE for Oracle Forms is named JInitiator. Using JInitiator is not mandatory. Once a JRE has been installed, Silk Performer is set up to record Oracle Forms applications.

Parent topic: Installation and Requirements


Configuring Oracle Applications Server Software

Silk Performer Recorder modifies the HTML page hosting the Oracle Forms applet. It will set the parameter record=names so you will get readable names instead of IDs in your script. If this does not work automatically, proceed as follows:
  1. On your Oracle Applications server, locate the file formsweb.cfg and open it with a text editor.
  2. Append the text record=names to this file and save it.
  3. Restart the Oracle Applications server.
Silk Performer is now able to record names instead of IDs.
Parent topic: Installation and Requirements


Managing Oracle Forms/Oracle Applications Load Tests

This section explains the tasks that must be completed to prepare for, run, and analyze the results of an Oracle Forms/Oracle Applications load test.

  1. Outlining Oracle Forms/Oracle Applications Projects
    Create an Oracle Forms/Oracle Applications project before you prepare a test script.
  2. Recording Oracle Forms/Oracle Applications Test Scripts
    Record an Oracle Forms/Oracle Applications test script with Silk Performer Recorder before customizing it.
Parent topic: Oracle Forms / Oracle Applications Support


Outlining Oracle Forms/Oracle Applications Projects

Before you begin testing an Oracle Forms application, ensure the following:
  • The Oracle Forms client can be started on the recording machine.
  • Know which version of Oracle Forms you are testing. Currently supported versions are Oracle Forms 6i, 9i, 10g, 11g, 12c and Oracle EBS 11i, 12.x.
  1. Click Start here on the Silk Performer workflow bar.
    Note: If another project is already open, choose File > New Project from the menu bar and confirm that you want to close your currently open project.
    The Workflow - Outline Project dialog box opens.
  2. In the Name text box, enter a name for your project.
  3. Enter an optional project description in Description.
  4. From the Type menu tree, select the application type that matches your Oracle Forms/Oracle Applications version (Application Server/Component Models > Oracle > Oracle Forms <version>, or ERP/CRM > Oracle > Oracle Applications <version>).
  5. Click Next.
    Note: If you need to add additional resources to the project, right-click the project icon in the Project menu tree view. It is particularly important that all the user data files (.csv), random data files (.rnd), and .idl files needed by Silk Performer are set up for your project.
The Workflow - Model Script dialog box appears.
Parent topic: Managing Oracle Forms/Oracle Applications Load Tests
Next topic: Recording Oracle Forms/Oracle Applications Test Scripts


Recording Oracle Forms/Oracle Applications Test Scripts

Record an Oracle Forms/Oracle Applications test script with Silk Performer Recorder before customizing it.
  1. Click Model Script on the workflow bar. The Workflow - Model Script dialog box appears.
  2. Select the default Oracle Forms recording profile. If you want to modify the settings of a custom recording profile, click Settings.
  3. In the URL text box, enter the URL of your Oracle Forms application.
  4. Click Start recording to begin recording the session.
  5. To see a report of the actions that happen during recording, maximize the Recorder dialog by clicking the Change GUI size button. The maximized Recorder opens at the Actions page.
  6. Using the client application, conduct the kind of interaction with the target server that you want to simulate in your test. The interaction is captured and recorded by the Recorder. A report of your actions and of the data downloaded appears on the Actions page.
  7. Insert transactions and timers into the test script during the recording phase. You can create as many transactions and timers as you want. To insert a transaction, click the New Transaction button. A transaction represents a piece of work that can be assigned to a virtual user.
  8. In the ensuing dialog, enter a name for the transaction and click OK. The new transaction appears in the Actions log.
  9. To insert a timer, click the New Timer Session button. A timer is a user-defined measurement period in a test. You should create timers for each component of a transaction for which you want to analyze performance. In the ensuing dialog, enter a name for the timer and click OK.
  10. To insert a timer, click the New Timer Session button. A timer is a user-defined measurement period in a test. You should create timers for each component of a transaction for which you want to analyze performance. In the ensuing dialog, enter a name for the timer and click OK.
  11. To end recording, click the Stop Recording button.
  12. Enter a name for the .bdf file and save it. The Capture File page displays. Click Generate Script to generate a script out of the capture file.
Parent topic: Managing Oracle Forms/Oracle Applications Load Tests
Previous topic: Outlining Oracle Forms/Oracle Applications Projects


Recording Concepts

Oracle Forms applications are recorded by recording your browser and using a special Java Recording API that captures the messages that are sent between the client and server.

  • Recording Profile Settings
    Explains Oracle Forms/Oracle Applications recording options that can be defined using the Profile Settings dialog.
  • Setting the Oracle Forms Log Level
    Define the log level to display the messages that you need to analyze after recording an Oracle Forms application.
  • Oracle Java Recording API
    Explains how Oracle Forms applications are recorded by Silk Performer.
  • Java Environment Settings
    Define the Java environment settings before recording a script.
  • Files Generated During Recording
    When recording an application, a script, a text log and a TrueLog are generated.
  • Oracle Forms HTTPS Support
    Explains how to add the Silk Performer certificate to your JVM’s truststore database to record an Oracle Forms application over HTTPS.
Parent topic: Oracle Forms / Oracle Applications Support


Recording Profile Settings

When choosing one of the Oracle Forms or Oracle Applications project types in your recording profile settings, a new recording profile is created for your project based on the active browser. You cannot modify the settings for this temporary recording profile. If you want to record using different settings, click Copy to create a custom recording profile based on the selected profile.

Oracle Forms 6 can operate on two different communication channels: HTTP/ HTTPS or Socket mode. When you select Oracle Forms 6, both channels are covered. If you encounter any problems during recording, select the correct Java Recording API in your recording profile (you must first determine which communication channel you are using).

Oracle Applications 12i will detect the communication channel (HTTP/ HTTPS or Socket mode) automatically.

Parent topic: Recording Concepts
Related concepts
Tips and Tricks
Related tasks
Setting Oracle Forms Options


Setting the Oracle Forms Log Level

The log level defines which messages and TrueLogs are captured when recording an Oracle Forms application.
  1. In Silk Performer, expand the Profiles node in the Project tree.
  2. Right-click the profile that you want to configure and choose Edit Profile.
    Tip: Alternatively, you can choose Settings > Active Profile from the menu bar.

    The Profile - [<profile name>] dialog box opens, and the Replay category is displayed in the shortcut list on the left.

  3. Select Record in the shortcut list and click the Oracle Forms icon.
  4. Click the Logging tab. Here you can specify that additional properties have their values logged during recording.
  5. From the Log level list box, select the log level for virtual user logging:
    • None - TrueLogs will be generated, though no Oracle Messages will be logged and no detailed information about controls in the log file will be written.
    • Error - In addition to the None log level, errors that occur during recording are logged.
    • Normal - In addition to the Error log level, Oracle messages are logged to the TrueLog and the log file.
    • Debug - In addition to the Normal log level, detailed information about control messages is logged, for example in the In Body and Out Body tab in TrueLog Explorer. This information is helpful for customizing and debugging your script when comparing it with Try Script runs. This option should also be used when you encounter a problem during replay and you must send your log files to Micro Focus SupportLine for analysis.
    Additional properties to be logged in the TrueLog for each control in your application can also be defined. Such properties are Oracle Forms internal properties that must be defined using their internal names. In most cases you will not need to use this feature, as default properties (name, value) are logged for each control. The OraForms.bdh file contains a complete list of all internal properties, most of which are not used by controls and so will generally be ignored if you define them.
  6. Click OK to save your settings.
Parent topic: Recording Concepts
Related tasks
Setting Oracle Forms Options


Oracle Java Recording API

The Java Recording API is comprised of two elements:
  • HTTP recording rules
  • Instructions regarding which Java classes implement recording logic

HTTP recording rules are necessary to prevent the recording of certain HTTP/ HTTPS traffic when HTTP/HTTPS is the transport protocol of the client/server communication channel. Not all HTTP/HTTPS traffic is ignored-only the traffic that sends/receives messages is ignored.

This means that if your Oracle Forms application is embedded in a normal HTML file with embedded objects or frames, the calls that request those pages will be scripted and therefore they will be requested during replay.

In terms of scripting the necessary OraForms API calls, all communication between the applet and the server is handled by the Java Recorder.

Parent topic: Recording Concepts


Java Environment Settings

As recording and replay of Oracle Forms applications is achieved through a Java implementation, it is necessary to configure your Java environment in Silk Performer, using the Profile settings dialog. You must define your Java home directory (Settings > Active Profile > Java > General > Java home).

Parent topic: Recording Concepts
Related tasks
Configuring Java Version and Classpath Settings


Files Generated During Recording

When recording an application, a script, a text log and a TrueLog are generated.
  • Script
    Explains the basic concepts of a recorded Oracle Forms script.
  • Recording Text Log
    The recording text log contains information about the HTTP traffic.
  • Record TrueLogs
    TrueLogs allow you to compare record and replay differences after you have executed your first TryScript.
Parent topic: Recording Concepts


Script

The script contains the OraFormsInit method call in the init transaction. OraFormsInit defines the server, port, servlet URL and version of your Oracle Forms application. Not all parameters will necessarily be scripted with values as required parameters vary based on version and connection type.

OraFormsInit initializes the internal Oracle Forms replay engine (the actual connect is achieved with OraFormsConnect) and therefore should be one of the first calls in the main transaction.

Wherever a new form window is activated the recorder scripts a OraFormsSetWindow, indicating that the new window is now the active window. OraFormsSetWindow has a special meaning in TrueLogs, which will be discussed later in this chapter.

All of the subsequent method calls until the next OraFormsSetWindow are executed on controls of the current window.

OraFormsDestroy is scripted in the end transaction to shut down the replay engine.

Parent topic: Files Generated During Recording


Recording Text Log

The recording text log contains information about the HTTP traffic.

Most of the HTTP information that would normally be logged for a Web application is disabled. If you are interested in detailed HTTP logs, enable this setting in your profile.

The relevant elements of the log are the Oracle Forms messages that are logged when you have a log level of Normal or Debug. Messages from and to the server are logged in the following format:
Sample Message | Description
===> | Direction: ===> (to server), <== (from server)
Block# 1 -------------------- | Block #: A block contains a message sent to the server and the server's response to the message. Both parts are terminated by a terminal message.
MSGTYPE: UPDATE | The type of message. Options include: -CREATE, UPDATE, GET, DESTROY, TERMINAL
CLASS: 1/1 | The class of control that handles the message
ID: 1 | The unique control identifier that handles the message
RESPONSE: 0 | Status message
PROPERTIES: TYPE:PROP_TYPE_INTEGER Name:INITIAL_VERSION Value:90290 TYPE:PROP_TYPE_POINT Name:INITIAL_RESOLUTION Value:java.awt.Point[x=96,y=96] TYPE:PROP_TYPE_POINT Name:INITIAL_DISP_SIZE Value: java.awt.Point[x=1280,y=1024] ... | A list of properties. Each property has a type, name, and value.

When the log level is set to Debug, log information required for troubleshooting is logged to the log file. If you encounter any problems and need to contact Micro Focus SupportLine, please provide a log file utilizing the log level Debug.

Parent topic: Files Generated During Recording


Record TrueLogs

Record TrueLogs contain the same information as replay TrueLogs. This allows you to compare record and replay differences after you have executed your first TryScript.

Parent topic: Files Generated During Recording
Related concepts
Oracle Forms / Oracle Applications TrueLogs


Oracle Forms HTTPS Support

Silk Performer enables you to record Oracle Forms applications that use secure connections via HTTPS. To record an Oracle Forms application over HTTPS you must add the Silk Performer certificate to your JVM’s truststore database:

  • Enabling Oracle Forms HTTPS Support Using a JVM
    Add the Silk Performer certificate to your JVM’s truststore database with a JVM.
  • Enabling Oracle Forms HTTPS Support Using JInitiator
    Add the Silk Performer certificate to your JVM’s truststore database with JInitiator.
Parent topic: Recording Concepts


Enabling Oracle Forms HTTPS Support Using a JVM

Silk Performer enables you to record Oracle Forms applications that use secure connections via HTTPS. To record an Oracle Forms application over HTTPS you must add the Silk Performer certificate to your JVM’s truststore database:
  1. Open the Java Control Panel on your system.
  2. Select the Security tab.
  3. Click Import to locate and import the Silk Performer certificate IRCAcert.pem. This file is located in your Silk Performer installation directory.
  4. Close the Java Control Panel.
    Note: Remember to start a new browser session before recording your Oracle Forms application.
You can now record your application.
Parent topic: Oracle Forms HTTPS Support


Enabling Oracle Forms HTTPS Support Using JInitiator

Silk Performer enables you to record Oracle Forms applications that use secure connections via HTTPS. To record an Oracle Forms application over HTTPS you must add the Silk Performer certificate to your JVM’s truststore database:
  1. Open the file certdb.txt with a text editor. This file is located in the directory \Lib\security\ of your JInitiator’s home directory.
  2. Open the Silk Performer certificate file IRCAcert.pem with a text editor. This file is located in your Silk Performer installation directory.
  3. Copy the content of the Silk Performer certificate file and append it to the content of the certdb.txt file.
  4. Save and close the certdb.txt file.
    Note: Remember to start a new browser session before recording your Oracle Forms application.
You can now record your application.
Parent topic: Oracle Forms HTTPS Support


Oracle Forms / Oracle Applications TrueLogs

TrueLog Explorer is a powerful tool that not only offers a convenient means of exploring Oracle Forms applications. It also enables you to add verifications for control values and customize input values for controls that are modified during recording.

  • Working With Oracle Forms Applications - Overview
    Explains how to customize an Oracle Forms test script based on the results of a Try Script run.
  • Oracle Forms TrueLog Structure
    Explains the Oracle Forms TrueLog structure and the Form Controls window.
  • Working With Web Calls
    Because Oracle Forms is a mixed protocol that often incorporates Web calls in scripts, TrueLog Explorer enables you to alternate between a tabular data-based representation view for binary Oracle Forms applets and a rendered HTML view for HTML pages.
  • Node Information
    Explains the information about the current state of all controls that is stored by Oracle Forms nodes.
  • Verification Checks with TrueLog Explorer
    Add content checks to your test scripts to verify that the content that is to be sent by servers is in fact received by clients under real-world conditions.
  • Parsing Functions Overview
    Explains how parsing functions can be used to maintain state information during load testing and to simulate real-world user-data input.
  • Input Data Customizable Functions
    Lists the input data functions that can be customized.
  • In Body / Out Body Pages
    Describes the message block types (OraForms call) that are communicated between Silk Performer and Oracle Forms.
Parent topic: Oracle Forms / Oracle Applications Support
Related tasks
Customizing Oracle Applications 12i Session Information


Working With Oracle Forms Applications - Overview

Oracle Forms, previously called “SQL*Forms”, is part of Oracle’s Internet Developer Suite (iDS). It is a 4GL Rapid Application Development (RAD) environment that allows forms to be deployed across the Web via Oracle’s Internet Application Server (iAS) Forms Services.

Because Oracle Forms is based on Java technology, before you can record and replay Oracle Forms transactions, you must configure Java Virtual Machine using Silk Performer profile settings. The Java Just-In-Time Compiler must also be disabled while recording Oracle Forms 6i or higher.

Before proceeding with this chapter, it is essential that you familiarize yourself with TrueLog Explorer basic functionality.

Parent topic: Oracle Forms / Oracle Applications TrueLogs
Parent topic: Working With Oracle Forms Applications


Oracle Forms TrueLog Structure

This section explains the Oracle Forms TrueLog structure and the Form Controls window.

  • Oracle Forms TrueLog Structure - Overview
    Explains the Form Controls window, which displays the elements of the selected Oracle Forms applet window in tabular-data representation.
  • Node Information
    Explains the information about the current state of all controls that is stored by Oracle Forms nodes.
  • Working With Web Calls
    Because Oracle Forms is a mixed protocol that often incorporates Web calls in scripts, TrueLog Explorer enables you to alternate between a tabular data-based representation view for binary Oracle Forms applets and a rendered HTML view for HTML pages.
  • In Body / Out Body Pages
    Describes the message block types (OraForms call) that are communicated between Silk Performer and Oracle Forms.
  • Terminal Messages
    Describes the three terminal-message types that are used to end communication round-trips between client and server.
  • Analyzing Errors in Oracle Forms Tests
    After tests, it is typical to have multiple TrueLog On Error files open in TrueLog Explorer. You can analyze these erroneous transactions chronologically, regardless of which TrueLogs the errors were recorded in.
  • Analyzing Oracle Forms Test Scripts
    Once you have generated a test script you can determine if the script runs without error by performing a Try Script run. A Try Script run determines if a script accurately recreates the recorded interactions.
  • Comparing Oracle Forms Replay and Record TrueLogs
    Compare a replay TrueLog with a record TrueLog to identify any differences in control values between replay and record.
  • Unanticipated Get Calls
    Describes the scenarios in which you must manually script OraFormsSet and OraFormsOnMessageGet because of unanticipated Get calls.
  • Setting Silk Performer Log Level to Debug
    To prepare for manual scripting when an unanticipated get call is received, it is necessary that you analyze the in-data and out-data that is exchanged between the client and server. This analysis can only be conducted if you have set the Silk Performer log level to debug.
Parent topic: Oracle Forms / Oracle Applications TrueLogs
Parent topic: Working With Oracle Forms Applications


Working With Web Calls

In addition to Oracle Forms API calls, Web calls that download HTTP content are also included in TrueLogs. The first call in each main transaction is the Web call that downloads the initial page of the Oracle Forms application under test.

The TrueLog Explorer feature set varies based on the protocol of the open TrueLog. Because Oracle Forms is a mixed protocol that often incorporates Web calls in scripts, TrueLog Explorer enables you to alternate between a tabular data-based representation view for binary Oracle Forms applets and a rendered HTML view for HTML pages. The Web-based protocol is significant because it enables you to customize session handling, insert verification functions, parse values out of HTML, and run searches on HTML included in Oracle Forms scripts.

  1. Choose Edit > TrueLog Type .
  2. Select Web (default).
Parent topic: Oracle Forms / Oracle Applications TrueLogs
Parent topic: Oracle Forms TrueLog Structure


Node Information

Each Oracle Forms node stores information about the current state of all controls of the active window. If you select a OraFormsSetWindow node that represents a window's first appearance, you will see all the controls and initial values as they existed when the form was initially created.

If you select a subnode, you will see the state and values of all controls as they existed after the action you selected was fulfilled. For example, if you select an OraFormsEditSet you will see the state of the controls after this action was fulfilled.

If a window is reactivated (meaning that an alternate window was activated in the meantime) and you select the OraFormsSetWindow of the reactivated window, you will see the status of the controls as they were after the reactivation (which in most cases is the same status they had when the window was deactivated).

Parent topic: Oracle Forms / Oracle Applications TrueLogs
Parent topic: Oracle Forms TrueLog Structure


Verification Checks with TrueLog Explorer

TrueLog Explorer enables you to insert content-verification functions into test scripts to verify the accuracy of content that is returned by application servers during testing.

TrueLog Explorer offers wizards that add verification functions to your scripts to verify control values at any time during an application's life cycle. To add a verification function, right-click in the Value column of a control that you wish to verify and select the relevant context menu.

When you identify the content that you want to verify, all required verification functions can be generated and automatically inserted into your test script. To identify content that is to be verified (within rendered HTML, HTML source code, SQL commands, Oracle Forms, or elsewhere), select and right-click it.

Verifications can be applied visually inTrueLog Explorer Rendered and Source views using any of the following methods:
  • Script menu
  • Add Verifications dialog box
  • Context menus within Rendered, Source, and Form Controls views
  • workflow bar
Parent topic: Oracle Forms / Oracle Applications TrueLogs
Parent topic: Verification Checks


Parsing Functions Overview

Parsing functions are typically used for the following tasks:
  • Replacing static session IDs in scripts with dynamic session IDs that maintain state information.
  • Building enhanced content verifications into scripts that can not be achieved with verification functions alone. For example, a parsing function might verify that a value in column 2 of row 3 of a database table is equal to the sum of the values in column 2 of row 1 and column 2 of row 2. This can be achieved by generating parsing functions that parse out the three values and compare them in a script.
  • Conditionally executing part of a testing script that is dependent on data returned from a server. For example, an HTTP request returns an HTML page that includes the following results: <nnn> items found. Different actions need to be executed against the value <nnn>. Say the transaction is designed to:
    • Exit if <nnn> = 0.
    • Link to a details page if <nnn> = 1.
    • Link to the next page if <nnn> is greater than 1.

To accomplish this, the value <nnn> must be parsed from the HTML page, and scripted actions must be run based on the parsed values.

TrueLog Explorer allows you to insert parsing functions visually in Rendered and Source views. TrueLog Explorer automatically generates parsing functions in scripts, so no manual writing of code is required. TrueLog Explorer offers wizards that add parsing functions to your scripts to parse control values at any time during an application's life cycle. To add a parsing function, right-click in the Value column of a control that you wish to parse and select the relevant context menu.

Parent topic: Oracle Forms / Oracle Applications TrueLogs
Parent topic: Parsing Functions


Input Data Customizable Functions

TrueLog Explorer offers a wizard that enables you to customize the input values of controls that have been changed by the user during recording. Input values can be customized at the same position where input originally occurred during recording. Here is a list of the functions that can be customized:

Function | Description
OraFormsEditSet | Customizes the value of a text control.
OraFormsRadioSet | Specifies whether a radio button is to be selected.
OraFormsCheckboxSet | Specifies whether a check box is to be selected.
OraFormsListSelect | Specifies which element of a list box is to be selected.
OraFormsPopListSelect | Specifies which element of a pop-up list box is to be selected.
OraFormsLogon | Customizes logon credentials on the Logon dialog.
OraFormsLovFind | Customizes the search pattern on a List Of Values dialog.
OraFormsLovSelect | Customizes the selection on a List Of Values dialog.
OraFormsEditorDialogOK | Customizes a text control value in an editor dialog.
Parent topic: Oracle Forms / Oracle Applications TrueLogs
Parent topic: Oracle Forms User-Input Data Customization


In Body / Out Body Pages

The data that is communicated between Silk Performer and an Oracle Forms server can be tracked on the In Body and Out Body pages. During Oracle Forms replay, the In Body page displays the data that is received by Silk Performer from the Oracle Forms server. The Out Body page displays the data that is sent by Silk Performer to the Oracle Forms server.

Note: These messages are only available when you set the logging options in the Profile Settings dialog to Debug.

Messages can be ignored during data customization (except when customizing GET messages). However if a problem arises and Customer Care is contacted, this information will be required for analysis. You may notice major differences between record and replay TrueLogs. All messages are likely to be included, but they may not be logged at the corresponding nodes; they may be logged one node earlier or later.

Each message block (OraForms call) that is communicated between Silk Performer and the Oracle Forms server is comprised of one or more of the following messages types:

Item Description
Create

Indicates that a new UI element must be created. Each UI object to be created is given a class, properties, and an ID.

Example: The server tells the client to create a text box of a given type, with a given name, and a given ID, at a given location.

Destroy

Indicates that a UI element must be destroyed.

Example: When a window is closed, all of the controls on the window must be destroyed.

Update

Indicates what an element within the applet should look like (for example, position, focus, and selection status).

Example: The client tells the server where the mouse cursor should be positioned. The server then responds by changing the mouse cursor position within the applet’s interface.

Get

Indicates internal communication between the client and server. Get messages are not visible in the UI.

Example: The server asks the client what the ID of a certain control is. Get messages are typically terminated with Terminal 3 messages.

Terminal
 Indicates the end of a communication round trip. Each message block is terminated with a terminal message. Three terminal types are available:
  • Terminal 1
  • Terminal 2
  • Terminal 3

The most common message block type involves the client sending an update message to the server and ending the communication with a Terminal 1 message. The server then typically responds with a create or destroy message that is terminated by a terminal 1 message.

Example In Body/Out Body message block:

With a mouse click function, the client sends an update message to the server with some properties. One of the properties is the mouse cursor location. Another property is that the mouse should be in the pressed-down state. The round trip of the communication is then closed with a Terminal message. The server then responds, indicating that the cursor has been repositioned and set to the pressed-down state.

 MSGTYPE:       UPDATE
 CLASS:         0/0
 ID:            2824
 TITLE:         N/A
 RESPONSE:      0
 PROPERTIES:
 TYPE:  PROP_TYPE_INTEGER
 Name:  MENU_MENUUPDATE/367
 Value: 2855

 MSGTYPE:       DESTROY
 CLASS:         0/0
 ID:            2855
 TITLE:         N/A
 RESPONSE:      0
 PROPERTIES:

 MSGTYPE:       GET
 CLASS:         0/0
 ID:            1644
 TITLE:         N/A
 RESPONSE:      0
 PROPERTIES:
 TYPE:  PROP_TYPE_VOID
 Name:  VALUE/131
 Value: null

 MSGTYPE:       TERMINAL
 CLASS:         0/0
 ID:            0
 TITLE:         N/A
 RESPONSE:      3
 PROPERTIES:
Parent topic: Oracle Forms / Oracle Applications TrueLogs
Parent topic: Oracle Forms TrueLog Structure


Replay Concepts

Silk Performer emulates multiple Oracle Forms clients distributed across multiple Silk Performer agents. Silk Performer's Oracle Forms clients are driven by a Java Runtime that is hosted by Silk Performer during replay.

  • Setting Oracle Forms Options
    Configure Oracle Forms settings, including connection mode and the enabling of timers and counters for controls.
  • Oracle Forms Client Sessions
    Explains Oracle Forms client session handling with the help of a recorded script.
  • Results
    Explains how to analyze how the Oracle Forms application performed during the test run.
  • Connection Handling
    Explains what needs to be considered ro properly handle Oracle Forms connections.
Parent topic: Oracle Forms / Oracle Applications Support


Oracle Forms Client Sessions

When executing a recorded Oracle Forms script, a client session begins with the OraFormsConnect function call and ends with OraFormsDisconnect or OraFormsDestroy.

Example

transaction TInit
begin
  WebSetBrowser(WEB_BROWSER_MSIE8);
  WebModifyHttpHeader("Accept-Language", "en,de-at;q=0.5");
  OraFormsInit("http://lnz-vmoraf11:8888/forms/lservlet", " lnz-vmoraf11", 9000,
  ORA_FORMS_11G);
end TInit;

transaction TShutdown
begin
  OraFormsDestroy();
end TShutdown;

transaction TMain
var
begin
  OraFormsSetString("DEFAULT_LOCAL_TZ", "Europe/Berlin");
  OraFormsConnect(
    "server module=healthyliving.fmx userid=hl/hl@ORCL_ SERVER  sso_userid="
    "output_dir=C:\\orant\\forms11\\demos\\temp");

  // New window activated: MAIN
  ThinkTime(3.7);
  OraFormsSetWindow("MAIN");
  OraFormsEditSet("EDIT_CONTROL_0", "USER", ORA_EDIT_SEND_DIRTY); // Supplier Name
  OraFormsDisconnect();
end TMain;

The above session begins with the OraFormsConnect call and ends with the end of the transaction (OraFormsDisconnect). Therefore each iteration of the transaction can be considered an Oracle Forms client session.

Parent topic: Replay Concepts


Results

Once a Silk Performer test is complete, Performance Explorer is used to analyze how the Oracle Forms application performed during the test run. Silk Performer automatically collects a configurable number of timers and counters for each function call, depending on which performance metrics you specified to be collected during test runs.

By default, Silk Performer collects the following counters for each function call:
  • bytes sent
  • bytes received
  • messages received
  • messages sent
  • roundtrips
These counters are found in Performance Explorer as follows:
Default Oracle Forms Counters

In addition to counters, Silk Performer offers timers, which measure how long it takes for a function call to complete its tasks. These timers are found in Performance Explorer as follows:

Default Oracle Forms Timers

Graphs can be assembled by dragging counters and timers into graphs.

Parent topic: Replay Concepts
Related tasks
Setting Oracle Forms Options


Connection Handling

Oracle Forms connections are established with OraFormsConnect and are closed with OraFormsDisconnect. Recorded scripts include OraFormsConnect at the beginning of the TMain transaction and OraFormsDisconnect as the last Oracle Forms call in TMain. OraFormsDisconnect must be called to ensure that the server connection is closed, otherwise the server runtime process that handles the client will continue to run.

OraForms.bdh implements event handlers that call OraFormsDisconnect when server errors cause virtual user process exits.

In scenarios in which you have a login procedure and multiple main transactions that perform actions that you want to test, you must ensure that you have established connections at the beginning of transactions. As connections may close due to severe errors, subsequent transactions must re-establish connections.

The suggested means of handling this issue is to create a BDL function that contains the script code that establishes the connection to the Oracle Forms application. The function can use the OraFormsIsConnected method to query if a connection is already established. This function should be called at the beginning of each Oracle Forms transaction that requires a connection to the application.

Example

After recording, your script should resemble the following:
var
  gsSSessionID : string;

dclrand

dcltrans
  transaction TInit
  begin
    OraFormsInit("http://lnz-vmoraf11:8888/forms/lservlet", "lnz-vmoraf11", 9000, ORA_FORMS_11G);
    //WebSetUserBehavior(WEB_USERBEHAVIOR_FIRST_TIME);
    //WebSetDocumentCache(true, WEB_CACHE_CHECK_SESSION);
  end TInit;

  transaction TShutdown
  begin
    OraFormsDestroy();
  end TShutdown;

  transaction TMain
  begin
    WebSetBrowser(WEB_BROWSER_MSIE8);
    WebModifyHttpHeader("Accept-Language", "de-at");
    WebPageUrl("http://lnz-vmoraf11:8888/forms/frmservlet", "iOrganizer", FORMS_FRMSERVLET001);

    WebSetBrowser(WEB_BROWSER_CUSTOM);
    WebSetUserAgent("Java1.6.0.21");
    WebSetHttpVersion("HTTP/1.1");
    WebModifyHttpHeader("Accept-Language", NULL, WEB_MODIFY_ OPT_Remove);
    WebUrl("http://lnz-vmoraf11:8888/forms/java/f90all_ jinit.jar", 29.61);
    WebUrl("http://lnz-vmoraf11:8888/forms/jars/iorganizer.jar", 0.42);
    WebUrl("http://lnz-vmoraf11:8888/forms/iorg_images/iorganizer.gif", 0.45);
    WebUrl("http://lnz-vmoraf11:8888/forms/images/blue.gif", 0.43);
    WebUrl("http://lnz-vmoraf11:8888/forms/java/oracle/forms/registry/Registry.dat", 0.08);
    WebUrl("http://lnz-vmoraf11:8888/forms/iorg_registry/iorg_registry.dat", 6.58);

    // Connect - with connection properties
    OraFormsSetInt("INITIAL_VERSION", 1111003);
    OraFormsSetPoint("INITIAL_RESOLUTION", 96, 96);
    OraFormsSetPoint("INITIAL_DISP_SIZE", 1280, 1024);
    OraFormsSetInt("INITIAL_COLOR_DEPTH", 256);
    OraFormsSetString("FONT_NAME", "Dialog");
    OraFormsSetInt("FONT_SIZE", 900);
    OraFormsSetByte("FONT_STYLE", 0);
    OraFormsSetByte("FONT_WEIGHT", 0);
    OraFormsSetPoint("INITIAL_SCALE_INFO", 8, 20);
    OraFormsSetBoolean("WINSYS_REQUIREDVA_LIST", false);
    OraFormsSetString("DEFAULT_LOCAL_TZ", "Europe/Berlin");
    OraFormsConnect("server escapeParams=true module=iorganizer.fmx userid=  debug=no host= port= usesdi=yes record=names",
      "http://lnz-vmoraf11:8888/forms/lservlet?ifcfs=/forms/frmservlet?config=iorg&ifsessid=formsapp.4&acceptLanguage=de-at",
      "http://lnz-vmoraf11:8888/forms/frmservlet?config=iorg");
    OraFormsGetSessionId(gsSSessionID);
    WebCookieSet(gsSSessionID, "http://lnz-vmoraf11:8888/forms/java/");

    // ---
    // New window activated: 10
    OraFormsSetWindow("10");
    ThinkTime(6.6);

    …
end TMain
After customization, your script should appear as follows:
var
  gsSSessionID : string;

dclfunc
  function DoConnect
  begin
    WebSetBrowser(WEB_BROWSER_MSIE8);
    WebModifyHttpHeader("Accept-Language", "de-at");
    WebPageUrl("http://lnz-vmoraf11:8888/forms/frmservlet", "iOrganizer", FORMS_FRMSERVLET001);

    WebSetBrowser(WEB_BROWSER_CUSTOM);
    WebSetUserAgent("Java1.6.0.21");
    WebSetHttpVersion("HTTP/1.1");
    WebModifyHttpHeader("Accept-Language", NULL, WEB_MODIFY_ OPT_Remove);
    WebUrl("http://lnz-vmoraf11:8888/forms/java/f90all_ jinit.jar", 29.61);
    WebUrl("http://lnz-vmoraf11:8888/forms/jars/iorganizer.jar", 0.42);
    WebUrl("http://lnz-vmoraf11:8888/forms/iorg_images/iorganizer.gif", 0.45);
    WebUrl("http://lnz-vmoraf11:8888/forms/images/blue.gif", 0.43);
    WebUrl("http://lnz-vmoraf11:8888/forms/java/oracle/forms/registry/Registry.dat", 0.08);
    WebUrl("http://lnz-vmoraf11:8888/forms/iorg_registry/iorg_registry.dat", 6.58);

    // Connect - with connection properties
    OraFormsSetInt("INITIAL_VERSION", 1111003);
    OraFormsSetPoint("INITIAL_RESOLUTION", 96, 96);
    OraFormsSetPoint("INITIAL_DISP_SIZE", 1280, 1024);
    OraFormsSetInt("INITIAL_COLOR_DEPTH", 256);
    OraFormsSetString("FONT_NAME", "Dialog");
    OraFormsSetInt("FONT_SIZE", 900);
    OraFormsSetByte("FONT_STYLE", 0);
    OraFormsSetByte("FONT_WEIGHT", 0);
    OraFormsSetPoint("INITIAL_SCALE_INFO", 8, 20);
    OraFormsSetBoolean("WINSYS_REQUIREDVA_LIST", false);
    OraFormsSetString("DEFAULT_LOCAL_TZ", "Europe/Berlin");
    OraFormsConnect("server escapeParams=true module=iorganizer.fmx userid=  debug=no host= port= usesdi=yes record=names",
      "http://lnz-vmoraf11:8888/forms/lservlet?ifcfs=/forms/frmservlet?config=iorg&ifsessid=formsapp.4&acceptLanguage=de-at",
      "http://lnz-vmoraf11:8888/forms/frmservlet?config=iorg");
    OraFormsGetSessionId(gsSSessionID);
    WebCookieSet(gsSSessionID, "http://lnz-vmoraf11:8888/forms/java/");

  end DoConnect;

dcltrans
  transaction TInit
  begin
    OraFormsInit("http://lnz-vmoraf11:8888/forms/lservlet", "lnz-vmoraf11", 9000, ORA_FORMS_11G);
    //WebSetUserBehavior(WEB_USERBEHAVIOR_FIRST_TIME);
    //WebSetDocumentCache(true, WEB_CACHE_CHECK_SESSION);
  end TInit;

  transaction TShutdown
  begin
    OraFormsDestroy();
  end TShutdown;

  transaction TMain
  begin
    DoConnect();

    // ---
    // New window activated: 10
    OraFormsSetWindow("10");
    ThinkTime(6.6);
    …
  end Tmain

  transaction TsecondMain
  begin
    DoConnect();

    // ---
    // New window activated: 10
    OraFormsSetWindow("10");
    ThinkTime(6.6);
    …
  end TsecondMain;

With this approach, if you run a load test with a user that executes multiple main transactions you will not experience problems with subsequent transactions if an active transaction fails and disconnects from the server.

Parent topic: Replay Concepts


Oracle Forms Performance Monitoring

Use Performance Explorer to retrieve performance metrics from Oracle Forms Dynamic Monitoring System (DMS). Performance Explorer can monitor the DMS performance Web page that is provided through the Oracle Forms HTTP server when the DMS module is installed.

For full details on Oracle Forms performance monitoring, please see Performance Explorer Help.

Parent topic: Oracle Forms / Oracle Applications Support


Root Cause Analysis

Errors that happen during a Try Script, baseline or load test-run can easily be analyzed with the log files that are written during the run - especially with the TrueLog.

  • TrueLog Analysis
    Explains how to check for errors with the TrueLog.
  • Log File Analysis
    Provides an explanation of log files used for error analysis.
  • OraForms Errors
    List of the OraForms errors thrown by OraForms API calls.
Parent topic: Oracle Forms / Oracle Applications Support


TrueLog Analysis

The most common error that occurs is: OraForms: 5 - Handler not found.

This error is thrown if the control (handler) that is referenced as the first parameter of a failing OraForms API call cannot be found, for example a button that should be pressed is not on the form.

By having a look at the preceding calls - prior to the one that throws the error - it is often easy to see why the control is not there. Oracle Forms applications often send a WINSYS_BEEP message if an error occurs, for example when entering invalid data. Some applications also update the status bar message. Moving through the preceding calls and looking at the Info tab will show you if there was a WINSYS_BEEP or a status bar update.

Very often, the server updates the status bar message in case of an error. Check the preceding calls, prior to the one that throws the error, if there is any information about a changed status bar message. Whenever the status bar message changes, an informational log entry will be logged.

Parent topic: Root Cause Analysis


Log File Analysis

The log files (recording and replay) contain different information depending on the log level defined in the profile settings. Whenever you have a problem and need to contact technical support, switch the log level to Debug and try to record/replay the script again and send those files. The Debug log level contains special development information that allows Technical Support to analyze the problem quicker.

The log file contains the Oracle Forms messages that are sent between the server and the client. Additionally, in debug log-mode all client side events will be logged, for example value changed, mouse down, and more.

Parent topic: Root Cause Analysis
Related concepts
Technical Support


OraForms Errors

Below is a list of the OraForms errors that can be thrown by the OraForms API calls.

ID | Message | Description
1 | Logon dialog not found | OraFormsLogon and OraFormsLogonCancel can throw this error if the Logon dialog is not the current active dialog. It is most likely that the OraFormsConnect failed because the logon dialog should be the first dialog after a successful connect.
2 | Window not found | OraForms-CloseWindow, -WindowMove, -WindowResize and -WindowUpdate will throw this error if the window with the passed window name/ID has not yet been created. Similar to the 5 - handler not found error message.
3 | Unsupported property | Can be thrown by multiple OraForms calls when the calls are querying handlers for special properties that should be set but are not. This error is not likely to happen under normal circumstances.
4 | Focus handler not found | OraFormsSetFocus throws this error if the handler with the passed handler name/id was not found. Similar to the 5 - handler not found error message.
5 Handler not found

This method can be thrown by any OraForms API call that takes a handler name/ID as first parameter. The first thing that every API call verifies is if the handler with the passed name/ID has already been created. If not, the operation cannot be executed on that handler. There are multiple reasons why a handler is not present during replay although it was during recording.

The most common case is that an error was raised on the server, for example because of invalid user input. This invalid input has caused the application to not display dialogs or other windows that would normally appear when entering valid data like it does during recording.

6 | The button to be pressed does not exist | OraFormsMessageBoxButton throws this error if an invalid button number was passed to the method. Valid buttons are: ORA_ ALERT_YES, ORA_ALERT_NO, ORA_ALERT_CANCEL.
7 | Menu item was not found | OraFormsMenuItem throws this error if the menu item passed by its full name was not found. The menu item is searched in the assigned menu of the passed window name/ID.
8 | Tab page not found | OraFormsTabSelect throws this error if there is no tab page with the passed name or passed index.
9 | Unrecognized dialog button | OraFormsCloseDialog throws this error if an invalid button number was passed to the method. Valid buttons are: ORA_DIALOG_OK and ORA_ DIALOG_CANCEL.
10 | The function cannot be applied for this handler | Several OraForms API calls throw this error if the method was called on a handler of a type that does not allow to execute that kind of function,for example OraFormsTabSelect on a non-tab control handler.
11 | The LOV row does not exist | OraFormsLovSelect throws this error if there is no entry in the current list of values dialog that matches the passed name or passed row index.
12 | The list item does not exist | OraFormsListSelect and OraFormsListActivated throw this error if the list handler referenced in the first parameter does not contain a list element with the passed value or index.
13 | Handler is of invalid class | Several OraForms API calls throw this error if the method was called on a handler of a type that does not allow to execute that kind of function, for example OraFormsTabSelect on a non-tab control handler.
14 | A value for this property is not set | All OraFormsGetProp{Type} methods throw this error if the requested property has not been set on the passed handler.
15 | Array index is out of bound | OraFormsGetPropStringArray and OraFormsGetPropByteArray throw this error if the passed element index is out of the array boundaries of this property. Use OraFormsGetPropStringArrayLen and OraFormsGetPropByteArrayLen to get the number of elements in the array. The index is 0-based.
16 | Verification failed | Every verification function throws this error if the defined verification fails.
17 | Received version too old | If the server returns the error VERSION_TOO_OLD during the connect phase, this error is thrown. This means that the version number of the client is too old to work with the version on the server. Use a different version number for the client by customizing the OraFormsSetInt for the property INITIAL_VERSION or the version number in the profile settings.
18 | Received version too new | If the server returns the error VERSION_TOO_NEW during the connect phase, this error is thrown. This means that the version number of the client is too new to work with the version on the server. Use a different version number for the client by customizing the OraFormsSetInt for the property INITIAL_VERSION or the version number in the profile settings.
19 | Alert dialog | Whenever an alert dialog is created, this error is thrown. The default severity of this error is INFORMATIONAL as alert dialogs are often used as the normal way to display a message to a user.
20 | Statusbar changed | Whenever the server updates the status bar text, this error is raised with the new text of the status bar. The default severity is INFORMATIONAL as a status bar update is normally a way to inform the user about server side actions, but it could also be an error message. Therefore, when doing root cause analysis of errors check for status bar changes.
21 | Runtime error, see log file for stack trace | If there are internal replay runtime errors, this error is logged with a detailed stack trace in the replay log file. In case of such an error, contact technical support and send all recorded and replayed files.
22 | WINSYS_BEEP | This error is logged if the server sends a WINSYS_BEEP message. Oracle Forms applications send a WINSYS_ BEEP to indicate that the last action caused some problems on the server, for example invalid user input. It is likely that a WINSYS_BEEP is followed by other errors like Handler not found. The reason for this is because a recorded session without errors could cause errors during replay if the script is customized with invalid input values, or if a script that should be customized is not customized, for example using different values each time a test is run.
23 | OraFormsSetConnectMode overrides the profile's connection setting | This is just a warning indicating that the setting in the profile is overruled by the scripted OraFormsSetConnectMode.
24 | Profile setting INITIAL_ VERSION overridden by function OraFormsSetInt | This is just a warning indicating that the setting in the profile is overruled by the scripted OraFormsSetInt ("INITIAL_ VERSION", version).
25 | Verification succeeded | Whenever verification succeeds, a success log entry is created.
26 | Handler already destroyed or not created yet | It is possible that the client applet sends messages from special handlers (controls) that are already officially destroyed by a destroy message from the server. This is not a real error and can only occur during recording. Therefore, a warning is logged.
27 | Tree item was not found | All OraFormsTree API calls throw this error if the referenced tree item was not found in the tree.
Parent topic: Root Cause Analysis


Tips and Tricks

Explains issues that need to be considered when testing Oracle Forms applications with Silk Performer.
  • Oracle Forms Memory Usage
    Explains the memory usage of VUsers simulating Oracle Forms applications.
  • Latest Available JDK Version
    Explains the reasons for using the latest available JDK version.
  • Virtual Memory Size of a JVM
    Explains the benefits of changing the default memory size values of a JVM.
  • Java VM JITter
    Provides options on how to disable Java JITting when recording Oracle Forms 6i on either HTTP or Sockets.
  • Recording Oracle Forms on Sockets
    Explains the setting needed to record an Oracle Forms script when the application you want to record uses sockets.
  • Problems with Oracle Forms 6 Recording
    Explains how to specify the transport channel you want to use for recording.
  • Problems with Oracle Forms 6 Recording Using Additional Java Beans
    Explains problems that can occur when implementing Java Beans with Oracle Forms applications.
  • Oracle Applications 12i Support
    Explains Silk Performer support for Oracle Applications 12i, including script recording, customization, and replay.
  • Customizing Oracle Applications 12i Session Information
    TrueLog Explorer can assist you in customizing hard-coded session information in your recorded test scripts so that they can be replayed.
  • Adding a New Java Bean to a System Classpath
    Explains how to update the system classpath to add a new Java Bean.
Parent topic: Oracle Forms / Oracle Applications Support


Oracle Forms Memory Usage

Oracle Forms Replay Engine uses Silk Performer’s Java Framework to send/receive Oracle Forms messages. Therefore each virtual user container (PerfRun) requires additional memory, as the Java Runtime must be hosted once per runtime process – not once per user executed in the runtime.

The initial footprint of the Java Runtime Environment depends on the JDK that is used for replay. The JDK must be defined in the profile settings of the Oracle Forms project. On average, 10 MB’s is required to host a Java Runtime. Additionally, each virtual user requires memory for Oracle Forms processing. The amount of required memory varies based on the following variables:

  • Length of executed scripts

  • Number of hosted controls

  • Oracle Forms log level

  • TrueLog On Error (enabled/disabled)

Significant memory is required for a log level that is higher than “Error.” “Normal” and “Debug” log levels log all Oracle Forms messages in the replay log and in the TrueLog’s In/Out Body section. This log information is helpful for error analysis, but requires significant additional overhead (the amount of memory required varies based on the length of scripts and the number of controls).

Parent topic: Tips and Tricks
Parent topic: Oracle Forms Functions Reference


Latest Available JDK Version

The JDK needs to be configured in your profile settings. You should use the latest available JDK version for the following reasons:

  • Performance: Newer versions perform better, allowing you to simulate more users on one machine.
  • Stability: There might be stability issues when using older JDK versions, such as encountering deprecated functions. Those deprecated functions might result in unpredicted results during a load test.

There is no impact in using a different JDK version than the Oracle Forms client applet is using. During recording, the selected JDK is only used within the Silk Performer Recorder process, not by the applet. During replay it is used in the virtual user runtime.

Parent topic: Tips and Tricks


Virtual Memory Size of a JVM

A Java Virtual Machine can be configured with minimum and maximum heap sizes. When the maximum heap size is reached, out of memory exceptions are thrown. During recording, a lot of memory is consumed. The amount varies based on the log level and the length of recorded transactions.

It is likely that you will run into a memory problem when using a default maximum heap size of only 16 MB. The Java runtime allows you to change the default values by defining two special runtime parameters:

  • -Xmsn for defining the minimum heap size (for example: -Xms10m)
  • -Xmxn for defining the maximum heap size (for example: -Xmx128m)

If you run into a memory problem during recording, please define the runtime parameter -Xmx with a high enough memory value in the runtime settings of your Oracle Forms applet viewer. In most cases, this can be set using the JInitiator configuration dialog.

Parent topic: Tips and Tricks


Java VM JITter

When recording Oracle Forms 6i on either HTTP or Sockets, it is recommended that you disable Java JITting in the Java runtime settings. This is because the JITting library of the Java Virtual Machine (symcjit.dll) may crash your browser.

Note: Disable JITting whenever your browser crashes during recording.

Option #1

Define -DJAVA.COMPILER=NONE in the Java runtime settings of the Oracle JInitiator Properties dialog. This must be done using the JInitiator control panel, which is installed with JInitiator (available in the Windows Control Panel). To do this:

  1. Launch the JInitiator Control Panel.
  2. Add -DJAVA.COMPILER=NONE in the Java Run Time Parameters text field.
  3. Click Apply.

Option #2

Use the check box on the Oracle JInitiator Properties dialog to disable the Just In Time Compiler (only available since version 1.1.8.x). To do this:

  1. Launch the JInitiator Control Panel.
  2. Select the Advanced tab.
  3. Deselect the Enable Just In Time Compiler check box.
  4. Click Apply.

Option #3

Define an environment variable: SET JAVA_COMPILER=NONE.

Parent topic: Tips and Tricks


Recording Oracle Forms on Sockets

The communication channel between the Java applet on the client and the Oracle Forms server can either be via HTTP/HTTPS or raw TCP/IP sockets. To accurately record an Oracle Forms script when the application you want to record uses sockets, there is a setting that you must change in Silk Performer's System Settings.

  1. In the Silk Performer menu, click Settings > System .
  2. Click the Recorder icon. The Recording Profiles page opens.
  3. Click the Proxies tab.
  4. Select the SOCKS proxy entry and click the Edit button. The Proxy Settings dialog appears.
  5. In the Suppress recording (only forward data) field, enter the port that your Oracle Forms application uses for communication with the applet.
  6. Click OK. If you fail to suppress the port, Silk Performer will record on both the Oracle Forms level and the TCP/IP level. This will generate a script with mixed OraForms and WebTcp calls.
Note: Disable the socks port of your application when your application uses raw socket communication.
Parent topic: Tips and Tricks


Problems with Oracle Forms 6 Recording

When recording an Oracle Forms 6 application using the Oracle Forms 6 project type, Silk Performer listens on both transport channels: HTTP/HTTPS and Sockets.

Some applications that operate on the Socket layer have been known to crash Internet Explorer while both channels are being recorded. This is why Silk Performer allows you to specify the transport channel that is of interest to you.

This setting is defined in the Recording Profile dialog box.

  1. In the Silk Performer menu, click Settings > System .
  2. Click the Recorder icon. The Recording Profiles page opens.
  3. Change the Java API to the protocol that you wish to record.

Now when you begin recording, do not select the preconfigured Oracle Forms 6i application type, use Internet Explorer as you have already changed its recording profile configuration.

Parent topic: Tips and Tricks


Problems with Oracle Forms 6 Recording Using Additional Java Beans

Implementing Java Beans can extend Oracle Forms applications with new GUI-Elements or Client-Side functionality. Those Java extensions will be downloaded by the client applet at startup.

When recording Oracle Forms 6, Silk Performer's Recorder will hook the main Java Archive containing the applet classes. The Java extensions either derive from classes or implement an interface that is contained within this archive. The Java Runtime, depending on some configuration settings, will verify class signatures when loading those Java Beans. As the main archive has been modified, those verifications will fail and the applet will no longer start.

To disable this verification process it is necessary to define an additional Java runtime parameter in the JInitiator Runtime Parameter settings. Define the parameter -noverify in your JInitiator settings.

Parent topic: Tips and Tricks


Oracle Applications 12i Support

Prerequisite for Recording

Important: Before recording Oracle Applications 12i you must disable ports 9000-9005.

Customized Recorded Scripts

Before you can replay a recorded Oracle Applications 12i script you need to customize the script.

The parameter icx_ticket contains session information for Oracle Applications 12i. The Silk Performer Recorder generates code to automatically parse the value of icx_ticket:

WebParseDataBoundEx(gsIcxTicket, STRING_COMPLETE, "icx_ticket='", 1, "'",
WEB_FLAG_IGNORE_WHITE_SPACE, 1);
WebPageParseUrl("IMG SRC", "IMG SRC=\"", "or", WEB_FLAG_IGNORE_WHITE_SPACE);
WebPageUrl("http://myserver.com:8005/OA_HTML/runforms.jsp", "Oracle Applications R12",
OA_HTML_RUNFORMS_JSP003);

The WebParseDataBoundEx function tells the Silk Performer runtime to parse the value of icx_ticket from the next HTML page call into the gsIcxTicket variable.

In this example, the next HTML page call is http://myserver.com:8005/OA_HTML/runforms.jsp.

This page takes input parameters from the form OA_HTML_RUNFORMS_JSP003. If this form already contains a recorded value for icx_ticket, the value has to be set to an empty value.

OA_HTML_RUNFORMS_JSP003:
  "icx_ticket"                   := "", // hvg4LnVEVjLLFU-e1pNr6Q...
  "resp_app"                     := "PER",
  "resp_key"                     := "VU_HRMS_MANAGER",
  "secgrp_key"                   := "STANDARD",
  "start_func"                   := "PERWSGEB",
  "other_params"                 := "";

For all subsequent usages of the icx_ticket parameter, the value stored in the icx_ticket variable must be used instead of the recorded value.

Note:

The Silk Performer Recorder scripts customized code for the OraFormsConnect function by default. Verify that the customization has been performed correctly.

OraFormsConnect(
  "server module=/data/oracle/ebs/application/apps/apps_st/appl/fnd/12.0.0/forms/US/FNDSCSGN
  fndnam=APPS record=names  config='VIS' icx_ticket='" + gsICXTicket + "' resp='PER/VU_HRMS_MANAGER'
  secgrp='STANDARD' start_func='PERWSGEB' other_params=''", "http://myserver:8005",
  "http://myserver.com:8005/forms/frmservlet?&lookAndFeel=ORACLE&colorScheme=KHAKI&
serverApp=OracleApplications3&lang="US"&env=NLS_LANG='AMERICAN_AMERICA'+FORMS_USER_DATE_FORMAT=
'DD-MON-RRRR'+FORMS_USER_DATETIME_FORMAT='DD-MON-RRRR+HH24%3AM"
"I%3ASS'+NLS_DATE_LANGUAGE='AMERICAN'+NLS_SORT='BINARY'+NLS_NUMERIC_CHARACTERS='.,'&
form_params=+config='VIS'+icx_ticket="'.hr7lGQhSIG3iAMWb9LkuVQ..'"+resp='PER%2FVU_HRMS_MANAGER'+
secgrp='STANDARD'+start_func='PERWSGEB'+other_params=''&encoding="UTF-8");
Parent topic: Tips and Tricks


Customizing Oracle Applications 12i Session Information

Ensure that the icx_ticket parameter has been customized correctly.

  1. Perform a trial run of the script by clicking the Try Script button on the Workflow Bar.
    Note: TrueLog generation must be enabled in Silk Performer
  2. Open the resulting Try Script TrueLog with TrueLog Explorer. Typically, an HTML page (appearing soon after login) will show errors. Example error:

  3. Click the Analyze Test button on the Workflow Bar.
  4. Select Compare your test run on the Workflow - Analyze Test wizard page.
  5. Close the Step through Truelog dialog.
  6. Select the TrueLog node that corresponds to the recorded application’s login page.
  7. Right-click the node and select Synchronize Truelogs from the context menu.
  8. Select Edit > Truelog Type > Web from the TrueLog Explorer menu bar.
  9. Click the Differences tab.

  10. Right-click any rows that show differences between the recorded TrueLog and the replay TrueLog that also occur in the script and therefore likely contain session information (highlighted in yellow) that should be customized.
  11. Run another Try Script run in Silk Performer to verify that your session information customizations have been successful.
Parent topic: Tips and Tricks
Parent topic: Working With Oracle Forms Applications


Adding a New Java Bean to a System Classpath

Oracle Forms applications can be pushed using Java Beans components. Java Beans, in this context, are Java archives that contain applications that can be run inside Oracle Forms applets. Examples of such applications are calendars and clocks.

There are requirements for testing Oracle Forms applications that make use of Java Beans. Ensure that the Java archives containing the Java Beans are also in the system classpath. To add a new Java Bean to a system classpath, follow these steps:

  1. Navigate to Start > Control Panel > System.
  2. Select the Advanced tab.
  3. Click Environment Variables. This launches the Environment Variables dialog box where you can edit the environment variables.
  4. Select the CLASSPATH variable in the System variables box and click Edit.
  5. In the Edit System Variable dialog box, update the Variable name and Variable value to add the Java archive that contains the Java Bean.
  6. Click OK.
  7. Restart the Oracle Forms server.
Parent topic: Tips and Tricks


SAP Support

This section explains Silk Performer support for testing of SAP applications, including project setup and SAP configuration. It also provides tips for customizing scripts and including verification functions.

  • SAP eCATT Support
    Explains Silk Performer's integration with SAP eCATT. SAP’s eCATT facility allows you to create test scripts in SAP using the scripting language of your choice.
  • SAPGUI Support
    Overview of how to use Silk Performer to test SAP systems via the SAPGUI interface
Parent topic: Load Testing Specific Application Types


SAP eCATT Support

SAP eCATT has been integrated with Silk Performer. SAP’s eCATT facility allows you to create test scripts in SAP using the scripting language of your choice. eCATT allows you to use external test tools (for example, Silk Performer) while utilizing eCATT as a repository for your test scripts. eCATT also serves as a basic test management solution for triggering script executions. Not only can both internal and external scripts be executed individually, they can also be combined and executed in sequence.

eCATT offers import arguments, a mechanism for calling scripts with special input values. Scripts can not only receive input values, scripts can also set output values when they are executed; scripts can be executed in sequence, using input values derived from the output values of earlier script executions.

For full details regarding Silk Performer’s integration with SAP eCATT, refer to the SAPGUI Tutorial. For more information regarding eCATT, consult the SAP documentation.

  • Configuring a SAP eCATT Connection
    Explains Silk Performer's integration with SAP eCATT. SAP’s eCATT facility allows you to create test scripts in SAP using the scripting language of your choice.
  • Configuring eCATT Extended Results
    Specify a UNC path to a public file share in which extended Silk Performer test results can be stored and accessed by users.
Parent topic: SAP Support


Configuring a SAP eCATT Connection

Connection details for Silk Performer’s communication with SAP eCATT must be specified in Silk Performer system settings. There are two options for connecting to SAP: You can either specify a SAPLOGONID or you can specify AS Host, RFC Type, and SystemNr settings. With either option you must specify client, language, username, and password details. Note that when you select a SAPLOGONID, the AS Host, RFC Type, and SystemNr fields are grayed out.

  1. Navigate to Settings > System .
  2. On the System Settings – Workbench dialog, select the SAPGUI group icon.
  3. The eCATT Connection page is selected by default. From the SAPLogon list box, select your SAP login ID.
    Note: This box is preconfigured with all available SAP login IDs.
  4. In the AS Host field, enter the combined router/application-server string (for example, H/195.61.176.22/H/194.117.106.130/S/3297/H/cpce801).
  5. In the RFC Type field, enter either 3 (for R/3) or 2 (for R/2).
  6. In the System NR field, enter the SAP system number.
  7. In the Client field, enter the internal client ID number from the SAP server (this is the value that must be entered on the SAP login screen).
  8. From the Language list box, select your language preference. The values EN (English) and DE (German) are preconfigured, though you can specify any other language abbreviation string if that language is installed on the SAP system.
  9. In the Username field, enter your SAP eCATT username.
  10. In the Password field, enter your SAP eCATT password.
  11. Once you have completed this dialog, click Test Connection to confirm that you have specified accurate connection details.
  12. Click OK to save your settings.
Parent topic: SAP eCATT Support


Configuring eCATT Extended Results

To enable the viewing of Silk Performer result files from within SAP GUI, you can specify a UNC path to a public file share in which extended Silk Performer test results can be stored and accessed by users (for example, \\fileserver\ecattresults). Silk Performer will use the specified directory to store the results of Silk Performer test executions initiated via SAP eCATT. Users can easily access test results by clicking a link in the SAP eCATT GUI.

  1. Navigate to Settings > System .
  2. On the System Settings – Workbench dialog, select the SAPGUI group icon.
  3. Click the eCATT Results tab.
  4. Check the Use SAP extended results check box.
  5. In the SAP extended results root directory field, browse to and select the directory that is to be used for SAP extended results.
  6. Click OK to save your settings.
Parent topic: SAP eCATT Support


SAPGUI Support

This section provides guidelines for customizing scripts (including verification functions) so that they can be run in distributed multi-user environments. For detailed instructions on how to use Silk Performer to test SAP systems via the SAPGUI interface, refer to the SAPGUI Tutorial.

  • Basic Concepts
    Explains Silk Performer's support for testing SAPGUI applications.
  • Installation and Requirements
    Explains the configuration requirements for setting up SAPGUI client and server software.
  • Recording and Replay Concepts
    Provides an overview of recording, replaying and customizing scripts for SAPGUI applications.
  • SAPGUI TrueLogs
    Explains how TrueLog Explorer can be used to explore the results of SAPGUI application tests and how to visually customize your scripts.
  • Settings for Large Load Tests
    Explains issues you should consider when running large load tests.
  • Tips and Tricks
    Explains issues that need to be considered when testing SAPGUI applications with Silk Performer.
Parent topic: SAP Support


Basic Concepts

SAP has a test interface that can be used by tool vendors to test SAP systems. This test interface offers the ability to listen to events as well as to execute user actions. Silk Performer uses this interface to record new scripts and for script execution.

This section provides an overview of how to use Silk Performer to test SAP systems via the SAPGUI interface and outlines possible server configurations and discusses how they can be tested.
  • SAPGUI Scripting
    Overview that describes what happens during recording and during replay in the SAPGUI scripting process.
  • SAP Patch Levels
    Lists the patch level required for SAP servers.
  • SAPGUI Application Architecture
    Overview of the architecture for the SAPGUI application object connections.
Parent topic: SAPGUI Support


SAPGUI Scripting

SAPGUI scripting must be installed on the client. It can be selected during the SAPGUI client setup process. Once it has been installed on the client, SAPGUI scripting must be enabled on both the client and the server.

Note: The SAP security parameter sapgui/user_scripting_disable_recording blocks access to key events on the SAP server that Silk Performer needs access to in order to facilitate replay and recording. Enabling the parameter sapgui/user_scripting_disable_recording results in replay failure. To allow replay, you must disable this parameter.

During recording

The SAPLogon process initializes the SAPGUI scripting API. This allows the recorder to attach to a COM object that offers full access to the SAP DOM where each component (control) within SAPGUI can be accessed. This COM interface also offers an event mechanism that notifies subscribers of changes in the GUI (for example, button presses, text edits) and server roundtrips (Start/End Request).

The Silk Performer Recorder is a subscriber of this event interface, so it receives notice of all changes that are made by the user in the SAPGUI user interface. Depending on recording profile settings, Silk Performer Recorder is either set for low-level scripting of API calls for each change event, or high-level scripting for API calls in which certain change events are merged with high-level calls (for example, SapGuiLogon).

During replay

When executing a SAPGUI load test, the SAPGUI user interface is automatically switched to invisible mode. There is a setting in the profile settings that allows you to execute a GUI-less TryScript run. This setting however, has no effect in load test scenarios as it does not make sense to show the UI when executing multiple users on a machine, because too many windows would be displayed; additional resource consumption would be required if each window has to render itself.

As each VUser has access to the full SAP DOM, it is possible to generate TrueLogs with rich control information.

Parent topic: Basic Concepts
Related tasks
Working With SAPGUI Applications


SAP Patch Levels

Silk Performer’s SAPGUI record/replay technology is based on the SAPGUI scripting API, which needs to be enabled on the server and client side.

SAPGUI scripting API is not available in all versions of SAPGUI client – you should therefore check your Patch Level.

Patch Levels on the Server

The components on the server also require a certain patch level. Following is an overview about the required patch levels:
Software Component | Release | Package Name | Kernel Patch Level
SAP_APPL | 31I | SAPKH31I96 | Kernel 3.1I level 650
SAP_APPL | 40B | SAPKH40B71 | Kernel 4.0B level 903
SAP_APPL | 45B | SAPKH45B49 | Kernel 4.5B level 753
SAP_BASIS | 46B | SAPKB46B37 | Kernel 4.6D level 948
SAP_BASIS | 46C | SAPKB46C29 | Kernel 4.6D level 948
SAP_BASIS | 46D | SAPKB46D17 | Kernel 4.6D level 948
SAP_BASIS | 610 | SAPKB61012 | Kernel 6.10 level 360
Note: On the client side, SAPGUI client 620 is required with a minimum patch level of 44.
  • Checking the SAP Patch Level
    Check if your SAP installation offers support for SAPGUI scripting.
  • Checking the SAP Patch Level on the Server
    Check the SAP Patch Level on your server.
  • Checking SAP R/3 Support Packages
    Verify that SAPKB46C29 is installed
  • Enabling SAPGUI Scripting on the Server
    Change the sapgui/user_scripting parameter in order to enable scripting.
  • Enabling SAPGUI Scripting API on the Client
    Ensure that SAPGUI scripting API was installed during SAPGUI setup.
Parent topic: Basic Concepts


Checking the SAP Patch Level

SAPGUI scripting is not supported by all versions of SAP. Therefore it is necessary to check if your installation offers this kind of support. You can do this by checking your current Patch Level. The Patch Level needs to be at least 66.

  1. Start your SAPGUI logon window which is normally accessible through Start > Programs > SAP Front End > SAPLogon > About SAP Logon. The SAP Version Information dialog box appears.
  2. Check that your Patch Level is at least 66.
Parent topic: SAP Patch Levels
Related concepts
SAP Functions


Checking the SAP Patch Level on the Server

  1. Logon to your SAP system.
  2. Select System > Status.
  3. Click the Other Kernel Information button. The Kernel Information dialog opens.
  4. Check the value of the field Sup. Pkg. lvl. Check your value and Kernel Release version with the table in SAP Patch Levels. If your Patch Version is lower than the required one update your system. Refer to the SAP OSS note #480149 for detailed instructions.
Parent topic: SAP Patch Levels
Related concepts
SAP Functions


Checking SAP R/3 Support Packages

  1. Logon to your SAP system.
  2. Run the SPAM transaction.
  3. In the Directory section, select All Support Packages, and click the Display button.
  4. If you have SAP_BASIS, 4.6C installed, verify that SAPKB46C29 is installed. You will see a green circle if it is installed. If you do not have the OCS package installed, download it from www.sap.com and install it. For more information, refer to the SAP OSS note #480149.
Parent topic: SAP Patch Levels
Related concepts
SAP Functions


Enabling SAPGUI Scripting on the Server

Silk Performer’s SAPGUI record/replay technology is based on the SAPGUI scripting API, which needs to be enabled on the server and client side. SAP servers of version 620 and higher offer SAPGUI scripting support. Earlier versions require certain patch levels.

A user with administrative privileges needs to change the sapgui/user_scripting parameter in order to enable scripting. The value needs to be changed to TRUE.

  1. Logon to your SAP server.
  2. Run transaction RZ11. Specify the parameter name sapgui/user_scripting and click Display. If Parameter name is unknown appears in the status bar, this indicates that you are missing the current support package. Check your installed packages.
  3. Change the value to TRUE.
  4. Click Save.
  5. Restart the application server, since this change only takes effect when you log onto the system.
Parent topic: SAP Patch Levels
Parent topic: Installation and Requirements
Related concepts
SAP Functions


Enabling SAPGUI Scripting API on the Client

All clients that are either used for recording, replay or monitoring must have a SAPGUI client with SAPGUI scripting installed. You have to select this option in the SAPGUI Setup.

After the installation you need to make sure that SAPGUI scripting is enabled:

  1. Start your SAPLogon and go to the logon screen of one of your servers.
  2. Open the Options dialog in your SAP client.
  3. Select the Scripting tab, check Enable Scripting, and disable both sub options. This prevents warning messages when Silk Performer interacts with SAPGUI scripting GUI.

If the installation status of the Scripting tab does not display Scripting is installed, you must install SAPGUI scripting by choosing the option in the SAPGUI client setup process.

Parent topic: SAP Patch Levels
Parent topic: Installation and Requirements
Related concepts
SAP Functions


SAPGUI Application Architecture

The SAPGUI application object, which is instantiated once per virtual user in test scenarios, can have infinite SAP connections. A connection can be opened with either SapGuiOpenConnection or SapGuiOpenConnectionByName. One connection should be opened by each virtual user that you want to simulate at the beginning of your test. When opening a new connection, an SAP session is created as well. A connection can hold up to 6 sessions, which can be created with SapGuiCreateSession.

When the last session on a connection is closed, the connection itself is closed and destroyed.

An SAP session holds the information about all control elements on the main window of the session. Additionally, a session info object can be accessed for specific data about the current transaction or performance related data.

An SAP session usually has a main window as its child. This window is the starting point for all user interaction with the current session.

  • Object IDs
    List of SAPGUI objects and descriptions.
  • Object Access with Silk Performer
    Describes how to make object access easier.
  • Accessing Object Properties
    Describes how to get a full list of all properties of each object type in a SAPGUI application.
  • Accessing Low-Level Properties
    Provides an overview of SAP properties and describes how to get the name of a control when you have the control's ID.
Parent topic: Basic Concepts


Object IDs

Each object within a SAPGUI application is identified by a unique ID, which contains the ID information of the complete object hierarchy, beginning with the application object itself. The IDs of the objects in the hierarchy are separated by forward slashes ("/") where the application object itself begins with a forward slash.
Object | ID Description
SAP Application | The application's ID is /app.
SAP Connection | A connection's partial ID is con[X], where X is the index of the connection. The index is required when there are multiple objects with the same base ID. The index is 0-based. Example: /app/con[0]
SAP Session | The session's partial ID is ses[X], where X is the index of the session within the current connection. Example: /app/con[0]/ses[0]
SAP Window or Dialog | The window's partial ID is wnd[X], where X is the index of the window within the current session. Example: /app/con[0]/ses[0]/wnd[0]
SAP User Area | The ID of the user area is usr. As there is only one user area per window, there is no need for an index here. Example: /app/con[0]/ses[0]/wnd[0]/usr
SAP Title Bar | The ID of the title bar is titl. It is a child of a window or dialog. Example: /app/con[0]/ses[0]/wnd[0]/titl
SAP Tool Bar | The partial ID is tbar[X]. There can be up to two tool bars on a window and therefore the index is needed. Example: /app/con[0]/ses[0]/wnd[0]/tbar[0]
SAP Status Bar | The ID of the status bar is sbar. As there is only one status bar per window, there is no need for an index here. Example: /app/con[0]/ses[0]/wnd[0]/sbar
Other Controls | Certain control types have special ID prefixes (for example, lbl for labels and txt for text controls). Following the prefix, controls have a programmatical name (for example, RSYST-BCODE). Controls that are listed in a table format can have multi-dimensional indices, similar to the indices shown above for sessions, connections, etc. A multi-dimensional index is defined as controlid[X,Y]. Examples: /app/con[0]/ses[0]/wnd[0]/usr/txtRSYST-BCODE /app/con[0]/ses[0]/wnd[0]/usr/sub:SAPMSYST:0020/txtINFO-TABTDLINE[0,0] /app/con[0]/ses[0]/wnd[0]/tbar[0]/btn[0]
Parent topic: SAPGUI Application Architecture


Object Access with Silk Performer

To make object access easier, Silk Performer API calls do not require full object IDs for controls. Instead, the relative object ID of the current window can be used for most API calls.

For example, pressing the button /app/con[0]/ses[0]/wnd[0]/tbar[0]/btn[0] can be done with SapGuiPressButton ("tbar[0]/btn[0]");.

To do this, Silk Performer requires the information about the current window, session, and connection. For this purpose there are three methods that allow you to set the current context:
  • SapGuiSetActiveConnection
  • SapGuiSetActiveSession
  • SapGuiSetActiveWindow

When you record a script you see one of the three above mentioned functions scripted wherever the context has changed.

A typical script looks like this:
gsConnID := SapGuiOpenConnection("CONNECTSTRING");
SapGuiSetActiveConnection(gsConnID);
SapGuiSetActiveSession("ses[0]");
SapGuiSetActiveWindow("wnd[0]");
SapGuiPressButton("/tbar[0]/btn[0]");

This makes scripts easier to read and customize.

Parent topic: SAPGUI Application Architecture


Accessing Object Properties

Each object has properties that can be accessed from a Silk Performer script during execution. To get a full list of all properties of each object type, do the following:

  1. Open a tool that allows you to view type libraries (for example, OLEView, which comes with Microsoft Visual Studio).
  2. Open the file <SAPINSTALLDIR>\FrontEnd\SAPGui\sapfewse.ocx. <SAPINSTALLDIR> is usually located in C:\Program Files\SAP.
  3. Explore the different COM classes for their properties. COM classes have meaningful names so that it is easy to find the correct COM objects for your requested object type, for example GUITextField for text controls.
  4. Special controls such as trees and grids can be explored by opening the corresponding dll, located in <SAPINSTALLDIR>\FrontEnd\Controls\Scripting. For example, open GridViewScripting.dll to get the information for grid controls.

Silk Performer offers methods to Get/Set properties, and even for invoking methods. If a method call or a GetProperty access returns another object, the object can be accessed with additional Get/Set/Invoke calls by passing the constant SAPGUI_ACTIVEOBJECT as the object identifier.

Parent topic: SAPGUI Application Architecture
Related concepts
Tips and Tricks


Accessing Low-Level Properties

The functions SapGuiInvokeMethod, SapGuiSetProperty, and SapGuiGetProperty can be used to access the low-level properties of any control on the active screen. This makes it possible to, for example, confirm that a text control is read-only, or to determine the background color of a label.

The SAPGUI scripting API that is used for SAPGUI testing is a large COM library that allows Silk Performer to access controls and perform actions. This same COM library can be used with the above mentioned API calls. To access the list of methods and properties that individual controls offer, you must inspect the type library of the SAPGUI scripting API. For this you need a tool that facilitates the inspection of type libraries (for example the Ole32View tool that comes with Microsoft Visual Studio). With the tool, open the sapfewse.ocx file, which can be found in the SAPGUI installation directory under \FrontEnd\SapGui. The image below shows the properties that can be accessed on a label control:

Image of properties that can be accessed using the label control

To get the name of a control for which you know the control's ID, use the following call:

SapGuiGetProperty("/usr/lbl[1,2]", "Name", sOutValue);
Print("The control has the following name:" + sOutValue);

Most properties return a simple data type such as a string, number, or boolean parameter. Some properties return other objects, for example the Parent property returns the parent control of the current control. When a property returns another control, the control is temporarily cached and can be accessed via the constant SAPGUI_ACTIVEOBJECT. Here is a code example for retrieving the name of a parent property:

SapGuiGetProperty("/usr/lbl[1,2]", "Parent");
SapGuiGetProperty(SAPGUI_ACTIVEOBJECT, "Name", sOutValue);
Print("The parent control has the following name:" + sOutValue);

Differences Between 620 and 640 Clients

SAP introduced new properties and methods with its SAPGUI 640 client. With 640 you can, for example, get the background color of a label or checkbox. So, when you develop a script on 640 you must ensure that your agents also run on 640 and that the same patch level is used. Otherwise you may request properties that are not available on the agent and generate an error.

Property Overview

SAP is comprised of components that have the following properties (ComClass GuiComponent):

  • 'Name' - Name of the control
  • 'Type' - The control type in text format (for example GuiButton, GuiTextField)
  • 'TypeAsNumber' - All types have internal numbers (for example 30=GuiLabel, 31=GuiTextField)
  • 'ContainerType' - A Boolean property that defines whether or not a control is a container. Containers contain other controls as children (for example a toolbar is a container that contains toolbar buttons).
  • 'Id' - The unique ID of a control
  • 'Parent' - When a control is contained in a container this property returns the parent control

Visual components, such as controls, have additional properties (ComClass GuiVComponent):

  • 'Text' - The main text of a control (for example the text in a text control or the text on a button)
  • 'Left', 'Top', 'Width', 'Height', 'ScreenLeft', 'ScreenTop' - Number values offering details about screen coordinates and coordinates within a parent container
  • 'Changeable', 'Modified' - Boolean parameters that indicate the current state of a control (is the control changeable or read-only; has the control been modified, etc)

Each control type may have additional properties which can be seen in the COM type library via your type library inspection tool.

Parent topic: SAPGUI Application Architecture


Installation and Requirements

To use Silk Performer's support for SAPGUI, SAPGUI scripting must be installed and enabled on the client and the server side.

  • Enabling SAPGUI Scripting on the Server
    Change the sapgui/user_scripting parameter in order to enable scripting.
  • Enabling SAPGUI Scripting API on the Client
    Ensure that SAPGUI scripting API was installed during SAPGUI setup.
Parent topic: SAPGUI Support


Recording and Replay Concepts

The following sections explain the workflow for recording, replaying and customizing scripts, as well as result analysis.

  • SAP Profile Settings
    Configure the profile settings, including recording, common, and replay settings, for Silk Performer SAPGUI support.
  • Password for SapGuiLogon
    Provides an explanation of why password fields cannot be retrieved via the SAPGUI scripting API.
  • Setting SAPGUI Options
    Configure SAPGUI settings, including counters/timers, log level, and screenshots.
  • Files Generated During Recording
    Describes the files that are generated when recording a SAPGUI application.
  • SAP Results
    Describes the measures that are generated for method calls that force a roundtrip to the SAP server.
  • SAP Performance Monitoring
    Establish a connection to a data source to monitor SAP systems and to create an initial view that contains the measures you want to monitor.
Parent topic: SAPGUI Support


SAP Profile Settings

Recording Settings

Settings specific for recording can be changed on the recording tab of your profile settings:

  • Script logon as single function - If enabled, the logon procedure will be scripted as SapGuiLogon API call. If disabled, multiple API calls like setting username, password and pressing ENTER will be scripted.
  • Script low level functions - Instead of high level API functions, like for example SapGuiSetText, low level API functions will be scripted, such as SapGuiInvokeMethod, SapGuiSetProperty, …
  • Script timers - Most of the SAPGUI API functions take an optional timer parameter. If this parameter is defined, measures for this will be generated during replay. If this option is enabled, SAPGUI Recorder will automatically script appropriate timer names for each function.
  • Attach to existing SAP session - If enabled, SAPGUI Recorder will attach to an existing SAPGUI session without recording the SapGuiOpenConnection statement.
  • Record window title verification - If enabled, SAPGUI Recorder will script the SapGuiSetActiveWindow with the window title in order to be verified during replay.

Common Settings

The following settings are common settings for both recording and replaying:

  • Log level - Defines the level of logging. For troubleshooting, use Debug, otherwise use Normal. When running large load tests logging should be Disabled in order to reduce memory consumption.
  • Capture screenshots - If enabled, screenshots will be captured for every new window that is activated. This option is only available if Show SAPGUI during single runs is enabled when replaying the script.
  • Capture screenshots for every action - If enabled, screenshots will be captured for every user action that causes a roundtrip to the SAP server. This option is only available if Capture screenshots is enabled.
  • Log control information in TrueLog - If enabled, control information about every control on the active window will be logged to the TrueLog. This allows you to use the customization feature in TrueLog Explorer. This option should be disabled when running load tests as it implies additional resource consumption.
  • Log control information for single run in TrueLog - Same as Log control information in TrueLog, but only for try script and verification runs.
  • Log control information on error - If enabled, control information about every control on the active window will be logged to the TrueLog in case of an error during replay. This allows you to troubleshoot your replay problem by getting the current state of all controls on the screen where the error happened. It is recommended to use this option during a load test rather than Log control information in TrueLog.

Default Profile Settings

When recording an SAP application using the default profile settings (capture screenshots and log control information), the SAP client may appear slower than usual. This is due to the extra overhead required for taking screenshots and logging control information for all controls on each SAP window. This option should not be changed however as you will lose the many benefits that the TrueLog provides. However if you experience timing problems, switch off the options in this order:
  • Capture screenshots for every action
  • Capture screenshots
  • Log control information in TrueLog

Replay Settings

Settings specific for replaying can be changed on the replay tab of your profile settings:

  • Replay timeout - Defines the timeout during replay. If there is no response from the server within this timeout period an error will be thrown.
  • Show SAPGUI during single runs - If enabled, the SAPGUI client will be shown during replay. This option should only be used for a Try-Script run. During a load test it should be turned of.
  • Enable client-side scripting - SAPGUI scripting needs to be enabled on every client machine via the Options menu in the SAPGUI client application. When running a test on multiple agents it would imply that this setting need to be changed manually on every machine before starting the load test. By enabling this option, Silk Performer is changing the setting automatically on every agent before starting the load test.
  • Use new SAP Visual Design - SAPGUI can be run in two visual modes, the old or the new visual design mode. The setting normally needs to be changed with the SAP Configuration Tool. By enabling/disabling this option, Silk Performer does this change automatically before starting the load test. This option allows you to test the different behavior in terms of resource consumption when using either the old or new visual design.

Timers and Counters

The Measuring tab contains settings for replay measuring. You can either Enable all timers and counters for all controls, or select those that are of interest to you. Timers will only be created for method calls that have the optional timer parameter specified.

For a description about those timers, see SAP Results.

Parent topic: Recording and Replay Concepts
Related concepts
SAP Results


Password for SapGuiLogon

Values in password fields cannot be retrieved via the SAPGUI scripting API. Silk Performer's Recorder therefore is not able to script values entered into password fields as it can on the logon screen.

SapGuiLogon is generated with asterisks in the password parameter. You must customize this value manually in the script or by using TrueLog Explorer after a TryScript run.

When running a TryScript or even a load test with an uncustomized password field of the SapGuiLogon method, the actual logon will not be executed. Instead, an error of severity process exit is thrown, because if you run a load test in which you forget to customize the password parameter, the user will be locked out after 3 attempts. To prevent this, Silk Performer stops script execution when the password parameter is not customized.

Parent topic: Recording and Replay Concepts
Related tasks
Working With SAPGUI Applications


Files Generated During Recording

Script

The script contains the SapGuiOpenConnection statement as the first statement in the TMain transaction, unless you have not selected the Attach to existing SAP Session option.

The complete logon sequence, from SapGuiOpenConnection to SapGuiLogon, should be moved to the Tinit transaction when performing large load tests.

When high-level scripting is enabled, the recorder scripts high-level API functions for most control interactions. For all others (where there are no high-level API calls) the low-level functions SapGuiInvokeMethod and SapGuiSetProperty are scripted.

Recording Text Logs

Text logs contain detailed information about SAPGUI events and controls when the log level is set to Debug. The additional information in this log is helpful for troubleshooting. If you experience a problem and need to contact technical support, switch the log level to Debug before recording. This also applies to the replay text log file.

Record TrueLogs

Record TrueLogs contain the same information as replay TrueLogs. This allows you to use TrueLog Explorer's Compare view after you execute a TryScript.

Parent topic: Recording and Replay Concepts
Related tasks
Settings for Large Load Tests


SAP Results

Depending on the measure settings in the active profile, measures are generated for those method calls that have the optional timer parameter defined.

Measures are generated for those method calls that force a roundtrip to the SAP server.
Note: Not all API calls force a roundtrip.

The following measures will be generated during a roundtrip:

Round Trips

Before SAPGUI sends data to the server, it locks the user interface. In many cases it will not unlock the interface once data arrives from the server, but instead will send a new request to the server immediately. Controls in particular use this technology to load the data they need for visualization. The count of these token switches between SAPGUI and the server is offered with this measure.

Flushes

Counts the number of flushes in the automation queue during server communication.

Interpretation Times

The interpretation time begins after the data has arrived from the server. It comprises the parsing of the data and distribution to the SAPGUI elements.

Response Times

This is the time that is spent on network communication from the moment data is sent to the server to the moment the server response arrives.

An overall counter for the roundtrips is shown in the Monitor window during a test and can also be monitored in Performance Explorer as one of the Silk Performer Controller/Agent measures.

Parent topic: Recording and Replay Concepts
Related reference
SAP Profile Settings


SAP Performance Monitoring

Use Performance Explorer to monitor performance and reliability metrics of a SAP system. Performance Explorer is shipped with two monitors specially designed for monitoring SAP installations.

  1. On the Real-Time Monitoring tab, in the Monitor group, click System. The Data Source wizard opens.
  2. Click the Select from predefined Data Sources option button.
  3. Expand the Application Server folder and the SAP folder.
  4. Depending on the type of SAPGUI monitor that you want to use, select the appropriate monitor type. The following types of SAPGUI monitors are available:
    • SAPGUI Monitoring (ST02): Monitors buffer related metrics. SAP transaction ST02 is executed when running this monitor.
    • SAPGUI Monitoring (ST03N): Monitors application specific metrics. SAP transaction ´ST03n is executed when running this monitor.
    • SAPGUI Monitoring (ST04): Monitors database related metrics. SAP transaction ST04 is executed when running this monitor.
    • SAPGUI Monitoring (ST07): Monitors user distribution on the SAP system. SAP transaction ST07 is executed when running this monitor.
    • SAPGUI OS-Monitoring (ST06): Monitors operating system specific metrics. SAP transaction ST06 is executed when running this monitor.
  5. Click Next.

    The Connection parameters page opens.

  6. In the Hostname text box, specify the host of the machine to be monitored This value is for display purposes only. It is not used in the monitor itself.
  7. Click Next. The Attributes Configuration page opens.
  8. Define the following monitoring-specific attributes:
    • ConnectionString – Complete connection string to the SAP server. If you are not sure, record the logon sequence with Silk Performer. The connection string is the first parameter of SapGuiOpenConnection.
    • Username – SAP username with access rights to the monitoring transaction.
    • Password – Password for the SAP user.
    • ClientNum – Client number for the logon procedure, such as 850.
    • Language – Language to use for logon, such as EN.
    • Entity – The data entity that should be monitored, such as Dialog, RFC, or Background.
      Note: The Entity attribute does not have to be provided for the SAP OS-Monitor.
    • TimeFrame – SAP provides the average values of the past interval that you define.
      Note: The Timeframe attribute does not have to be provided for the SAP OS-Monitor.
    • Server - (ST03N only)The server that should be monitored. Its the name of the tree node that is to be selected in ST03N. Total will return measures from the overall SAP System
  9. Click OK. The Select displayed measures page opens.
  10. Check the check boxes for those measures that you want to include in the initial monitor view and then click Finish.
A connection to the specified host is established, and an initial view that contains the measures you selected is displayed.
Parent topic: Recording and Replay Concepts
Parent topic: Predefined Data Sources


SAPGUI TrueLogs

TrueLog Explorer is a powerful tool that not only offers a convenient means of exploring SAPGUI applications, it also enables you to add verifications for control values and customize input values for controls that are modified during recording.

  • SAPGUI TrueLog Structure
    Describes the elements of a SAPGUI TrueLog.
  • Node Information
    Describes the nodes displayed with SAPGUI TrueLogs.
  • Control Information
    Describes the control information logged for each SAPGUI control.
  • Verification and Parsing Functions
    Explains how verification functions verify whether the content that is to be sent by servers is in fact received by clients and the usefulness of adding a SAPGUI parsing function.
  • Input Data Customization
    Explains how simulated user input can be customized visually in TrueLog Explorer.
Parent topic: SAPGUI Support


SAPGUI TrueLog Structure

SAPGUI TrueLogs have a similar structure to Oracle Forms TrueLogs. Each SapGuiSetActiveWindow call results in a new top-level node. A SapGuiSetActiveWindow call is scripted for each window that is activated during a recording session. All actions that are performed on windows (for example, control edits, list entry selections) are shown as sub-nodes grouped by a virtual SapGuiRoundtrip node.

Parent topic: SAPGUI TrueLogs
Parent topic: Working With SAPGUI Applications


Node Information

TrueLog Explorer supports the visualization of SAPGUI requests and responses in the same way it supports the visualization of HTTP client requests and HTTP/HTML server responses.

The three panes that are displayed with SAPGUI TrueLogs are:
  • TrueLog menu tree – Lists all SAPGUI API calls included in the test run.
  • Content pane (upper-right pane) – Displays the state of the GUI at each API node. The End Request and Start Request pages enable you to view both the initial and final states of each SAPGUI server request. These views enable you to see how the server request has affected the GUI display, such as the display of a new dialog box or error message.

    It is possible that when a window is destroyed or when a new window is created due to the action of a selected API node (for example, a button click) that the End Request pane will show a screenshot of the next activated window. This can be confusing as control information in the tree and the screenshot will not match. This only happens on the last node of a window.

    Note: TrueLog screenshots are captured only during Try Script runs, not full load tests.
  • Information pane (lower-right pane) – Displays data regarding the most recent test run. The pages in this pane that are active and applicable to SAPGUI TrueLogs are Info, BDL, and Controls. The Controls page offers a convenient means of viewing and working with all customizable controls in their hierarchical order that are included on each GUI screen.
    Graphic that shows the Controls tab

Under each SapGuiSetActiveWindow node is a virtual node that does not reflect an API call. Those nodes are called SapGuiRoundtrip and contain all API calls that have been sent to the server in a single roundtrip. Only the last API call under the SapGuiRoundtrip node forces a roundtrip. This API call also generates the measures that have been selected in the profile settings with the timer name specified as the last parameter for the call.

When you have Capture Screenshots enabled, a screenshot is captured with each newly activated window. Screenshots are displayed in TrueLog Explorer when you click a SapGuiSetActiveWindow node or a sub node.

When you also have Capture Screenshots for every action enabled, a screenshot is taken before and after each roundtrip. These screenshots are displayed in TrueLog Explorer when you click a SapGuiRoundtrip node or a sub-action node.

When the Log control information in TrueLog option is enabled, information about each control on each window is logged. When a control changes its value at a certain API node, the changes are reflected in the TrueLog and the controls are displayed in a tree hierarchy.

Parent topic: SAPGUI TrueLogs


Control Information

Depending on profile settings, controls are either logged for all windows (Log control information in TrueLog) or only logged in the case of errors (Log control information on error).

The following control information is logged for each control:
  • Internal unique sequence number
  • Absolute and relative object/control ID
  • Current value of the object
  • Type of object
  • Sequence number of parent control
  • Screen coordinates of the control

The unique internal sequence number is for internal use only. It makes it possible to build a hierarchical view of the controls.

The current value of each object depends on the control type. For text controls, the Text property is used. Other controls have properties that reflect other value types.

Parent topic: SAPGUI TrueLogs


Verification and Parsing Functions

Verifications and parsing are possible with most control types. TrueLog Explorer offers standard verification and parsing wizards for SAPGUI TrueLogs. All you need to do to access a wizard, is right-click a control in a screenshot or on the control tree. Via a context menu you can then launch the verification and parsing wizards.

Verification and parsing functions are scripted after the currently selected API node in the tree. Replay errors can result when verification and parsing functions are inserted after the last API call of a window. For example, if a currently selected API node is a button press on a Close button, the current window and all the controls of that window will be destroyed by this action. A verification/parsing function scripted after this call will therefore fail with a Handler not found error during replay. For this reason TrueLog Explorer prompts you to confirm that you wish to add verification/ parsing functions that are inserted on the last nodes of windows.

TrueLog Explorer allows you to add content checks to verify whether the content that is to be sent by servers is in fact received by clients under real-world conditions. For any SAPGUI function call in which input data is inserted, you can insert a return value verification function. Verification functions can be inserted from either Source view or the Controls menu tree.

By comparing replay test runs with record test runs, TrueLog Explorer allows you to confirm visually whether or not text, graphics, field data, and more are downloaded and displayed by clients while SAPGUI applications are under heavy load. This comparison allows you to detect a class of errors that other SAPGUI traffic simulation tools are not able to detect: Errors that occur only under load that are not detected with standard test scripts.

Content verification functions remain useful after system deployment as they can be employed in ongoing performance management.

  • Adding a Value Verification
    Right-click a SAPGUI control that you want to have verified. The required verification function can easily be generated and inserted into your BDL script.
  • Adding a SAPGUI Parsing Function
    Value parsing is useful for enabling replay when session-specific strings must be parameterized to enable accurate replay.
Parent topic: SAPGUI TrueLogs
Parent topic: Working With SAPGUI Applications


Input Data Customization

API calls that simulate user input can be customized in TrueLog Explorer. Such API calls include SapGuiSetText and SapGuiLogon. TrueLog Explorer's Step-through-TrueLog dialog allows you to step through all customizable calls.

TrueLog Explorer's Parameter Wizard can be used to customize input data with:
  • Constant values
  • Random values from multiple sources
  • Multi-column data file support
  • Values from previously parsed values
Parent topic: SAPGUI TrueLogs


Settings for Large Load Tests

Explains issues you should consider when running large load tests.
  • Suggested Profile Settings
    Explains the best profile settings to use when running large load tests.
  • Connection Handling
    Provides recommendations and a script sample on the best way to handle SAPGUI connections.
  • Logon
    Explains best practices to manage user name parameters for SapGUILogon.
Parent topic: SAPGUI Support


Suggested Profile Settings

Control Information

When running large load tests it is recommended that you disable the Log control information in TrueLog setting. This improves the overall performance of each executed virtual user. With this option enabled, all controls of each window iteration are logged to the TrueLog, which is resource (CPU) intensive.

By instead enabling Log control information on error, you still gain the benefit of seeing each control of the windows on which errors occur.

Screenshots

Screenshots are only captured when SAPGUI is run in visible mode. This behavior can be enabled/disabled via the Show SAPGUI during single runs profile setting. When running load tests, this setting is automatically disabled regardless of profile settings. This ensures that screenshots will not be taken during load tests and thereby impact the overall performance of virtual users.

When errors occur, you can however see control information in a TrueLog On Error file if either the Log control information on error or Log control information in TrueLog option is enabled. Control information is displayed in a tree structure, which enables you to see which controls led to errors and the screen coordinates of those controls. To visually see where controls are located, open corresponding record and replay TrueLogs in compare mode and synchronize them. You can then compare the state of a control when an application was recorded with the state of that same control when the script was replayed.

Parent topic: Settings for Large Load Tests


Connection Handling

It is not recommended that you place SapGuiOpenConnection calls in main transactions, otherwise each user opens a new connection with each transaction iteration. Because the SAPGUI scripting API performs connection closes asynchronously, this leads to the problem that your load test agents will open too many connections to the SAP server simultaneously. Errors will then result if you exceed the maximum connection limit.

Unless you are interested in load testing the establishment of new connections, it is recommended that you move logon procedures to INIT transactions. Furthermore, main transactions should always end at the same location where they begin, which is likely to be the screen after a successful logon.

Likewise, logout sequences should be moved out of main transactions and into end transactions.

A fully customized script should resemble the following:
dcluser
  user
    VUser
  transactions
    TInit           : begin;
    TMain           : 1;
    TEnd            : end;
var
  gsConnID : string;

dcltrans
  transaction TInit
  begin
    // Connecting to SAP
    gsConnID := SapGuiOpenConnection("CONNECTSTRING");
    SapGuiSetActiveConnection(gsConnID);
    SapGuiSetActiveSession("ses[0]");
    SapGuiSetActiveWindow("wnd[0]");
    // Logon to SAP System
    // Before running a test you have to customize the password
    parameter!
    SapGuiIgnoreError(SAPENGINE_STATUSBAR_CHANGED, SEVERITY_SUCCESS);
    SapGuiLogon("username", "password", "000", "", "SapGuiLogon");
  end TInit;

  transaction TMain
var
  begin
    SapGuiSetActiveWindow("wnd[0]", "SAP Easy Access", SAP GUI_MATCH_
    ExactNoCase);
...
...
...
    // The VUser should now be again back on the window after a
    successful logon
  end TMain;

  transaction TEnd;
  begin
    SapGuiPressButton("tbar[0]/btn[15]", "SapGuiPressButton\\btn[15]");
    // Log Off
    SapGuiSetActiveWindow("wnd[1]", "Log Off", SAP GUI_MATCH_
    ExactNoCase);
    // Yes
    SapGuiPressButton("usr/btnSPOP-OPTION1", "SapGuiPressButton\\Yes");
  end TEnd;
Parent topic: Settings for Large Load Tests


Logon

When running load tests it is recommended that you use a different SAP user for each virtual user. This can be managed by creating users with user names that have sequence numbers appended to them, for example SAPUSER1-SAPUSER99.

In scripts, it is then possible to customize the username parameter of SapGuiLogon in the following way:
SapGuiLogon("SAPUSER" + string(GetUserId()), "PASSWORD", "000", "");

By default SapGuiLogon enters passed parameters to corresponding text fields on the logon screen and then presses the Enter key.

When you attempt to login a user who is already logged in, SAP opens a dialog that tells you that the user is already logged in. Three options are then offered for proceeding:
  • Continue and cancel other logged in users
  • Continue and do not cancel other logged in users
  • Do not log in the new user
By default SapGuiLogon chooses the second option: logging into the system without canceling other sessions of the same user. Changing the option SAPGUI_OPT_LOGON_BEHAVIOR with SapGuiSetOption allows you to customize this behavior:
SapGuiSetOption(SAPGUI_OPT_LOGON_BEHAVIOR, nValue)
Where nValue can be one of 4 values:
0 | Do not Handle Multi-Logon automatically This means that the dialog will not handled automatically; it will be treated as a normal new window. You can then handle the window manually.
1 | No multiple Logon This means that the option Do not logon is selected.
2 | Multiple Logon (default) This means that the option Continue and do not cancel other logged on users is selected.
3 | Logon-Kill other sessions This means that the option Continue and cancel other logged on users is selected.
Parent topic: Settings for Large Load Tests


Tips and Tricks

Explains issues that need to be considered when testing SAPGUI applications with Silk Performer.
  • Memory Usage for SAPGUI Load Testing
    Describes how to determine the number of users that you can simulate during SAPGUI load tests.
  • Checking for Unexpected Windows
    Describes how to check whether additional windows might appear during recording and how to handle the situation.
  • Browsing Through Grids and Tables
    Examples of functions used for accessing the data in grid and table controls.
  • Accessing Control Properties
    Describes how to access control properties.
  • Invoking Control Methods
    Describes how to invoke SAP control methods.
Parent topic: SAPGUI Support


Memory Usage for SAPGUI Load Testing

The general rule of thumb for SAPGUI load tests is that you can run 50 virtual users on a 1 GB RAM and 1 GHz computer.

It is possible to execute more than 50 users on a computer if you have more power and more RAM, but the increase is not linear nor can this rule be applied to all operating systems.

The real bottleneck for SAPGUI testing is neither RAM nor CPU; it is the number of system-wide GUI resources.

The exact number of possible virtual users per computer is difficult to estimate; it depends on the scripts that are executed. If the virtual users execute transactions that contain lots of controls on the screen, it is more likely that the system runs out of GUI resources faster than with another script.

Therefore you should do some test runs to determine the exact number of users that you can simulate. Do this by executing an increasing workload. When the limit is reached you will see users that are either:

  • Not able to open a new SAP connection
  • Run into timeouts
Parent topic: Tips and Tricks


Checking for Unexpected Windows

Sometimes it is possible that additional windows and dialogs that did not appear during recording appear during replay. For example, a multiple user login alert displays when logging in with the same user multiple times.

To create an error-free script, it is necessary to check whether a new window is available before scripting such functions as SapGuiSetActiveWindow, otherwise an error will occur.

The Multiple Logon dialog is normally handled automatically by SapGuiLogon. The following script shows you how to handle this situation correctly:
if(SapGuiVerifyWindowAvailability("wnd[1]", null, false,
SEVERITY_INFORMATIONAL)) then
SapGuiSetActiveWindow("wnd[1]");
SapGuiSelectRadioButton("");
SapGuiPressButton("");
end;
In addition to SapGuiVerifyWindowAvailabiltity, it is also possible to use SapGuiVerifyObjectAvailability with an absolute object ID. For example:
SapGuiVerifyObjectAvailability(gsConnId + "/ses[0]/
wnd[1]", true, SEVERITY_INFORMATIONAL)

The reason we use SEVERITY_INFORMATIONAL is that we do not want to receive an error if the object/window is not present, we only want to perform an action if the object is there. No error should be logged if the object is not there.

SapGuiVerifyWindowAvailability has an additional parameter with which the window title can be verified. This can be useful when you expect one of multiple possible dialogs where the user can proceed in one of several ways. The function can be used to simply verify if a dialog with a certain title is available.

Parent topic: Tips and Tricks


Browsing Through Grids and Tables

Below are some examples of functions used for accessing the data in grid and table controls.

Grid Control

A grid control has columns and rows. A cell is identified by its row index and column name. To get the value of a cell you must specify the row index and the column name. The following sample shows you how to access all cells in a grid by iterating through all columns and rows.
SapGuiGridGetColumnCount("CTRLID", iColCount);
SapGuiGridGetRowCount("CTRLID ", iRowCount);
for rowix:=0 to iRowCount-1 do
for colix:=1 to iColCount do
SapGuiGridGetColumnName("CTRLID ", colix, colName);
SapGuiGridGetCellData("CTRLID ", rowix, colix,
cellValue);
end;
end;

Row indices are 0-based. Therefore, you iterate from rowix 0 to row count -1.

Table Control

The table control is similar to the grid control. A cell is identified by its row and column index. Both indices are 0-based. The following sample shows you how to access all cells in the table by iterating through all columns and rows.
SapGuiTableGetColumnCount("CTRLID", iColCount);
SapGuiTableGetRowCount("CTRLID ", iRowCount);
for rowix:=0 to iRowCount do
for colix:=1 to iColCount do
cellValue := SapGuiTableGetText("CTRLID ", rowix,
colix);
end;
end;
Parent topic: Tips and Tricks


Accessing Control Properties

The SAPGUI scripting interface offers the ability to access all controls on the current window. Each control has different properties that can be accessed with SapGuiGetProperty. As SAPGUI scripting is based on COM technology, there are many COM libraries that implement those COM objects. Those libraries also include type information for each control type.

To get a list of properties and methods of the different control types, you can view those libraries with a tool that allows COM type library inspection. OLEView32 is a tool that comes with Microsoft Visual Studio that can be used for this purpose.

The following libraries can be found in the SAP install directory (usually: C:\Program Files\SAP\Frontend):
  • SAPGUI\sapfewse.ocx

    This contains the basic controls (for example, text, button)

  • Controls\Scripting\*.dll

    This contains extended controls such as trees and grids

All object properties can be accessed with SapGuiGetProperty. For example:
SapGuiGetProperty("TXTCTRLID", "text", sTextValue);
When a property returns another SAPGUI object or SAPGUI collection, the returned object is stored internally and can be accessed with the constant value SAPGUI_ACTIVEOBJECT for any SapGui API call for the control ID parameter. For example:
SapGuiPressButton(SAP GUI_ACTIVEOBJECT);
Parent topic: Tips and Tricks


Invoking Control Methods

Methods on SAP controls can be invoked using SapGuiInvokeMethod. The basic information about methods that are offered by controls can be viewed in the COM type library. OLEView32 is a tool that comes with Microsoft Visual Studio that can be used for this purpose.

To press a button, you can either use the high-level SapGuiPressButton method or you can invoke the pressButton method on the button control, like this:
SapGuiInvokeMethod("BUTTONCTRLID", "pressButton");

When a method call returns another SAPGUI object or SAPGUI collection, the returned object is stored internally and can be accessed with the constant value SAPGUI_ACTIVEOBJECT for any SAPGUI API call for the control ID parameter.

Parent topic: Tips and Tricks


Siebel Support

This section explains how to use Silk Performer to load test Siebel 8.x CRM applications. It covers the testing of Siebel thin client (Web client) installations that utilize front ends comprised of HTML and applets running within a Web browser (for example, Internet Explorer).

This chapter explains how with the Silk Performer Web Recorder:

  • There is no need for session info customization.
  • There is no need to manually insert parsing functions for database keys.
  • Scripts work correctly, even with transactions that insert new records into databases.
  • Scripts are prepared for easy randomization.

Also covered are:

  • Best practices for properly preparing recording sessions
  • Basic architecture of Siebel thin client installations

This section is intended for experienced users who are knowledgeable about load testing Web (HTTP/HTML based) applications with Silk Performer.

  • Siebel CRM Application Architecture
    Contains an overview of a typical Siebel CRM deployment.
  • Setting Up Your Project
    Explains that the Siebel Web client runs in browsers as a Java applet.
  • Dynamic Information in Web Client HTTP Traffic
    Explains that HTTP traffic generated by Siebel Web clients incorporates dynamic information that must be addressed to ensure successful and accurate replay.
  • Best Practices
    Explains the common pitfalls, offers hints, and explains best practices for successfully testing Siebel Web clients.
Parent topic: Load Testing Specific Application Types


Siebel CRM Application Architecture

This topic contains an overview of the Siebel client. The figure below illustrates the architecture of a typical Siebel deployment.

Siebel system architecture

This section covers the portion of the above figure that is highlighted in blue: the Web client (thin client). This is the default deployment for Siebel CRM installations.

The Web client is an HTTP-, HTML-, Java-applet based application that does not require a client-side software installation.

The load testing of Siebel thin client installations is achieved by recording and replaying HTTP traffic generated by browsers and Java applets.

Dedicated Web clients and mobile Web clients can also be tested using Silk Performer, although those topics are not covered in this section.

HTTP Traffic

To understand recorded scripts, it is helpful to distinguish between two types of HTTP traffic:

  • HTTP traffic generated by browsers
  • HTTP traffic generated by Java applets

HTTP traffic generated by browsers is similar to HTTP traffic generated by typical Web applications (for example, HTML and pictures).

HTTP traffic generated by Java applets consists primarily of POST requests sent to servers. The bodies of HTTP requests have the MIME type application/x-www-form-urlencoded, which is the same MIME type used for form submissions in HTML based applications. HTTP response bodies however are in a proprietary Siebel format.

The first example below shows the body of a typical Java applet HTTP request.

HTTP Request Body from a Java Applet

SWERPC=1&SWECount=5&SWECmd=InvokeMethod&SWEMethod=GetPreference&SWEInputPropSet=%400%600%603%600%60GetPreference%603%60%60pCategory%60SWE%3AListAppletLayout%60pPrefName%60%60SWEJSXInfo%60false%60

BDL Form Definition for a HTTP Request Body from a Java Applet

This example shows the corresponding BDL form definition that is generated by the Web Recorder for this HTTP request.

SALES_START_SWE018 <ENCODE_CUSTOM> :
  "SWERPC"               := "1",
  "SWECount"             := "5",
  "SWECmd"               := "InvokeMethod",
  "SWEMethod"            := "GetPreference",
  "SWEInputPropSet"      := "@0`0`3`0`GetPreference`3``pCategory` SWE:"
                                  "ListAppletLayout`pPrefName``SWEJSXInfo`false`";
Parent topic: Siebel Support


Setting Up Your Project

Note: The Siebel Web client does not require an explicit software installation on the client computer. The client runs within a Web browser. Your browser may however prompt you for security reasons to confirm that the Siebel Java applet should be downloaded and installed. To avoid unnecessary security warnings in the future, add the name of the Siebel Web server to your browser's list of trusted sites.
  1. Select File > New Project to create your project.
  2. Select ERP/CRM > Siebel > Siebel Web Client
  3. Click Next. The Recorder is displayed, ready to begin recording your interactions with the Siebel application.
  4. (optional) If the Siebel installation under test uses load balancing through varying server names or requires additional context management, go to Settings > Active Profile > Web > Recording and adjust Web context management settings.

Scripts that use the host name standardhost in place of a real host name can be replayed against different servers by changing the host name at Settings > Active Profile > Internet > Hosts. The recorder can generate such scripts only if the host name is changed before recording takes place.

  • Configuring TrueLog Explorer
    Explains how to ensure best results on the Differences pane within TrueLog Explorer.
Parent topic: Siebel Support
Related concepts
Web Context Management Settings


Configuring TrueLog Explorer

To ensure best results on the Differences pane within TrueLog Explorer you must add some characters to both the Compare tags and Compare tags HTML lists.
  1. Within TrueLog Explorer, go to Settings > Options > Compare Tags.
  2. Enter the following values into the table rows:
    1. & (ampersand)
    2. * (asterisk)
    3. ` (reverse single quote)
    4. @ (at)
  3. Go to Settings > Options > Compare Tags HTML and enter the same table row values there.
Parent topic: Setting Up Your Project


Dynamic Information in Web Client HTTP Traffic

This section explains that HTTP traffic generated by Siebel Web clients incorporates dynamic information that must be addressed to ensure successful and accurate replay.

  • Error Detection
    Explains that failure to handle dynamic data does not always generate error messages during script replay.
  • Session IDs
    Explains that Siebel Web Server uses session IDs to track user sessions.
  • Time Stamps
    Explains that HTTP communication between Java applets and the Siebel Web Server includes timestamps, which are strings that tell the number of milliseconds since Jan 1, 1970.
  • URL Encoding
    Explains that unsafe HTTP characters are replaced with hexadecimal equivalents.
  • User Input
    Explains that it is desirable if user input recorded during recording sessions can be easily identified and changed in recorded scripts.
  • Dynamic Data
    Explains that Siebel HTTP traffic includes a variety of dynamic data that are sent to servers within HTTP requests.
  • Reformatting Functions
    Explains that the Siebel Web client reformats phone numbers and date/time values that are sent by the server or entered by users.
  • Meaningful Timer Names
    Explains that the Recorder extracts meaningful timer names from form fields.
Parent topic: Siebel Support


Error Detection

Failure to handle dynamic data does not always generate error messages during script replay. This is because the Siebel Web Server does not use HTTP error status codes to indicate errors. Instead, it sends error notifications to the applet, which in turn displays an error message indicating the condition.

This may lead to a false impression of successful replay when in fact load generated on the database tier of the application was different, more than likely less, than it should have been.

The example below shows an HTTP response body sent from a server to a Java applet that describes an error condition. Such a response is returned with the HTTP status code 200 OK, falsely suggesting that the HTTP request was handled successfully.

Error Condition Response Sent from Server to Applet

@0`0`3`2``0`UC`1`SWECount`10`Status`Error`0`1`Errors`0`2`0`Level0`0`ErrMsg`An error happened during restoring the context for requested location`ErrCode`27631`0`0`Notifications`0`

Application Level Error Detection in Recorded Scripts

Silk Performer scripts can detect such application level errors. The Web Recorder generates scripts that contain such checks by adding the lines highlighted in the example below:

use "WebAPI.bdh"
use "SiebelWeb.bdh"

// ...

  transaction TInit
  begin
    WebSetBrowser(WEB_BROWSER_MSIE55);
    WebFormDefineEncodeCustom("base=ENCODE_FORM;"
                              " +'@'; -'!()$,'; -'''");
    SiebelWebInit();
  end TInit;
Parent topic: Dynamic Information in Web Client HTTP Traffic


Session IDs

Siebel Web Server uses session IDs to track user sessions. Servers can be configured to send session IDs either in cookies or in URLs (form fields or query strings; this is the default configuration).

The example below shows an HTTP response header with a Set-Cookie header for a session ID. Session IDs in cookies are handled automatically by Silk Performer.

Siebel Session ID in a Cookie

HTTP/1.1 200 OK
Server: Microsoft-IIS/5.0
Date: Tue, 12 Mar 2002 17:26:01 GMT
Content-Language: en
Cache-Control: no-cache
Content-Type: text/html;charset=windows-1252
Content-Length: 3043
Set-Cookie: _sn=!1.428.556d.3c8e3a29; Version=1; Path=/sales

Siebel Session ID in a URL

This example shows a fragment of an HTML frameset with a frame that incorporates a session ID in a URL.

<frameset>
  <frame name="_sweclient">
  <frame name="_swe" src="http://lab61/sales/start.swe?
                          SWEFrame=top._swe&SWECount=1&
                          _sn=!1.6c0.447b.3ceccd1b
                          &SWECmd=GetCachedFrame">
</frameset>

The Silk Performer Web Recorder generates scripts that accurately handle such session IDs.

Fragments of a Recorded Script with Session IDs

This example shows fragments of a recorded script that handles the above session ID using the following techniques:

  • A variable gsSid is declared to hold the session ID.
  • A parsing function WebParseDataBoundEx is inserted before the function call WebPageLink for parsing of the session ID, which is included in the server response of the WebPageLink function (see example above).
  • The parsed result can be used wherever it is required. In this example, it is required for a form submission.
  • Informational comments enhance readability.
var
  gsSid : string; // !1.6c0.447b.3ceccd1b

// ...

WebParseDataBoundEx(gsSid, sizeof(gsSid), "&_sn=", 1,
                    "&", WEB_FLAG_IGNORE_WHITE_SPACE);
WebPageLink("replace", "Siebel Sales (#2)", 1, "_sweapp");

WebPageForm("http://lab61/sales/start.swe",
            SALES_START_SWE003, "Unnamed page (#2)");

// ...

dclform
  SALES_START_SWE003 <ENCODE_CUSTOM> :
    "SWERPC"     := "1",
    "SWECount"   := "1",
    "_sn"        := gsSid,// value: "!1.6c0.447b.3ceccd1b"
    "SWEJSXInfo" := "false",
    "SWECmd"     := "InvokeMethod",
    "SWEService" := "SWE Command Manager",
    "SWEMethod"  := "PrepareGlobalMenu";
Parent topic: Dynamic Information in Web Client HTTP Traffic


Time Stamps

HTTP communication between Java applets and the Siebel Web Server includes timestamps, which are strings that tell the number of milliseconds since Jan 1, 1970. Proper replays must include correct timestamps. The Silk Performer kernel API (file kernel.bdh) provides the function GetTimeStamp(), which is used to obtain accurate timestamp strings.

The Web Recorder recognizes timestamps and generates scripts that use them.

HTTP Request Body with Timestamp

This example shows the body of a Java applet HTTP request that incorporates a timestamp.

SWEUserName=undisclosed&SWEPassword=undisclosed&SWEForm=SWEEntryForm&SWENeedContext=false&SWECount=0&SWECmd=ExecuteLogin&SWETimeStamp=1023377037797

Corresponding BDL Form with Timestamp

This example shows the corresponding BDL form generated by the Web Recorder. The value of the timestamp has been replaced by a call to the function GetTimeStamp().

dclform
  SWEENTRYFORM002:
    "SWEUserName"    := "undisclosed", // changed
    "SWEPassword"    := "undisclosed", // changed
    "SWEForm"        := "SWEEntryForm", // added
    "SWENeedContext" := "false", // added
    "SWECount"       := "0", // added
    "SWECmd"         := "ExecuteLogin", // added
    "SWETimeStamp"   := GetTimeStamp(); // added, value: "1023377037797"
Parent topic: Dynamic Information in Web Client HTTP Traffic


URL Encoding

According to HTTP specifications, unsafe characters included in transmitted data with the MIME type application/x-www-form-urlencoded must be encoded (escaped). This is achieved by replacing unsafe characters with hexadecimal equivalents and preceding them with percent (%) symbols.

Silk Performer provides four standard encoding types: ENCODE_FORM, ENCODE_ESCAPE, ENCODE_BLANKS and ENCODE_NONE. These encoding types differ in terms of the characters they escape.

Siebel Web client Java applets apply a unique encoding type that differs from the standard Silk Performer encoding types. For this reason, Silk Performer provides a new encoding type, ENCODE_CUSTOM, which can be configured using the function WebFormDefineEncodeCustom.

Siebel uses an encoding type that differs from the standard encoding type ENCODE_FORM in the following respects:

  • Characters not escaped: !()$,'
  • Characters escaped: @

The Silk Performer Web Recorder detects when an HTTP request applies this special encoding type, and then generates a script using the following techniques:

  • Function WebFormDefineEncodeCustom() is used to define the encoding type ENCODE_CUSTOM in the TInit transaction.
  • The encoding type ENCODE_CUSTOM is used in form definitions.

Fragments of a Recorded Script that utilizes ENCODE_CUSTOM

This example shows fragments of a recorded script that utilizes these techniques.

dcltrans
  transaction TInit
  begin
    WebSetBrowser(WEB_BROWSER_MSIE55);
    WebFormDefineEncodeCustom("base=ENCODE_FORM;"
                              " +'@'; -'!()$,'");
  end TInit;

// ...

dclform
  SALES_START_SWE011 <ENCODE_CUSTOM> :
    "SWERPC"                    := "1",
    "SWECount"                  := "4",
    "SWECmd"                    := "InvokeMethod",
    "SWEMethod"                 := "GetPreference",
    "SWEInputPropSet"           := "@0`0`3`0`GetPreference`3``pCategory`"
                                   "Behavior`pPrefName``SWEJSXInfo`false`";
Parent topic: Dynamic Information in Web Client HTTP Traffic


User Input

Generally, it is desirable if user input recorded during recording sessions can be easily identified and changed (for example, randomized) in recorded scripts.

This is especially true for Siebel Web client scripts because Java applets often send values for all input fields to the server. If a new database record is created (for example, for a new customer) and the record is subsequently edited or viewed, input (for example, customer name) may appear multiple times in recorded scripts.

The Silk Performer Web Recorder:

  • Detects user input by assuming that form field values are user input when one of the following is true:
    • Values are enclosed in $ symbols
    • Values are enclosed in underscores(_)
    • Values begin with the character sequence i.
  • Generates a variable for each user input and uses that variable in a script, in place of the original value.

Fragments of a Recorded Script that Includes User Input

var
  gsInputNewName     : string init "$NewName$";
  gsInputNewSite     : string init "_NewSite_";
  gsInputiHttp_x_com : string init "i.http://x.com";

// ...

dclform
  SALES_START_SWE020 <ENCODE_CUSTOM> :
    "SWEMethod"   := "GetQuickPickInfo",
    "SWEViewId"   := "",
    "SWEView"     := "Account List View",
    "SWEApplet"   := "Account List Applet",
    "SWEField"    := "s_1_2_46_0",
    "SWERow"      := "0",
    "SWEReqRowId" := "1",
    "s_1_2_38_0"  := "N",
    "s_1_2_39_0"   := gsInputNewName, // value: "$NewName$"
    "s_1_2_40_0"   := gsInputNewSite, // value: "_NewSite_"
    "s_1_2_41_0"  := "(999) 999-9123",
    "s_1_2_37_0"  := gsInputiHttp_x_com,
                           // value: "i.http://x.com"
    "s_1_2_49_0"    := "",
    "s_1_2_46_0"    := "",
    "s_1_2_44_0"    := "",
    "SWEBCVals"     := "@0`0`0`1``3``2`0`FieldValues`3``FieldArray"
                       "`4*Name8*Location17*Main Phone Number"
                       "`ValueArray`14*" + gsInputNewName +
                       "14*" + gsInputNewSite + "10*9999999123`";

Choose input values during recording based on these descriptions so that the Web Recorder will detect them.

Parent topic: Dynamic Information in Web Client HTTP Traffic


Dynamic Data

Siebel HTTP traffic includes a variety of dynamic data that are sent to servers within HTTP requests. Such data can be parsed from previous server responses and substituted into scripts in place of hard-coded values.

This includes:

  • Existing database record values
  • Row IDs

Siebel uses database keys to identify records in databases. Such keys are present in HTTP traffic emanating from both browsers and applets. Database keys are also known as Row IDs. Accurate handling of row IDs and other dynamic data is essential for successful replay.

Row IDs and other dynamic data can be included in HTML documents (see first example below) or in responses to HTTP requests from Java applets (see second example below).

Dynamic data are always contained in value arrays (lists of values for single rows to be displayed in the Siebel GUI).

Value Array in JavaScript Code, within a HTML Document

<script>
  row = new top._swescript.JSSRecord();
  row.id = "1-9Q1";
  row.valueArray = ["Foo","Bar","1234567890","","Active",
                    "http://www.foo.com/bar","","","USD",
                    "11/26/2002","","USD","11/26/2002",
                    "","","","","N","N","","1-9Q1"];
  S_BC1.Rec(row);
</script>

Value Array in an Applet Response

@0`0`3`2``0`UC`1`Status`Completed`SWEC`10`0`24`Notifications`0`2`0``0`OP`bn`bc`S_BC1`7`0``0`type`SWEIRowSelection`OP`g`br`0`cr`6`bc`S_BC1`size`7`ArgsArray`20*Account Entry Applet1*1`7`0``0`type`SWEIRowSelection`OP`g`br`0`cr`6`bc`S_BC1`size`7`ArgsArray`19*Account List Applet1*11*01*01*01*01*01*0`7`0``0`type`SWEIPrivFlds`OP`g`br`0`cr`6`bc`S_BC1`size`7`ArgsArray`19*Account List Applet11**BlankLine11*?11**BlankLine21*?9**HTML URL1*?15**HTML RecNavNxt1*?`7`0``0`type`SWEICanInvokeMethod`OP`g`br`0`cr`6`bc`S_BC1`size`7`ArgsArray`19*Account List Applet1*01*11*11*01*21*11*31*01*41*11*51*11*61*11*71*11*81*11*91*12*101*02*111*02*121*12*131*02*141*12*151*12*161*12*171*12*181*12*191*12*201*12*211*12*221*12*231*12*241*12*251*02*261*12*271*12*281*02*291*02*301*02*311*02*321*02*331*02*341*12*351*12*361*1`7`1``0`OP`iw`index`7`br`0`cr`6`bc`S_BC1`size`7`ar`0`1`0`FieldValues`0`ValueArray`3*Foo3*Bar10*12345678900*6*Active22*http://www.foo.com/bar0*0*3*USD10*11/26/20020*3*USD10*11/26/20020*0*0*0*1*N1*N0*5*1-9N9`8`0``0`OP`dw`index`7`br`0`cr`6`bc`S_BC1`nr`1`size`7`ar`0`8`0``0`value`0`OP`sc`br`0`cr`6`bc`S_BC1`size`7`ar`0`state`n`8`0``0`value`1`OP`sc`br`0`cr`6`bc`S_BC1`size`7`ar`0`state`n`8`0``0`value`7`OP`sc`br`0`cr`6`bc`S_BC1`size`7`ar`0`state`cr`8`0``0`value`1`OP`sc`br`0`cr`6`bc`S_BC1`size`7`ar`0`state`nrk`8`0``0`value`13`OP`sc`br`0`cr`6`bc`S_BC1`size`7`ar`0`state`nr`6`0``0`OP`nd`br`0`cr`6`bc`S_BC1`size`7`ar`0`2`0``0`OP`en`bc`S_BC1`0`3`

Dynamic information typically appears in the dclform section of scripts.

When required, the Web Recorder automatically generates a parsing function (WebParseDataBoundEx) and substitutes parsed values wherever they appear in scripts. Parsing functions parse for complete value arrays in HTML and applet responses. The Recorder uses an appropriate tokenizing function SiebelTokenHtml or SiebelTokenApplet to retrieve individual tokens from parsed value arrays.

Script Fragment Utilizing Parsing Functions

This example shows fragments of a recorded script that utilizes the following techniques:

  • Variables are declared for the value array (gsRowValArray and gsRowValArray_001).
  • Parsing functions WebParseDataBoundEx are inserted to parse the value arrays, which are included in the server response of the subsequent function (see examples above).

The parsed result can be used wherever it is required. In this example, individual tokens of the parsed values occur in various locations in form definitions. Informational comments are used to enhance readability.

var
  gsRowValArray     : string; // = ["Foo","Bar","1234567890","","Active",
                              //    "http://www.foo.com/bar","","","USD",
                              //    "11/26/2002","","USD","11/26/2002",
                              //    "","","","","N","N","","1-9Q1"];
  gsRowValArray_001 : string; // 3*Foo3*Bar10*12345678900*6*Active
                              // 22*http://www.foo.com/bar
                              // 0*0*3*USD10*11/26/20020*3*USD10*11/26/2002
                    // 0*0*0*0*1*N1*N0*5*1-9N9

// ...

  WebParseDataBoundEx(gsRowValArray, sizeof(gsRowValArray),
            "row.valueArray", 2, "S_", WEB_FLAG_IGNORE_WHITE_SPACE, 1);
// function call where parsing function is in effect

  WebParseDataBoundEx(gsRowValArray_001, sizeof(gsRowValArray_001),
                     "ValueArray`", 1, "`", WEB_FLAG_IGNORE_WHITE_SPACE, 1);
// function call where parsing function is in effect

// ...

dclform

// ...

SALES_ENU_START_SWE016 <ENCODE_CUSTOM> :
  "SWEMethod"  := "Drilldown",
  "SWEView"    := "Account List View",
  "SWEApplet"  := "Account List Applet",
  "SWEReqRowId":= "1",
   "s_1_2_40_0"      := SiebelTokenHtml(gsRowValArray, 0), // value: "Foo"
   "s_1_2_41_0"      := SiebelTokenHtml(gsRowValArray, 1), // value: "Bar"
  "s_1_2_42_0" := "(123) 456-7890",
  "s_1_2_51_0" := "",
   "s_1_2_47_0"      := SiebelTokenHtml(gsRowValArray, 4), // value: "Active"
  "s_1_2_45_0" := SiebelTokenHtml(gsRowValArray, 5),
                       //value:"http://www.foo.com/bar"
  "SWECmd"     := "InvokeMethod",
  "SWERowId"   := SiebelTokenHtml(gsRowValArray, 20), // value: "1-9Q1"
  "SWETS"      := GetTimeStamp(); // value: "1038305654969"

// ...

SALES_ENU_START_SWE022 <ENCODE_CUSTOM> :
  "SWEMethod"  := "Drilldown",
  "SWEView"    := "Account List View",
  "SWEApplet"  := "Account List Applet",
  "SWEReqRowId":= "1",
   "s_1_2_40_0"   := SiebelTokenApplet(gsRowValArray_001, 0), // value: "Foo"
   "s_1_2_41_0"   := SiebelTokenApplet(gsRowValArray_001, 1), // value: "Bar"
  "s_1_2_42_0" := "(123) 456-7890",
  "s_1_2_51_0" := "",
  "s_1_2_47_0" := SiebelTokenApplet(gsRowValArray_001, 4), // value: "Active"
  "s_1_2_45_0" := SiebelTokenApplet(gsRowValArray_001,5),
                                    // value: "http://www.foo.com/bar"
  "SWECmd"     := "InvokeMethod",
  "SWERowId"   := SiebelTokenApplet(gsRowValArray_001, 20), // value: "1-9N9"
  "SWETS"      := GetTimeStamp(); // value: "1038305711331"
Parent topic: Dynamic Information in Web Client HTTP Traffic


Reformatting Functions

The Siebel Web client reformats phone numbers and date/time values that are sent by the server or entered by users. Therefore the format of such values in client-sent HTTP request bodies is different from the format that is used in server-sent HTTP response bodies.

Phone Number in Server-Response Body

10*987140255510*78140110000*0*0*22*main.contact@MyCompany.com5*1-FIH

Phone Number in Recorded Script, Reformatted by the Siebel Web Client

"s_1_1_25_0" := "(987) 140-2555";

Without modification, the format used in request bodies would also be used in recorded scripts, making it impossible to replace such values with parsed values.

Reformatting Function for Phone Numbers

To allow such reformatted strings to be replaced with parsed values, the Silk Performer Web recorder records an appropriate reformatting function that mimics the Siebel Web client's reformatting and records actual values in the same format that is used in server responses.

"s_1_1_25_0" := SiebelPhone("9871402555");

Using a Parsed Value as a Parameter of a Reformatting Function

Unless a value is an input value, values can generally be replaced with parsed values in a second step. The Recorder actually records a parsed value instead of a hard-coded string.

"s_1_1_25_0" := SiebelPhone(SiebelTokenApplet(gsParsed, 5));

The following reformatting functions are available and are automatically recorded as required:

  • SiebelPhone
  • SiebelDate
  • SiebelTime
  • SiebelDateTime
  • SiebelDecodeJsString
  • SiebelParam
Parent topic: Dynamic Information in Web Client HTTP Traffic


Meaningful Timer Names

The Recorder extracts meaningful timer names from form fields. This makes it easier for human readers to interpret scripts, TrueLogs, and performance reports.

Meaningful Timer Names

Here is an example of an intuitive timer name.

WebPageForm("http://standardhost/sales_enu/start.swe",
            SALES_ENU_START_SWE022,
            "Account List Applet: InvokeMethod: Drilldown");

// ...

dclform

// ...

SALES_ENU_START_SWE022 <ENCODE_CUSTOM> :
  "SWEMethod"  := "Drilldown",
  "SWEView"    := "Account List View",
  "SWEApplet"  := "Account List Applet",
// more form fields
  "SWECmd"     := "InvokeMethod",
  "SWERowId"   := SiebelTokenApplet(gsRowValArray_001, 20),
  "SWERowIds"  := "",
  "SWEP"       := "",
  "SWETS"      := GetTimeStamp(); // value: "1038305711331"
Parent topic: Dynamic Information in Web Client HTTP Traffic


Best Practices

This topic explains the common pitfalls, offers hints, and explains best practices for successfully testing Siebel Web clients.

Read-Only Transactions

A read-only transaction is a transaction in which new records aren't inserted and data is not altered. Recorded scripts for read-only transactions run without modification.

Such scripts may however contain parsing functions for value arrays. Parsing functions may, for example, parse the value array of the third record in a table. If during replay this table contains fewer than 3 records, no value array can be parsed and the result may be replay errors. Such situations can be avoided by adjusting the occurrence parameter of parsing functions so that existing value arrays are parsed.

The better solution however is to ensure that each table in a database contains adequate records during load tests, thereby avoiding the problem altogether.

Read/Write/Update Transactions

A writing transaction is a transaction that inserts new records or changes the values of existing records.

Required Script Customizations

Scripts for writing transactions require only minimal customization to ensure successful replay. This is because value arrays for new records can be parsed from server responses.

When modifications are required for successful replay, it is generally because many tables in Siebel do not allow duplicate records. The circumstances by which Siebel considers records to be duplicates vary between tables. In most instances, a certain combination of record fields must be different for Siebel to consider a record unique.

For successful replay, these fields must be changed, even with Try Script runs. This can be done easily when the Web Recorder creates these values as variables.

For Try Script runs, it is sufficient to manually change these values directly in scripts. For tests however, data files must be prepared and scripts must be customized in such a way that each virtual user inserts records with unique value combinations.

Be Aware of Empty Tables

HTTP traffic generated by the insertion of records into empty tables differs significantly from HTTP traffic generated by inserting records into tables that are already populated with one or more records. For this reason, scripts that record the insertion of records into empty tables can not later be used during replay sessions once tables have been populated - and vice versa.

To avoid such problems, ensure that you do not insert records into empty tables during recording sessions. Also ensure that tables are not emptied before or during load tests.

Note that the following scenarios are not affected by these constraints:

  • Creating new records in tables that include other records (for example, accounts).
  • Creating new records in a table associated with the records just created (for example, creating new notes for new accounts). While the notes table for newly created accounts is empty, the notes table of newly created accounts during script replay is also empty, so such scripts will not cause problems.
Parent topic: Siebel Support


Microsoft Silverlight Support

Prerequisites

Transformation is enabled for HTTP requests and responses that have the HTTP header Content-Type set to "application/soap+msbin1" or "application/msbin1". If you need to transform data with a different HTTP Content-Type header, see Transformation of Custom Content-Types.

Setting up a Microsoft Silverlight Project

The workflow for testing Microsoft Silverlight browser-based applications with Silk Performer is the same as the workflow used for testing Web-based applications, with the following exception:

  • On the Outline Project - Workflow dialog, you must select Silverlight under the Web browser node.
Parent topic: Load Testing Specific Application Types


Terminal Emulation Support

Silk Performer’s support for terminal emulation applications enables the recording of terminal-emulator traffic based on the Telnet protocol (“green screen” applications). Supported terminal types include VT100 and VT200 (UNIX, IBM AS400) and IBM mainframes accessed via TN3270(E) & TN5250.

A prerequisite for recording terminal-emulator traffic is an installed terminal-emulator for accessing host applications, while the recorder records the telnet traffic which results. Many such emulators are available on the market (for example, Rumba).

Note: For additional details regarding Silk Performer support for terminal emulation applications, please see Miscellaneous Tutorials, a PDF that accompanies your Silk Performer installation at Documentation > Tutorials.

Script Customization

For terminal-emulation script customization details, please see TrueLog Explorer Help.

Testing IBM Mainframe Protocols

The Host Screen Info page of terminal emulation TrueLogs offers controls for all fields and statuses that appear in recorded and replayed screens. These controls offer easy access to field-value and value-status parsing/verification functions.

IBM terminals rely on EBCDIC code pages that vary based on locality. Silk Performer chooses an EBCDIC code page among the code pages installed on the system. If national language characters are not displayed correctly it is possible to change the code page during project configuration.

IBM code pages control translation of human-readable ASCII input data (for example, search parameters) into and out of binary hexadecimal representation. This translation process facilitates script customization.

  • Creating a Terminal Emulation Project
    To test a terminal emulation application you must set up a project with the appropriate terminal-emulation application type.
  • Configuring Terminal Emulation Profile Settings
    Before recording, you must configure profile settings for the recording of terminal-emulation applications via terminal emulators.
  • Setting Up a Terminal Emulation Recording Profile
    Before recording a terminal-emulation application, you must set up a TCP/IP-based recording profile.
  • Recording Terminal Emulation Applications
    To record a test script for your terminal-emulation application you must select your recording profile, perform the required user interactions, and execute a Try Script to test your script.
  • Terminal Emulation Session Customization
    When session customization of terminal-emulation application test scripts is required, customizations must be performed manually with some assistance from TrueLog Explorer.
Parent topic: Load Testing Specific Application Types
Related concepts
Working With Terminal-Emulation Applications


Creating a Terminal Emulation Project

  1. Click Start here on the Silk Performer workflow bar.
    Note: If another project is already open, choose File > New Project from the menu bar and confirm that you want to close your currently open project.
    The Workflow - Outline Project dialog box opens.
  2. In the Name text box, enter a name for your project.
  3. Enter an optional project description in Description.
  4. From the Type menu tree, expand the Terminal Emulation application type node and select the terminal emulation type you need.
  5. Click Next to create a project based on your settings.
The Workflow - Model Script dialog box appears.
Parent topic: Terminal Emulation Support


Configuring Terminal Emulation Profile Settings

  1. In Silk Performer, expand the Profiles node in the Project tree.
  2. Right-click the profile that you want to configure and choose Edit Profile.
    Tip: Alternatively, you can choose Settings > Active Profile from the menu bar.

    The Profile - [<profile name>] dialog box opens, and the Replay category is displayed in the shortcut list on the left.

  3. In the shortcut list on the left, click the Record button. The Record category is displayed.
  4. In the shortcut list, click the Terminal Client icon.
  5. Click the Telnet tab.
  6. In the Telnet settings area, specify one of the following Telnet detection modes:
    • Click the Always assume Telnet-mode option button to instruct the recorder to assume that each connection is a Telnet connection. Use this option for troubleshooting purposes only.
    • Click the Auto-detect Telnet-mode option button to instruct the recorder to automatically detect Telnet on each new connection (default).
    • Click the Never assume Telnet-mode option button to instruct the recorder to assume that no connections are Telnet connections. Use this option for troubleshooting purposes only.
  7. In the Command prompt string text box, specify a command-prompt string that the recorder uses to script WebTcpipRecvPacketsUntilData functions wherever possible. This string increases the effectiveness of recorded scripts for dynamic content.
  8. In the Terminal properties section, select one of the following items from the Log level list box:
    • None
    • Error
    • Normal
    • Debug
  9. Ensure that the specific terminal type you are testing is displayed in the Terminal type list box. This setting was configured automatically when you selected the application type for the project. When correctly specified, the recorder scripts the appropriate terminal-type initialization functions and renders the screens to the TrueLog.
  10. In the Configuration string text box, initialize the terminal emulator with a custom configuration string. For available options, refer to your terminal emulator documentation.
  11. Specify the following Screen values to indicate the appearance of the terminal screen to the recorder:
    • Type a value in the rows text box to indicate the height of the terminal screen. An empty value lets Silk Performer detect the height during session initialization.
    • Type a value in the columns text box to indicate the width of the terminal screen. An empty value lets Silk Performer detect the width during session initialization.
    • Check the Colors check box to specify the default color to use on the terminal screen.
    The supplied values overrule the default values that Silk Performer may detect. If your terminal application uses a custom screen size, make sure to set these values before you record a script in order to replay the script without errors.
  12. In the Host code page text box, specify the code page that the server uses. The code page is used for various data conversions, and all available code pages have been installed with the system. If the required code page is not listed, you can install it. Ensure that the selected code page is also available on each agent computer. To review all installed code pages, or to enable a specific code page, go to Start > Control Panel > Regional and Language Options > Advanced . Only the host code pages that are listed and enabled with a checkmark are available.
  13. Click the Advanced tab and check the Record basic functions check box to prevent the recorder from scripting synchronized receive-functions, such as WebTcpipScreenRecvPacketsUntilCursor and WebTelnetScreenRecvRecordsUntilStatus. If this option is enabled, scripted receive functions do not rely on rendered screen content. This option is enabled by default when a terminal type is not specified.
  14. Click OK to save your settings.
Parent topic: Terminal Emulation Support


Setting Up a Terminal Emulation Recording Profile

  1. From the Settings menu, select System.
  2. Click the Recorder button.
  3. Click the Add button.
  4. On the Recording Profile dialog, give the profile a name in the Profile name field.
  5. Click Browse and select the .exe file of the terminal emulator on your local system.
    Note: All other settings on this dialog are standard for all TCP/IP-based applications.
  6. If you are using RUMBA as your terminal emulator, check the Record executable is different from application path check box.
  7. Enter WDDspPag.exe in the Record executable field.
  8. Check the TCP/IP check box (note that Silk Performer TCP/IP-level API facilitates terminal-emulation application support).
  9. Click Web Settings. The Web Settings dialog box opens.
  10. From the WinSock list box, select ws2_32.dll.
  11. Click OK to close the Web Settings dialog box.
  12. Click OK to close the Recording Profile dialog box.
The new profile now appears on the Recording Profiles page.
Parent topic: Terminal Emulation Support


Recording Terminal Emulation Applications

  1. Click Model Script on the workflow bar. The Workflow - Model Script dialog box appears.
  2. From the Recording Profile menu tree, select your terminal-emulation recording profile.
  3. Enter the location of your terminal-emulation application in the Command line field.
  4. Click Start recording. The Silk Performer Recorder dialog opens in minimized form, and the client application starts.
  5. Using the client application, conduct the kind of interaction with the target server that you want to simulate in your test. The interaction is captured and recorded by the Recorder. A report of your actions and of the data downloaded appears on the Actions page.
  6. When recording is complete, close the application, close the recorder, and save the test script.
  7. To confirm that your test script runs as expected, execute a Try Script run in animated mode; you will then be able to view the results of the test run in TrueLog Explorer.
Parent topic: Terminal Emulation Support
Related concepts
Working With Terminal-Emulation Applications


Terminal Emulation Session Customization

Session customization of terminal emulation application test scripts is normally not required. If session customizations are required, they must be partly performed manually. However, TrueLog Explorer can be used to insert parsing functions into test scripts.

In some cases the synchronization between replay and a host application may not work well, for example if the requested screen is not complete but the cursor position already assumes a completed screen. A recorded cursor synchronization function in the script will be satisfied with the first portion of the screen and continue executing the script out of synchronization, which may lead to replay errors. In such a case you would have to replace the recorded synchronization function(s) manually with a more suitable synchronization function in the script (for example, WebTcpipRecvPacketsUntilData or WebTelnetRecvPacketsUntilData).

Parent topic: Terminal Emulation Support
Related concepts
TCP/IP Functions Reference


TCP/IP Based Protocol Support

This section explains how to develop load test scripts for applications that use legacy or custom TCP/IP based protocols. It explores the challenges that are commonly encountered in this type of testing: dealing with dynamic server responses, translating between character code tables, string manipulation of binary data, and more.

Three protocols are examined in detail: Telnet, TN3270e, and a custom TCP/IP based protocol. Using recorded scripts from actual load test projects as examples, you will be guided through the process of recording an application, analyzing traffic, configuring recording rules, and customizing a script.

  • Overview
    Explains that with Silk Performer, you can record protocols at the TCP level and customize the resulting scripts using WebTcpip functions.
  • Script Customization
    This section covers the challenges that are typically faced when customizing TCP-based load test scripts: dynamically receiving and verifying server responses, character conversion, and string manipulation of binary data.
  • Telnet, TN3270e, and Custom Protocols
    This section applies the theories discussed in the preceding topics to specific real-world examples.
  • Recorder Settings
    Explains how to configure the two available mechanisms for recording TCP/IP based protocol traffic.
Parent topic: Load Testing Specific Application Types


Overview

Note: The following protocols are directly supported by Silk Performer and do not require the types of customizations that are described in this section. Protocols not listed below, including so called legacy systems, do require script customization:
  • TN3270
  • TN5250
  • VT100
  • VT200+

All of the protocols discussed in this section are based on TCP/IP. With Silk Performer, you can record protocols at the TCP level and customize the resulting scripts using WebTcpip functions. With Silk Performer enhanced TCP/IP support, TrueLog Explorer, and rule-based recording, the process is straightforward.

This section has two objectives:

  • To take you through the process of analyzing recorded custom TCP/IP traffic and give you the generic tools and methodology you need to customize such traffic.
  • To analyze two protocols in-depth: Telnet and TN3270e.

Memory Usage of TCP/IP Virtual Users

Each virtual user running in its own process requires approximately 1.6 MB system memory.

Running more than one user per process results in the following memory consumption:

  • 25 vusers: Approx. 0.2 MB per vuser
  • 50 vusers: Approx. 0.1 MB per vuser
Parent topic: TCP/IP Based Protocol Support


Script Customization

This section covers the challenges that are typically faced when customizing TCP-based load test scripts: dynamically receiving and verifying server responses, character conversion, and string manipulation of binary data.

  • Character Conversion
    Explains common challenges with converting characters along with corresponding solutions.
  • Dynamically Receiving Server Responses
    Explains that full control of client requests can be easily achieved however anticipating appropriate server responses can be challenging.
  • String Manipulation of Binary Data
    Explains how to manage request parameterization and searching in response data.
  • Session IDs
    Explains that since many TCP/IP based protocols rely on TCP/IP connections between server and client to remain open and active during sessions, they don't contain session IDs.
  • Finding Information
    Explains where you can find samples of RFCs.
Parent topic: TCP/IP Based Protocol Support


Character Conversion

Following is a sampling of TCP/IP traffic recorded by Silk Performer:

WebTcpipSendBin(hWeb0,
    "\h00000000007DD7D311D57CA2899392F0"        // ·····}×Ó·Õ|¢···ð
    "\hF0F14011D74CA2899392F0F0F140FFEF", 32);  // ðñ@·×L¢···ððñ@·ï
WebTcpipRecvExact(hWeb0, NULL, 645);

Customization of such a script may at first appear daunting. The server responses (not shown in the example) look much like the client request. They do not include a single readable character.

The reality is that customization of such a script is fairly simple. The server is an IBM mainframe that uses the EBCDIC (Extended Binary Coded Decimal Interchange Code) character set rather than the more familiar ASCII character set. There is a simple one-to-one mapping between these two character sets, which can be implemented as a Silk Performer function.

Other possible causes for traffic that contains unreadable strings:

Reason | Consequence
Traffic uses a character set other than ASCII. | Character mapping functions can easily be implemented in Silk Performer BDL language.
Traffic is encrypted with a custom encryption algorithm (for example, one that does not rely on SSL, which is automatically supported by Silk Performer). | The encryption/decryption routines should be re-implemented in BDL, or made accessible to Silk Performer using a DLL or a Silk Performer framework (for example, Java Framework).
Traffic does not contain any strings, only numbers sent as binaries. | In such instances you do not have to worry about strings.
Parent topic: Script Customization


Dynamically Receiving Server Responses

Full control of client requests can be easily achieved however anticipating appropriate server responses can be challenging. Most significantly, virtual users must know when server responses are complete so that they can proceed with subsequent requests, or raise errors if server responses contain errors or aren't complete.

The Silk Performer recorder doesn't know in advance about the semantics of the TCP based protocols it records. Therefore, all server responses are recorded as follows:
WebTcpipRecvExact(hWeb0, NULL, 26);

During replay, the virtual user expects to receive exactly 26 bytes from the server. It then continues on with the next statement in the script. If the server sends more then 26 bytes, the bytes are received by the next WebTcpipRecvExact statement (making all further script execution unpredictable). If the server sends fewer bytes, WebTcpipRecvExact will report a timeout error.

Therefore this line can remain unchanged only if the number of response bytes won't change under any circumstances. If response length cannot be guaranteed, scripts must be customized so that they can handle server responses of varying length.

Appropriate customization depends on the semantics of the protocol. Three common scenarios are reflected by Silk Performer API functions, which simplify the customization process.

Case I: Packet Length Contained in the Packet

The length of request and response data may be encoded into packets at a defined position (typically in the packet header). The Silk Performer function WebTcpipRecvProto and its sibling, WebTcpipRecvProtoEx, can adequately handle such situations. They allow for definition of the position and length of packet-length information in response data. For example, the following BDL code line will be used if the length of the response data remains a two-byte sequence in the first two bytes (for example, position 0) of the server response:

WebTcpipRecvProto(hWeb, 0, 2, TCP_FLAG_INCLUDE_PROTO,
sData, sizeof(sData), nReceived);

Case II: Termination Byte Sequence

In this scenario data packets are terminated by a constant byte sequence. The corresponding Silk Performer function is WebTcpipRecvUntil. If, for example, the end sequence is defined by the two-byte sequence 0xFF00, the following line would be appropriate:

WebTcpipRecvUntil(hWeb, sResp, sizeof(sResp), nRecv,
 "\hff00", 2);

Case III: No Information on Response Packet Size

This is the most challenging of the three scenarios. You can use a combination of the functions WebTcpipRecv, which receives a buffer of unknown length from the server, and WebTcpipSelect, which checks whether or not a subsequent WebTcpipRecv operation on the provided connection handle will block or succeed immediately.

Rule Based Recording

An advanced feature offered by Silk Performer is rule-based recording. You can configure the TCP/IP recorder to be aware of the semantics of proprietary TCP/IP protocols. In particular, the recorder can be configured for two of the scenarios discussed earlier (Packet length contained in the packet and termination byte sequence).

As a result, the recorder can automatically generate correct WebTcpipRecvProto(Ex) and WebTcpipRecvUntil functions so that further customization for this part of the script isn't required.

When configuring recording rules, you write a configuration file encoding the recording rules in XML and save them to the project's Documents folder (project specific rules) or in the public or the user’s RecordingRules directory (global rules). Recording rule files carry the file extension .xrl.

Rule-based recording exists for TCP/IP and HTTP, however only recording rules for TCP/IP are discussed in this section.

Parent topic: Script Customization


String Manipulation of Binary Data

Request Parameterization

Example code contained in a recording of a TCP session:

WebTcpipSendBin(hWeb0, "\h0000104F0000005065746572FFFF",
14); // ···O···Peter

The actual business data sent here, the data that should be parameterized, is "Peter" = 0x50 65 74 65 72, but that will not work here. "\h0000104F000000" + sName + "\hFFFF" will not yield the results you might expect. The problem is caused by the zero (0x00) bytes in this string, which Silk Performer (like C) uses for string termination. Therefore all bytes after the first zero byte in a string are ignored when performing such string concatenation.

For manipulation of binary data that may contain zero bytes, you should use the function SetMem. Using the function library detailed below, the above request can be broken into the following lines:

ResetRequestData();
AppendRequestData("\h0000104f000000", 7);
AppendRequestData(sName); // e.g., "Peter"
AppendRequestData("\hFFFF");
SendTcpipRequest(hSend);

The function library is included using an include file (*.bdh). It uses two global variables for the request data and request data length. The function AppendRequestData appends a string (which may contain zero bytes) to the request buffer, and SendTcpipRequest sends the request data using an open TCP connection.

Here are the contents of the include file, which consists of three functions:

const
  BUFSIZE := 10000; // maximal size for request data
var
  // global variables for Request data contents and length
  gsRequestData : string(BUFSIZE);
  gnRequestLen  : number init 0;

dclfunc
  // start a new request string
  function ResetRequestData
  begin
    gnRequestLen := 0;
  end ResetRequestData;

  // append data (of length nLen) to the request string
  // if nLen=0, use strlen(sData) instead
  function AppendRequestData(sData: string;
                             nLen: number optional): number
  begin
    if nLen = 0 then nLen := strlen(sData); end;
    if nLen + gnRequestLen <= BUFSIZE then
      // append sData to gsRequestData
      SetMem(gsRequestData, gnRequestLen + 1, sData, nLen);
      // the request length has grown by nLen bytes:
      gnRequestLen := gnRequestLen + nLen;
    else
      RepMessage("Request buffer too small!",
                  SEVERITY_ERROR);
    end;
    AppendRequestData := gnRequestLen;
  end AppendRequestData;

  // Send the request buffer
  // (TCP-connection identified by hTcp)
  function SendTcpipRequest (hTcp: number): boolean
  begin
    SendTcpipRequest :=
      WebTcpipSendBin(hTcp, gsRequestData, gnRequestLen);
  end SendTcpipRequest;

Searching in Response Data

When zero bytes are contained in response data, it makes it difficult to search for strings. The reason is that the StrSearch and StrSearchDelimited functions search in a source string only until they hit the first zero byte, which is interpreted as the string terminator.

Silk Performer offers the function BinSearch, which works on binary data exactly as StrSearch does on strings. You can search for a string (or a sequence of binary data) in response data as follows:
nPos := BinSearch(sResponseData, nResponseLength, sSearch);

There is no binary counterpart for the StrSearchDelimited function. If you only want to search for strings (as opposed to binary data containing zero bytes), a workaround is to introduce a function that first eliminates all zero bytes from the response data by mapping them (for example, to the byte 0xFF).

Here is a simple version of such a function. Note that it works only if sLeftVal, sRightVal and the string you are searching are strings (meaing, they don't contain zero bytes).

function BinSearchDelimited(sSource   : string;
                            nSrcLength: number;
                            sLeftVal  : string;
                            sRightVal : string)
                           :string(BUFSIZE)
var
  i : number;
begin
  // eliminate zero bytes in the source string
  for i:=1 to nSrcLength do
    if ord(sSource[i]) = 0 then
      sSource[i] := chr(255);
    end;
  end;
  StrSearchDelimited(BinSearchDelimited, BUFSIZE, sSource,
                    sLeftVal, 1, sRightVal, 1,
                    STR_SEARCH_FIRST);
end BinSearchDelimited;
Parent topic: Script Customization


Session IDs

Since many TCP/IP based protocols rely on TCP/IP connections between server and client to remain open and active during sessions, they don't contain session IDs. Therefore the problems that can arise when customizing test scripts for stateless protocols such as HTML often don't exist.

There are of course exceptions to this rule, so pay attention to session IDs. The TCP support in TrueLog Explorer can be helpful in this regard.

Parent topic: Script Customization


Finding Information

Standard protocols are typically defined in Requests for Comments (RFCs). You'll find samples of these at http://www.rfc-editor.org/rfcxx00.html. [RFC854], [RFC2355] and others are relevant to the examples included in the following topics.

Parent topic: Script Customization


Telnet, TN3270e, and Custom Protocols

The following topics apply the theories discussed in the preceding topics to specific real-world examples.

  • Telnet Protocol
    Explains that the primary goal of Telnet is to facilitate the interfacing of terminal devices and terminal-oriented processes.
  • TN3270e Protocol
    Explains that the TN3270e protocol is a method of emulating 3270 terminal and printer devices using Telnet.
  • Custom TCP/IP Based Protocols
    Includes an example from an application that uses an entirely custom TCP/IP based protocol.
Parent topic: TCP/IP Based Protocol Support


Telnet Protocol

The introduction of RFC 854, the Telnet protocol specification, states: "The purpose of the TELNET Protocol is to provide a general, bi-directional, eight-bit byte oriented communications facility. Its primary goal is to facilitate the interfacing of terminal devices and terminal-oriented processes."

A Telnet session consists of two main parts:

  • A connection is established, and session details and options are negotiated between client and server.
  • The application launches. From that point forward, generated traffic is user-driven.

The following Silk Performer Telnet script comes from a project in which a script was recorded and customized from a Telnet session with VT220 terminal emulation. The client (the terminal emulation software) is NT based and the server application resides on a Unix box.

Part I: Establishing a Connection

Here is the first part of the Telnet session recording:

WebTcpipConnect(hWeb0, "myserver", 23);

WebTcpipRecvExact(hWeb0, NULL, 3);
WebTcpipSendBin(hWeb0, "\hFFFC24", 3); // ·ü$

WebTcpipRecvExact(hWeb0, NULL, 3);
WebTcpipSendBin(hWeb0, "\hFFFB18", 3); // ·û·

WebTcpipRecvExact(hWeb0, NULL, 6);
WebTcpipSendBin(hWeb0, "\hFFFA18005654323230FFF0", 11);
                                   // ·ú··VT220·ð

WebTcpipRecvExact(hWeb0, NULL, 3);
WebTcpipSendBin(hWeb0, "\hFFFC20", 3); // ·ü

WebTcpipRecvExact(hWeb0, NULL, 60);

There is only one readable string in the inline comments: VT220, the terminal type. This is a first hint at the semantics of this Telnet traffic; server and client are negotiating terminal type and various other session settings.

In terms of script customization, nothing needs to be changed here. Silk Performer virtual users should negotiate session settings exactly as the terminal emulation software has done here.

Nevertheless, an analysis of the record.log file, along with the information from RFC 854 (the Telnet protocol specification), reveals how the conversation was achieved. The first part of the log is translated into TELNET codes in the following table:

Server-to-Client | Client-to-Server
FF FD 24 (IAC DO ENVIRONMENT VARIABLES) |
 | FF FC 24 (IAC WON'T ENVIRONMENT VARIABLES)
FF FD 18 (IAC DO TERMINAL-TYPE) |
 | FF FB 18 (IAC WILL TERMINAL-TYPE )
FF FA 18 01 FF F0 (IAC SB TERMINAL-TYPE SEND IAC SE) |
 | FF FA 18 00 56 54 32 32 30 FF F0 (IAC SB TERMINAL-TYPE IS "VT220" IAC SE)
FF FD 20 (IAC DO TERMINAL-SPEED) |
 | FF FC 20 (IAC WON'T TERMINAL-SPEED)
… | …

Each command begins with the "Interpret as Command" (IAC) escape character 0xFF. Server and client agree on a terminal type (VT220) and a number of other session settings. Telnet session settings that can be negotiated between client and server include terminal speed, echo, "suppress go ahead," window size, remote flow control, and more.

Part II: User Interaction

The second part of the script contains the user interaction. The script generated from the recording session looks like this:

// …
    // login: send username
    WebTcpipSend(hWeb0, "t");
    WebTcpipRecvExact(hWeb0, NULL, 1);
    WebTcpipSend(hWeb0, "e");
    WebTcpipRecvExact(hWeb0, NULL, 1);
    WebTcpipSend(hWeb0, "s");
    WebTcpipRecvExact(hWeb0, NULL, 1);
    WebTcpipSend(hWeb0, "t");
    WebTcpipRecvExact(hWeb0, NULL, 1);
    WebTcpipSend(hWeb0, "u");
    WebTcpipRecvExact(hWeb0, NULL, 1);
    WebTcpipSend(hWeb0, "se");
    WebTcpipRecvExact(hWeb0, NULL, 2);
    WebTcpipSend(hWeb0, "r");
    WebTcpipRecvExact(hWeb0, NULL, 1);
    WebTcpipSend(hWeb0, "\r");
    WebTcpipRecvExact(hWeb0, NULL, 2);
    WebTcpipRecvExact(hWeb0, NULL, 10);
    // login: send password
    WebTcpipSend(hWeb0, "password\r");
    WebTcpipRecvExact(hWeb0, NULL, 2);
    WebTcpipRecvExact(hWeb0, NULL, 230);
    WebTcpipRecvExact(hWeb0, NULL, 47);
    WebTcpipRecvExact(hWeb0, NULL, 58);
    WebTcpipRecvExact(hWeb0, NULL, 40);
    WebTcpipRecvExact(hWeb0, NULL, 594);
    WebTcpipRecvExact(hWeb0, NULL, 340);
    WebTcpipRecvExact(hWeb0, NULL, 1);
    WebTcpipRecvExact(hWeb0, NULL, 188);
    WebTcpipRecvExact(hWeb0, NULL, 147);
    // Choose "1" from main menu and hit RETURN
    ThinkTime(7.0);
    WebTcpipSend(hWeb0, "1");
    WebTcpipRecvExact(hWeb0, NULL, 1);
    WebTcpipSend(hWeb0, "\r");
    WebTcpipRecvExact(hWeb0, NULL, 2);
    WebTcpipRecvExact(hWeb0, NULL, 7);
    WebTcpipRecvExact(hWeb0, NULL, 21);
    WebTcpipRecvExact(hWeb0, NULL, 691);
    // …

As you can see from the inline comments, this part of the script contains a login process (account name and password), followed by the selection of an item from a main menu (by hitting the 1 and <RETURN> keys).

If you leave a recorded script unchanged, it will typically play back without problems. However changes do have to be applied to scripts for data parameterization, and response verification.

Each keystroke is sent to the server as a single byte (without header or footer). The log file reveals that the server sends back the same byte as an echo:

WebTcpipSend(hWeb0, "s");
WebTcpipRecvExact(hWeb0, NULL, 1);
TcpipServerToClient(#432, 1 bytes)
{
  s
}

Looking back at the recorded script, you'll find that the sending of the password, as opposed to the sending of the user login name, doesn't trigger a sequence of echoes. This is because the password isn't supposed to appear on the terminal screen.

Note that the communication is full duplex. This means that both server and client can send simultaneously; they don't have to wait for each other. In the above example, you can see the result of this in the lines:

WebTcpipSend(hWeb0, "se");
WebTcpipRecvExact(hWeb0, NULL, 2);

Here, because of rapid typing during the recording session, the echo s came back only after the e keystroke had been sent to the server.

Once the password is sent, a number of WebTcpipRecvExact statements follow in the above code. In the recording's log file, one of these statements looks like this:

TcpipServerToClientBin(#432, 59 bytes)
{
  00000000 [8;19H·[;7m+---  1B 5B 38 3B 31 39 48 1B 5B 3B 37 6D 2B 2D 2D 2D
  00000010 ---Hinweis: Kein 2D 2D 2D 48 69 6E 77 65 69 73 3A 20 4B 65 69 6E
  00000020 Kunde gefunden-  20 4B 75 6E 64 65 20 67 65 66 75 6E 64 65 6E 2D
  00000030 ------+·[m·      2D 2D 2D 2D 2D 2D 2B 1B 5B 6D 0A
}

The server response contains plain text as well as meta information, such as text position and format (note that in German, "Hinweis: Kein Kunde gefunden" means "Message: No customer found").

In this Telnet example, determining when the server response is complete is challenging. First, the packet length is not included in the response data (Case I). Second, there is no termination byte sequence (Case II). Therefore this example represents Case III: No information on response packet size from section “Dynamically Receiving Server Responses”.

Note: In other Telnet based projects, you may find terminator strings in server response data (for example, the command prompt character). This depends entirely on the application under test.

To solve this problem generically, a TelnetReceive-Response function that accepts incoming server responses of unspecified length in a loop is written. The loop is terminated when the client waits for a new response packet for more than a specified number of seconds. The corresponding function code is included later in this section.

Looking at the same part of the script after customization, the structure is more visible, and the server responses are handled by the new function. Note that complete strings can be sent to the server, as opposed to sending each key stroke as a single packet. You consequently don't have to wait for each echo character individually, because they can be read asynchronously (due to the full-duplex nature of the Telnet protocol) after sending the complete request.

// Login: Send Username
WebTcpipSend(hWeb0, "testuser\r");
TelnetReceiveResponse(hWeb0, 1.0, "Login: Username");

// Login: Send Password
WebTcpipSend(hWeb0, "password\r");
TelnetReceiveResponse(hWeb0, 5.0, "Login: Passwort");

// Choose "1" from main menu and hit RETURN
WebTcpipSend(hWeb0, "1\r");
TelnetReceiveResponse(hWeb0, 5.0, "Choose 1 from menu");

The TelnetReceiveResponse function eliminates the need to wait for incoming server data for appropriate periods of time. It takes three parameters:

hWeb0: Is the handle of the open TCP connection

fTimeout: Defines how to decide when the server response is complete: If after fTimeout seconds, no further server response is available, the function returns.

sAction: This string is used for appropriate naming of the custom timer, and can be used for logging and debugging purposes.

Example

function TelnetReceiveResponse(hWeb0: number;
                               fTimeout: float;
                               sAction: string): number
var
  sData:      string(4096);
  nRecv:      number;
  nRecvSum:   number;
  fTime:      float;

begin
  gsResponse := "";
  nRecvSum   := 0;

  MeasureStart(sAction);

  while WebTcpipSelect(hWeb0, fTimeout) do
    if NOT WebTcpipRecv(hWeb0, sData, sizeof(sData), nRecv)
    then
      exit;
    end;
    if nRecv = 0 then
      exit;
    end;
    SetMem(gsResponse, nRecvSum + 1, sData, nRecv);
    nRecvSum   := nRecvSum + nRecv;
  end;

  MeasureStop(sAction);
  MeasureGet(sAction, MEASURE_TIMER_RESPONSETIME,
             MEASURE_KIND_LAST, fTime);

  if fTime > fTimeout then
    fTime := fTime - fTimeout;
  end;
  MeasureIncFloat("RespTime: " + sAction, fTime, "sec",
                  MEASURE_USAGE_TIMER);

  TelnetReceiveResponse := nRecvSum;

end TelnetReceiveResponse;

The function works as follows: It waits until a server response is ready to be read in under fTimeout seconds (WebTcpipSelect). As soon as a server response is available, it is received and appended to the global string variable gsResponse. The loop terminates when the server response is empty, when the timeout is exceeded, or if WebTcpipRecv fails for any reason.

This loop structure is necessary because often a Telnet server will send a line of characters, nothing will happen for a couple of seconds, and then suddenly more lines come in.

Some care must be taken when looking at these time measurements. Because of the nature of the timeout, the time measurements usually include a final timeout period of fTimeout seconds. This has to be subtracted from the measured time to get the true roundtrip time measurement. This corrected time measurement is made available as a custom measurement with the name "RespTime: " + sAction and the dimension seconds.

Parent topic: Telnet, TN3270e, and Custom Protocols


TN3270e Protocol

The TN3270e protocol is a method of emulating 3270 terminal and printer devices using Telnet. It is used by terminal emulation software such as Rumba® and Hummingbird's HostExplorer® for direct connections to mainframes.

Similar to Telnet, a typical TN3270e session consists of two main parts:

  • A connection is established; session details and options are negotiated.
  • The application starts, and from that point forward generated traffic is user-driven.

Part I: Establishing a Connection

The first part of a typical recorded script of a TN3270e session looks like this:

WebTcpipConnect(hWeb0, "10.19.111.201", 7230);
WebTcpipRecvExact(hWeb0, NULL, 3);
WebTcpipSendBin(hWeb0, "\hFFFB28", 3);    // ·û(
WebTcpipRecvExact(hWeb0, NULL, 7);
WebTcpipSendBin(hWeb0,
  "\hFFFA28020749424D2D333237382D342D"
    // ·ú(··IBM-3278-4-
  "\h45FFF0", 19);                        // E·ð
WebTcpipRecvExact(hWeb0, NULL, 28);
WebTcpipSendBin(hWeb0, "\hFFFA2803070004FFF0", 9);
  // ·ú(·····ð
WebTcpipRecvExact(hWeb0, NULL, 9);
WebTcpipRecvExact(hWeb0, NULL, 347);

This looks similar to the first part of the Telnet session from the previous section because the TN3270e protocol is based on the Telnet protocol. Again, nothing needs to be changed here. Because this is a stateful, connection-oriented protocol, session handling is not an issue.

The traffic from the first part of the session is translated into TELNET code in the following table:

Server-to-Client | Client-to-Server
FF FD 28 (IAC DO TN3270E) |
 | FF FB 28 (IAC WILL TN3270E)
FF FA 28 08 02 FF F0 (IAC SB TN3270E SEND DEVICE-TYPE IAC SE) |
 | FF FA 28 02 07 49 42 4D 2D 33 32 37 38 2D 34 2D 45 FF F0 (IAC SB TN3270E DEVICE-TYPE REQUEST "IBM-3278-4-E" IAC SE)
FF FA 28 02 04 49 42 4D 2D 33 32 37 38 2D 34 2D 45 01 54 39 35 49 54 51 4D 55 FF F0 (IAC SB TN3270E DEVICE-TYPE IS "IBM-3278-4-E" CONNECT "T95ITQMU" IAC SE) |
 | FF FA 28 03 07 00 04 FF F0 (IAC SB TN3270E FUNCTIONS REQUEST [BIND-IMAGE SYSREQ] IAC SE)
FF FA 28 03 04 00 04 FF F0 (IAC SB TN3270E FUNCTIONS IS [BIND-IMAGE SYSREQ] IAC SE) |

In summary, server and client agree on a protocol, a device type (IBM-3278-4-E), and on whether or not to use certain protocol features. Note that the terminal name (T95ITQMU) is assigned by the server, not the client. This is because the server system holds a database that handles the mapping of client IP addresses to terminal names.

Part II: User Interaction

The second part of the script contains the user interaction. The following request-response pair example represents an interaction where the user enters an account number (238729) into a text field and then hits the RETURN key:

WebTcpipSendBin(hWeb0,
  "\h00000000007DC6C61140C4F311C640F2"
     // ·····}ÆÆ·@Äó·Æ@ò
  "\hF3F8F7F2F9FFEF", 23);               // óø÷òù·ï
WebTcpipRecvExact(hWeb0, NULL, 199);

Knowing that the traffic is encoded in EBCDIC (rather than ASCII), the account number can be found in the request string using an EBCDIC code table: 238729 is represented as the binary byte sequence 0xF2 F3 F8 F7 F2 F9 in EBCDIC. This is the part that is relevant to customization; the rest may be left unchanged.

Here's an account of the other parts of this message. The first five bytes represent the TN3270e message header (RFC 2355):

Field | Length | Value in our example
Data type | 1 byte | 0x00 | 3270-DATA
Request flag | 1 byte | 0x00 | ERR-COND-CLEARED
Response flag | 1 byte | 0x00 | NO-RESPONSE
Sequence number | 2 bytes | 0x0000 | Sequence numbers may or may not be used. In this case, they aren't.

Each client request is terminated by a two-byte sequence: 0xFF EF.

The remainder of the request data (bytes #6 - #21 in this example) is application data containing screen positions, key codes, and text.

The server response can be analyzed in the corresponding log or TrueLog files from the recording session. In this example, the response is a 199-byte data block beginning with five zero bytes (0x00) and ending with 0xFF EF, just like the request data. The data content in between is similar to the request data: cursor positions, formatting, and text content (encoded in EBCDIC).

A simple customization of the script extract above using the function library would look like this:

ResetRequestData();
AppendRequestData("\h00000000007DC6C61140C4F311C640",
                15);
AppendRequestData(ASC2EBCDIC(sAccountNr) + "\hFFEF");
SendTcpipRequest(hWeb0);
WebTcpipRecvUntil(hWeb, sResp, sizeof(sResp), nRecv,
                  "\hFFEF", 2);

Here a string variable sAccountNr has been introduced for the account number (where 238729 was used during recording). The function ASC2EBCDIC that converts between ASCII and EBCDIC is explained in the following section.

Finally, the inflexible WebTcpipRecvExact has been replaced with WebTcpipRecvUntil, which is appropriate here because the trailing byte sequence is known. The response data is stored in the string variable sResp, and nRecv contains the number of received bytes.

For logging and verification purposes, the server response should be translated from EBCDIC to ASCII. For example:

Writeln("Response: " + EBCDIC2ASC(sResp, nRecv));

When necessary, single response data (such as a new ID that's needed as input data for subsequent requests) can be extracted from this response using the StrSearchDelimited function.

Taking customization a step further, it's good practice to replace the WebTcpipRecvUntil call in the script above with a MyWebTcpipRecv function that encapsulates all the necessary actions on server responses:

  • Call WebTcpipRecvUntil with the appropriate end byte sequence.
  • Convert the response from EBCDIC to ASCII.
  • Log the response to the output file (in ASCII).
  • Do generic error checking on the response by searching for common error messages.
  • Make the response data available as a return value or global variable for further verification or data extraction.

In the Silk Performer script, each client request should be followed by a call to this new function, replacing the WebTcpipRecvExact function calls from the recording session.

  • EBCDIC to ASCII Character Code Conversion
    Explains how to implement a conversion routine that translates server responses from the EBCDIC character set to ASCII.
  • Issues with "Keep Alive" Mechanisms
    Examines a test script sequence taken from a TN3270e traffic recording.
  • IP Spoofing
    Explains that for successful replay of such a script with parallel virtual users, each user must use a unique IP address.
  • Recording Rule Configuration Files
    Explains that the Silk Performer recorder can be configured to generate correct WebTcpipRecvUntil calls for the TN3270e protocol automatically using a recording rule configuration file.
Parent topic: Telnet, TN3270e, and Custom Protocols


EBCDIC to ASCII Character Code Conversion

EBCDIC (Extended Binary Coded Decimal Interchange Code) is the data alphabet used in all IBM computers, except personal computers. A conversion routine that translates server responses from the EBCDIC character set to ASCII is easy to implement.

The function EBCDIC2ASC uses the code map defined by the array as EBCDIC_2_ASCII, which maps each EBCDIC character to its ASCII equivalent. The function ASC2EBCDIC, which is required for translating client requests from ASCII to EBCDIC, works in a similar manner.

var
  asEBCDIC_2_ASCII : array[256] of string(1) INIT
" ", " ", " ", " ", " ", " ", " ", " ", " ", " ", " ", " ", " ", " ", " ", " ",
" ", " ", " ", " ", " ", " ", " ", " ", " ", " ", " ", " ", " ", " ", " ", " ",
" ", " ", " ", " ", " ", " ", " ", " ", " ", " ", " ", " ", " ", " ", " ", " ",
" ", " ", " ", " ", " ", " ", " ", " ", " ", " ", " ", " ", " ", " ", " ", " ",
" ", " ", " ", " ", " ", " ", " ", " ", " ", " ", " ", " ", " ", " ", " ", " ",
" ", " ", " ", " ", " ", " ", " ", " ", " ", " ", " ", " ", " ", " ", " ", " ",
" ", " ", " ", " ", " ", " ", " ", " ", " ", " ", " ", " ", " ", " ", " ", " ",
" ", " ", " ", " ", " ", " ", " ", " ", " ", " ", " ", " ", " ", " ", " ", " ",
" ", "a", "b", "c", "d", "e", "f", "g", "h", "i", " ", " ", " ", " ", " ", " ",
" ", "j", "k", "l", "m", "n", "o", "p", "q", "r", " ", " ", " ", " ", " ", " ",
" ", "~", "s", "t", "u", "v", "w", "x", "y", "z", " ", " ", " ", " ", " ", " ",
" ", " ", " ", " ", " ", " ", " ", " ", " ", " ", " ", " ", " ", " ", " ", " ",
" ", "A", "B", "C", "D", "E", "F", "G", "H", "I", " ", " ", " ", " ", " ", " ",
" ", "J", "K", "L", "M", "N", "O", "P", "Q", "R", " ", " ", " ", " ", " ", " ",
" ", " ", "S", "T", "U", "V", "W", "X", "Y", "Z", " ", " ", " ", " ", " ", " ",
"0", "1", "2", "3", "4", "5", "6", "7", "8", "9", " ", " ", " ", " ", " ", " ";

function EBCDIC2ASC(pEBCDIC: string; pMaxLen: number optional)
  var
    i: number;
  begin
  //
  if pMaxLen = 0 then
     pMaxLen := Strlen(pEBCDIC);
  // writeln("length of string : " + string(pMaxLen));
  end;
  //
  // writeln("EBCDIC STRING " + pEBCDIC);
  //
  for i := 1 to pMaxLen do
  //
  //writeln("Ordinal Value:" + String(ord(pEBCDIC[i])));
  //write("Value From Array:" + asASCII_2_EBCDIC[ord(pEBCDIC[i]) + 1]);
    write(asEBCDIC_2_ASCII[ord(pEBCDIC[i]) + 1]);
  //writeln;
  //
  end;
    writeln;
  end EBCDIC2ASC;

The table below is the standard EBCDIC table for the 2780/3780 Protocol code map (taken from [EBCDIC_CTI]). As an example, to decode the EBCDIC byte 0x83, choose row 8 and column 3. You'll find that 0x83 maps to the letter c in ASCII.

[EBCDIC_UNI] is a reference that presents the specifications of the UTF-EBCDIC - EBCDIC Friendly Unicode (or UCS) Transformation Format.

Parent topic: TN3270e Protocol


Issues with "Keep Alive" Mechanisms

The following test script sequence was taken from a TN3270e traffic recording:

WebTcpipRecvExact(hWeb0, NULL, 3);
WebTcpipSendBin(hWeb0, "\hFFFB06", 3);  // IAC WILL TIMING-MARK
WebTcpipRecvExact(hWeb0, NULL, 3);
WebTcpipSendBin(hWeb0, "\hFFFC06", 3);  // IAC WON'T TIMING-MARK

In this example, the server challenges the client with a three-byte code (first line of the code above) whenever the client is inactive for a period of time. The client responds with three-byte sequence of its own. Such "ping pong" activity, initiated by the server, can serve as a control mechanism for detecting whether or not a client is still active.

These lines cause problems during replay because they aren't predictable or reproducible. To address such a situation, rather than incorporating the appropriate intelligence into a Silk Performer script, which would be a daunting task, simply disable this feature on the server.

Some background info from RFC 860 (Telnet timing mark option):

"It is sometimes useful for a user or process at one end of a TELNET connection to be sure that previously transmitted data has been completely processed, printed, discarded, or otherwise disposed of. This option provides a mechanism for doing this. In addition, even if the option request (DO TIMING-MARK) is refused (by WON'T TIMING-MARK) the requester is at least assured that the refuser has received (if not processed) all previous data."

Parent topic: TN3270e Protocol


IP Spoofing

For successful replay of such a script with parallel virtual users, each user must use a unique IP address.

Enable the Client IP address multiplexing option in Silk Performer at Settings > Active Profile > Internet > Optimization and configure enough IP addresses on Silk Performer agents so that each virtual user can have a unique IP address ("IP Spoofing"). IP addresses can also be configured using the Silk Performer System Configuration Manager at Tools > System Configuration Manager > IP Address Manager.

Parent topic: TN3270e Protocol


Recording Rule Configuration Files

The Silk Performer recorder can be configured to generate correct WebTcpipRecvUntil calls for the TN3270e protocol automatically using a recording rule configuration file.

Two different rules must be specified: in the first part of the session where the session parameters are negotiated, 0xFF F0 is used as the termination sequence, while 0xFF EF serves as the termination sequence in the 3270-DATA part of the session.

These two parts can be distinguished by checking the first byte of the response data. In the first part, it is equal to 0xFF (Telnet code IAC - "Interpret as Command"), while it is equal to 0x00 (Code 3270-DATA, compared to the TN3270e response header above) in the second part.

The resulting recording rule XML file looks like this:

<RecordingRuleSet>
  <TcpRuleRecvUntil>
    <Name>Telnet session start</Name>
    <Identify>
      <TermData>&#xFF;&#xF0;</TermData>
      <IgnoreWhiteSpaces>false</IgnoreWhiteSpaces>
    </Identify>
    <Conditions>
      <CompareData>
        <Data>&#xFF;</Data>
        <ApplyTo>Left</ApplyTo>
        <Offset>0</Offset>
      </CompareData>
    </Conditions>
  </TcpRuleRecvUntil>
  <TcpRuleRecvUntil>
    <Name>3270-DATA</Name>
    <Identify>
      <TermData>&#xFF;&#xEF;</TermData>
      <IgnoreWhiteSpaces>false</IgnoreWhiteSpaces>
    </Identify>
    <Conditions>
      <CompareData>
        <Data>&#x00;</Data>
        <ApplyTo>Left</ApplyTo>
        <Offset>0</Offset>
      </CompareData>
    </Conditions>
  </TcpRuleRecvUntil>
</RecordingRuleSet>
Parent topic: TN3270e Protocol


Custom TCP/IP Based Protocols

The following example comes from an application that used an entirely custom TCP/IP based protocol. In this protocol, both the client request and server response data obey a set of predefined message telegram structures consisting of fixed-length fields. Some of the fields are binary (and may therefore contain zero bytes) and some are string type.

Here is a typical request-response pair from the recorded traffic:

WebTcpipConnect(hWeb0, "10.9.96.81", 3311);
WebTcpipSendBin(hWeb0,
"\h00000280000000000000000000000000" // ················
"\h000100000000000000004F4B36302020" // ··········OK60
...
"\h303030302B3030303030303030303030" // 0000+00000000000
"\h30303030000000000000000000000000" // 0000············
, 640);
WebTcpipRecvExact(hWeb0, NULL, 80);
WebTcpipShutdown(hWeb0);

Here is the server response from the record log. Based on the third argument of the WebTcpipRecvExact function in the above script, we already know that it contains 80 bytes:

00 00 00 00  ···P············  00 00 00 50 00 00 00 00 00 00 00 00 00 00 00 00
00 00 00 10  ··········OK60    00 01 00 00 00 00 00 00 00 00 4F 4B 36 30 20 20
00 00 00 20    ··U60OKS1 SILK  20 20 00 00 55 36 30 4F 4B 53 31 20 53 49 4C 4B
00 00 00 30  01  ············  30 31 20 20 00 00 00 00 00 00 00 00 00 00 00 00
00 00 00 40  ················  00 00 00 00 00 00 00 00 00 00 00 00 00 00 00 00
Note: The first four bytes (0x00 00 00 50) are a representation of a four-byte integer (a long variable) with the decimal value 80 (5 * 16 = 80). Note that the length of the entire packet is 80 bytes, hence the 4 initial bytes are included in the "packet size" variable. If available, consult protocol documentation regarding the custom application under test. Otherwise you will have to experiment to discover such protocol behavior on your own.
Note: The client request telegram contains the same information. The first four bytes are 0x00 00 02 80, equal to 2*256 + 8*16 = 640. This is the number of bytes sent to the server.

Here is the script after customization. Note that:

  • An added pair of MeasureStart/MeasureStop functions has been added to measure the time for the request.
  • The request has been split into several pieces for parameterization, using the function library.
  • The WebTcpipRecvExact function has been replaced by a call to WebTcpipRecvProto.

Here is the result:

ResetRequestData();
AppendRequestData("\h00000280000000000000000000000000"
                 "\h00010000000000000000", 26);
AppendRequestData("OK60    ");
AppendRequestData("\h0000", 2);
AppendRequestData(sUser + sPassword);
// ... (some more lines not displayed here)

MeasureStart("Write Journal");
WebTcpipConnect(hWeb0, "10.9.96.81", 3311);
SendTcpipRequest(hWeb0);
WebTcpipRecvProto(hWeb0, 0, 4, TCP_FLAG_INCLUDE_PROTO,
               sResponse, sizeof(sResponse), nReceived);
// ... (response verification not displayed here)
WebTcpipShutdown(hWeb0);
MeasureStop("Write Journal");

Recording Rule Configuration Files

The following recording rule XML file configures the Silk Performer recorder so that it generates the correct WebTcpipRecvProto calls in place of WebTcpipRecvExact. The settings in the Identify node map to the arguments of WebTcpipRecvProto in the script extract above.

<RecordingRuleSet>
  <TcpRuleRecvProto>
    <Name>My custom TCP protocol</Name>
    <Identify>
      <LengthOffset>0</LengthOffset>
      <LengthLen>4</LengthLen>
      <OptionFlags>ProtoIncluded</OptionFlags>
    </Identify>
  </TcpRuleRecvProto>
</RecordingRuleSet>
Parent topic: Telnet, TN3270e, and Custom Protocols


Recorder Settings

Silk Performer offers two mechanisms for recording TCP/IP based protocol traffic. Socksifying such an application is the most commonly accepted approach. There are however some scenarios in which using a TCP proxy recorder is the better solution:

  • Using the TCP proxy mechanism, Silk Performer doesn't have to run on the same machine as the client application. This works if for example both client and server are Unix applications. Just configure them in such a way that they connect to each other using the Silk Performer proxy residing on a Windows box.
  • Sometimes, there are numerous client application processes all connected to the same server. In such instances it may be quicker to set up a TCP proxy than to it is to search NT's task manager for all processes that are generating traffic.
  • Configuration is easy if you only need to record on one or a small number of TCP ports.
  • "Socksifying" an Application
    Explains that if you know the path of the client application executable that's connecting to the server, you can set up a recording profile for the application
  • TCP Proxy Recorder
    Explains that if you are able to control the server name and TCP port number the client application connects to, you can use the TCP/IP proxy recorder.
Parent topic: TCP/IP Based Protocol Support


"Socksifying" an Application

If you know the path of the client application executable that's connecting to the server, you can set up a recording profile for the application in Silk Performer at Settings > System > Recorder > Recording Profiles > Add.

Parent topic: Recorder Settings


TCP Proxy Recorder

An alternative solution involves using a TCP/IP proxy recorder. As a prerequisite, you must be able to control the server name and TCP port number the client application connects to. Typically, these settings can be found in the registry or in a configuration file. Then, you can configure Silk Performer and the client application so that traffic is explicitly routed over the Silk Performer recorder.

Assuming that the client connects to MYSERVER on port 5012, you would change these settings to LOCALHOST and port 49152 (or any other unused TCP port) in the registry or appropriate configuration file. In Silk Performer, choose Settings > System > Recorder > Proxies > Add. Add a new proxy, and configure it as a TCP proxy listening on port 49152, connecting to the remote host MYSERVER on port 5012.

In this way, the following scenario is configured:

The client application doesn't notice a difference in performance when the recorder is running. This is in contrast to the scenario in which the client is connected directly to the server.

Parent topic: Recorder Settings


Load Testing PeopleSoft

This section explains how to use Silk Performer to load test PeopleSoft applications. It explains how to use the PeopleSoft SilkEssential package to record and customize PeopleSoft scripts for realistic simulation of virtual users.

  • Specifying the PeopleSoft Project Type
    Describes how to create a project based on the PeopleSoft project type.
  • Script Modeling
    Describes how script modeling for PeopleSoft transactions works.
  • Application-Level Errors
    Describes how PeopleSoft handles application-level errors.
  • Parameterization
    Describes how to make use of script customization and randomization.
Parent topic: Load Testing Specific Application Types


Specifying the PeopleSoft Project Type

  1. Click Start here on the Silk Performer workflow bar.
    Note: If another project is already open, choose File > New Project from the menu bar and confirm that you want to close your currently open project.
    The Workflow - Outline Project dialog box opens.
  2. In the Name text box, enter a name for your project.
  3. Enter an optional project description in Description.
  4. In the Type menu tree, select ERP/CRM > PeopleSoft.
  5. Click Next to create a project based on your settings.
Parent topic: Load Testing PeopleSoft


Script Modeling

Script modeling for PeopleSoft transactions is straightforward. Recorded scripts work without any required modification, however by following a few standard customization steps after recording, you can get more out of recorded scripts. Recorded scripts are designed to make the process quick and easy.

  • Recording
    Describes how to record PeopleSoft user transactions.
  • Script Customization
    Describes how to customize and enhance recorded scripts.
Parent topic: Load Testing PeopleSoft


Recording

Before recording, make sure that the project has been created based on the PeopleSoft project type. Record user interactions in a single BDL transaction. Ensure that the transaction begins with the sign-in process and ends with the sign-out process. Do not use the back button of your browser as this is generally problematic for highly state-dependent web applications such as PeopleSoft.

PeopleSoft scripts have a standard structure. Apart from the sign-in and sign-out processes, there are basically two types of user interaction involved:
  • Navigation in the menu tree
  • Work in the work area
  • Inclusion of PeopleSoft API Functions
    Describes how to initialize and use PeopleSoft API functions.
  • Wrapper Functions
    Lists the available wrapper functions the BDH files contain.
  • Sign-In and Sign-Out
    Describes how to correctly begin a recorded script with the sign-in process and how to end it with the sign-out process.
  • Navigation in the Menu Tree
    Describes how navigation in the menu tree is recorded.
  • Interaction in the Work Area
    Describes how interaction in the work area is recorded.
Parent topic: Script Modeling


Inclusion of PeopleSoft API Functions

The recorded script contains a use statement for PeopleSoft8Api.bdh, a BDH file that contains PeopleSoft specific API functions. It also contains PeopleSoftInit(), the initialization function call in the TInit transaction (see the example below).

This initializes the PeopleSoft framework contained in several BDH files of the PeopleSoft SilkEssential package. It also enables global verification rules to catch PeopleSoft specific application-level errors. This is especially useful when used in conjunction with the TrueLog On Error option.

In addition, it enables global parsing rules for the parsing of dynamic form names. Parsed form names are available in the global variable gsFormMain.

Example: Initializing PeopleSoft API functions

benchmark SilkPerformerRecorder

use "WebAPI.bdh"
use "PeopleSoftApi.bdh"

dcluser
  user
    VUser
  transactions
    TInit : begin;
    TMain : 1;

var
  // ...

dclrand

dcltrans
  transaction TInit
  begin
    WebSetBrowser(WEB_BROWSER_MSIE6);
    WebModifyHttpHeader("Accept-Language", "en-us");
    WebSetStandardHost("crm.ps.my.company.com");
    PeopleSoftInit();
    //GetLoginInfoPS("LoginPS.csv", gsUserId, gsPassword);
    //WebSetUserBehavior(WEB_USERBEHAVIOR_FIRST_TIME);
    //WebSetDocumentCache(true, WEB_CACHE_CHECK_SESSION);
  end TInit;
Parent topic: Recording


Wrapper Functions

The BDH files contain wrapper functions for all page-level API functions. These wrapper functions call the original API functions and perform some additional tasks.

The following wrapper functions are defined:

Wrapper function | Wrapped original function
WebPageUrlPS | WebPageUrl
WebPageLinkPS | WebPageLink
WebPageSubmitPS | WebPageSubmit
WebPageSubmitBinPS | WebPageSubmitBin
WebPageFormPS | WebPageForm
WebPageFileUploadPS | WebPageFileUpload
Parent topic: Recording


Sign-In and Sign-Out

Recorded scripts should begin with the sign-in process and end with the sign-out process, as shown in the example below. The BDH files define and the recorder records, the functions HomepagePS, SignInPS and SignOutPS.

Example: Recorded sign-in and sign-out processes

var
  gsHomepageUrl : string init "http://standardhost/psp/ps/
?cmd=login";

transaction TMain
begin
  HomepagePS(gsHomepageUrl, "PeopleSoft 8 Sign-in");
  ThinkTime(6.0);
  SignInPS("login", LOGIN002, "EMPLOYEE"); // Form 1

  // more function calls ...
  SignOutPS(gsSignoutUrl, "PeopleSoft 8 Sign-in");
end TMain;

These function calls do not require customization. the SignInPS function parses the sign-out URL to the gsSignoutUrl variable, and the recorded script uses the variable in the SignOutPS function call. The recorder records the URL of the homepage into a variable for easy customization.

Parent topic: Recording


Navigation in the Menu Tree

Navigation in the menu tree is recorded by a WebPageLinkPS call that uses a custom hyperlink from a WebPageParseUrl call of a previous API call.

Example: Recorded navigation in the menu tree

This process does not require any modification:

WebPageParseUrl("JavaScript Link in page EMPLOYEE",
                "DEFINITION\",\"", "\"",
                 WEB_FLAG_IGNORE_WHITE_SPACE);
WebPageLinkPS("Home", "EMPLOYEE"); // Link 1

WebPageLinkPS("JavaScript Link in page EMPLOYEE",
              "CR_PRODUCT_DEFINITION", 3);
Parent topic: Recording


Interaction in the Work Area

User interaction in the work area is recorded by a WebPageSubmitPS call. The form relies on the form field attribute USE_HTML_VAL, and thus ensures proper context management without customization.

The form name may change dynamically. While the form name is usually main or win (depending on the PeopleSoft version), it may, depending on server load, become main1, main2, win1, win2, and so on.

Because of this, the recorder records a WebPageSubmitPS(NULL, ...) function call that references the form by ordinal number rather than form name.

However, the BDH files implement global parsing for the dynamic form name during script execution, so the actual form name of the current page is always available in the global variable gsFormMain.

Example: User interaction within the work area

WebPageSubmitPS(NULL, MAIN005, "Product Definition", 4); // Form 4

The above example shows a WebPageSubmitPS function, which references the dynamic form by its ordinal number on the page.

The next example shows a typical submitted form. There is no need for customization of session or state management here because of the USE_HTML_VAL attributes. The only customization that may be required is the randomization of input values.

Example: Submitted form

MAIN008:
"ICType"       := "" <USE_HTML_VAL> ,
               // hidden, unchanged, value: "Panel"
"ICElementNum" := "" <USE_HTML_VAL> ,
               // hidden, unchanged, value: "0"
"ICStateNum"   := "" <USE_HTML_VAL> ,
               // hidden, unchanged, value: "5"
"ICAction"     := "#ICSearch",
               // hidden, changed(!)
"ICXPos"       := "" <USE_HTML_VAL> ,
               // hidden, unchanged, value: "0"
"ICYPos"       := "" <USE_HTML_VAL> ,
               // hidden, unchanged, value: "0"
"ICFocus"      := "" <USE_HTML_VAL> ,
               // hidden, unchanged, value: ""
"ICChanged"    := "" <USE_HTML_VAL> ,
               // hidden, unchanged, value: "-1"
"RBF_PRD_DF_SRCH_SETID"      := "" <USE_HTML_VAL> ,
                             // unchanged, value: ""
"RBF_PRD_DF_SRCH_PRODUCT_ID" := "" <USE_HTML_VAL> ;
                             // unchanged, value: "NEXT"
Parent topic: Recording


Script Customization

The PeopleSoft SilkEssential package contains some utility functions that can be accessed through manual script enhancement to get more from recorded scripts. This section describes these optional steps.

  • Customizing Think Times
    Explains how to use the ThinkTimePS function to customize think times.
  • Uniquely Seed Randomness
    Describes how to improve the randomness of script execution.
  • Customizing Timer Names
    Describes how to customize timer names for easier results analysis.
  • Targeting a Different Server
    Describes the three options for targeting a different server.
  • Enable Server-Side Tracing
    Describes how to enable the detailed server-side tracing features PeopleSoft offers.
  • Randomizing Table Row Selection
    Describes how to randomize or customize a form, which is returned when clicking an item within a table.
Parent topic: Script Modeling


Customizing Think Times

The recorder of Silk Performer records think times as they occur during recording. Often however, this is not what is required. The PeopleSoftApi.bdh file provides a substitute for the ThinkTime API function that is called ThinkTimePS.
function ThinkTimePS( fTime           : float optional;
                      bForceThinkTime : boolean optional);

To customize the script, click Edit in the menu and click Replace. In the Replace dialog box, replace all ThinkTime function calls with ThinkTimePS function calls.

The behaviour of the ThinkTimePS function depends on the value of the bForceThinkTime parameter. When bForceThinkTime is set to false (the default value), ThinkTimePS ignores the value of the fTime parameter and calls the ThinkTime API function with the value of the ThinkTimePS project attribute. The behaviour follows the usual thinktime-related profile settings (for example stresstest, random think time, exponential/uniform distribution, think time limited to x seconds, and so on).

When bForceThinkTime is set to true, ThinkTimePS calls the ThinkTime API function with the value of the parameter fTime and the OPT_THINKTIME_EXACT option. This results in a think time that is exactly as specified, regardless of profile settings and project attributes.

There are two project attributes available for customizing the behaviour of the ThinkTimePS function. Click Project in the menu and click Project Attributes to access these attributes:
  • ThinkTimePS (float): Think time value used by ThinkTimePS when bForceThinkTime is false. Unit: Seconds; Preset: 10.0
  • ForceThinkTime (boolean): Allows for global override of the bForceThinkTime parameter of the ThinkTimePS function. Preset: false
Parent topic: Script Customization


Uniquely Seed Randomness

To improve the randomness of script execution, it can be advantageous to uniquely seed the random number generator for each virtual user. This is done by changing the value of the UniquelySeedRandomness project attribute to true.

Parent topic: Script Customization


Customizing Timer Names

For easier results analysis, it is desirable to have timer names that can be sorted based on their occurrence in scripts and amended with additional information. To accomplish this, the wrapper functions amend original timer names with additional information.

Project attributes can be used to include any combination of the following items in amended timer names:
  • Agent name
  • Transaction name
  • Modem emulation speed
  • Page counter for the current transaction

The WebPage*PS wrapper functions keep track of internal page numbers, which are prepended to timer names when this option is selected in the project attributes. While page numbers are automatically reset to 0 at the end of each transaction, you can manually reset the page counter at any time by calling the ResetPageCount function.

You may also call the IncPageCount function to manually increment the internal page counter. This is useful for keeping a consistent page counter after an unbalanced if statement.

The WebPage*PS wrapper functions also allow you to specify a specific value for the page counter. This value may be passed as the parameter where the frame name is passed in the original wrapped functions.

Note: Wrapper functions do not allow you to pass a frame name. This rule is also obeyed by the recorder. You may pass the special value PAGE_NUMBER_KEEP to reuse the current page counter, rather than increment it.
Parent topic: Script Customization


Targeting a Different Server

Recorded scripts contain a call to WebSetStandardHost in the TInit transaction.

Example: Call to WebSetStandardHost as recorded

transaction TInit
begin
  // ...
  WebSetStandardHost("crm.ps.my.company.com");
  // ...
  PeopleSoftInit();
end TInit;
There are three options for targeting a different server:
  1. Edit the recorded WebSetStandardHost function call.
  2. Delete the recorded WebSetStandardHost function call and specify a standard host in the profile settings.
  3. Specify a different standardhost in project attributes. These project attributes will be evaluated in the PeopleSoftInit() function call and will therefore override the recorded WebSetStandardHost function call.
Parent topic: Script Customization


Enable Server-Side Tracing

PeopleSoft offers the option to enable detailed server-side tracing for individual login session. Scripts should be recorded without tracing being enabled, because this would enable tracing for all virtual users.

Instead, server-side tracing can be enabled on a virtual user basis by inserting a call to the EnableTracingPS function in the TInit transaction, as shown in the sample below. The form used for login must be passed to this function. It is important to note that tracing should only be enabled for individual virtual users. Enabling tracing for all virtual users would impose significant overhead on servers and could skew test results.

Enabling tracing for one virtual user

transaction TInit
begin
  // ...
  PeopleSoftInit();
  if GetUserId() = 1 then
     EnableTracingPS(LOGIN001);
  end;
end TInit;

dclform
  LOGIN001:
    "httpPort" := "" <USE_HTML_VAL> ,
    "timezoneOffset" := "-60",
    "userid" := gsUserId,
    "pwd" := gsPassword,
    "Submit" := "" <USE_HTML_VAL> ;

Tracing options can be modified by editing the Tracing.csv file, which is available in the Data Files node of the project tree view.

Parent topic: Script Customization


Randomizing Table Row Selection

PeopleSoft pages often contain tables, for example lists of search results. Clicking an item within such a table returns a form where the ICAction field is set to #ICRowX, where X denotes the ordinal number of the selected row.

Example: Form submitted while selecting an item in a table

dclform
  MAIN003:
    "ICType" := "" <USE_HTML_VAL> ,
    "ICElementNum" := "" <USE_HTML_VAL> ,
    "ICStateNum" := "" <USE_HTML_VAL> ,
       "ICAction" := "#ICRow9", // hidden, changed(!)
       "ICXPos" := "" <USE_HTML_VAL> ,
       "ICYPos" := "" <USE_HTML_VAL> ,
       "ICFocus" := "" <USE_HTML_VAL> ,
       "ICChanged" := "" <USE_HTML_VAL> ,
// ...

To accurately randomize or customize such forms, you must determine the number of table rows.

There are four functions that assist with this:
  • GetMaxRowNr returns the maximum valid row number (for example in a table with 47 rows the maximum valid row number is 46, since row numbers are zero-based). If the current page does not contain a table, it returns -1.
  • GetRowCount returns the number of rows on the current page. If the current page does not contain a table, it returns 0.
  • GetRndRowStr returns a valid, random row string.
  • FindICRow(sStringToFind : string) : string returns the row string of the first row that contains the given text.

In the example below the GetRndRowStr function is used to randomize the selection of an item in a table.

Example: Randomizing the selection of an item in a table

dclform
  MAIN003:
// ..
    "ICStateNum" := "" <USE_HTML_VAL> ,
    "ICAction" := GetRndRowStr(),
    "ICXPos" := "" <USE_HTML_VAL> ,
// ...
Parent topic: Script Customization


Application-Level Errors

PeopleSoft does not use HTTP response status codes to indicate application-level errors. Instead, it returns HTML with status code 200 Success, even when the HTML contains error messages.

There are two error message types:
  • Error messages embedded in HTML.
  • Error messages in the parameters of JavaScript functions (Alert) that display dialog boxes.

Additionally, not all messages that are displayed with an Alert function are error messages. Some messages are simply informational, for example: Record has been saved.

If severe errors occur, transactions should not be continued.

Using the PeopleSoft SilkEssential package, recorded scripts are automatically able to handle application-level errors. When severe errors occur, errors of SEVERITY_TRANS_EXIT severity are raised and virtual users gracefully terminate their transactions by signing out. It is strongly recommended to enable the Trulog On Error option to fully benefit from this feature.

  • Customizing Error Messages in HTML
    Describes how to customize the lists of specific error messages.
  • Customizing Alerts
    Describes how to customize alerts.
Parent topic: Load Testing PeopleSoft


Customizing Error Messages in HTML

Lists of specific error messages are contained in the AppErrors.csv and AlertSeverities.csv files, which can be edited by double-clicking them in the Data Files section of the project tree view. These lists are based on significant consulting experience and meet the needs of most users. If however you feel that certain error messages are missing, or you wish to add additional error messages, you can customize these files.

Customizing Error Messages in HTML

The AppErrors.csv file contains error messages that cause errors to be raised when they occur in HTTP responses. Each row defines one error message across three columns:

  • Severity: Specifies the severity of error that is to be raised. Values in this column must begin with S, I, W, E, or T (signifying the severities Success, Informational, Warning, Error, or Transaction Exit).
  • Data or Html: Specifies whether the entire HTTP response should be searched for the error message (API function WebVerifyData), or whether only the visible HTML content should be searched for the error message (API function WebVerifyHtml). Values in this column must begin with either D or H.
  • Error String: The text of the error message. If you want to catch a set of error messages that have a common substring, it is good practice to enter only one entry where the Error String is the common substring. Example: If you have 100 different error messages, which all begin with Microsoft SQL error:, it is sufficient to have one list entry with the Error String "Microsoft SQL error:.

The AppErrors.csv file can be edited to meet your needs.

Parent topic: Application-Level Errors


Customizing Alerts

Alerts are pop-up windows that are implemented by a JavaScript function called Alert. This function is called from the onload section of HTML pages.

Example: Alert in an HTML response

<body·class='PSPAGE'··onload="
  processing_main(0,3000);
  setKeyEventHandler_main();
  self.scroll(0,0);
  setEventHandlers_main('ICFirstAnchor_main',
                       ·'ICLastAnchor_main',·false);
  setupTimeout();
alert(&#039;Highlighted·fields·are·required.·(15,30)
>

The error detection mechanism detects any alert contained in a HTML response and treats it as being an error of SEVERITY_TRANS_EXIT severity. Known alerts that are to be ignored or reported with another severity can be specified in the AlertSeverities.csv file.

Each known alert message is represented by a single row in the AlertSeverities.csv file, across two columns:
  • Severity: Specifies the severity of error that is to be raised. Values in this column must begin with N, S, I, W, E, or T (signifying the severities None (=ignore), Success, Informational, Warning, Error or Transaction Exit).
  • Alert String: The text of the alert string (or fragment thereof).

Alert messages are reported with the actual alert text, prefixed with the gsAlertMsgPrefix global variable. This variable contains an empty string by default, but can be assigned any value at anytime during script execution to meet your reporting needs.

Parent topic: Application-Level Errors


Parameterization

The recorder can create variables for certain strings that appear in scripts. This makes script customization and randomization easier.

  • Sign-In Data
    Describes how to customize sign-in data.
  • Input Values
    Describes how to randomize input values.
Parent topic: Load Testing PeopleSoft


Sign-In Data

The user names and passwords that are used for sign-in are created as variables at the top of a script. The recorder also records a commented call to the GetLoginInfoPS function in the TInit transaction. The GetLoginInfoPS function retrieves values for the gsUserId and gsPassword variables from the LoginPS.csv file, which can be edited by double-clicking it in the Data Files section of the project tree view.

Customization of login data is done by uncommenting the recorded GetLoginInfoPS function call and populating the LoginPS.csv file with valid user accounts from your PeopleSoft application.

Example: Sign-in data created as variables

var
  gsUserId : string init "Admin";
  gsPassword : string init "Secret";
  // ...

  transaction TInit
    begin
    // ...
    PeopleSoftInit();
    //GetLoginInfoPS("LoginPS.csv", gsUserId, gsPassword);
    // ...
  end TInit;

  transaction TMain
  begin

  // ...

    SignInPS("login", LOGIN001, "EMPLOYEE"); // Form 1

  // ...

  end TMain;

dclform

  // ...

  LOGIN001:
    "httpPort"       := "" <USE_HTML_VAL> ,
                     // hidden, unchanged, value: ""
    "timezoneOffset" := "-120",
                     // hidden, changed(!)
    "userid"         := gsUserId,
                     // changed, value: "Admin"
    "pwd"            := gsPassword,
                     // changed, value: "Secret"
    "Submit"         := "" <USE_HTML_VAL> ;
                     // unchanged, value: "Sign In"
Parent topic: Parameterization


Input Values

Form field values that begin and end with underscores, or begin with inp., are treated as input values. The recorder generates variables at the top of a script for these values. this makes randomization of input values easier.

Example: Variables created for input values

var
  gsInput_NewProduct : string init "_New Product_";
  gsInput_inp_Customer : string init "inp.Customer";

  // ...

dclform

  // ...

  MAIN009:
    "ICType"          := "" <USE_HTML_VAL> ,
                      // hidden, unchanged, value: "Panel"
    "ICElementNum"    := "" <USE_HTML_VAL> ,
                      // hidden, unchanged, value: "0"
    "ICStateNum"      := "" <USE_HTML_VAL> ,
                      // hidden, unchanged, value: "6"
    "ICAction"        := "#ICSave",
                      // hidden, changed(!)
    "ICXPos"          := "" <USE_HTML_VAL> ,
                      // hidden, unchanged, value: "0"
    "ICYPos"          := "" <USE_HTML_VAL> ,
                      // hidden, unchanged, value: "0"
    "ICFocus"         := "" <USE_HTML_VAL> ,
                      // hidden, unchanged, value: ""
    "ICChanged"       := "" <USE_HTML_VAL> ,
                      // hidden, unchanged, value: "0"
    "ICFind"          := "" <USE_HTML_VAL> ,
                      // hidden, unchanged, value: ""
    "PROD_ITEM_DESCR" := gsInput_NewProduct,
                      // changed, value: "_New Product_"
    "PROD_ITEM_EFF_STATUS" := "A",
                          // added
    "RBF_ARRA_WRK_PROD_ATTR_CATEGORY" := "",
                                      // added
    "PRD_KIT_ARR_FLG1" := "" <USE_HTML_VAL> ,
                       // unchanged, value: "S"
    "DESCR$0"         := "" <USE_HTML_VAL> ,
                      // unchanged, value: ""
    "RBF_ARRA_PRD_VW_DESCR$0" := "" <USE_HTML_VAL> ,
                              // unchanged, value: ""
    "RBF_PROD_ARGMT_RAISE_PCT$0" := "" <USE_HTML_VAL> ,
                                 // unchanged, value: ""
    "RBF_PROD_ARGMT_REDUCTION_PCT$0" := "" <USE_HTML_VAL> ,
                                     // unchanged, value: ""
Parent topic: Parameterization


HLS Support

HTTP Live Streaming (HLS) is an HTTP-based communications protocol for media streams. HLS has been widely adopted for video and audio delivery across the industry around the world. No matter if embedded in a web page or consumed through a standalone video player, Silk Performer automatically detects HLS traffic during recording and simulates a video player consuming HLS data during playback.

Silk Performer provides the BDL functions HlsInit and HlsPlay to load test audio and video delivery systems in on-demand or live streaming scenarios.

Silk Performer provides comprehensive statistics and metrics for streams and reliably detects stoppages due to bandwidth constraints or server issues.

Parent topic: Load Testing Specific Application Types


Load Testing in Specific Environments

Silk Performer supports testing within a variety of computing environments.

  • Silk Performer CloudBurst
    Introduces you to Silk Performer CloudBurst and explains how load testing in the cloud works.
  • Developing Performance Tests in Visual Studio
    Describes how you can develop performance tests in Microsoft Visual Studio using the Visual Studio extension.
  • Multibyte Support
    Defines frequently-used character encodings, the subset of characters that are used in specific regional areas of the world, and multibyte support.
  • Integrating Silk Performer in CI Environments
  • Network Emulation
    Describes how you can emulate networks with Silk Performer and provides important information around the network emulation driver.
  • Windows Vista and Windows 7
    Explains Silk Performer support for User Account Control (UAC) on Windows Vista and Windows 7 machines. Also explains the value of launching agent processes under an administrator account in certain situations.
Parent topic: Silk Performer Workbench 21.0


Silk Performer CloudBurst

  • Overview
    Explains what Silk Performer CloudBurst is and how it works.
  • Working with CloudBurst
    Introduces the Cloud Agent Manager and explains how to deal with various CloudBurst tasks you might have to perform.
  • CloudBurst VPN
    Describes how to configure a VPN to test an application within a secure company network.
  • Micro Focus Credits
    Describes what Micro Focus Credits are and how these are calculated.
Parent topic: Load Testing in Specific Environments


Overview

Silk Performer CloudBurst offers an affordable and flexible approach to confirming whether the system under test meets your performance requirements. CloudBurst enables you to rent virtual infrastructure, virtual users, or a combination of the two for as long as you need them.

With CloudBurst you can run load tests without permanent licenses. You are charged on a per-use basis, up to a number of concurrently executed virtual users within a 24-hour testing period.

The CloudBurst virtual infrastructure is made available to you in the form of pre-configured, ready-to-use cloud agents, which can be deployed across multiple geographical regions. You can even combine pay-per-usage CloudBurst virtual agents with other agents you may have access to in your on-premise testing infrastructure (using a permanent Silk Performer license), all within the same load test.

If you choose to run tests with workload that requires additional virtual users beyond what your permanent Silk Performer license offers, you can use your CloudBurst license to deliver the additional virtual users on a pay-per-use basis.

  • CloudBurst Infrastructure
    Describes the basic concept behind Silk Performer CloudBurst and outlines the CloudBurst infrastructure.
  • Advantages of Using CloudBurst
    Load testing with cloud agents offers a number of advantages.
  • CloudBurst Offering
    Describes how the CloudBurst offering works.
Parent topic: Silk Performer CloudBurst


CloudBurst Infrastructure

Cloud computing and Silk Performer CloudBurst extend the capabilities of traditional load testing. Silk Performer CloudBurst allows you to deploy agents in the cloud and let them load test all your applications, no matter if they are hosted on-premise or in the cloud. In addition, you can use a CloudBurst VPN to test your internal (non-Internet-facing) applications.

The diagrams below illustrate the basic concept behind CloudBurst. The first diagram shows how the cloud is used as a platform for Silk Performer agents that run tests against an Internet-facing application (the System Under Test).

Cloud-based load test infrastructure

The second diagram shows a hybrid scenario: Besides the agents that reside in the cloud, additional local agents, which reside in the local intranet, are used. This allows you to set up a number of agents that access your System Under Test from various locations. With the help of CloudBurst, you can define a broad range of regions, which provides you with comprehensive performance data.

Furthermore, such a combined setup provides you with the best possible test results: While cloud agents provide a realistic simulation of end-users through the Internet (and also help to detect performance issues), the local agents can be used for conventional performance testing and for identifying performance issues and bottlenecks.

Hybrid load test infrastructure
Parent topic: Overview


Advantages of Using CloudBurst

Load testing with cloud agents offers a number of advantages:
  • Availability: Cloud agents are available within minutes. You save time, because no setup or maintenance work is required, as it is with physical machines.
  • Scalability: The number of cloud agents is scalable. No matter if you need hundreds or just two of them - you can increase or decrease their number at any time. By default, Silk Performer offers a certain amount of cloud agents. If you require more cloud agents, get in touch with support.
  • Deployment: Cloud agents can be deployed easily and quickly. You can choose your cloud agents from a variety of regions across the globe.
  • Maintenance Cost: With CloudBurst, you save maintenance cost: You only pay for the time your cloud agents are actually running.
  • Cloud Agent Manager: All cloud-related settings can be managed easily with a single intuitive tool: the Cloud Agent Manager.
Parent topic: Overview


CloudBurst Offering

To get started with Silk Performer CloudBurst, register on the Micro Focus Build Portal and contact your sales representative to purchase Micro Focus Credits. Once your account is filled with Micro Focus Credits, you can use them to purchase the virtual infrastructure and/or virtual users you need to successfully run your performance tests.

Silk Performer CloudBurst is available as prepaid and as pay-as-you-go model, where you are charged monthly according to your Micro Focus Credits consumption.

Before you launch virtual agents or consume virtual user resources from CloudBurst, Silk Performer will confirm your approval that your CloudBurst account can be debited.

Parent topic: Overview


Working with CloudBurst

  • Cloud Agent Manager
    Explains how to use the Cloud Agent Manager to start and stop cloud agents, to reserve and release IP addresses, and to configure a CloudBurst VPN.
  • CloudBurst Connectivity Requirements
    Explains how the controller machine must be connected to the Internet.
  • Downloading Results from Cloud Agents
    Describes how to manually download results from cloud agents, and explains what happens if the connection is lost during a load test execution or during the process of downloading results from cloud agents.
  • Configuring Java for Cloud Agents
    If you want to use Java-related technology on cloud agents, you might have to define the path to the java runtime environment (JRE).
Parent topic: Silk Performer CloudBurst


Cloud Agent Manager

To start the Cloud Agent Manager, click Tools in the Silk Performer menu and click Cloud Agent Manager. Then, login to an existing account or register.

The Cloud Agent Manager is an easy to use tool for managing all your CloudBurst tasks. It provides the following features:
  • Reserve Addresses: Reserve IP addresses for your cloud agents. This ensures that your cloud agents keep the same IP addresses, which prevents you from regularly recurring work like specifying IP address exceptions for your firewall.
    Note: IP addresses are perpetually reserved for 24-hour time periods until you release the IP addresses.
  • Release Addresses: Release IP addresses you have had reserved.
  • Start Agents: Start cloud agents to use them in a load test. On the Start Agents dialog, you can specify the number of agents per region as well as how and when the agents are supposed to be shut down.
  • Stop Agents: Manually stop agents when you no longer need them. On the Manage your Cloud Agents dialog, you can also see when the agents are automatically shut down, if an automatic shutdown behavior had been specified.
  • Configure VPN: Configure a CloudBurst VPN to enable testing a machine that is part of your secured company network.
  • Refresh: Refreshing the displayed data is useful as it may take some time before agents you start become available in the cloud.
  • Logout: You can find the logout button on the bottom right of the window.

Close the window to exit the Cloud Agent Manager. The list of available agents on the Workload Configuration dialog box is updated automatically.

Parent topic: Working with CloudBurst


CloudBurst Connectivity Requirements

Controller

To use CloudBurst, a controller machine must be connected to the Internet by one of the following methods:
  • direct connection
  • HTTP Proxy (no authentication)
  • HTTP Proxy (basic authentication)
  • HTTP Proxy (NTLM authentication)
  • HTTP Proxy (Kerberos authentication)

If a proxy server is present, the server must allow the HTTP CONNECT method to port 443.

Cloud Agents

A cloud agent is a virtual image. Communication between the controller and cloud agents is conducted over an HTTPS connection. The cloud agent allows for unrestricted outbound traffic. Inbound traffic is limited to port 443 and the HTTPS protocol.

Parent topic: Working with CloudBurst


Downloading Results from Cloud Agents

When a load test is completed, Silk Performer automatically downloads all results from your cloud agents. However, when the connection to the cloud agents is lost, the following applies:

  • If the connection is lost during the execution of a load test, the controller tries to retrieve the results when the load test is completed. However, these results are not merged with the rest of the results. In such a case, Silk Performer will notify you with a message that results from disconnected agents are available in the results folder.
  • If the connection is lost during the download process, Silk Performer will try to restart the download process and will add the results to the rest of the results. Usually, as a user, you will not notice any difference.
  • You can also manually download results: In the Cloud Agent Manager, right-click an agent and click Retrieve Results. A dialog opens, containing a list of all the results. Specify a target folder and download the results to your machine.
Parent topic: Working with CloudBurst


Configuring Java for Cloud Agents

If you want to use Java-related technology on cloud agents, you might have to define the path to the java runtime environment (JRE). The 64-bit JRE is located in C:\Program Files\Java\JRE. The 32-bit JRE will be found automatically.
Parent topic: Working with CloudBurst


CloudBurst VPN

Company networks are usually protected by one or more firewalls, which typically block any unknown incoming traffic. If you intend to use cloud agents to test an application on a server environment that is part of your company network, you have the following options:

  • Make the system under test accessible from the internet by configuring the company firewall for port forwarding or DMZ operation. Your IT department will help you with this task. Note that due to restrictive company policies, this option might be difficult to implement.
  • Configure a CloudBurst VPN, a virtual private network between the cloud agents and a routing device within the company network, which allows the agents to access the system under test in the company network via proven and secure VPN technologies. The routing device forwards the incoming traffic between the system under test and the cloud agents.

To learn how to correctly configure a CloudBurst VPN, see Configuring a CloudBurst VPN.

Note: CloudBurst VPN is based on the UDP (User Datagram Protocol). It works through firewalls, which allow to establish UDP communication initiated from the router appliance (on-premise). Furthermore, operation through an HTTP proxy is not supported.
  • Basic Concept Behind CloudBurst VPN
    This topic outlines the basic concept behind CloudBurst VPN.
  • Configuring a CloudBurst VPN
    Describes how to configure a CloudBurst VPN in Cloud Agent Manager.
  • VPN Router Appliance
    Describes what the VPN router appliance is and how to execute it on the router.
Parent topic: Silk Performer CloudBurst


Basic Concept Behind CloudBurst VPN

Note: This topic is supposed to help you understanding the basic concept behind CloudBurst VPN. To learn how to actually configure a CloudBurst VPN, see Configuring a CloudBurst VPN.
The basic steps to configure a CloudBurst VPN are:
  1. Open the CAM (Cloud Agent Manager)
  2. Add a VPN configuration
  3. Download the VPN router appliance and install it on the routing device
  4. Start one or more cloud agents. Once the VPN is operational running cloud agents will automatically join it. Note that you can start agents any time, before or after the VPN configuration
The following paragraph explains what happens in the background when a VPN is configured. Take a look at the graphic below to get a better idea of the concept behind the process:
  1. When you open the CAM and start cloud agents, the CAM connects to the Silk Performer CloudBurst Service and requests cloud agents to be launched.
  2. The CloudBurst Service updates the CAM about all cloud agents and their status.
  3. When you add a VPN configuration, the CAM connects to the CloudBurst Service, which tells the Cloud Agents to act as VPN Servers.
  4. When you download the VPN router appliance and install it on the routing device (Router), the device acts as VPN Client.
  5. The VPN Client/Router requests the VPN details from the CloudBurst Service along with the list of available cloud agents.
  6. The VPN Client/Router connects to the Cloud Agents/VPN Servers.
  7. The Cloud Agents/VPN Servers connect to the specified DNS Server to check if the company network can be reached.
  8. When you start a load test, the Cloud Agents can use the connection through the Firewall and through the VPN Client/Router to put load onto the System Under Test (SUT).
Parent topic: CloudBurst VPN


Configuring a CloudBurst VPN

  1. In the main menu, click Tools > Cloud Agent Manager.
  2. Login to your CloudBurst account with your user name and password.
  3. Click Start Agents, enter the desired amount of agents per region, and click Start. The Status column displays Starting. When the agents are started, the column displays Ready.
  4. Click Configure VPN and click Add.
  5. Enter a Name for your VPN configuration.
  6. Enter the hostname of your System Under Test (SUT) and click Get network settings. The Cloud Agent Manager (CAM) then tries to resolve the IP address of the SUT. Based on that IP address, all company network settings are filled in automatically.
  7. If the SUT cannot be reached, an information dialog box displays. This is generally the case when your machine and the SUT are not in the same subnet and when your machine is not allowed to access the subnet of the SUT. In such a case, fill in the company settings manually.
    Note: If you have problems finding out the correct settings, contact your system or network administrator.
  8. Make sure that Activate VPN immediately is checked and click OK. The State column displays Preparing VPN.
  9. When the State column displays Waiting for router, click the link download router image. This will download an appliance for the virtual machine software VirtualBox.
  10. Transfer the appliance to the routing device.
    Note: The router appliance must be located in the same network segment as the System Under Test (SUT). If this is not possible, contact TechSupport for further instructions.
  11. If you have not installed VirtualBox on the routing device, download the setup file from the VirtualBox website (https://www.virtualbox.org/) and install it.
  12. Start VirtualBox, import the appliance and start it.
    Note: Make sure to assign new MAC addresses to all network cards before you import the appliance.
  13. Enter your CloudBurst credentials. A Linux operating system starts in Virtual Box. This makes the routing device a VPN client.
Once the Linux operating system runs, the Cloud Agent Manager (CAM) displays that the connection to the router is established. Your CloudBurst VPN is set up.
Parent topic: CloudBurst VPN


VPN Router Appliance

During the process of configuring a CloudBurst VPN, you have to download the VPN router appliance and transfer it to the routing device. The VPN router appliance is a Linux appliance for the virtualization software VirtualBox. Hence, make sure that VirtualBox is installed on the router beforehand.

Then, import the appliance in VirtualBox and start it. VirtualBox will start a Linux operating system. Once Linux is running, the routing device acts as VPN client. The VPN client is then part of the CloudBurst VPN and routes all incoming traffic from the cloud agents to the specified subnet within the company network.

Note: The router appliance must be located in the same network segment as the System Under Test (SUT). If this is not possible, contact TechSupport for further instructions.
Parent topic: CloudBurst VPN


Micro Focus Credits

Micro Focus Credits are a virtual currency that can be used to purchase CloudBurst testing services, available from the Micro Focus Build Portal. The billing process follows a pre-paid model: You first purchase Micro Focus Credits and then decide how and when you want to spend them.

The price per Micro Focus Credit depends on how many credits you buy at one time. There are several credit packages to choose from.

Note that Silk Performer CloudBurst provides an invitation system: On the Micro Focus Build Portal, you can invite other CloudBurst users to join your CloudBurst account. This allows the other CloudBurst users to make use of the Micro Focus Credits that are purchased for your account.

  • CloudBurst Load Test Fees
    Describes the CloudBurst load test fees, which are comprised of the infrastructure rental fees and the virtual user license fees.
  • Estimating and Debiting Micro Focus Credits
    Describes how the consumption of Micro Focus Credits is estimated and how Micro Focus Credits are debited.
Parent topic: Silk Performer CloudBurst


CloudBurst Load Test Fees

The amount of Micro Focus Credits required to purchase a CloudBurst test is comprised of infrastructure rental fees and virtual user license fees.

Infrastructure Rental Fees

There are three types of infrastructure rental fees:
  • active infrastructure rental fee
  • passive infrastructure rental fee
  • fee for IP address reservation

Infrastructure rental fees are paid for each hour following the start of a cloud agent. Each started hour is charged as a full hour. For example: If an agent runs for 50 minutes, you are charged for 1 hour. If the agent runs for 1 hour and 5 minutes, you are charged for 2 hours.

The infrastructure rental fee is comprised of a passive and an active fee. The passive fee is charged for the time an agent runs, the active fee is charged for the time the running agent is used to execute a load test. During the execution of a load test, both the passive and the active fee are charged. For example: You start a load test with a simulation time of 2 hours. When the load test is complete, you prepare for a second load test, which takes you 1 hour. In the meantime, you leave the agent running. Then you start the second load test with a simulation time of 30 minutes. For this scenario, you are charged a 4-hour passive fee and a 3-hour active fee. Note: The 30 minutes are calculated as a full hour.

Note: If you run out of Micro Focus Credits while using the CloudBurst infrastructure, you will be notified by email 24 hours before your agents are shut down automatically.

Reserving IP addresses for your cloud agents also causes infrastructure rental fees. The current rate for reservation displays in the Cloud Agent Manager. Reserving IP addresses prevents you from regularly recurring work like specifying IP address exceptions for your firewall.

Note: IP addresses are perpetually reserved for 24-hour time periods until you release the IP addresses.

Virtual User License Fees

Virtual user license fees are calculated based on the maximum number of concurrently active virtual users consumed within a 24-hour testing period. The fee per active virtual user is largely dependent on the application type under test. For example: If you start a load test with 100 virtual users, you are charged a 100 virtual users license fee for the 24-hour testing period. When the load test is complete, you start another load test with 150 virtual users. Now you are charged a fee for the 50 additional virtual users. For the next load test, you configure to use 120 virtual users. This test will not cause an additional fee, since the already debited fees cover up to 150 virtual users. This is true if you execute all three load tests from this example within the 24-hour testing period.

For more information about current rates, visit the Micro Focus website.

Spanning Testing Periods

The 24-hour testing period model allows you to run a load test, analyze the results, and rerun the load test multiple times with adjusted settings. Within the 24-hour testing period, you can optimize the settings of your load test and rerun the test without paying for each additional test run.

If a test, which is started within one 24-hour testing period, would extend into the next testing period, a new 24-hour testing period is automatically created with the start of the load test.

Note: The maximum simulation time for CloudBurst load tests is 24 hours.
Parent topic: Micro Focus Credits


Estimating and Debiting Micro Focus Credits

Estimating Micro Focus Credits Consumption

Before you start a load test, Silk Performer displays an estimate of how many Micro Focus Credits you will likely be charged by the end of the load test. The estimate takes all virtual user license fees that are covered in the current testing period into account. However, it does not include any unforeseen charges that may be related to changes in simulation time or concurrently executed load tests.

If you use the dynamic workload model, which requires you to stop tests manually, the infrastructure rental fee estimate will be equal to the required Micro Focus Credits per started hour.

Debiting Micro Focus Credits

When a test is complete, Silk Performer calculates the amount of Micro Focus Credits that is to be debited from your account. This calculation takes into account the actual simulation time, which is used to calculate the active infrastructure rental fee, and the testing period boundary for virtual user license fees.

A detailed balance sheet is available from the Silk Performer Load Test Summary page, which is displayed following each test.

Parent topic: Micro Focus Credits


Developing Performance Tests in Visual Studio

The Silk Performer Visual Studio extension allows you to develop performance tests in Microsoft Visual Studio. It offers functionality to record web technologies, supporting both the protocol-level as well as the browser-driven approach. The recording functionality of the Visual Studio extension resembles the one of the Silk Performer Workbench and includes capturing web traffic and user interactions. The captured information can be converted into a C# class including methods, each representing a user transaction.

The Visual Studio extension offers a comprehensive C# binding for all kernel, web, and browser API functions. Thus, it combines the rich development feature set of Visual Studio, including all debugging features, with the powerful load testing capabilities of Silk Performer, including capture file recording and TrueLog analysis.

Tests created with the Visual Studio extension can be executed either within Visual Studio for trial runs, or within Silk Performer for concurrency and load testing scenarios. When exporting C# projects to Silk Performer, a short BDL script stub is generated, containing calls into the compiled C# code (assembly).

To learn how to install the Visual Studio extension, refer to the Installation Guide.

  • The C# Binding
    Describes details about the C# binding, the structure of the C# script, and the mapping of data types.
  • Licensing
    Describes how licensing works when executing load tests that were created in Visual Studio using the Visual Studio extension.
  • Capture File Compatibility
    Capture files created during a recording session are fully compatible between Visual Studio and the Silk Performer Workbench.
  • Advanced Topics
    Explains a number of advanced topics around developing performance tests in Visual Studio.
Parent topic: Load Testing in Specific Environments


The C# Binding

Currently, Silk Performer supports all kernel, web, and browser BDL functions for C# binding. In Visual Studio you can access these functions by calling their equivalent static C# class methods, such as Kernel.MeasureStart(), Web.PageUrl(), or Browser.Click().

In other words: For each built-in Silk Performer .bdh file, you will find a corresponding C# class in the PerfRunDotNet assembly. And for each API function defined in that .bdh file, there is an equivalent static method in the corresponding C# class.

C# script structure

A C# class that is intended to be used for load testing in Silk Performer contains a VirtualUser attribute and a CodePage attribute. VirtualUser specifies a UserName and a ScriptName property. CodePage specifies the codepage of the recording system. Methods with the Transaction attribute will be mapped to transactions when exported to Silk Performer.

namespace SilkPerformerRecorder
{
  [VirtualUser(UserName = "VUser", ScriptName = "MyScript")]
  [CodePage(1252)]
  public class MyScript
  {
    [Transaction(ETransactionType.TRANSTYPE_INIT)]
    public void TInit()
    {
    }

    [Transaction(ETransactionType.TRANSTYPE_MAIN)]
    public void TMain()

Data Type Mapping

To pass parameters from .Net/C# to BDL and vice versa, some built-in data types have to be converted.

Strings

While Silk Performer and its BDL are based on the multi-byte character set (MBCS) encoding, the C# language works with Unicode. Thus, every string has to be converted when passed between the two worlds. The PerfRunDotNet assembly works with the BdlString class, which handles all these conversions. Moreover, it also takes care about binary buffers. For convenience, the BdlString class is assignment compatible with the C# string.

Sizespec and lenspec variables have been removed in the C# mapping, since C# strings typically know their length.

Static parameter values

Some static integer values, like severity parameters, have been replaced by specific enums.

Forms

BDL forms are mapped to a BdlForm class in C#:

private static readonly BdlForm ZIP_SEARCH001 = new BdlForm()
    {
      Entries = new BdlFormEntries()
      {
        { "zip-search", "", Kernel.USE_HTML_VAL }, // hidden, unchanged, value: "zip-search"
        { "zip-search:zipcode", "", Kernel.USE_HTML_VAL }, // unchanged, value: ""
        { "javax.faces.ViewState", "", Kernel.USE_HTML_VAL }, // hidden, unchanged, value: "j_id3:j_id4"
        { "zip-search:search-zipcode.x", "62" }, // added
        { "zip-search:search-zipcode.y", "4" } // added
      }
    };

Code page dependent replay

Due to Silk Performer being a MBCS-based application, the recorder automatically generates a codepage attribute in the C# script, which gets carried over to the .bdf script stub. It also takes care about converting all Unicode strings that cannot be represented in the system codepage into hex-byte arrays.

If the CodePage attribute is defined in a C# script, the following applies:

  • All classes in the project must have the same codepage.
  • Each string used in the C# script has to be convertible to MBCS strings using that codepage.
  • The defined codepage is used to convert C# strings (Unicode) into MBCS strings, and also to interpret the hex byte arrays generated by the recorder. Therefore the codepage attribute should always be set, especially if the recorder generated hex byte arrays when encountering otherwise unprintable characters.
  • A compiletime-check makes sure that all strings work for the defined codepage.

If the CodePage attribute is not defined in a C# script, the system codepage is used during replay.

Parent topic: Developing Performance Tests in Visual Studio


Licensing

The licensing of load tests with C# test scripts is similar to the licensing model that applies when using BDL as scripting language. A single user run is always license-free. During a trial run, no license is being checked out. When executing a load test using C# scripts, Silk Performer checks for the technologies used in the scripts and maps them to equivalent feature license type web, standard, or premium. The mapping is the same as with BDL.

If however a C# script is used for .Net testing rather than driving one of the supported Silk Performer technologies, a standard license will be checked out.

Parent topic: Developing Performance Tests in Visual Studio


Capture File Compatibility

Capture files created during a recording session in Visual Studio are fully compatible to capture files created directly within the Silk Performer Workbench. Thus, you can add a capture file to a C# project - by dragging it onto the Visual Studio project tree - and generate a C# script.

You can also reuse a capture file created in Visual Studio by adding it to a Silk Performer project manually and then generating a BDL script out of it.

Parent topic: Developing Performance Tests in Visual Studio


Advanced Topics

Note the following when working with the Visual Studio extension.

  • If the C# code is compiled in debug mode and debug symbols are available, those are used to add information about the current position in the C# script also to nodes in the replay TrueLog. In this case, the current position in the C# script is shown in the Script tab of TrueLog Explorer instead of the current position in the .bdf stub script.
  • In Visual Studio you can create a C# or VB.Net project and code manually. Note however, that the recorder only prints C# code. The recording feature is only available if a C# project is used.
Parent topic: Developing Performance Tests in Visual Studio


Multibyte Support

Unicode is a list of all known characters. It includes all alphabets of all spoken and unspoken languages. Each character has its own unique index in the Unicode list. The first 128 characters are known as ASCII characters.

Multibyte example graphic

When data is stored or computed, the Unicode list is not used to represent the characters. Instead, so-called character encodings (or character sets) define how characters are represented on computers and within files. Numerous character sets are used throughout the world.

Two of the more frequently-used character encodings that cover all Unicode characters are:

  • UTF-8: Requires 1-4 Bytes per character; this character set is widely used for international Web sites and international text representation. Strings in the Linux kernel and Java are encoded in UTF-8.
  • UTF-16: Requires 2 or 4 Bytes per character; this encoding is mainly used for string representation in the Windows NT kernel (Win NT and newer).
Most character sets do not define a representation for all characters in the Unicode list. Rather, they define a subset of characters that are used in a specific regional area of the world. These are commonly referred to as code pages (cp):
  • ASCII: Single Byte encoding: 1 Byte per character
  • Latin-1 (Windows Codepage 1252): Single Byte encoding: 1 Byte per character
  • Shift-JIS (Windows Codepage 932): Double Byte encoding: 1 or 2 Bytes per character
  • EUC-JP (Windows Codepage ): Includes 3 Japanese char sets: 1, 2, or 3 Bytes per character

When developing applications for Windows, programmers can choose between Unicode (UTF-16) string representation or Multi-Byte-Character-Set (MBCS) string representation. MBCS representation refers to a geographic region-dependent code page encoding (for example, Shift-JIS for Japan; Latin-1 for the Americas and most European countries). This affects all GUI elements, as all data needs to be displayed in the same string representation that has been selected for the application.

  • Multibyte Support in Silk Performer
    Describes how Silk Performer uses MBCS format.
  • Codepage Check
    Describes how Silk Performer uses @codepage annotation.
  • API Functions That Require Additional Encoding
    Lists API functions that require additional encoding.
  • Copying Strings into Silk Performer
    Describes the process that occurs when a string is pasted into Silk Performer.
Parent topic: Load Testing in Specific Environments
Related reference
Keywords


Multibyte Support in Silk Performer

Silk Performer is a MBCS-based application, meaning that to be displayed correctly, every string must be encoded in MBCS format. Because Silk Performer, and particularly TrueLog Explorer, visualize and customize data that originates from Web servers with different encodings (UTF-8, EUC-JP, ISO-8859-1, and so on), many string conversion operations may be involved before data can be displayed.

Sometimes when testing UTF-8 encoded Web sites, data containing characters cannot be converted to the active Windows system codepage. In such cases, Silk Performer’s Web Recorder scripts all non-convertible strings into hex format. If the data is only displayed, TrueLog Explorer will replace the non-convertible characters with a configurable replacement character (usually '?').

Example

On an English Windows system with Japanese local settings (system codepage is Shift-JIS) a UTF-8 application is recorded. For some reason a link name on a particular Web page contains a Korean character. Silk Performer’s Web Recorder attempts to convert the string from UTF-8 to Shift-JIS to make it readable in the script. The conversion fails because of the Korean character, which does not occur in the Shift-JIS code page. The Web Recorder then uses hex notation for the link name in the script.

Parent topic: Multibyte Support


Codepage Check

One of the most important things to know about Silk Performer's multibyte support is that the system codepage of the recording machine must match the system codepage of the replay machine. This is necessary for the replay engine to correctly interpret the byte sequences in the script as characters and strings.

Therefore the Silk Performer Recorder scripts the @codepage annotation into the script along with the currently active system codepage. Whenever this annotation is present in a script the Silk Performer runtime system checks if the system codepage of the machine matches the one specified in the script. If they do not match the runtime stops and an error message displays. However, you can add a second parameter to the @codepage annotation with the value false. In this case an information displays but the execution continues.

Syntax

@codepage( in codepage        : number,
           in abortOnMismatch : boolean optional := true )

Example

@codepage(123)          // aborts the execution when the codepages do not match
@codepage(123, false)   // an information indicates the mismatch, but the execution continues
Parent topic: Multibyte Support


API Functions That Require Additional Encoding

Regardless of the character encoding that a Web site uses, Silk Performer can only visualize multi-byte character set (MBCS) strings. However, several API functions require the encoding of some string parameters in the encoding that the server expects. Silk Performer's Web Recorder scripts SetEncoding(), ToEncoding(), and FromEncoding() functions at appropriate locations so that replay engines can know the required encoding. Typically, parameters that require an appropriate encoding, such as link names, if they refer to data that needs interpreting. Parameters that are not a part of client-server communication, such as timer names, do not require conversion.

The SetEncoding() function sets an encoding for all subsequent ToEncoding() and FromEncoding() functions. The encoding itself is passed as the name of the encoding as it appears in the charset specification of the Web page, such as UTF-8, SHIFT_JIS, WINDOWS-1252, WINDOWS-1255, or EUC-JP.

ToEncoding() converts the string that is passed as a parameter, which is encoded in the system codepage (MBCS), to the encoding specified by the last SetEncoding() function.

FromEncoding() converts the string that is passed as a parameter, which is encoded in the encoding specified by the last SetEncoding() call, to the system codepage (MBCS).

Parent topic: Multibyte Support
Related reference
SetEncoding Function
ToEncoding Function
FromEncoding Function


Copying Strings into Silk Performer

When copying strings into Silk Performer, the paste operation checks if the data:
  • Needs to be converted to the MBCS (system codepage)
  • Can be converted to the MBCS
  • Cannot be converted and so needs to be opened with Silk Performer’s Unicode Text/Hex Editor

If copied data is, for example, UTF-8 encoded and the paste operation fails to convert it to the system codepage, Silk Performer launches its Unicode Text/Hex Editor. The tool is a Unicode application and is therefore able to display any string, regardless if the characters exist in the system codepage. The editor can also display the hex notation of strings in order to paste them into a BDL script.

Parent topic: Multibyte Support


Integrating Silk Performer in CI Environments

  • Starting Silk Performer from the Command Line
    This topic explains how to start Silk Performer load tests directly from a command-line interface. Additionally, it lists the available command line parameters.
  • Executing Load Tests Through the Command Line
    Explains the syntax of the PerfExec.exe command line tool, shows a sample command, and lists the parameters of the tool.
  • Modifying Project Settings Through the Command Line
    Explains the syntax of the PerfProj.exe command line tool, shows a sample command, and lists the parameters of the tool.
  • Result Files in JUnit Format
    Silk Performer lets you generate result files in JUnit format, which can be automatically interpreted in various CI tools, like Jenkins.
Parent topic: Load Testing in Specific Environments


Executing Load Tests Through the Command Line

Command Syntax

PerfExec.exe is a tool that lets you execute load tests through the command line. In contrast to the command line tool performer.exe, which opens the Silk Performer workbench UI, PerfExec.exe operates completely UI-less. Status information about a running test is logged to the command line. To store the output, you can use standard redirection operators like > or >>.

To start PerfExec.exe from a command line, use the following syntax:

perfExec.exe –ltp project file [-wl workload name] [-rd custom results directory]

Here is a sample command with sample parameters:

perfExec.exe –ltp "<my documents>\Silk Performer <version>\Projects\SPProject\SPProject.ltp" –wl Workload1 –rd "<my documents>\ResultsDirectory"
Note: When files or folders in the project path contain spaces, include quotation marks (") around the project path.

Command Line Parameters

Parameter | Description
-ltp | The path of the project to be executed. Specify an .ltp or .ltz file.
-wl | Optional: The name of the workload to be used. If omitted, the active workload is used.
-rd | Optional: The path of the results directory. If omitted, the results are stored in the directory of the .ltp file.
-? | Displays the help.
Parent topic: Integrating Silk Performer in CI Environments


Modifying Project Settings Through the Command Line

Command Syntax

PerfProj.exe is a tool that lets you modify or query settings of a Silk Performer project through the command line.

To start PerfProj.exe from a command line, use the following syntax:

perfProj.exe –ltp project file {[-sh standard host] [-sp standard port] [-af agents list file]} | {[-list profiles|workloads|usertypes] [-wl workload]}

Here are some sample commands with sample parameters:

perfProj.exe –ltp "<my documents>\Silk Performer <version>\Projects\SPProject\SPProject.ltp" –sh "microfocus.com" –sp 80
perfProj.exe –ltp "<my documents>\Silk Performer <version>\Projects\SPProject\SPProject.ltp" –af "<my documents>\Silk Performer <version>\Projects\SPProject\agents.txt"
perfProj.exe –ltp "<my documents>\Silk Performer <version>\Projects\SPProject\SPProject.ltp" –list profiles
perfProj.exe –ltp "<my documents>\Silk Performer <version>\Projects\SPProject\SPProject.ltp" –list usertypes –wl Workload1
Note: When files or folders in the project path contain spaces, include quotation marks (") around the project path.

Command Line Parameters

Parameter | Description
-ltp | The path of the project to be executed. Specify an .ltp or .ltz file.
-sh | The new standard host.
-sp | The new standard port.
-af The path to a file containing a list of agents. The listed agents will replace the current agents of the project.
Note: Make sure that every agent in the list is on its own line.
-list Query the project. Use one of the following options:
  • profiles
  • workloads
  • usertypes
-wl | If the list parameter is usertypes, this parameter specifies for which workload the usertypes will be listed.
? Displays the help.
Parent topic: Integrating Silk Performer in CI Environments


Result Files in JUnit Format

Silk Performer lets you generate result files in JUnit format, which can be automatically interpreted in various CI tools, like Jenkins. The result file displays any errors that might have occurred and shows warnings if performance levels were not met.

For each user type, the JUnit-formatted result file contains:
  • error messages, if any errors occurred
  • information in case performance levels were not met
To use JUnit-formatted result files:
  • Enable the feature in the system settings: click Settings > System in the menu, click the Results tab and check the check box Write JUnit result.
  • Save the project.
  • Upload the project to your CI tool.
  • Configure your CI tool to use the file junit.xml, which is being generated in the load test directory.
Parent topic: Integrating Silk Performer in CI Environments


Network Emulation

Network Emulation Settings

Whenever a client and a server need to communicate, a connection between the two is established through one or more networks. This network connection is used to send and receive data, which typically is split into data packets.

The connection between client and server can comprise various networks with vastly diverse characteristics. This can result in a delayed transfer of data packets (latency), in a loss of data packets (packet drop rate), or in a reduced transfer rate of one of the networks (bandwidth).

Silk Performer allows you to emulate complex network connections by configuring a range of settings and parameters:

  • The Latency is the time that is required for a data packet to travel from one endpoint of the network connection to the other. It depends on various factors, such as the physical speed limit of the network medium (fiber, wire, over-the-air), the bandwidth restrictions and the distance between the two endpoints. The latency of a network connection can vary over time. This variation is called jitter. For typical web load testing scenarios jitter is of less importance as network emulation parameter. Emulating jitter is not supported by Silk Performer.
  • The Bandwidth is defined as the data transfer rate, bit rate or throughput. It is measured in bits per second (bit/s or bps), kbps, Mbps, or Gbps.
  • The Packet drop rate: Occasionally data packets can get lost on the way from the sender to the receiver. The main reason for dropped packets is an overloaded network or network device. The TCP/IP (Transmission Control Protocol/Internet Protocol) has a built-in detection of dropped packets and guarantees that sent packets are delivered even if some get lost and need to be retransmitted. A high packet drop rate involves high administration effort on the TCP/IP level and thus has a significant effect on the data throughput.

Silk Performer offers presets (preconfigured settings) for a variety of wired and wireless network technology standards. You can adjust all settings to your needs to simulate specific network conditions.

The Network Emulation Driver

Silk Performer can emulate bandwidth limitation out of the box. For latency and packet drop emulation a dedicated network emulation driver is required. By default, the driver is not installed with Silk Performer. To use the full network emulation functionality, make sure to install the driver during Silk Performer setup on your agents.

Important: Enable Use Network Emulation Driver in the profile settings only if the network emulation driver is installed on your agents. You can then adjust the Latency and Packet Drop settings to your needs. If the driver is not installed and you enable this option, an error will occur during load test execution.

Note the following specifics:

  • The network emulation driver is not compatible with all network adapters. In such a case, machines or network interfaces might no longer be accessible and the network might slow down.
  • The network emulation driver is currently not supported for Windows 10.
  • Network emulation is not supported for CloudBurst.
Parent topic: Load Testing in Specific Environments


Windows Vista and Windows 7

Silk Performer is fully compliant with Microsoft User Account Control (UAC) guidelines. It has been designed such that it does not require administrative privileges at any point in its workflow, beginning with project definition and continuing through to test analysis. Even activities such as recording and the launching of remote agent processes can be done with standard user privileges.

The System Configuration Manager however, due to its system administration functions, does require elevation into administrator mode in accordance with UAC guidelines.

UAC Overview

With Windows Vista and Windows 7, Microsoft encourages use of standard user accounts for daily work rather than administrator accounts. Several changes have been made to Silk Performer privilege management to accommodate this change, though these changes are undetectable to users because they do not affect Silk Performer workflow.

Microsoft encourages users to follow their privilege-management paradigm with UAC. UAC informs users when an application leaves the standard user account privileges path and requires higher-level privileges, even when the user account already has the required privileges. For this reason, even administrators are prompted when performing tasks that require administrator privileges. Another consequence of UAC is that software developers are encouraged to write Windows applications that require as few privileges as possible for normal operation.

UAC on Agent Machines

Silk Performer agent processes can be run without administrative privileges. There are exceptions to this however (for example, if an executed script contains an action that requires administrative privileges). In some situations it may be useful or even necessary to launch an agent process under a particular administrator user account. By default however, agent processes are launched under the built-in SYSTEM account.

On machines running a Windows operating system that supports UAC, an administrator account does not automatically hold administrator privileges. Administrator accounts gain new privileges by prompting the user for elevation, which the user may then grant explicitly. By default there is one exception to this behavior: the built-in administrator account does not require manual elevation.

To start an agent process on a UAC-enabled machine, you have the following options:
  • Use the SYSTEM account (default)
  • Use the built-in administrator account and meet one of the following requirements:
    • Turn off UAC
    • Disable security policy User Account Control: Run all administrators in Admin Approval Mode. This can be configured using the Windows Local Security Policy tool (secpol.msc).
  • Use a non-built-in administrator account and meet one of the following requirements:
    • Executed script does not require administrator privileges
    • Executed script does not perform administrative actions
Note: UAC functionality is relevant to the Advanced tab at System Settings > Agents. It is also relevant to SysConfManager > Applications > User Credentials.
Parent topic: Load Testing in Specific Environments


Silk Performer Plug-Ins

Silk Performer offers a plug-in interface which extends Silk Performer’s compatibility to third-party technologies, enabling coordination and control of third-party technologies from within the Silk Performer environment.

The controls that are available for plug-ins vary based on the functionality offered by each plug-in. By default, each plug-in offers the following attributes through the Silk Performer System Settings dialog:

On the General page:

  • plug-in name, version, and description details
  • enabling/disabling of the plug-in
  • a list of features supported by the plug-in
On the Attributes page:
  • name, description, datatype, and value for each available attribute

Depending on available plug-in functionality, other tabs and configurable attributes may also be available.

Silk Performer offers a plug-in framework for third-party diagnostics tools. The framework enables third-party tool vendors to integrate into one or more of the following tools:

  • Silk Performer

    The Silk Performer plug-in can be used to modify profile settings so that the runtime sends an additional HTTP header tag with each page request. The same functionality is available through the WebSetHttpTag BDL function.

  • TrueLog Explorer

    When a user selects an API node, TrueLog Explorer passes the plug-in header and body, including the additional HTTP tag. TrueLog Explorer’s lower-right window includes an additional tab for each enabled plug-in. The plug-in tabs are Internet Explorer controls, so plug-ins can present anything that can be expressed through HTML.

    Plug-ins can use the HTTP tag to identify traces and present complete component break-downs for each web page call.

  • Performance Explorer

    Plug-ins that implement the PerfExp plug-in interface can be called from the (OVR) Overview Report/Ranking section. Overview reports show plug-in related icons for each ranking measurement for which the plug-in can provide in-depth information.

  • Plug-In Initialization and Configuration
    Describes how plug-ins are recognized by Silk Performer.
  • Message Output
    Describes the contents of the Output page.
  • AppDynamics Plug-In
    Silk Performer offers a plug-in framework for AppDynamics, a third-party diagnostics tools.
  • Dynatrace AppMon Plug-In
    Describes how the Dynatrace AppMon plug-In works with Silk Performer.
  • Dynatrace SaaS and Managed Plug-In
    Provides an introduction to the Dynatrace SaaS/Managed plug-in and describes how to configure it.
  • Integrating Silk Performer with InfluxDB and Grafana
    Provides an introduction to the Silk Performer support for InfluxDB and Grafana.
Parent topic: Silk Performer Workbench 21.0


Plug-In Initialization and Configuration

All available plug-ins are installed to the following directory during Silk Performer setup: C:\Program Files\Silk\Silk Performer 21.0\Plugins.

When Silk Performer is launched, it checks for installed plug-ins. All installed plug-ins are then loaded, verified, and initialized.

Plug-ins can be enabled, disabled, or configured by users via Silk Performer’s System Settings dialog. The System Settings dialog adds a new icon in the left-hand pane for each available plug-in. On the General page, basic information (including description, version, and supported features) and the ability to enable/disable the plug-in is provided for each installed plug-in. Each plug-in is also provided an Attributes tab that lists all attributes associated with the plug-in. Some plug-ins may include additional tabs related to available functionality.

Plug-ins are disabled by default and must be enabled before use.

Parent topic: Silk Performer Plug-Ins


Message Output

A new tab is inserted into Silk Performer’s Output window for each installed and enabled plug-in.

Silk Performer outputs all messages from plug-ins into these tabs. Output tabs are removed when plug-ins are disabled.

Output pages display the following information:

  • Timestamp (HH:MM:SS).
  • Severity ("Error," "Warning," or "Info").
  • Numerical message code.
  • The text of the message. Messages are displayed in the color that corresponds to their severity (Error = red; Warning = orange; Info = magenta).
Parent topic: Silk Performer Plug-Ins


AppDynamics Plug-In

The AppDynamics plug-In is installed along with Silk Performer setup. It is disabled by default.

AppDynamics focuses on monitoring performance at the Business Transaction level. Business transactions mirror end user activity and are defined as a category of user requests.

The current Silk Performer - AppDynamics integration supports automatic naming of such transactions based on Silk Performer timer names.

After successful configuration, an API call from Silk Performer such as the following:

BrowserNavigate("http://myserver.mydomain.com/login", "LoginPage");

Appears as the following business transaction in AppDynamics:

SilkPerformer.LoginPage

  • Configuring AppDynamics Plug-In Settings
    Enable the AppDynamics plugin in Silk Performer settings.
  • Configuring Automatic Transaction Naming in AppDynamics
    Define how transactions are to be named so that they can be recognized by both AppDynamics and Silk Performer.
  • Verifying the Integration
    Compare results shown in the AppDynamics Business Transactions List with the Silk Performance Explorer overview report to confirm that the applications are in sync.
  • How Timers are Matched with Business Transactions
    AppDynamics automatic transaction naming parses the HTTP header and applies a custom expression.
  • Advanced Configuration
    The AppDynamics plug-in allows you to specify which tags are being set along with web requests in the additional HTTP header.
Parent topic: Silk Performer Plug-Ins


Configuring AppDynamics Plug-In Settings

  1. In Silk Performer, select Settings > System Settings.
  2. Select the AppDynamics Plug-In group icon.
  3. On the General page, check the Enable plug-in check box.
  4. Configure name/value pairs on the Attributes page as required. The default Tag value is AppDynamicsTag.
    Note:

    A number of integration settings are dependent on the Tag attribute retaining the value AppDynamicsTag. If you change this default value, you will need to change additional settings, as explained below.

  5. Click OK to save your settings.
Parent topic: AppDynamics Plug-In


Configuring Automatic Transaction Naming in AppDynamics

  1. In the leftmost AppDynamics navigation pane, click Configure > Instrumentation.
  2. Select the Use Custom Configuration for this tier option button.
  3. Scroll down to the custom rules section of the page.
  4. Click + to add a custom match rule.
  5. On the Transaction Match Criteria page, select Servlet from the drop-down list.
  6. Specify the name of the custom rule. This name will become the first part of the generated transaction name. For URI select Is Not Empty. Select Check for parameter existence and type AppDynamicsTag, to match what as you configured in Silk Performer, into the Parameter Name field.
  7. Select the Split Transactions using Request Data page and check the Split Transactions using Request Data check box.
  8. In the Apply a custom expression on HTTPServletRequest and use the result in Transaction names field, add the following string:

    ${getHeader(AppDynamicsTag).substring(Int/3)}

  9. Click Save.
Parent topic: AppDynamics Plug-In


Verifying the Integration

  1. Within Silk Performer, start your test. After a few minutes, AppDynamics displays the transaction names in the Business Transactions List. When the test is complete, the Silk Performance Explorer Overview Report appears.
  2. Compare the results of the test shown in the overview report alongside the AppDynamics’ Business Transactions list.
Parent topic: AppDynamics Plug-In


How Timers are Matched with Business Transactions

HTTP requests executed by Silk Performer's replay engine are extended by an additional HTTP header. For example, the following API call:

BrowserFormSubmit("//FORM[@name='loginForm']", "Login");

The HTTP header AppDynamicsTag (the tag attribute you defined during Silk Performer/AppDynamics plug-in configuration) contains the specified timer name NA=<TimerName> (for this example, NA=<Login>.

AppDynamics automatic transaction naming parses the HTTP header by applying the above custom expression “${getHeader(AppDynamicsTag).substring(Int/3)}” to the HTTPServletRequest object and evaluates it to the following Java code: request.getHeader(“AppDynamicsTag”).substring(3)

Note: The purpose of the substring method is to exclude the NA= portion of the HTTP header.

Requests containing the same AppDynamicsTag header are grouped into the same business transaction. For example, all requests with an AppDynamicsTag: NA=Login header would be grouped into a Login business transaction.

Parent topic: AppDynamics Plug-In


Advanced Configuration

The AppDynamics plug-in allows you to specify which tags are being set along with web requests in the additional HTTP header. For a detailed description of the tags refer tot the explanation in the settings UI.

The Probability attribute is a floating point value between 0 and 1, specifying the percentage of virtual users that should send the additional HTTP header.

Parent topic: AppDynamics Plug-In


Dynatrace AppMon Plug-In

The Dynatrace AppMon plug-in is installed with Silk Performer and disabled by default. To work with this plugin you need Dynatrace AppMon Client to be installed on the controller machine. If enabled, the plug-in modifies profile settings so that the runtime sends an additional HTTP header with each page request.

This HTTP header contains load test specific data which is thus made available to Dynatrace AppMon. The Dynatrace AppMon plug-in also integrates with TrueLog Explorer: For the selected node in the TrueLog, the plug-in tab in the lower right window allows direct access to the corresponding PurePath in Dynatrace.

Note: The additional HTTP header is only added during protocol-level testing and browser-driven testing using Internet Explorer.
To configure the plugin:
  1. In the Silk Performer menu, click Settings > System.
  2. Click Dynatrace AppMon.
  3. Check Enable plug-in.
  4. Click the Attributes tab and configure Name/Value pairs as desired.
    • The Dynatrace AppMon plugin requires the correct port to be configured to be able to communicate with the AppMon client. In addition, the system profile value must match the Dynatrace AppMon profile you want Silk Performer to work with.
    • The tagging header name is expected to be x-dynatrace. Use dynatrace as header name only for very early versions of Dynatrace Diagnostics. For more details refer to the Dynatrace AppMon documentation.
    • In the Tag Selection section you can choose the tags you want virtual users to send as part of the additional HTTP header with each request.
Parent topic: Silk Performer Plug-Ins


Dynatrace SaaS and Managed Plug-In

The Dynatrace SaaS/Managed plug-in is installed with Silk Performer and disabled by default. If enabled, the plug-in modifies profile settings so that the runtime sends an additional HTTP header with each page request. Besides, the plug-in can
  • configure request attributes in Dynatrace to extract the load test specific information contained in this additional header, making it available for analysis in Dynatrace.
  • inform Dynatrace about virtual user errors through the plug-in.
  • add an annotation containing general load test information.
  • configure request naming rules in Dynatrace based on the timer name parameters passed to Web* and Browser* API calls.
Note: The additional HTTP header is only added during protocol-level testing and browser-driven testing using Internet Explorer.
To configure the plugin:
  1. In the Silk Performer menu, click Settings > System.
  2. Click Dynatrace SaaS/Managed.
  3. Check Enable plug-in.
  4. Click the Attributes tab and configure Name/Value pairs as desired.
    1. Set the base URL to your Dynatrace environment.
    2. Generate an authentication token with the required permissions in Dynatrace and specify it in the plug-in attributes.
    3. Tag relevant components of your system under test in Dynatrace and specify the used tag as application tag in the plug-in attributes.
    Additionally, you can choose which configurations the plug-in should do for you and which tags to send in the additional HTTP header.
Parent topic: Silk Performer Plug-Ins


Integrating Silk Performer with InfluxDB and Grafana

Silk Performer lets you export all the data that is collected during a load test to InfluxDB, an industry-wide well-known database for time series data. This allows you to quickly display and share your load test data using tools such as Grafana. For Grafana in particular, you can download a pre-configured set of Grafana dashboards, which can serve as a starting point for your own visualization requirements.

During a load test, Silk Performer records various measurements. While most of the measures are available in the form of time series data in the proprietary TSD format or in the form of raw data in CSV files, some dedicated measures and statistics are also exposed in real-time.

There are two main components to the Silk Performer InfluxDB integration:
  • The InfluxDB plug-in in the System Settings handles data export during load tests. It lets you export the general data displayed in the Monitor window as well as active client-side measures in real-time. On the plug-in settings tab, you can configure exactly what data to export and how to access your Influx database. Once the plug-in is enabled and configured accordingly, Silk Performer automatically pushes the real-time data to InfluxDB while a test is running.
  • The tsd2InfluxDb.exe tool, located in the Silk Performer installation folder, lets you export load test results from TSD or raw data files. In Performance Explorer, on the Results tab, in the Data Processing group, you can find the TSD to InfluxDB utility, which offers a convenient UI to the tsd2InfluxDb.exe command line tool. For integration in your CI/CD environment, you can call the tool from the command line.
  • The tsd2InfluxDb Command Line Tool
    Describes the tsd2InfluxDb command line tool, the parameter it accepts, information about working with config files, and provides examples.
  • Tags and fields in InfluxDB
    Provides detailed information on how the exported data is structured in InfluxDB.
  • Results Visualization with Grafana
    Describes how to visualize the load test results from within InfluxDB using Grafana.
Parent topic: Silk Performer Plug-Ins


The tsd2InfluxDb Command Line Tool

The tool

tsd2InfluxDb.exe is a command line tool, located in the Silk Performer installation folder, that lets you export .tsd files and raw data files to either a database instance of InfluxDB directly or to a file, which can easily be imported into InfluxDB in a two-step approach.

The parameters

The tool accepts the following parameters:

Parameter name | Parameter value
loadtestDir | Full path to a load test directory.
exportTsds | No value. Add this parameter to export .tsd files from the folder specified with the loadtestDir parameter.
exportRaw | No value. Add this parameter to export raw data files from the folder specified with the loadtestDir parameter.
inputFile | Full paths to selected input files, separated by a semicolon (;).
baseUrl | URL of the InfluxDB instance. For example: https://myInfluxDB:8443/
Db | Name of the database in InfluxDB.
Auth | Authentication data in the format username:password
outputFile | Full path to a text file receiving the measurements in Influx line protocol.
loadtestName | Name of the load test. Used for the Loadtest tag.
customTags | Custom tags in the format key1=value1; key2=value2;
Config | Full path to a configuration file. Only applicable in command line parameters.
selectedMeasures | Only available through the config file. Allows specifying exactly which measures are to be exported. The Copy to Clipboard button of the Tsd2InfluxDB tool helps you to generate the selectedMeasures node in your config file.

Working with config files

Note the following when working with config files:
  • The configuration file is an .xml file with base node InfluxDbParams.
  • The parameter names specified above are used as xml node names.
  • Use the Copy to Clipboard button of the Tsd2InfluxDB tool to get the configuration corresponding to the current dialog settings.
  • A configuration file cannot point to another configuration file. This means that the config parameter is only allowed in the command line.
  • You can specify some parameters in the command line and read the rest from a command file. If a parameter is set in both, the command line value has precedence over the value in the configuration file.

Examples

Export .tsd and raw data files from the specified load test to an output file and tag all measure points with tag Loadtest=MyDemoTest:

tsd2InfluxDb.exe
  -loadtestDir "D:/Users/myUser/Documents/Silk Performer 21.0/Projects/WebProject_2/MyDemoTest"
  -exportTsds
  -exportRaw
  -loadtestName MyDemoTest
  -outputFile "D:/myOutputFile.txt"

Export using a given config file:

tsd2InfluxDb.exe -config "D:/myInfluxConfigFile"

Example content of config file:

Export three selected measures from .tsd files and raw data files from a given load test directory to an InfluxDB database. Tag each measure point with a tag Loadtest=MyDemoTest.

<InfluxDbParams>
  <loadtestDir>D:/Users/myUser/Documents/Silk Performer 21.0/Projects/WebProject_2/MyDemoTest</loadtestDir>
  <exportTsds></exportTsds>
  <exportRaw></exportRaw>
  <loadtestName>MyDemoTest</loadtestName>
  <baseUrl>http://localhost:8086</baseUrl>
  <db>mydb</db>
  <auth>myUser:myPassword</auth>
  <selectedMeasures>
    <MeasuresCollection>
      <Measure type="8" name="TInit" />
      <Measure type="8" name="#Overall Response Time#" />
      <Measure type="8" name="TMain" />
    </MeasuresCollection>
  </selectedMeasures>
</InfluxDbParams>
Parent topic: Integrating Silk Performer with InfluxDB and Grafana


Tags and fields in InfluxDB

This section provides detailed information on how the exported data is structured in InfluxDB.

Measure 'SPMeas':
  General tags
    Tag 'Project'
    Tag 'Loadtest'
    Tag 'SourceType':
      Use this tag to distinguish between data exported from raw files, TSD files, and real-time data.
      Has values 'Realtime', 'Tsd', 'Raw'
    Tag 'TsdType' (not available for real-time measures):
      Use this tag to filter for the level of aggregation that you are interested in.
      Corresponds to the prefixed letters in tsd/raw file names.
      Values: 'm', 'k', 'i', 't', ...
    Tag 'Machine' (agent name or 'aggregated')
    Tag 'UserType' (usertype name or 'aggregated')
    Tag 'Region' (where applicable)
  Measure tags
    Tag 'MeasGroup' (eg. 'Page and Action timer')
    Tag 'MeasType' (eg. 'Page time[s]')
    Tag 'MeasName' (Timer name in Silk Performer)
    Tag 'ValueType':
      Has values 'Avg', 'Sum/sec' or 'Count/sec'
      describes what kind of data 'value' field contains
  Fields:
    N, Sum, Min, Max, Avg, StdDev (not available for real-time measures)
    value:  contains the value that would be shown per default in Silk Performance Explorer: sum/sec, count/sec or average

Load test health metrics from the Monitor/Summary panel in the Workbench, such as Errors, CPU, Memory, or Transactions, are grouped in the synthetic MeasGroup 'RtHealth', while their names are stored in the MeasType tag.

Parent topic: Integrating Silk Performer with InfluxDB and Grafana


Results Visualization with Grafana

Once you have exported load test results data to InfluxDB, you can use Grafana for its visualization.

To do so, import the pre-configured Silk Performer related public dashboards from grafana.com into your Grafana installation and configure the InfluxDB database as a data source. Then, load the Silk Performer dashboards, set the correct time frame, project and load test name and you will see panels automatically filled with graphs from the exported data.

Even though the pre-configured dashboards cover many customer needs, you can always use them as a starting point for further customization.

Parent topic: Integrating Silk Performer with InfluxDB and Grafana


Silk Central Integration

Silk Performer is fully integrated with Silk Central's test-planning and test-execution functionality. Silk Performer projects can be integrated into Silk Central test plans and can be directly executed through Silk Central. This feature allows for powerful test-result analysis and reporting, and it provides for tests that are run automatically by Silk Central based on pre-configured schedules. This type of testing is called unattended testing.

Silk Central projects can be downloaded to Silk Performer, where scripts and settings can be edited. Edited projects can subsequently be uploaded to Silk Central to make them available for future test executions.

Note: The term Project is used differently in Silk Performer than it is in Silk Central. When uploaded to Silk Central, a Silk Performer project becomes the core element of a Silk Central test definition. Silk Central projects are higher-level entities that can include multiple test definitions, executions definitions, and requirements.

Silk Performance Explorer can be used for in-depth analysis of test runs. Performance Explorer can be launched directly from Silk Central's Executions unit by way of execution runs on the Runs page, either from Silk Performer or from Performance Explorer itself. For details regarding Performance Explorer's integration with Silk Central, refer to the Performance Explorer Help .

The results of Silk Performer test runs can be uploaded to Silk Central and associated with test definitions. To complete this task, Silk Performer searches its results directories and uploads the appropriate files to Silk Central.

For additional information about Silk Central's integration with Silk Performer and Silk Performance Explorer, refer to Silk Central Help and Silk Performance Explorer Help.

  • Configuring Silk Central Integration
    Explains how Silk Performer can be configured to work with Silk Central.
  • Opening Silk Performer Projects from Silk Central
    Explains how to open a Silk Performer project from Silk Central.
  • Checking Out and Editing Downloaded Projects
    Explains how to check out a Silk Central project from a source-control tool (or retrieve a project from a UNC path), edit the project, and check the project back into Silk Central.
  • Importing Projects from Silk Central
    Explains how to download projects from Silk Central and work with them independently of Silk Central.
  • Uploading Projects to Silk Central
    Upload a Silk Performer project to Silk Central to assign it to a test.
  • Uploading Test Results to Silk Central
    Upload Silk Performer attended-test results to Silk Central to save them with the results of other test runs.
  • Downloading Test Results from Silk Central
    Download Silk Performer test results from Silk Central to analyze the results of the last execution run.
Parent topic: Silk Performer Workbench 21.0
Related concepts
Silk Central Integration


Configuring Silk Central Integration

  1. In the Silk Performer menu, click Settings > System . The System Settings display.
  2. Click the Silk Central tab.
  3. In the URL field, specify the URL of the host on which Silk Central's front-end server is running. Make sure to specify the full URL including the port and the Silk Central instance.
  4. Click Use credentials and type valid credentials for Silk Central in the fields Username and Password.
  5. Alternatively, click Use token and type or paste the web-service token into the field. To obtain the web-service token, login to Silk Central and open the User Settings. Here you can also regenerate and delete the token.
    Note: A web-service token is similar to a password and should be protected as such. The token-based authentication offers increased security and convenience, because your Silk Central credentials will not be distributed outside Silk Central and the authentication will not break due to password update policies.
    Note: To use token-based authentication, both Silk Performer 19.5 (or newer) and Silk Central 19.5 (or newer) are required.
  6. Click Test Connection to verify the URL and the credentials or the token.
  7. Click OK. These are now the default settings for all tasks that require a connection to Silk Central, which includes opening projects from Silk Central, importing projects from Silk Central, and uploading projects to Silk Central.
Parent topic: Silk Central Integration
Related tasks
Uploading Projects to Silk Central
Uploading Test Results to Silk Central


Opening Silk Performer Projects from Silk Central

Note: If Silk Central is using StarTeam for source-control integration, you need to install StarTeam Microsoft SCC Integration on your computer.
  1. Click File > Open Project from Silk Central . The dialog that displays shows the default settings for connections to Silk Central.These default connection settings can be specified in the System Settings on the Silk Central page.
  2. If you are connecting for the first time, or if you do not want to use the default settings, specify the settings as follows.
  3. In the URL field, specify the URL of the host on which Silk Central's front-end server is running. Make sure to specify the full URL including the port and the Silk Central instance.
  4. Click Use credentials and type valid credentials for Silk Central in the fields Username and Password.
  5. Alternatively, click Use token and type or paste the web-service token into the field. To obtain the web-service token, login to Silk Central and open the User Settings. Here you can also regenerate and delete the token.
    Note: A web-service token is similar to a password and should be protected as such. The token-based authentication offers increased security and convenience, because your Silk Central credentials will not be distributed outside Silk Central and the authentication will not break due to password update policies.
    Note: To use token-based authentication, both Silk Performer 19.5 (or newer) and Silk Central 19.5 (or newer) are required.
  6. Click Test Connection to verify the URL and the credentials or the token.
  7. Optional: Click Set as Default to define the specified connection settings as the default settings for future connections.
  8. Optional: Click Internet Options to define Internet connection properties, such as proxy settings, security settings, and browser connection settings.
    If you perform this step, click OK on the Internet Properties dialog box to save the settings.
  9. On the Open Project from Silk Central dialog box, click Next to view a list of the Silk Central projects to which the active user has read access. This list is the same list that is available in Silk Central's Projects's unit.
  10. Select the Silk Central project to open and click Next. Alternatively, you can double-click the project to open.
  11. In the Project menu tree, open test containers and test folders as necessary and select the Silk Performer test definition to open in Silk Performer. If the Silk Performer test definition is located on a UNC path, click Finish. Otherwise, click Next to open the Target Directory Selection dialog box and specify the location to which the project is copied. If you are using source-control integration like Visual SourceSafe for Silk Central, you are presented with a logon screen for your source-control client. Type valid user connection settings and click OK to continue.
Silk Performer projects can also be opened directly from Silk Central by clicking Open Project on the Silk Central Properties page in the Test Plan unit. For more information, refer to Silk Central Help.

For information regarding the configuration of source-control integration with Silk Central, refer to Silk Central Help.

Parent topic: Silk Central Integration
Related tasks
Integrating StarTeam SCC with Silk Performer


Checking Out and Editing Downloaded Projects

After you download a Silk Central project from Silk Central, the project appears in Silk Performer, where you can edit it before uploading it back into Silk Central source control.

If you have configured source-control integration for your Silk Central installation, Silk Performer automatically checks the Silk Performer project file out of the source-control database.
Note: In the Silk Performer menu tree, red check marks identify Silk Performer projects that have been checked out by way of Silk Central source-control integration.
This integration is facilitated by Silk Performer by using Web Services to connect to Silk Central and request source-control link information, such as the connection string, user name, and LTP project file name.
Note: If Silk Central is using StarTeam for source-control integration, you need to install StarTeam Microsoft SCC Integration on your computer.
  1. After you complete and save the required changes to the Silk Performer project file, choose File > Close Project . Alternatively, you can right-click the Project menu tree and choose Check In (and Close Project). A Message dialog box opens.
  2. Click Yes to confirm that you want to check the edited files back into the source-control database. All subsequent executions of this project through Silk Central use the updated project file.
Parent topic: Silk Central Integration
Related tasks
Integrating StarTeam SCC with Silk Performer


Importing Projects from Silk Central

Importing a project involves downloading a copy of a project from Silk Central and working with it independently of Silk Central. Changes that you make to an imported project do not effect Silk Central. Only a standard Web connection is necessary to import a Silk Central project. No source-control tool connection or credentials are required.

Importing a file into Silk Performer enables you to perform attended test runs independently of Silk Central. Attended test runs differ from tests that are run automatically based on predefined schedules in Silk Central because they can be executed manually in Silk Performer. Test results can subsequently be uploaded back to Silk Central and associated with a test definition.

Even if you have configured source code control integration with Silk Central, imported project files are not checked out of your source control tool because they are saved locally to your hard disk as compressed ZIP archives. Attended tests can also be initiated from the Silk Central side.

  1. Choose File > Import Project from Silk Central . You are presented with the connection settings that are specified on the System Settings - Workbench - Silk Central page.
  2. Optional: If you are connecting for the first time, or if you do not want to use the default connection settings, specify the following information:
    • In the URL field, specify the URL of the host on which Silk Central's front-end server is running. Make sure to specify the full URL including the port and the Silk Central instance.
      Note: The port is usually port 80 if you are using an ISAPI Web server or port 19120 if you are using Silk Central's standalone Web server.
    • Type valid user credentials for your Silk Performer installation in the Username and Password fields.
  3. Optional: Click Set as Default to define the specified connection settings as the default settings for future connections.
  4. Optional: Click Internet Options to define Internet connection properties, such as proxy settings, security settings, and browser connection settings.
    If you perform this step, click OK on the Internet Properties dialog box to save the settings.
  5. On the Import Project from Silk Central dialog box, click Next to view a list of the Silk Central projects to which the active user has read access. This list is the same list that is available in Silk Central's Projects's unit.
  6. Select the Silk Central project to import and click Next. Alternatively, you can double-click the project to import.
  7. In the Project menu tree, open test containers and test folders as necessary and select the Silk Performer test definition to import to Silk Performer.
  8. If you do not want to use the default target directory, type a different directory in the Target Directory text box.
  9. Click Finish.
Parent topic: Silk Central Integration


Uploading Projects to Silk Central

Before uploading a Silk Performer project to Silk Central, ensure that you have properly configured the project's workload through Silk Performer. Workload settings are subsequently specified along with uploaded projects in the Silk Performer Test Properties portion of the Properties page in Silk Central’s Tests unit.
  1. In Silk Performer, open the project that you want to upload and choose File > Upload Project to Silk Central . If the project has previously been uploaded to Silk Central, the association with a Silk Central test is already known and preselected. Click Next and go to step 3.
  2. From the Projects list, select the Silk Central project to which you want to upload the Silk Performer project and click Next. You can select an existing test to replace or you can create a new test by right-clicking the appropriate folder or container choosing New Child Test.

    You can also create a new folder within an existing test container by right-clicking a container and choosing New Child Test Folder.

    Note: Newly created tests and folders are displayed with bold text to indicate that they have not yet been written to the Silk Central database. If you click Cancel, the items you have created are not saved.
  3. Check the Enable Results Upload check box to select specific test run results to upload with the project and then click Next. If you do not want to upload test run results at this time, do not check the Enable Results Upload check box. Instead, click Finish.
  4. On the Select results page, check the appropriate check boxes in the Results list to select the results that you want to upload along with the project and then click Next.
  5. Specify version and build numbers for the assigned product to which the uploaded results belong.
  6. Click Finish to upload the project to Silk Central. The newly uploaded items appear in Silk Central's test and Project menu tree.
Parent topic: Silk Central Integration
Related tasks
Configuring Silk Central Integration


Uploading Test Results to Silk Central

  1. Choose Results > Upload Results to Silk Central . Alternatively, you can right-click a results node and choose Upload Results to Silk Central .

    If the project has previously been uploaded to Silk Central, the association with a Silk Central test is already known and preselected. Click Next and go to step 4.

  2. From the Projects list, select the Silk Central project to which you want to upload the Silk Performer test results and click Next.
  3. From the menu tree, select the test to which you want to upload the results and click Next. Alternatively you can right-click in the tree and choose various menu items to create a new test, child test, test folder, or child test folder to which the results are saved.
  4. On the Select results page, check the appropriate check boxes in the Results list to select the results to upload along with the project.
  5. Click Next.
  6. On the Specify product information and result status page, specify the version and build numbers for the assigned product to which the uploaded results belong.
  7. Check the checkbox Enable automatic test result upload to let Silk Performer upload test results automatically after each test run.
    Note: You can click the Upload path link to start Silk Central and go directly to the selected test. Check the Open Upload path on finish check box to automatically perform this action after clicking Finish.
  8. Click Finish to upload the results. A confirmation dialog box asks if you want to delete the local copies of the uploaded results.
  9. Click Yes.
Parent topic: Silk Central Integration
Related tasks
Configuring Silk Central Integration


Downloading Test Results from Silk Central

  1. In Silk Performer, click the Results tab.
  2. Click the Click here to add Silk Central results node in the Results menu tree. To download results from another test definition, project, or Silk Central server, click Back to navigate back through Silk Central's menu tree. The Open results from Silk Central wizard opens. The corresponding Silk Central's test definition is preselected. You can select multiple executions and download the results of multiple test executions.
  3. In the Test executions from the last <> day(s) text box, specify how many past days' worth of results to retrieve.
  4. Click Finish to download the results.
Parent topic: Silk Central Integration


Silk Performance Manager Integration

This section describes how to integrate Silk Performer with Silk Performance Manager by creating client monitors and infrastructure monitors and how to upload them to Silk Performance Manager.

  • Creating a Silk Performance Manager Client Monitor
    Describes how to create a Silk Performance Manager client monitor.
  • Creating a Silk Performance Manager Infrastructure Monitor
    Introduces the workflow required to generate a Silk Performance Manager infrastructure monitor.
Parent topic: Silk Performer Workbench 21.0


Creating a Silk Performance Manager Client Monitor

  1. Start the Silk Performer Monitor Workbench or switch to the Monitoring workflow bar by right-clicking the workflow bar and clicking Show Monitoring Workflow Bar.
  2. By clicking the respective buttons on the workflow bar, create a project, record a transaction, and customize your script as usual.
  3. Perform a Try Script run.
  4. Click Upload Project on the workflow bar.
  5. Click Upload project to Performance Manager.
  6. On the subsequent dialog, specify all necessary settings and click OK.

Before a project is uploaded to Silk Performance Manager, Silk Performer automatically sets default threshold values for all measures. The thresholds are calculated either from an existing baseline (if such exists) or from the latest Try Script run.

Parent topic: Silk Performance Manager Integration


Creating a Silk Performance Manager Infrastructure Monitor

  1. Click File > New Project or click Start here on the workflow bar if no project is open. The Workflow - Outline Project dialog opens.
  2. Enter a Name and optionally a Description.
  3. From the list of application types, select Monitoring > Performance Manager - Infrastructure Monitor and click Next. Performance Explorer opens and the Data Source Wizard displays.
  4. Follow the wizard to select a data source. A monitor chart displays and the monitoring automatically starts.
  5. On the Real-Time Monitoring tab, in the Export group, click As Project.
  6. Follow the Reuse Monitor Wizard to export the monitor chart.
  7. Specify the settings on the Upload Project dialog and click OK.
Parent topic: Silk Performance Manager Integration
Parent topic: Generating BDL Monitoring Projects


Source Control Integration

Silk Performer's source control integration (SCC integration, also referred to as source code control integration) enables you and other members of your organization to manage and share your Silk Performer project files, test scripts, custom include files, and data files in a common repository (source control system)—enabling file check-in, check-out, get-latest-version, and other functions typical of source control systems.

Silk Performer’s source control integration is facilitated by commands on the Silk Performer File menu ( File > Source Control ) and context menus in Silk Performer’s Project menu tree. All project nodes, script nodes, custom include file nodes, and data file nodes in the Project menu tree offer SCC commands.

In addition to offering commands that select all the files of complete projects (project file, custom include files, data files, and scripts), a sub-set of SCC commands that select only the project file are also available (you can easily check-in/check-out project files without overwriting associated script and data files).

Status icons in Silk Performer’s Project menu tree indicate the status of files under source control:

  • Files that have been placed under source control and are currently checked out (the source control version of the file is writable) are indicated with red checkmark icons.
  • Files that have been placed under source control, but are currently NOT checked out (the source control version of the file is read-only) are indicated with blue padlock icons.

Silk Performer supports StarTeam, Microsoft Visual SourceSafe, and PVCS. Source control integration must be enabled in Silk Performer system settings ( Settings > System > Source Control ). You must have StarTeam, PVCS, or Visual SourceSafe installed on your system before source control integration can be enabled.

  • Integrating StarTeam SCC with Silk Performer
    Download the integration module and run the installation wizard to set up StarTeam.
  • Configuring Source Code Control Integration in Silk Performer
    Set up source control integration, which enables source control functions on the File menu ( File > Source Control ).
  • Placing Projects and Files Under Source Control
    Configure a connection between your local disk and source code control for projects or files.
  • Checking In Files
    Check in individual scripts, include files, data files, or entire projects to source code control.
  • Checking Out Files
    Check out individual scripts, custom include files, data files, or entire projects to source code control.
  • Getting the Latest Version of a File from the Source Control System
    Download the latest version of a file to your local disk (by default, in read-only format) without actually checking the file out.
  • Project-File Only Source Control Commands
    Describes the source code control commands that work at the project file level only.
  • Removing Source Control from a Project
    Clear all linkage information from the project file that connects the version of a file on your local disk with the version of the file in source control.
  • Synchronizing the Source Control Status of a Project
    The Synchronize command looks at the check-in/check-out status of files in the source control system and updates the status of those files in Silk Performer.
  • Source Control Known Issues and Workarounds
    Describes source control known issues and solutions including client reconnect functionality and MS VSS login requests for each check in and check out operation.
Parent topic: Silk Performer Workbench 21.0


Integrating StarTeam SCC with Silk Performer

The integration consists of downloading the integration module and running the installation wizard.

  1. Downloading the StarTeam SCC Integration Module
    To create the link between Silk Performer and StarTeam, download and install the StarTeam SCC integration module.
  2. Running the StarTeam Microsoft SCC Integration Setup Wizard
    To complete the link between Silk Performer and StarTeam, run the StarTeam SCC integration wizard.
Parent topic: Source Control Integration


Downloading the StarTeam SCC Integration Module

  1. Navigate to the StarTeam product downloads area for the latest StarTeam Integration for SCC release at http://supportline.microfocus.com/websync/StarTeam2009EA.aspx. You may need to login or verify your email address.
  2. Scroll down to the StarTeam 2008 R2 Integration for Microsoft SCC section near the bottom of the page.
  3. Locate and double-click the ST-SCC-Int-10.4.7-Win-EN.exe file.
  4. Click Run or Save, depending on which browser you are using.
  5. Specify the location where you want to save the SCC Integration files or executable file and then click Save.

Follow the steps in the StarTeam SCC Integration Module wizard to install the SCC Integration module.

Parent topic: Integrating StarTeam SCC with Silk Performer
Next topic: Running the StarTeam Microsoft SCC Integration Setup Wizard


Running the StarTeam Microsoft SCC Integration Setup Wizard

Download the StarTeam SCC Integration Module before beginning this task.

  1. Choose one of the following:
    • Immediately after the download completes, click Launch on the Download Manager to launch the installation wizard.
    • At your convenience, navigate to the location where you saved the SCC Integration executable file, scc_integration.exe, and double-click the file.
    The SCC Integration InstallShield wizard opens.
  2. Click Next. The Welcome page opens.
  3. Click Next. The Software License Agreement page opens.
  4. Click Yes to install the SCC Integration module. The User Information page opens.
  5. Specify your Name and Company and then click Next.

    The StarTeam SDK runtime is installed if needed.

    The Choose Destination Location page opens.
  6. Accept the default destination location or click Browse to specify another location and then click Next. The Select Components page opens.
  7. Select the SCC API Integration check box and then click Next. The Folder Selection page opens.
  8. Accept the default program folder location or specify another folder and then click Next. Setup adds program icons to the folder that you specify.
  9. Select the language for your installation from the list box and then click OK. The File Compare/Merge page opens.
  10. Click Next. The License Agreement page opens.
  11. Specify whether you agree to accept the license terms and then click Next. The Choose Install Folder page opens.
  12. Accept the default location or click Choose to select another location and then click Next. The Choose Shortcut Folder page opens.
  13. Specify where you want to install the shortcut and then click Next. The Pre-Installation Summary page opens.
  14. Click Install.
  15. Click Done. The Setup Complete page opens.
  16. Specify whether you want to restart your computer now or later and then click Finish.
Important: It is critical that you set up and manage your projects using the StarTeam client. This includes creating projects, adding files to a project, and removing files from a project.
Parent topic: Integrating StarTeam SCC with Silk Performer
Previous topic: Downloading the StarTeam SCC Integration Module


Configuring Source Code Control Integration in Silk Performer

Ensure that StarTeam, MS VSS, or PVCS is installed on your local system before beginning this task.

  1. Select Settings > System . The System Settings dialog opens.
  2. Select the Workbench group icon.
  3. Click the Source Control tab (this tab is farthest to the right of the tab list; use the small right-pointing arrow to access this tab).
  4. Check the Enable Source Control integration check box. All SCC providers that are installed on your local machine and supported by Silk Performer (i.e., StarTeam, VSS, or PVCS) are listed in the SCC Provider list box.
  5. Enter a username in the Username field. The username you enter here will be suggested automatically as the default username value in future operations, such as login dialogs.
    Note: Custom include and user data files are configured independently from project and system files for the SCC because Silk Performer may require that these files be stored separately in the SCC (e.g., an organization might have a common repository for include files that are shared amongst a group of developers. These developers might also be required to check in files from their individual projects).
  6. In the Custom user data files SCC path field, click [...] and select the location in the SCC database where the custom user data files are to be saved.
  7. At this point you will be required to log into your SCC system. The username that you entered above will be entered into the login dialog automatically. See StarTeam, MS VSS, and PVCS documentation for full details regarding the use of your source control system.
    1. Your SCC system will also likely require that you enter the password that corresponds to the submitted username.
    2. If not already selected, you may need to select the target SCC database.
    3. Following that, browse the file structure of your SCC system and select the directory to which your custom user data files are to be saved (you may also create a new directory for this purpose).
    The SCC database path field is automatically populated with the database-path root of the source control system you specified.
  8. In the Custom include files SCC path field, click [...] and select the location in the SCC database where the custom include files are to be saved.
  9. Repeat step 7. The SCC database path field is automatically populated with the database-path root of the source control system you previously specified.
  10. Click OK to exit the System Settings dialog. Source control integration is now complete. Source control functions are now available from the File menu ( File > Source Control ).
Parent topic: Source Control Integration


Placing Projects and Files Under Source Control

Place a project and all its associated files under source control or place an individual file under source control.

  • Placing a Complete Project Under Source Control
    Place all scripts, include files, and data files associated with a project under source code control.
  • Placing Individual Files Under Source Control
    Place a file that is currently only available on your local disk under source control in the specified SCC file location (thereby configuring a connection between your local disk and the SCC).
Parent topic: Source Control Integration


Placing a Complete Project Under Source Control

Note: System include files and data files cannot be placed under source control. Only custom include files and data files can be placed under source control.
  1. With a project loaded into Silk Performer, select the project node in the Project menu tree.
  2. Choose one of the following:
    • Select File > Source Control > Add to Source Control .
    • Right-click the project node and select Add to Source Control from the context menu.
    The Add To Source Control dialog opens. All scripts, include files, and data files associated with the project are automatically selected for placement under source code control.
  3. Uncheck any file type selections for file types that should not be placed under source control.
  4. Ensure that source control paths have been configured for each project file type. As you have already configured source control paths for custom include files and data files in Silk Performer’s system settings, you should now only have to specify source control paths for project files and script files. If required, log into your SCC and specify directories for your project and script files. For example, with VSS, a Click here to specify link appears in the Source Control Project column of the Add to Source Control dialog for any project file type for which a source control path has not been specified.
  5. Click Add to place the project’s files under source control.
Parent topic: Placing Projects and Files Under Source Control


Placing Individual Files Under Source Control

Note: System include files and data files cannot be placed under source control. Only custom include files and data files can be placed under source control.
Note: Project files (.ltp), script files (.bdh), custom include files, and custom data files can be independently placed under source code control.
  1. In the Project menu tree, choose one of the following:
    • Right-click a file and select Add to Source Control from the context menu.
    • Right-click the Scripts, Data Files, or Include Files nodes and select Add to Source Control from the context menu to select all files of those types for placement under source control.
    The Add to Source Control dialog opens, showing the files upon which the operation is to be performed.
    Note: The remainder of this process is handled via dialogs provided by your SCC provider (StarTeam, PVCS, or VSS). See StarTeam, MS VSS, and PVCS documentation for full details regarding the use of your source control system.
  2. Select the check boxes for the files that you want to place into source control.
    Note: If not already defined, a source control project path must be defined for each file that is to be placed under source control. If a file marked for placement under source control does not yet have a source control project path configured for it, you will be prompted to configure a path (the source control project of the Silk Performer project file (*.ltp) is suggested by default).
    Note: Files added to source control are written to the corresponding *.ltp file. Therefore, to add files to source control, the corresponding *.ltp file must be checked out.
  3. Click Add to place the file under source control. A blue padlock appears next to files in the Project menu tree that are under source control and are currently checked in (read-only). This is the default status of files that are newly placed under source control.
Parent topic: Placing Projects and Files Under Source Control


Checking In Files

  1. In the Project menu tree, perform one of the following steps:
    • To check in an individual file, right-click the file that is currently checked out, as indicated by a red check mark, and choose Check In.
    • To check in all the files of a specific type, right-click the Scripts, Data Files, or Include Files node and choose Check In.
    • To check in an entire project, right-click the project node and choose Check In.
    The Check In dialog box opens, showing the local path where the file or project is currently saved.
  2. Optional: Deselect any files that you do not want to check in.
  3. Click Check In to check in the file or project. The status icon of the file appears as a blue padlock, indicating that the source control version of the file or project is now read-only.
Parent topic: Source Control Integration


Checking Out Files

  1. In the Project menu tree, choose one of the following:
    • To check out an individual file, right-click the file that is currently checked in (indicated by a blue padlock icon) that you want to check out.
    • Right-click the Scripts, Data Files, or Include Files nodes to select all files of those types for check out.
    • To check out an entire project, right-click the project node.
  2. Select Check Out from the context menu. The Check Out dialog opens, showing the local path to where the file or project will be copied.
    Note: If a single checked-in file is selected for check out, then only that file will be listed on the Check Out dialog. If no file or a checked-out file is selected for check out, then all currently checked-in files of the project will be listed on the Check Out dialog.
  3. If required, deselect individual files that you do not want to check out.
  4. Click the Check Out button to check out the files or project. The status icon of the files now appear as a red checkmark, indicating that the source control version of the files or project are available and writable.
  • Undoing File Check Out
    Replaces the file on your local disk (regardless of whether or not it includes recent changes) with the most recently checked-in version of the file in the SCC. The local version of the file is then read-only.
Parent topic: Source Control Integration


Undoing File Check Out

  1. In the Project menu tree, choose one of the following:
    • To undo checkout of an individual file, right-click a file that is checked out (indicated by a red checkmark icon).
    • Right-click the Scripts, Data Files, or Include Files nodes to select all files of those types at once.
    • To undo checkout of an entire project, right-click the project node.
  2. Select Undo Checkout from the context menu. The Undo Checkout dialog opens, showing the local path to where the file or project is located.
  3. If required, deselect individual files that you do not want to check out.
  4. Click the Undo button to undo the check out. The status icon of the file or project now appears as a blue padlock, indicating that the source control version of the file is read-only.
Parent topic: Checking Out Files


Getting the Latest Version of a File from the Source Control System

These instructions apply to the Get Latest Version command for individual scripts, include files, data files, and entire projects.

Note: See StarTeam, MS VSS, or PVCS documentation for full details regarding use of your SCC’s Get Latest Version command.
  1. In the Project menu tree, choose one of the following:
    • To get an individual file, right-click the file in the Project menu tree.
    • Right-click the Scripts, Data Files, or Include Files nodes to select all files of those types.
    • To get the latest version of an entire project, right-click the project node.
  2. Select Get Latest Version from the context menu. The Get Latest Version dialog opens, showing the local path where the file will be copied.
  3. If required, deselect individual files that you do not want to get.
  4. Click the Get button.
    Note: Get Latest Version commands do not change the checked-in/checked-out status of files. For example, if the Get Latest Version operation is performed on a file that is currently checked out, the file remains checked out (if the file is open, you will be prompted as to whether or not you want to have the file reloaded with the new version).
Parent topic: Source Control Integration


Project-File Only Source Control Commands

In addition to offering source control commands that operate on all the files of a complete project (project file, custom include files, data files, and scripts), a sub-set of SCC commands that select only the project file itself are available from the File menu ( File > Source Control > Project File Only ) and the project node of the Project menu tree. These commands operate the same as their counterparts for associated files do; the only difference is that they do not affect the associated files (scripts, custom include files, and data files). Such functionality is useful if, for example, you want to check in a project file without overwriting the associated script, custom include, and data files that are currently stored in the SCC.

The project-file only commands that are available from the File menu ( File > Source Control > Project File Only ) and the project node of the Project menu tree include:

  • Get Latest Version
  • Check Out
  • Check In
  • Undo Checkout
  • Add to Source Control
Parent topic: Source Control Integration


Removing Source Control from a Project

The Remove Source Control Linkage command is the reverse of the Add to Source Control command. This command is useful when working with files (possibly received from a customer or support staff) for which the associated source control system is not available.

Note: Source control linkage can be removed for complete projects only, not individual files.
  1. Choose one of the following:
    • In the Project menu tree, right-click the project node of a project that is under source control and select Remove Source Control Linkage.
    • Select File > Source Control > Remove Source Control Linkage .
  2. Click OK to confirm that you understand that all source control connection data for the project will be lost.
Parent topic: Source Control Integration


Synchronizing the Source Control Status of a Project

Under certain conditions, Silk Performer may fall out of sync with source control systems due to the corruption of linkage information. For example, if one were to close Silk Performer while Silk Performer is loaded with a checked out file and then check in that same file via the SCC, Silk Performer would not be aware that the file had been checked in.

Note: This function can be applied to complete projects only, not individual files.
  1. Choose one of the following:
    • In the Project menu tree, right-click the project node of a project that is under source control and select Synchronize.
    • Select File > Source Control > Synchronize .
  2. Click OK to confirm that you understand that all source control connection data for the project will be lost.
Parent topic: Source Control Integration


Source Control Known Issues and Workarounds

The following issues may occur when using source control.

  • SCC Client's Reconnect Functionality Is Not Supported
    Describes the source control known issue and solution for client reconnect functionality.
  • MS VSS 8.0 Requests Username/Password for Each File Check-in/Check-out Operation
    Describes the source control known issue and solution for MS VSS login requests for each check in and check out operation.
Parent topic: Source Control Integration


SCC Client's Reconnect Functionality Is Not Supported

Issue | Workaround
When Silk Performer projects and/or files are linked to a defined SCC directory, and the directory is changed via the SCC client, Silk Performer does not reconnect to the new directory. | Remove the existing source control linkage then add the affected projects/files to the new directory.
Note: It is generally not recommended to use SCC client functionality for maintaining linked Silk Performer projects.
Parent topic: Source Control Known Issues and Workarounds
Related tasks
Placing Projects and Files Under Source Control
Removing Source Control from a Project


MS VSS 8.0 Requests Username/Password for Each File Check-in/Check-out Operation

Issue | Workaround
MS VSS 8.0 introduced a security setting that, when activated, requests the user to enter their username and password each time they check in or check out a file from VSS. This request also appears in Silk Performer when performing file operations with VSS. | Disable the MS VSS manual login.
  • Disabling the MS VSS Manual Login
    Disables the request for the user to enter their username and password each time they check in or check out a file from VSS.
Parent topic: Source Control Known Issues and Workarounds


Disabling the MS VSS Manual Login

Note: This procedure only works if the username in VSS is identical to the network username.
  1. Open SourceSafe Administrator.
  2. Open the database where your Silk Performer projects are saved.
  3. Select Tools > Options .
  4. Click the General tab.
  5. Check the Use network name for automatic user login check box.
Parent topic: MS VSS 8.0 Requests Username/Password for Each File Check-in/Check-out Operation


Importing, Uploading, and Emailing Projects

Silk Performer enables you to export, import, email, and upload projects.

Silk Performer offers the option of exporting entire test projects to a separate directory or an archive file. Such exported project files can subsequently be imported into Silk Performer.

  • Exporting Projects
    You can export an entire test project to a separate directory or an archive file (ZIP format).
  • Importing Projects
    You can import a project archive file (ZIP format) and specify the location where the extracted files should be saved.
  • Emailing Projects
    Emailing archived projects is an easy method of transferring project files between colleagues.
Parent topic: Silk Performer Workbench 21.0


Exporting Projects

  1. From the Silk Performer menu bar, select File > Export Project . The Export Project dialog appears.
  2. In the Export location area, specify the location to which you want to export the current project. If you want to export all the project files to a directory, specify the directory name. If you want to export all the files to a ZIP archive, specify the archive name. Click [...] to the right of the field to locate the directory or file where the project is to be exported.
  3. Select the ZIP to single archive file option to export all files that belong to your current project to a ZIP archive. This is useful when you want to backup your project or when you want to send a copy of your project to someone.
  4. Select the Open in Windows Explorer after export check box to have the folder in the export location open automatically in Windows Explorer after an export. This provides you with quick access to the project file after the export, without having to navigate to find the directory where the file is stored.
  5. In the Options area, select the Include results files of all tests option to export the results of all tests that belong to this project (the results of all TryScript tests, baseline tests, and actual tests). If you disable this option, only the results of the most recent TryScript test will be exported.
  6. Select the Protect ZIP file with password option to protect the export file (LTZ) with a password. This is useful when your project contains confidential data (for example, user names and passwords for the application you are testing). If you select this option, enter a password and confirm it.
  7. Select the Include a system diagnostic report check box to include a diagnostic report with the export. This report lists the processors in the computer, the name and version of the operating system, and information regarding the drives, memory, services, and drivers. Relevant information from the Windows registry is also included.
  8. Click OK. Silk Performer then exports the project and displays the progress of packing all relevant files into a ZIP archive in a status bar.
Parent topic: Importing, Uploading, and Emailing Projects


Importing Projects

  1. From the Silk Performer menu bar, select File > Import Project .
    Note: If you have a project open, you will be prompted to close your project. Click Yes.
    An Open dialog appears. Browse to and select the archive file that you want to import.
  2. After selecting the archive file, click OK.
  3. The Import Project dialog appears.
  4. In the Import target directory area, specify the location where you want to extract the project files.
    1. If you have configured password protection, you will be prompted to enter your password. Enter your password and confirm it.
  5. Click OK. Silk Performer then extracts the archive file to the specified target directory and opens the project.
Parent topic: Importing, Uploading, and Emailing Projects


Emailing Projects

  1. From the Silk Performer menu bar, choose File > Email Project . The Email Project dialog box opens.
  2. In the Email address field, specify the email address where your project is to be sent.
  3. In the Options area, check the Include results files of all tests check box to attach the results of all TryScript tests, baseline tests, and actual tests that belong to this project. If you uncheck this check box, only the results of the most recent TryScript test are sent.
  4. Check the Protect archive file with password check box to protect the contents of the email with a password. This feature is useful when your project contains confidential data, such as user names and passwords for an application under test. If you check this check box, type a password and confirm it.
    Note: Inform the recipient of the password in a phone call or separate email.
  5. Check the Include a system diagnostic report check box to attach a system diagnostic report. This report includes the following information:
    • Computer processors
    • OS name and version
    • Information regarding the drives, memory, services, and drivers
    • Relevant information from the Windows registry
  6. Click OK. Silk Performer emails the project, using a status bar to display the progress of packing all relevant files into a ZIP archive.
Parent topic: Importing, Uploading, and Emailing Projects


Troubleshooting

All customers whose products qualify for maintenance and all prospective customers who are evaluating products are eligible for Technical Support.

  • Results Recovery Workflow
    Describes how to recover load test results based on two common use cases.
  • Technical Support
    How to contact Technical Support.
  • Controller Agent Communication Troubleshooting
    Troubleshooting issues that may occur when a controller computer attempts to connect to agent computers.
  • Error Message Overview
    Describes Silk Performer's system-level error types.
Parent topic: Silk Performer Workbench 21.0


Results Recovery Workflow

In environments with unreliable network connections such as the Internet, unforeseen exceptions can happen. If the controller loses connection to an agent during a load test or while collecting results, Silk Performer will try to re-establish the connection. However, this might not always be possible and would lead to an incomplete results set.

For such a case, Silk Performer provides a recovery workflow. It allows you to recover results and build a new set of valid data. Recovering results is not an ideal solution, but it prevents you from entirely losing the already gathered data.

The recovery workflow varies, depending on the type of load test you have executed.

Recovering CloudBurst load tests

Assumed, you are executing a CloudBurst load test. For an unknown reason, the Workbench becomes unresponsive and finally crashes. When you restart the Workbench, the recovery workflow dialog automatically displays. Follow the recovery workflow and review the following fields, which are automatically prefilled:

  • Missing results: This folder contains the results that could not be completely transferred from the agents to the controller. The transfer of these results was interrupted by the crash and therefore the data was truncated.
  • Transferred results: This folder contains the results that have been completely transferred from the agents to the controller. The transfer of these results was successful and the data is complete and valid.
  • Recovered results: This folder will contain the recovered results, once the recovery is completed. Silk Performer will merge the missing results and the transferred results and generate the recovered results out of it.

For CloudBurst load tests, these fields are automatically prefilled. Review the directories and adjust them if necessary

Recovering on-premise load tests

For recovering an on-premise load test, we assume you are executing a load test with agents in your server lab. For some reason the connection to several agents gets lost and cannot be re-established. Thus, the load test ends with an incomplete results set. In this case, click Tools > Recover Load Test Results.

Follow the recovery workflow and specify all required directories. The directories are the same as described above. However, the fields are not automatically prefilled. Before you specify a directory for the missing results, make sure to create this directory on the controller and to create a subfolder for every lost agent. Then, copy the results from the agents into the subfolders. Specify all three directories and start the recovery workflow.

Recovering results

Silk Performer will execute several steps to recover the results. If an issue occurs during recovery, the process stops and you can view a log file for more information. Depending on the issue, you can ignore it and let the recovery process continue, or you can restart the process.

Once the recovery is completed, the new set of results displays in the Results tree.

Parent topic: Troubleshooting


Technical Support

All customers who are under a maintenance and support contract, as well as prospective customers who are evaluating products are eligible for technical support. Our highly trained customer care staff will respond to your requests as quickly and professionally as possible.

If you have a question on recording Web traffic, load testing scenarios or any other product or implementation issue, our highly trained technical support staff will respond to your requests as quickly and professionally as possible.

To reach Micro Focus SupportLine, visit https://supportline.microfocus.com. First time users may be required to register to the site.

Please have the following information ready when you call:

  • Product name and version number
  • Operating system name and version
  • Exact wording of any error messages involved
  • Customer ID found on your shipping receipt for Silk Performer or on an index card found in your software box
Parent topic: Troubleshooting


Controller Agent Communication Troubleshooting

The following issues may occur when a controller computer attempts to connect to agent computers.

  • Load Test Controller - 3211: Could not connect agent control service
  • Load Test Controller - 3212: Could not authenticate the Agent Control Service
  • Load Test Controller - 3213: The agent control service could not create the agent
  • Load Test Controller - 3223: Agent connection lost
  • Load Test Controller - 3233: The agent's version does not match the version of its controller
  • Load Test Controller - 3303: The local results directory could not be created
  • Load Test Controller - 3304: The local results directory could not be cleared
  • Load Test Controller - 3305: The local data directory could not be created
  • Load Test Controller - 3306: The local data directory could not be cleared
  • Load Test Controller - 3422: Command (connection) timed out
  • Silk Performer - 32: Access denied, authentication required
  • Silk Performer - 33: Authentication failed (wrong password)
  • Silk Performer - 25: Limit of concurrent instances exceeded
  • System - 2: The system cannot find the file specified
Parent topic: Troubleshooting


Load Test Controller - 3211: Could not connect agent control service

Possible Cause | Resolution
The agent control service is not running. | Start the agent control service.
A port mismatch occurs (the port that the agent control service is listening to and the port at which the controller wants to connect the agent control service are different). | Adjust the agent connection settings.
The agent is connected through a proxy and the proxy is down. | Check the agent connection settings and restart the proxy.
Parent topic: Controller Agent Communication Troubleshooting


Load Test Controller - 3212: Could not authenticate the Agent Control Service

Possible Cause | Resolution
The agent requires a password and encryption is enabled. The agent’s server certificate could not be found or a required dynamic link library (.dll) is missing (for example "ssleay32.dll"). However, note that the agent control service does not report an error when it is started, if this is the problem. | Your best option is to re-install the remote agent, because missing certificates or dynamic link libraries are indications that the agent was not installed correctly.
Parent topic: Controller Agent Communication Troubleshooting
Related reference
Load Test Controller - 3213: The agent control service could not create the agent


Load Test Controller - 3213: The agent control service could not create the agent

Possible Cause | Resolution
This is the same type of error as 3212, except that the agent does not require a password. | See "Load Test Controller - 3212: Could not authenticate the Agent Control” Service"
Parent topic: Controller Agent Communication Troubleshooting
Related reference
Load Test Controller - 3212: Could not authenticate the Agent Control Service


Load Test Controller - 3223: Agent connection lost

Possible Cause | Resolution
This occurs when the connection is broken between the controller and agent or when the underlying communication units of the load test controller report connection problems. Furthermore, connecting the agent through a proxy might be the cause of the error if the proxy itself is buggy. | There should be log files named orbClient_<agentName>.log, orbServer_<agentName>.log in the controller’s or agent’s home directory, respectively, where logging information related to the error can be found.
Parent topic: Controller Agent Communication Troubleshooting


Load Test Controller - 3233: The agent's version does not match the version of its controller

Possible Cause | Resolution
The agent's version does not match the version of its controller. | Install the correct remote agent version.
Parent topic: Controller Agent Communication Troubleshooting


Load Test Controller - 3303: The local results directory could not be created

Possible Cause | Resolution
This is an access rights problem, that is, the user account of the agent process does not have the necessary access rights to create a directory; the parent directory of the desired directory is probably a read-only version for all accounts. | Grant the necessary access rights.
Parent topic: Controller Agent Communication Troubleshooting


Load Test Controller - 3304: The local results directory could not be cleared

Possible Cause | Resolution
A file within the local results directory is still open and being used by another process (most likely the perfLtcAgent.exe and perfRun.exe). This is usually a hint that either the agent or the runtime processes did not shutdown at the end of a previous load test, which should not happen. | Check for pending perfLtcAgent.exe or perfRun.exe files and terminate them manually. If this is not the case, check that other programs are not using an open file from the local results directory. If none of the above options solve the problem, reboot the remote agent’s machine.
Parent topic: Controller Agent Communication Troubleshooting


Load Test Controller - 3305: The local data directory could not be created

Possible Cause | Resolution
See "Load Test Controller - 3303: The local results directory could not be created" | See "Load Test Controller - 3303: The local results directory could not be created"
Parent topic: Controller Agent Communication Troubleshooting
Related reference
Load Test Controller - 3303: The local results directory could not be created


Load Test Controller - 3306: The local data directory could not be cleared

Possible Cause | Resolution
See "Load Test Controller - 3304: The local results directory could not be cleared". | See "Load Test Controller - 3304: The local results directory could not be cleared".
Parent topic: Controller Agent Communication Troubleshooting
Related reference
Load Test Controller - 3304: The local results directory could not be cleared


Load Test Controller - 3422: Command (connection) timed out

Possible Cause Resolution
Usually the controller has 30 seconds to:
  • Connect to the remote agent control service
  • Pass authentication information to the remote agent control service (if required)
  • Ask the agent control service to create the agent
  • Connect to the agent
  • Exchange version information with the remote agent
These tasks may take more time than the default timeout of 30 seconds, especially if the agent is connected through a proxy or if the connection is slow. 		Specify a higher timeout in the system settings.
Parent topic: Controller Agent Communication Troubleshooting
Related tasks
Configuring Control Settings


Silk Performer - 32: Access denied, authentication required

Possible Cause | Resolution
The agent expects a password, but the controller did not send a password, meaning the controller did not authenticate itself. | Adjust the agent connection settings.
Parent topic: Controller Agent Communication Troubleshooting
Related concepts
Remote Agents
Related reference
Silk Performer - 33: Authentication failed (wrong password)


Silk Performer - 33: Authentication failed (wrong password)

Possible Cause | Resolution
The agent expects a password but the password sent by the controller is incorrect. | Adjust the agent connection settings.
Parent topic: Controller Agent Communication Troubleshooting
Related concepts
Remote Agents
Related reference
Silk Performer - 32: Access denied, authentication required


Silk Performer - 25: Limit of concurrent instances exceeded

Possible Cause | Resolution
Two agents cannot run simultaneously on the same computer. Most likely, the agent is involved in a load test started by another controller. | Wait for the other controller to finish its load test and then try again. If this is not the problem, the agent did not terminate correctly at the end of a previous load test and you must terminate the agent process manually.
Parent topic: Controller Agent Communication Troubleshooting


System - 2: The system cannot find the file specified

Possible Cause | Resolution
The agent executable (perfLtcAgent.exe) could not be found or there is a different entry for the agent executable in the performerLocal.ini file. | Check the performerLocal.ini file. If it is not there or if the perfLtcAgent.exe is not present, then re-install the agent.
Parent topic: Controller Agent Communication Troubleshooting


Error Message Overview

Silk Performer system-related errors occur either during script compilation or during load test execution and can cause load tests to fail. As they occur, Silk Performer reports system-level errors on the screen. Severe system-level errors are reported to the Windows NT Event Log.

Silk Performer distinguishes among the following types of system-level errors:

  • Compiler errors
    • Lexical errors
    • Semantic errors
    • Syntax errors
  • Internal errors
  • System limitation errors
  • Runtime errors

Each error message is identified by a sequential error number (unique within an error category) plus a three-character code that indicates the category of error, followed by a string providing a detailed description of the error.

  • Compiler Errors
    If an error occurs during compilation, the Silk Performer compiler stops at the position where the error was detected.
  • Internal Errors
    Silk Performer can detect internal script errors (error type COM).
  • System Limitation Errors
    System limitation errors (error types RES) can occur while either compiling a script or running a load test .
  • Runtime Errors
    Runtime errors indicate programming errors in test scripts that cannot be recognized during compilation.
Parent topic: Troubleshooting
Related concepts
Error-Handling Functions


Compiler Errors

If an error occurs during compilation, the Silk Performer compiler stops at the position where the error was detected. The error message is displayed, and the line that caused the error is highlighted.

The compiler distinguishes among the following categories of errors:

  • Lexical errors (LEX)
  • Semantic errors (SEM)
  • Syntax errors (SYN)
  • Lexical Errors
    A lexical error (error type LEX) occurs if the compiler detects lexical symbols that are not allowed in Benchmark Description Language.
  • Semantic Errors
    A semantic error (error type SEM) occurs if semantic conditions do not comply with the requirements of Benchmark Description Language.
  • Syntax Errors
    A syntax error (error type SYN) occurs if the syntax of a test script does not agree with the syntax of Benchmark Description Language.
Parent topic: Error Message Overview


Lexical Errors

A lexical error (error type LEX) occurs if the compiler detects lexical symbols that are not allowed in Benchmark Description Language.

Example

If a script contains an invalid character such as '{', compilation is aborted and an error message is printed:

1 benchmark WebTest
2
3 dcluser
4   user    {

Output

compile error LEX 13: not a lexical symbol of BDL
--- compilation was not successful ---
Parent topic: Compiler Errors


Semantic Errors

A semantic error (error type SEM) occurs if semantic conditions do not comply with the requirements of Benchmark Description Language.

Example

If you use an undeclared variable ("i" in the example below), compilation is aborted and an error message is displayed:

46 dcltrans
47   transaction TMain
48   var
49     artname      : string(40);
50     artno, price : number;
51     result set c1;
52   begin
53     writeln; write("transaction TMain:"); writeln;
54     c1: SelArticle(out artno, price, artname);
56     write("rows found: "); write(rows(c1));
57     fetch c1 all;
58     for i:

Output

compile error SEM 12: variable is not declared
--- compilation was not successful ---
Parent topic: Compiler Errors


Syntax Errors

A syntax error (error type SYN) occurs if the syntax of a test script does not agree with the syntax of Benchmark Description Language.

Example

If you do not specify the keyword then within an if statement, an error message appears:

 8 transaction TMain
 9 var
10   j : number init 1;
11   i : array [500] of number;
12   s : array [5] of string(10);
13 begin
14   if j=1
15   j:

Output

compile error SYN 38: 'then' expected
--- compilation was not successful ---
Parent topic: Compiler Errors


Internal Errors

Silk Performer can detect internal script errors (error type COM). Please contact Customer Care if you encounter one.

Parent topic: Error Message Overview


System Limitation Errors

System limitation errors (error types RES) can occur while either compiling a script or running a load test . If they occur during a test execution, they will cause the test to fail. These errors indicate that a system limitation has been exceeded.

Parent topic: Error Message Overview


Runtime Errors

Only the Silk Performer simulator will produce runtime errors (error type RUN). Runtime errors indicate programming errors in test scripts that cannot be recognized during compilation (for example, using array indexes outside the scope of an array). If a runtime error occurs, an error message is printed on screen and to a .rpt file.

Parent topic: Error Message Overview


Known Issues in Silk Performer

This list contains known issues in Silk Performer and provides work-arounds where available:

  • General Silk Performer Issues
  • TrueLog Explorer Issues
  • SAPGUI Issues
  • Citrix Issues
  • Oracle Forms Issues
  • Browser-Driven Load Testing Issues
  • Java over HTTP Issues
Parent topic: Silk Performer Workbench 21.0


General Silk Performer Issues

  • Multi-byte character set support limitations
  • How can I get Silk Performer "What's This" contextual Help to work on Windows Vista or later?
  • The Silk Launcher Service is falsely removed when a previous version of Silk Performer is removed
  • GUI-level testing does not work if Silk Test is not installed in the Program Files folder
  • GUI-level scripts generated from Japanese libraries do not compile
  • The System Configuration Manager entry in the Tools menu is disabled
  • Reports created from recovered results show incorrect values
  • GUI-level testing with keyword-driven tests and Selenium is only supported with Java 8
  • Underlined and marked BDL functions in custom .bdh files
Parent topic: Known Issues in Silk Performer


Multi-byte character set support limitations

Problem:

The protocol / testing support of the Multi-Byte Character Set / UTF-8 / EUC-JP is limited to certain application types.

Resolution:

The protocol / testing support of the Multi-Byte Character Set / UTF-8 / EUC-JP is limited to the following application types:
  • Web application testing, both protocol-level and browser-driven level
  • SAPGUI testing
  • Oracle Forms/Oracle Applications testing
  • Citrix testing
.
Parent topic: General Silk Performer Issues


How can I get Silk Performer "What's This" contextual Help to work on Windows Vista or later?

Problem:

How can I get Silk Performer "What's This" contextual Help to work on Windows Vista or later Windows versions?

Resolution:

In Silk Performer it is possible to get information about GUI functionality by right-clicking GUI controls and choosing What's This?. This contextual help does not work on Windows Vista or later Windows versions. This is a known issue related to the fact that the Windows Help program WinHlp32.exe is no longer included with newer Windows versions. To resolve this, download the respective .exe file from the Microsoft Download Center. For more information, see: http://support.microsoft.com/kb/917607.

Parent topic: General Silk Performer Issues


The Silk Launcher Service is falsely removed when a previous version of Silk Performer is removed

Problem:

If you have multiple versions of Silk Performer installed on your system and you remove a previous version of Silk Performer, the Silk Launcher Service is falsely also removed.

Resolution:

Uninstall all Silk Performer versions from your system and reinstall the needed versions in ascending order.

Parent topic: General Silk Performer Issues


GUI-level testing does not work if Silk Test is not installed in the Program Files folder

Problem:

GUI-level testing does not work if Silk Test is not installed in the Program Files (Program Files (x86)) folder.

Resolution:

None.

Parent topic: General Silk Performer Issues


GUI-level scripts generated from Japanese libraries do not compile

Problem:

When importing Silk Test test cases with names that contain non-ASCII characters, the generated script stubs cannot be compiled.

Resolution:

Either rename the test case in Silk Test so it does not use any non-ASCII characters, or rename the generated transactions in the Silk Performer script accordingly.

Parent topic: General Silk Performer Issues


The System Configuration Manager entry in the Tools menu is disabled

Problem:

If you have multiple versions of Silk Performer installed on your system and you uninstall a previous version of Silk Performer, the System Configuration Manager entry in the Tools menu might be disabled.

Resolution:

Re-install the current Silk Performer version.

Parent topic: General Silk Performer Issues


Reports created from recovered results show incorrect values

Problem:

The test summary, detailed, and region summary report created from recovered results show incorrect values.

Resolution:

Due to limitations in the recovery process, not all values can be recovered completely. The following issues can occur:
  • The summary data is missing.
  • The number of Active Users is incorrect.
  • The Session Time and the Session Busy Time cannot be recovered, they always displayed as 0.
  • The Average Action Time cannot be recovered, it always displays as -.
  • The number of Errors is incorrect.
Parent topic: General Silk Performer Issues


GUI-level testing with keyword-driven tests and Selenium is only supported with Java 8

Problem:

GUI-level testing with keyword-driven tests and Selenium is only supported with Java 8.

Resolution:

This is a Selenium restriction. The only workaround is to use Java 8.

Parent topic: General Silk Performer Issues


Underlined and marked BDL functions in custom .bdh files

Problem:

When working with custom (user-created) .bdh files, some or all built-in BDL functions are underlined and marked as Function or event handler not declared, even though the main .bdf file compiles successfully.

Resolution:

The BDL parser in the code editor cannot determine which .bdh files have been included before the current .bdh file in the main .bdf file. Make your custom .bdh files self-contained. This means: for all underlined API functions add a use statement for the corresponding .bdh file, where the function is defined.

Parent topic: General Silk Performer Issues


TrueLog Explorer Issues

  • On-access virus scanner software may cause TrueLog Explorer to crash
  • Visual script modifications fail if the related transaction is in an include file
  • Visual user data customization does not work for browser-level scripts
Parent topic: Known Issues in Silk Performer


On-access virus scanner software may cause TrueLog Explorer to crash

Problem:

On-access virus scanner software may cause TrueLog Explorer to crash.

Resolution:

Virus scanner software may cause a variety of problems including TrueLog Explorer crashes or performance degradation. We recommend disabling virus scanner software on the agent computers and on the controller computer for the duration of load tests.

Parent topic: TrueLog Explorer Issues


Visual script modifications fail if the related transaction is in an include file

Problem:

Visual script modifications fail if the related transaction is in an include file.

Resolution:

Do not move transactions to BDH files.

Parent topic: TrueLog Explorer Issues


Visual user data customization does not work for browser-level scripts

Problem:

Visual user data customization does not work for browser-level scripts

Resolution:

This behavior is by design, as TrueLog Explorer only considers forms submitted by WebPageSubmit calls (page-based browser-level API), because the HTML form names are required to match HTML and BDL forms. If you want to customize your script using TrueLog Explorer Visual User Data Customization, you need to record a page-based browser-level API script.

Parent topic: TrueLog Explorer Issues


SAPGUI Issues

  • Control position information cannot be retrieved correctly from SAP
Parent topic: Known Issues in Silk Performer


Control position information cannot be retrieved correctly from SAP

Problem:

In rare instances, control position information can not be retrieved correctly from SAP. Therefore TrueLog Explorer might not be able to display the selected control rectangle at the correct position on the screenshot.

Resolution:

Use the control tree instead of the screenshot.

Parent topic: SAPGUI Issues


Citrix Issues

  • Connecting to existing session during Citrix recording results in unusable script
  • Limitations for load testing with Citrix Receiver or Citrix Workspace-App
  • Citrix passthrough authentication is not enabled for custom tools
  • Citrix process is already running under a different user account
Parent topic: Known Issues in Silk Performer


Connecting to existing session during Citrix recording results in unusable script

Problem:

Connecting to existing session during Citrix recording results in unusable script

Resolution:

When connecting to an existing Citrix session, the Citrix client does not recognize any windows and therefore no synchronization functions are scripted. You should always record a new session.

Parent topic: Citrix Issues


Limitations for load testing with Citrix Receiver or Citrix Workspace-App

Problem:

Several versions of Citrix Receiver and Citrix Workspace App are buggy, which causes several issues.

For example:
  • The BDL function CitrixConnect does not work for Citrix load testing in Citrix Receiver 4.4, 4.10 and newer.
  • Citrix Workspace-Apps 20.8.0.46 (2008) and 20.9.0.3 (2009) can neither record onmove nor onsize events.

Resolution:

Use a different version (preferably the LTSR versions) of Citrix Receiver or Citrix Workspace-App.
  • Option 1: Use Citrix Receiver (LTSR) 4.9.7 or later.
  • Option 2: Use the latest Citrix Workspace-App (LTSR) 19.12.1001.3
Parent topic: Citrix Issues


Citrix passthrough authentication is not enabled for custom tools

Problem

The Citrix passthrough authentication mode is not enabled for custom tools. Therefore, Silk Performer cannot record or replay this authentication mode.

Resolution

Recording and replaying Citrix with enabled passthrough authentication is possible and no issues will occur, however you are prompted to enter your credentials anyway. Be aware that though passthrough authentication is enabled, it is in fact not working.

Parent topic: Citrix Issues


Citrix process is already running under a different user account

Problem

When executing a Citrix load test, the following error message displays: Citrix process is already running under a different user account. This happens when the Citrix process wfcrun32.exe is already running under a certain user account. For example: A Windows session is already used by the user A. When a load test is started, an agent logs into the same Windows session as user B. User B now attempts to start the process wfcrun32.exe, which does not work and causes the error to display in Silk Performer.

Resolution

Close the running Windows session by logging out user A before you start the load test.

Parent topic: Citrix Issues


Oracle Forms Issues

  • After hooking into main Oracle Forms applet classes, JInitiator cannot load additional jar files that rely on those classes
  • Browser crashes during recording of Oracle Forms
  • Oracle Forms cannot be recorded
Parent topic: Known Issues in Silk Performer


After hooking into main Oracle Forms applet classes, JInitiator cannot load additional jar files that rely on those classes

Problem

After hooking into main Oracle Forms applet classes, JInitiator cannot load additional jar files that rely on those classes

Resolution

When recording Oracle Forms or Oracle Applications, define the following Java Runtime Options on the JInitiator Properties Dialog: "-noverify -mx128m" NoVerify prevents these loading issues. Additionally, the default Virtual Memory Size of JInitiator 1.1.7.x is between 16 and 64 MB. The option -mx128m increases the virtual memory size to 128MB. This additional memory is needed as there is some extra memory overhead caused by recording. If you run into an OutOfMemory error you can further increase this value.

Parent topic: Oracle Forms Issues


Browser crashes during recording of Oracle Forms

Problem

Browser crashes during recording of Oracle Forms.

Resolution

When recording Oracle Forms 6i it is recommended that you disable Java JIT (Just-In-Time compiling) in the Java Runtime settings. This is because the JIT library of the Java Virtual Machine (symcjit.dll) may crash your browser.

Java JIT can be disabled using one of the following options:

Option 1: Define - DJAVA.COMPILER=NONE in the Java runtime settings of the Oracle JInitiator Properties dialog. This must be done using the JInitiator control panel, which is installed with JInitiator (available in the Windows control panel).
  1. Launch the JInitiator Control Panel.
  2. Add DJAVA.COMPILER=NONE to the Java Run Time Parameters text field.
  3. Click Apply.
Option 2: Use the check box on the Oracle JInitiator Properties dialog to disable the Just In Time Compiler (only available since version 1.1.8.x).
  1. Launch the JInitiator Control Panel.
  2. Select the Advanced tab.
  3. Uncheck the Enable Just In Time Compiler checkbox.
  4. Click Apply.
Option 3: Define environment variable: JAVA_COMPILER=NONE.
  1. Right-click My Computer and choose Properties.
  2. Choose Advanced.
  3. Choose Environment Variables.
  4. Under System Variables click New.
  5. For Variable Name enter JAVA_COMPILER.
  6. For Variable Value enter NONE.
  7. Click OK to exit out of dialogs.
Parent topic: Oracle Forms Issues


Oracle Forms cannot be recorded

Problem

When attempting to record Oracle Forms, a dialog appears, containing the following question: Do you want to run this application? However, the Run button on this dialog cannot be clicked and therefore the recording cannot be continued. This happens primarily under Windows 7.

Resolution

Navigate to the Essentials folder within your Silk Performer installation directory. Your path should resemble this one: C:\Program Files (x86)\Silk\Silk Performer <version>\Essentials. Locate the respective Oracle Forms Essentials file: OraForms<version>.sep. The .sep file contains the file DeploymentRuleSet.jar. Extract the .sep file and copy DeploymentRuleSet.jar to the following directory: C:\Windows\Sun\Java\Deployment. Restart Silk Performer. Now, when you start a recording, the dialog no longer appears. DeploymentRuleSet.jar is available for Silk Performer 18.5 and newer versions.

Parent topic: Oracle Forms Issues


Browser-Driven Load Testing Issues

  • ShowModalDialog and ShowModelessDialog not fully supported
  • Webbrowser control of primary BrowserWindow is terminated
  • TrueLog Explorer displays the size of uncompressed data in browser-driven tests
Parent topic: Known Issues in Silk Performer


ShowModalDialog and ShowModelessDialog not fully supported

Problem

The non-standard functions showModalDialog and showModelessDialog are not fully supported. The browser-driven implementation of these functions is not fully compatible with the implementation of Internet Explorer. In particular javascript-heavy pages that are loaded in such a dialog may not function correctly.

Resolution

Try to use a GUI-level testing approach in such situations.

Parent topic: Browser-Driven Load Testing Issues


Webbrowser control of primary BrowserWindow is terminated

Problem

Silk Performer's browser-driven approach relies on the webbrowser control of the primary (initial) BrowserWindow through the entire scenario of a test. To implement a particular workflow, some applications open a new child window and close the base window. If the closed window is the primary (initial) BrowserWindow of the test scenario, the internal state of Silk Performer' s browser-driven engine is undefined. This might result in unexpected application behavior during recording as well as during playback.

Resolution

Add an additional BrowserWindow to your test - it will act as the new base window. The primary (initial) BrowserWindow remains unused in your scenario. To add an additional window during recording, click File > New Tab. Make sure to add the window right at the beginning of your recording. For existing scripts, add a BrowserCreateWindow statement right before the first BrowserGetActiveWindow statement.

Parent topic: Browser-Driven Load Testing Issues


TrueLog Explorer displays the size of uncompressed data in browser-driven tests

When receiving compressed data during a browser-driven test, the results displayed in TrueLog Explorer and in the Virtual User Report can be misleading. TrueLog Explorer displays the size of the uncompressed data for the measure Response data received in the Statistics tab, while the Virtual User Report shows the value 0. Note that this is only the case for browser-driven tests and when compressed data is transmitted during the test.

Parent topic: Browser-Driven Load Testing Issues


Java over HTTP Issues

  • Previous Java over HTTP scripts might not run successfully
Parent topic: Known Issues in Silk Performer


Previous Java over HTTP scripts might not run successfully

Problem

Java over HTTP scripts recorded with a previous Silk Performer version might no longer run successfully.

Resolution

Due to the upgrade of the third-party component XStream, some Java over HTTP scripts that have been recorded with previous versions of Silk Performer might no longer run successfully. In such a case, re-record your scripts with the current Silk Performer version.

Parent topic: Java over HTTP Issues


Benchmark Description Language (BDL) Reference

This Help describes the Silk Performer Benchmark Description Language (BDL) and the components included in a test script.

  • Scripting Language Structure and Statements
    Explains the lexical and program structure of Silk Performer's Benchmark Description Language (BDL) and the statements for expressing sequences, selections, and iterations.
  • General Functions
    Lists the functions that set specific simulation options, allocate, read and write memory, handle files, and more.
  • Application Server Functions
    Lists BDL functions for testing application servers and the architectures they are based on.
  • Browser-Driven Web Load Testing Functions
    Lists the functions that are specific to Silk Performer browser-driven Web load testing functionality.
  • Database (DBMS) Functions
    Describes the different levels at which you can create load testing scripts for a database server.
  • ERP/CRM Functions
    Silk Performer provides functions for testing ERP/CRM systems like SAP, Siebel, and PeopleSoft.
  • Internet Functions
    Lists BDL functions for testing Web applications and protocols, such as HTML, FTP, Remedy, SMTP, TCP/IP, and many more.
  • Java Framework Functions
    As a powerful extension to Silk Performer’s Benchmark Description Language, the Java Framework enables you to implement user behavior in Java.
  • JMS Functions Reference
    Silk Performer provides JMS API functions to write and run scripts for testing JMS applications and providers.
  • Monitoring Functions
    Silk Performer provides functions for real-time monitoring server resources via PDCE and SNMP, supported by Performance Explorer.
  • .NET Framework Functions
    Lists the functions that are available for interaction with .NET objects.
  • GUI-Level Testing Functions
    Lists BDL functions for performing GUI-level testing against (fat) client applications.
  • Terminal Services Functions
    Silk Performer provides functions for testing applications that are hosted via terminal services.


Scripting Language Structure and Statements

  • Lexical Structure
    Describes the Silk Performer Benchmark Description Language (BDL) and the components of a load testing script.
  • Program Structure of Load Testing Scripts
    Defines the sections within a load testing script.
  • Statements
    Lists the statements for expressing sequences, selections, and iterations in Silk Performer.
Parent topic: Benchmark Description Language (BDL) Reference


Lexical Structure

The scripting language used by Silk Performer is called Benchmark Description Language (BDL). BDL is not case-sensitive.

A BDL load testing script consists of:

  • Keywords
    Lists the keywords reserved for Benchmark Description Language use only.
  • Names
    Provides an overview of names and includes examples of valid and invalid names.
  • Strings
    Describes the syntax for strings within Silk Performer.
  • Escape Sequences In String Constants
    Lists and describes the escape sequences for string constants.
  • Single Characters
    Provides an overview of single-character constants and includes valid and invalid examples.
  • Numbers
    Distinguishes between integers and floating-point numbers and provides valid and invalid examples.
  • Special Characters
    Lists the special characters that Silk Performer uses.
  • Comments
    Describes line, block, and nested comment use in Silk Performer.
Parent topic: Scripting Language Structure and Statements


Keywords

All names listed in the table below are reserved Benchmark Description Language keywords. They must not be used as identifiers in any context of a Silk Performer test script.
all | allownull | and | array
begin | benchmark | bin | boolean
callback | char | chr | commit
const | cursor | dclform | dclfunc
dclparam | dclrand | dclsql | dcltrans
dcluser | dll | do | double
dstring | else | elseif | end
eos | exit | explicit | false
fetch | float | for | form
function | halt | handler | if
in | init | inout | into
last | lenspec | long | loop
mod | next | not | number
of | optional | or | ord
out | proc | ptr | rc
Reset | result | return | RndBin
RndExpF | RndExpN | RndFile | RndInd
RndPerN | RndSno | RndStr | RndStream
RndUniF | RndUniI | RndUniN | rollback
row | rows | set | short
sizeof | sizespec | sql | stored
string | then | throw | to
transaction | transactions | true | unicode
union | unique | unsigned | use
user | var | wait | while
write | writeln | @codepage | @deprecated
Parent topic: Lexical Structure
Related concepts
Syntax of Load Testing Scripts
Program Structure of Load Testing Scripts
Related reference
Multibyte Support


Names

Names are used to identify random variables, named constants, users, transactions, functions, parameters, variables, Web forms, SQL commands, database cursors and the benchmark itself. There is no length limitation for names (except for names identifying users, cursors and SQL commands). Benchmark Description Language does not distinguish between upper-case and lower-case letters (for example, IndX INDX indx).

The table below lists all length restrictions for identifiers in BDL:

Identifier | Maximum length
for SQL command | 18 characters
for user group | 15 characters
for database cursor | 8 characters

Syntax

ident  = letter { letter | digit}

letter =  "abcdefghijklmnopqrstuvwxyz"
          "ABCDEFGHIJKLMNOPQRSTUVWXYZ_@".
digit  =  "0123456789".

Examples

The following names are valid:

  • abc123
  • a
  • _a
  • __1x
  • ABX1
  • _1
  • This_is_a_very_long_name

The following are invalid names:

  • 123
  • 1a

The following names for cursors and users are valid:

  • abc123
  • a
  • usr1
  • cursor1
  • c_1

The following are invalid names for cursors and users:

  • 1a
  • name_is_too_long
  • 12
Parent topic: Lexical Structure
Related reference
Special Characters


Strings

String constants are bound with double quotes ("). String constants can exceed line boundaries using the escape sequence "\" (backslash). Any character is a valid character in a string constant. To use a double quote inside a string, you must place a backslash in front of the double quote (\"). To use a backslash inside a string, you must write two backslashes (\\). Multiple string constants bound with double quotes and separated only with white space are treated as one string constant.

This data type represents an object consisting of a memory buffer for holding character data and its length. The memory buffer is always equal or larger than the character data represented by a string variable. You can declare the initial size of the memory buffer, which corresponds to the number of characters a size of the memory buffer, which corresponds to the number of characters a variable of type string can hold without resizing its buffer. During its use, the memory buffer can grow and shrink on demand

If you omit the length specification, the memory buffer is automatically pre-allocated to hold 254 characters including a termination character. A string is terminated by a null character (\0). However, if binary data is stored in the string variable several null characters may occur. The string variable knows the length of the data it is holding.

The elements of a string (single characters) can be referenced by an index beginning at one (1) for the first character in the string.

The string data type is as well designed to hold binary data. If binary data is assigned to a string variable the real length of the binary data is set accordingly.

A string variable implements the so-called NULL-pointer semantics, which means that it can differentiate between an empty string and a null string. A null string can be interpreted as string variable referencing no string object (null). An Empty string is a variable that references a string object, which holds a string without characters (""). In order to investigate or manipulate the current state of a string variable several string manipulation functions are provided.

Note: Any string variable, which is declared in any var section is initialized to its declared initial memory buffer size and represents an empty string (not null).

Syntax

string = '"' char { char } '"'.

BDL Example

The following string constants are valid:

dcltrans
  transaction TMain
var
  sString1 : string(40);
  sString2 : string(100);
  sString3 : string;

  sBin1 : string;
  sBin2 : string;
  sBin3 : string;
begin
  sString1 := "This is a string";
  sString2 := sString1;
  sString3 := "Hello" + sString1;

  sBin1 := "\h11223300445566";
  sBin2 := sBin1;
  sBin3 := "Hello " + sBin2 + "\h20";
end TMain;

SQL Example

String constants used in SQL commands are enclosed in single quotes (')

SELECT * FROM article WHERE name = 'pants'
Parent topic: Lexical Structure
Parent topic: Data Types
Related reference
Single Characters
Escape Sequences In String Constants


Escape Sequences In String Constants

Benchmark Description Language permits the use of escape sequences (for example, \, \n, \t, \n) in formatting string constants. The valid escape sequences match those in the programming language C and extend this set with the hexadecimal sequence \h. The meaning of the escape sequences are as follows:

Escape sequence | Description
\ | line continuation
\n | new line, line feed
\r | carriage return
\t | tabulator
\v | vertical tab
\b | backspace
\a | bell alert
\f | new page, form feed
\\ | backslash
\" | double quote
\h | hexadecimal representation
\x | next character in hexadecimal representation Example: \x2A indicates an asterisk

Example

dcltrans
  transaction TString
  var
    sString1, sString2: string;
  begin
    sString1 := "This is a constant string"
                "split into two lines"
    sString2 := "This is the first line, \
                 this is still the first line\nThis is the second line";
    write(sString1); writeln; write(sString2); writeln;
  end TString;

Example

const
  cbuf1 := "\h4142434A" // "ABCJ" length = 4
           "\h204142434A20" // " ABCJ " length = 6
           "\x20b\x20c\x20d"; // " b c d" length = 6
  // "ABCJ ABCJ b c d" length = 16

dcltrans
  transaction TMain
  const
    c1 := "abc";
  var
    s1 : string;
    n1 : number;
  begin
    s1 := "abc"
          "def";
    s1 := cbuf1;
    n1 := sizeof(cbuf1);
    write("length=" + string(n1)); writeln;
    write("\h4142434A" // "ABCJ" length = 4
          "\h204142434A20" // " ABCJ " length = 6
          "a\x20\x20b\x20c\x20d" // "a b c d" length = 8
    // "ABCJ ABCJ a b c d" length = 18);
    writeln;
    write("length=" + string(sizeof(
          "\h4142434A" // "ABCJ" length = 4
          "\h204142434A20" // " ABCJ " length = 6
          "a\x20\x20b\x20c\x20d") // "a b c d" length = 8
    // "ABCJ ABCJ a b c d" length = 18
    ));
    writeln;
    end TMain;

Output

length=16
ABCJ ABCJ a b c d
length=18

Parent topic: Lexical Structure
Related reference
Strings
Single Characters


Single Characters

A single-character constant is bounded with single quotes.

Syntax

char          = "'" noSingleQuote "'".

noSingleQuote = ANY - "'". (any single character
                            except the quote)

Example

The following single characters are valid:

  • '1'
  • 'x'
  • '§'
  • '}'

The following are invalid as single characters:

  • "1"
  • 'xy'
Parent topic: Lexical Structure
Related reference
Strings
Special Characters


Numbers

Silk Performer distinguishes between integers and floating-point numbers. The range of integer values is -231 to 231-1 (-2147483648 to 2147483647). The range of floating-point values is 1.7E +/- 308 (15 digits). Integer values can be represented in decimal or in hexadecimal format.

Syntax

number   = digit { digit } | "0x" hexdigit { hexdigit }.
signum   = [ "+" | "-" ] number.
float    = [ "+" | "-" ] digit { digit } "." digit { digit }.
digit    = "0" | "1" | "2" | "3" | "4" | "5" | "6" | "7" | "8" | "9".
hexdigit = digit | "A" | "B" | "C" | "D" | "E" | "F".

Example

dcltrans
  transaction TMain
  var
    nValue1, nValue2, nValue3:  number;
  begin
    nValue1 := -99;
    nValue3 := nValue2;
  end TMain;

The following numbers are valid:

  • 1
  • 01
  • +1234
  • -2378999
  • 0x1F
  • 0xEFA0
  • 1.0
  • 1.999
  • 20000.00001
  • -1.1

The following are invalid numbers:

  • 1.
  • .01
  • 99999999999
  • 12a
Parent topic: Lexical Structure
Parent topic: Data Types
Related reference
Strings


Special Characters

Silk Performer uses the following special characters:

Character | Name | Character | Name
: | colon | <> | noteq
; | semicolon | >= | greatereq
( | obracket | > | greater
) | cbracket | - | minus
[ | lbrack | + | plus
] | rbrack | * | asterisk
.. | pointpoint | / | slash
, | comma | . | period
:= | assign | “ | quote
< | less | ’ | single quote
<= | lesseq | | | logical_or
= | eq | & | logical_and
Parent topic: Lexical Structure
Related reference
Strings


Comments

Line comments

Silk Performer provides the // operator for managing comments at line level. All the characters of the current line following the // operator are marked as a comment.

Example

// this is a comment line
c1: SelArticle(); // select an article

Block comments

Block comments are bounded between /* and */. Nested comments are also allowed.

Example

/**********************************
* this is a valid comment *
**********************************/
/* this is a valid /* nested */ comment */
Note: Comments are not permitted inside a SQL command.
Parent topic: Lexical Structure
Related reference
Special Characters


Program Structure of Load Testing Scripts

A Silk Performer load testing script consists of the following sections:

  • Symbols
    • External functions
    • Include files
    • Constants
    • Parameters
    • Variables
    • Random variables
    • Functions
    • Event handlers
  • Workload
  • Transactions
  • Web forms (Silk Performer Web Testing Only)
  • SQL (Silk Performer Database Testing Only)

Silk Performer permits the use of multiple sections for external functions, global variables, constants, random variables, and functions, in any order.

  • Syntax of Load Testing Scripts
    Lists the keywords to use within the sections of a load testing script.
  • Script Structure Sample
    Illustrates the basic structure and syntax of a Silk Performer load testing script.
  • String vs. Binary Data
    Describes why data is defined as string or binary data.
  • Handling Memory Buffers
    Describes how Silk Performer recognizes and works with memory blocks and buffers.
  • Null Pointer Semantics
    Provides an overview of null pointer semantics for Silk Performer.
  • External Functions Section
    Lists all functions that are available through dynamic link libraries.
  • Include Files Section
    Provides an overview of the include file, which you can use to define global constants, DLL functions and helper functions.
  • Constants Section
    Describes the types of constants available and where to use them.
  • Variables Section
    Provides an overview for variables used in a global section or in a transaction.
  • Parameters Section
    Provides an overview of parameters and describes where to use them within a test script.
  • Random Variables Section
    Provides an overview of random variables and describes where to use them within a test script.
  • Functions Section
    Provides an overview of functions and describes where to use them within a test script.
  • Event Handler Section
    Describes how to implement an event handler function to perform clean-up statements after a transaction exit error, or generally catch an error or warning before it gets reported.
  • Workload Section
    Provides an overview of the workload section, which contains the names of user groups and the transactions to be invoked by the user group together with their calling frequency.
  • Transactions Section
    Describes what a transaction is and how transactions are used to define the actions of virtual users in a load test.
  • Web Forms Section
    Provides an overview of the web forms section, which can easily be randomized and is used by WebForm functions.
  • SQL Section
    Provides an overview of the SQL section, which can contain several definitions of SQL commands or stored procedures.
  • Expressions
    Provides an overview of expressions including which type of expressions are supported and the functions that can be used in expressions.
Parent topic: Scripting Language Structure and Statements


Syntax of Load Testing Scripts

The various sections of a Silk Performer load testing script must be declared using the following syntax:

  • External functions contained in a dynamic link library that are called from a script must be declared using the keyword dll.
  • Include statements in a script include one or more files during the compilation of a script. Declare include files with the keyword use.
  • Constants are defined using the keyword const. Wherever you can use an integer constant, a floating-point constant, a boolean constant or a string constant, you can likewise use a named constant declared in this section. You do not need to specify the data type when declaring a constant.
  • Variables are defined using the keyword var. Global variables have global scope and therefore can be used in every transaction and as bind or INTO variables in every SQL command. You can also define variables with local scope for any transaction
  • Parameters are variables, which are re-used by the visual script customization wizards. Parameters are (automatically) defined using the keyword dclparam.
  • Random variables are defined using the keyword dclrand.
  • Functions used in a script are defined using the keyword dclfunc.
  • Users to be simulated are defined using the keyword dcluser.
  • Transactions executed by the users specified in the workload section of a script are defined using the keyword dcltrans.
  • Web forms used in transactions in a script are defined using the keyword dclform.
  • SQL commands that are called by transactions in a script are defined using the keyword dclsql.
  • Handler functions are defined using the keyword dclevent.
  • The code page with which a script was recorded is defined by the @codepage keyword.
Parent topic: Program Structure of Load Testing Scripts
Related reference
Script Structure Sample
Memory Requirements


Script Structure Sample

The following example illustrates the basic structure and syntax of a Silk Performer load testing script.

Examples

@codepage(1252)

benchmark Sample
use "Kernel.bdh"

dll "kernel32.dll"

"WaitForSingleObject"
    function WaitForSingleObject(in number,
                                                                                in number): number;

const
  NUMBER_CONST  := 1;
  STRING_CONST  := "ABCD";
  BOOLEAN_CONST := true;

var
  nNumber  : number;
  sString  : string;
  bBoolean : boolean;

dclparam
  nNumParam    : number;
  sStringParam : string;
  bBoolParam   : boolean;

dclrand
  rNumber: RndUniN(1..6);

dclfunc
  function Function1
  begin
  end Function1;

dclevent
  handler ErrorHandler <EVENT_RAISE_ERROR>
  begin
  end ErrorHandler;

dcluser
  user
    User1
  transactions
    TMain : 1;

dcltrans
  transaction TMain
  begin
  end TMain;

dclform
  Form1:
    "elem1" := "Value1",
    "elem2" := "Value2";
Parent topic: Program Structure of Load Testing Scripts
Related concepts
Syntax of Load Testing Scripts


String vs. Binary Data

A string in BDL represents a combination of a memory buffer and the length of the valid data within that buffer. For this reason, the string data type does not depend on a zero termination for its data. Due to the nature of this implementation, a BDL string can be interpreted as a zero-terminated sequence of characters (e.g., a string in C++ or as binary data with a specified length, no matter how many zeros exist within the data).

For backward compatibility reasons, a string is usually interpreted as a zero terminated sequence of characters (C++ string).

Example

transaction TMain
var
  s1 : string;
  s2 : string;
  s3 : string;
begin
  // s1 now holds the string "hello
  s1 := "hello"; "
  // s2 now holds also the string "hello"
  s2 := s1;
  // s3 now holds the concatenation of
  // s1 and s2, or "hellohello";
  s3 := s1 + s2;
end TMain;

When hex notation is used to specify a string, the data is automatically interpreted as binary data. However, if two BDL strings are concatenated with the ‘+’ operator, or if one string is assigned to another string, they will still be interpreted as strings.

Example

transaction TMain
var
  s1 : string;
  s2 : string;
  s3 : string;
begin
  // s1 now holds the binary data "\h110022"
  s1 := "\h110022";
  // s2 now holds the string "\h11"
  s2 := s1;
  // s3 now holds the string concatenation of
  // s1 and s2, or "\h1111"
  s3 := s1 + s2;
end TMain;

To change the way a string is interpreted, the bin() operator must be used. The bin() operator is allowed in conjunction with a string variable or a function call that returns a string. Using the previous example, if the bin() operator is used, the result is quite different.

Example

transaction TMain
var
  s1 : string;
  s2 : string;
  s3 : string;
begin
  // s1 now holds the binary data "\h110022"
  s1 := "\h110022";
  // s2 now holds the string "\h110022"
  s2 := bin(s1);
  // s3 now holds the binary concatenation of
  // s1 and s2, or "\h110022110022";
  s3 := bin(s1) + bin(s2);
end TMain;
Note: The bin() operator can be used in string assignments, concatenations, in string comparisons and in the actual parameters of function calls.
Parent topic: Program Structure of Load Testing Scripts


Handling Memory Buffers

Occasionally it is necessary to work with raw memory blocks. In such cases the user is responsible for allocating and freeing the memory blocks. However, many API functions can work with not only BDL strings, but also with memory buffers.

A memory block is represented by a handle returned by the Alloc() function. The keyword IN together with the memory handle represent the newly allocated memory buffer. When used as a parameter for an API function, runtime automatically converts the handle into a valid parameter for the external function. The only difference between an ordinary string variable is that the LENSPEC and SIZEPEC parameters are not set automatically by runtime.

Example

dll "some.dll"
  "FillBuffer"
    function FillBuffer(sBuffer : inout string,
                        nBufSize : in number sizespec optional,
                        nDataLen : out number lenspec optional);
  "WriteData"
    function WriteData(sData : in string,
                       nDataLen : in number lenspec optional);
transaction TMain
var
  sBuffer : string;
  hBuffer : number;
  nLen    : number;
begin
  FillBuffer(sBuffer, 1024); // sBuffer is automatically resized and the length is automatically set
  WriteData(sBuffer); // nDataLen is automatically set correctly
  hBuffer := Malloc(1024);
  FillBuffer(in hBuffer, 1024, nLen);
  WriteData(in hBuffer, nLen);  // nDataLen must be set manually
  Free(hBuffer);
end TMain;
Note: The IN modifier for actual number parameters requires either a STRING, PTR or DSTRING formal parameter type.
Parent topic: Program Structure of Load Testing Scripts


Null Pointer Semantics

Most native string implementations use null pointer semantics, which means that they differentiate between empty strings (pointers to "") and null strings (null pointers).

To write wrapper functions for external functions in BDL that have optional string parameters, null pointer semantics are also implemented for BDL strings.

Example

dll "some.dll"
  "ApiFunc"
    function ApiFunc(in dstring optional);

dclfunc
  function ApiFuncWrapper(theString : string optional)
  begin
    ApiFunc(theString);
  end T1;

dcltrans
  transaction TMain
  begin
    ApiFuncWrapper();
  end TMain;

In cases where the optional parameter is omitted, external functions expect a NULL as the optional dstring parameter. Also if a string variable is set to NULLusing the StrSetNull() function, external functions expect NULL rather than DSTRING objects.

Note:
  1. A BDL string can explicitly be set to null: StrSetNull(str)
  2. Declared strings are always initialized to "". StrIsNull() returns false for declared strings, except when StrSetNull has been applied to them.
  3. An optional formal parameter may be a temporary object, as in the example above. In such cases StrIsNull(theString) returns true.
Parent topic: Program Structure of Load Testing Scripts
Related reference
StrSetNull Function
StrIsNull Function


External Functions Section

This section lists all functions that are available through dynamic link libraries. All external functions declared in a dynamic link library that are called from the script must be declared before they are used. Use the keyword dll.

Syntax

DllDecl       = "dll" DllName Prototype { Prototype }.

Prototype     = ExtFuncName [ @deprecated [ "(" NewFuncName  ")" ] ] "function" FuncName
                [ "(" ParamList ")" ] [ ":" RetType ].

ParamList     = ParamDecl { "," ParamDecl }.

ParamDecl     = [ ParamName ":" ] [ PassMode ]
                ( BDL_Type | C_Type ) { ParamModifier }.

PassMode      = "in" | "inout" | "out".

ParamModifier = "allownull" | "explicit" |
                  "lenspec" | "sizespec" |
                  "optional"[":=" (signum | float | boolean | ident)].

BDL_Type      = "number" | "float" | "string" | "boolean" | "list".

C_Type        = "ptr" | "dstring" | "union" | "long" |
                "short" | "char" | "unsigned short" |
                "unsigned char" | "double".

RetType       = "number" | "float" | "string" |
                "dstring" | "boolean" | "long" |
                "short" | "char" | "unsigned short" |
                "unsigned char" | "double".
Section | Description
DllName | A constant string that specifies the name of the DLL file that contains the function(s) you want to call
Prototype | The definition of the function prototype of a DLL function you want to call
ExtFuncName | A constant string that specifies the name of the function as used inside the DLL (case-sensitive)
FuncName | An identifier that specifies the name of the function as used inside the BDL script (case-insensitive)
ParamName | An identifier that specifies the name of the parameter (optional).
PassMode | Indicates whether the parameter is passed into the function by reference (out and inout) or by value (in). The default is in. (Optional)
C_Type | The data type of a function parameter specified using C data types
BDL_Type | The data type of a parameter of a function using BDL data types. The BDL data types correspond to the C data types in the table below
RetType | The data type of the return value of the function using BDL data types or C data types, explained in the table below
BDL data type | C data type | Description
number | long | BDL data type number represents a 4-byte signed integer value
float | double | BDL data type float represents an 8-byte floating point value
string | char* | BDL data type string represents a null terminated character string value
boolean | long | BDL data type boolean represents a 4-byte integer value where 1 represents true and 0 represents false

The following table shows valid data type combinations between actual parameters (BDL data types) and formal parameters of external functions using C data types.

Actual BDL parameter type | Formal BDL parameter type | Formal C/C++ parameter type | Internal Type (accessible via rtPlugInLib.lib)
number | char | char | TByte1
number | unsigned, char | unsigned, char | TUByte1
number | short | short | TByte2
number | unsigned, short | unsigned, short | TUByte2
number | number, long | long | TByte4
number | number, long | unsigned, long | TUByte4
number | number, long, ptr | void* | TPointer
float | float | float | Real4
float | double | double | Real8
string, in <number> | string | char* | TString
string, in <number> | ptr | void* | TPointer
string, in <number> | dstring | void* | CBdlStr*
boolean | boolean | int | TBool
boolean, number, float, string, boolean[], number[], float[], string[] | union | void* | CBdlUnion*
Note: If you use ptr as data type for your external function, the compiler does not perform a type check between actual and formal parameters. Actual parameters of type number can be passed to DLL functions by reference (default) or by value using the ptr data type for the formal parameter. To pass an argument by value, preface the argument with the in keyword in the call to the DLL function.
Note: Functions marked with @deprecated issue a warning during compiling and highlight the new function to use instead.

Example

dll "odbc32.dll"
  "SQLConnect"
    function SqlConnect(in number, in string, in number,
                        in string, in number,
                        in string, in number): short;

dll "testdll.dll"
  "MyStrlen"
    function StrLen(inout string): number;

dcltrans
  transaction TConnect
  const
    SQL_NTS := -3;
  var
    hdbc, retcode : number;
    dsn_name : string;
  begin
    dsn_name := "dsn_sample";
    retcode := SqlConnect(hdbc, dsn_name, SQL_NTS, "u1",
    SQL_NTS, "u1", SQL_NTS);
  end TConnect;
  • Formal Parameter Modifiers
    Lists the formal parameter modifiers that can be used to interpret parameters correctly.
Parent topic: Program Structure of Load Testing Scripts
Related reference
Script Structure Sample


Formal Parameter Modifiers

In order for the Silk Performer runtime to interpret parameters correctly, the following formal parameter modifiers can be used. The external function is called with a zero value of the specified type, which is false for Boolean, 0 for integer numbers, 0.0 for floating point numbers, NULL for string types and an empty list of unspecified type, which must not be modified, for lists.

  • Lenspec
    Calculate the length specification for a string or dstring parameter.
  • Sizespec
    Calculates the size specification for buffers or the actual size of string parameters.
  • Allownull
    Indicates that an actual parameter may also be 0.
  • Optional
    Indicates that an actual parameter may not be specified for this formal parameter.
  • Explicit
    Makes the compiler check that an actual parameter is a non-indexed BDL string variable.
Parent topic: External Functions Section


Lenspec

Lenspec can be used in combination with numeric formal parameters of type long or number. If specified along with an in or inout parameter, the actual parameter is used as length specification for the next string or dstring parameter on the left. If specified along with an inout or out parameter, the actual parameter variable is used as length specification for the next left string parameter.

Formal in parameters declared with the lenspec modifier allow actual parameters to be 0 or STRING_COMPLETE. If one of these values is used, Silk Performer's runtime calculates the actual length of the next string or dstring parameter on the left and sets this parameter accordingly.

The length of a BDL string variable usually is the number of characters before the first zero termination character. If the string variable is specified using the bin() operator, the binary length of the string variable is used.

Note: The validity of the lenspec semantics is always limited to the next string or dstring parameter on the left, no matter if its semantics could be applied or not.

Example

dll "some.dll"
    "Send"
      function Send(sData : in string,
                     nDataLen : in number lenspec optional);

dcltrans
  transaction TMain
  var
    s1 : string;
  begin
    s1 := "\h110022";
    // sData = "\h11", nDataLen = 1
    Send(s1);
    // sData = "\h110022", nDataLen = 3
    Send(bin(s1));
    // sData = "\h11", nDataLen = 1
    Send(s1, STRING_COMPLETE);
    // sData = "\h110022", nDataLen = 3
    Send(bin(s1), STRING_COMPLETE);
  end TMain;
Parent topic: Formal Parameter Modifiers
Related reference
Sizespec
Allownull
Optional
Explicit


Sizespec

Sizespec can be used in combination with numeric formal parameters of type long or number. It may only be specified along with an in or inout parameter. The actual value of the sizespec parameter is taken as size specification for buffers. As such, its semantics are only applied to the next inout or out stringformal parameter on the left.

Formal parameters declared with the sizespec modifier allow actual parameters to be 0 or STRING_COMPLETE. If one of these values is used, Silk Performer's runtime calculates the actual size of the next string parameter on the left and sets this parameter accordingly. If the actual parameter specifies a size that is more than the actual size of the corresponding string parameter, the variable is automatically resized to the specified size.

Example

dll "some.dll"
  "GetData"
    function GetData(sBuffer : out string,
                     nBufferLen : in number sizespec
optional);

dcltrans
  transaction TMain
  var
    sBuffer : string;
  begin
    // sBuffer unmodified, nBufferLen = 253
    GetData(sBuffer);
    // sBuffer unmodified, nBufferLen = 253
    GetData(sBuffer, STRING_COMPLETE);
    // sBuffer unmodified, nBufferLen = 12
    GetData(sBuffer, 12);
    // sBuffer is resized, nBufferLen = 40000
    GetData(sBuffer, 40000);
  end TMain;
Parent topic: Formal Parameter Modifiers
Related reference
Lenspec
Allownull
Optional
Explicit


Allownull

Allownull indicates that an actual parameter may also be 0. No matter what type the formal parameter is.

Example

dll "some.dll"
  "DoAllowNull"
    function DoAllowNull(nParam1 : out number allownull,
                         nParam2 : in number);

dcltrans
  transaction TMain
  begin
    // although a variable should be set as first parameter,
    // we can also
    // specify 0, as the formal parameter
    // is declared allownull
    DoAllowNull(0, 12);
  end TMain;
Parent topic: Formal Parameter Modifiers
Related reference
Lenspec
Sizespec
Optional
Explicit


Optional

Optional indicates that an actual parameter may not be specified for this formal parameter. The external function is called with a zero value of the specified type, which is false for Boolean, 0 for integer numbers, 0.0 for floating point numbers, NULL for string types, and an empty list of unspecified type, which must not be modified, for lists.

Note: All formal parameters on the right of an optional must also be optional.

Example

dll "some.dll"
  "DoOptional"
    function DoOptional (nParam1 : out number optional,
                         nParam2 : in number optional);

dcltrans
  transaction TMain
  begin
    // both actual parameters can be omitted
    DoOptional();
  end TMain;
Parent topic: Formal Parameter Modifiers
Related reference
Lenspec
Sizespec
Allownull
Explicit


Explicit

Explicit may only be specified along with a dstring formal parameter. The modifier makes the compiler check that an actual parameter is a non-indexed BDL string variable. Any other string notations are not allowed.

Example

dll "some.dll"
  "DoExplicit"
    function DoExplicit(sVar : in dstring explicit);

dcltrans
  transaction TMain
  var
    s1 : string;
    hMem : number;
  begin
    DoExplicit(s1);         // ok
    DoExplicit(s1[2]);      // compiler error
    DoExplicit(in hMem);    // compiler error
    DoExplicit("hello");    // compiler error
    DoExplicit("\h110022"); // compiler error
  end TMain;
Parent topic: Formal Parameter Modifiers
Related reference
Lenspec
Sizespec
Allownull
Optional


Include Files Section

Silk Performer supports an include-file technique with a syntax similar to include statements in C. Include files (extension bdh) can contain any code sections of a BDL script. Usually you define global constants, DLL functions and helper functions in include files. This enables you to reuse code written in include files in other BDL scripts. The include file section lists the external files to be included during the compilation of a BDL script. Include files must be declared before the objects they contain are used. Include statements in Silk Performer cause one or more specified files to be included during the compilation of a test script. Multiple sections (dclrand, var, const, dclfunc, dll) in any order are supported in include files.

Include files are declared with the keyword use.

The include file search path order is as follows:
  1. Default Include directory (system setting)
  2. Custom Include directory (system setting)
  3. <actual project directory>\Include (if existing)
  4. <actual project directory>\Custom Include (if existing)
  5. <actual project directory>

Syntax

IncludeStatement = "use" Filename.

FileName: string constant (the name or path of the include file).

Example

The following is an example of a BDL file:

const
  DSN1 := "dsn_oracle";
  DSN2 := "sample";

use "odbc.bdh"
use "test.bdh"

Example

The following is an example of an Include file (ODBC.BDH)

const
  SQL_SUCCESS := 0;

dll "odbc32.dll"
  "SQLAllocEnv" function SqlAllocEnv(out number): number;

use "..\\bdh\\kernel.bdh"
Parent topic: Program Structure of Load Testing Scripts
Related reference
Script Structure Sample


Constants Section

Wherever you can use an integer constant, a floating-point constant, a boolean constant, or a string constant, you can likewise use a named constant declared in a constant declaration section. If you want to declare named constants with program scope (global constants), specify these constants at the top of your Silk Performer test script. If you want to declare local constants with transaction scope, specify these constants in a constant declaration section within the transaction.

The global constants used in the script are defined using the keyword const.

Syntax

ConstSection = "const" ConstDecl.

ConstDecl    = Constant { ";" Constant }.

Constant     = IdentList ":="
               ( signum | float | string | boolean
               | ident).

IdentList    = ident { "," ident }.

Example

const
  cnNumber1, cnNumber2 := -21;
  cnNumber3            := -cnNumber1;
  cbBoolean            := true;
  cfFloat              := -1.234;
  csString             := "This is a string constant";
Parent topic: Program Structure of Load Testing Scripts
Related reference
Script Structure Sample


Variables Section

Variables used in a load test can be defined in the global section of a Silk Performer test script or in a transaction. Variables defined in the global section have global scope and global life span and therefore can be used in any transaction and as bind or into variables in any SQL command or Web form. Variables of a transaction have local scope but also global life span and therefore can be used only in the transaction where they are defined.

Variables used in a script are defined using the keyword var.

Syntax

VarSection  = "var" VarDecl.

VarDecl     = TVar ";" { TVar ";" }.

TVar        = IdentList ":" (ExplicitSizedType | ImplicitSizedType).

ExplicitSizedType = [ "array" "[" number "]" "of" ] SimpleType.
// "[" [number] "]" is optional, but if not used, init is obligatory

SimpleType     = "number" [ "init" NumList ]
            | "float" [ "init" FloatList ]
            | "boolean" [ "init" BoolList ]
            | "string" [ "(" number ")" ]
                         [ "init" StringList ].

ImplicitSizedType = [ "array" "of" ] SimpleTypeInit).

SimpleTypeInit = "number" "init" NumList
            | "float" "init" FloatList
            | "boolean" "init" BoolList
            | "string" [ "(" number ")" ]
                         "init" StringList.

NumList     = signum { "," signum }.

FloatList   = float { "," float }.

BoolList    = boolean { "," boolean }.

StringList  = string { "," string }.
  • Data Types
    Lists the Silk Performer data types.
  • Arrays
    Provides an overview of arrays and array initialization.
  • Initialization of Variables
    Provides an overview of the initialization of boolean, number, and string transaction variables.
  • Compatibility of Data Types
    Distinguishes between variables used for the same data type versus variables used for different data types.
  • Memory Requirements
    Lists the memory requirements for transaction variables.
  • Sizeof Operator
    Indicates the amount of storage, in bytes, associated with a type, variable, parameter or constant.
  • Callback Operator
    Use the callback operator to enable passing callback functions to API calls.
  • Bin Operator
    Makes the runtime system interpret a string variable or the result of a string returning function as binary data.
Parent topic: Program Structure of Load Testing Scripts


Data Types

All variables used in a Silk Performer test script have a data type. Available data types are:

  • Boolean
    Defines the boolean data type.
  • Numbers
    Distinguishes between integers and floating-point numbers and provides valid and invalid examples.
  • Float
    Defines the float data type.
  • Strings
    Describes the syntax for strings within Silk Performer.
  • List
    Defines a List data type.
Parent topic: Variables Section
Related concepts
Compatibility of Data Types
Related reference
Memory Requirements
Type Conversion


Boolean

A variable of type boolean can have one of two values:
  • true or
  • false

These values are system-defined constants.

Example

dcltrans
  transaction TMain
  var
    bValue1, bValue2:  boolean;
  begin
    bValue1 := true;
    bValue2 := not bValue1;
  end TMain;
Parent topic: Data Types


Float

This data type represents an 8-byte floating-point value whose range is +/-1.7E308 with at least 15 digits of precision.

Example

dcltrans
  transaction TMain
  var
    fValue1, fValue2, fValue3:  float;
  begin
    fValue1 := -99.9;
    fValue3 := (fValue2 / fValue1 + 10.7) * 3.99;
  end TMain;
Parent topic: Data Types


List

A List is a container of variables of the same type, where the data types boolean, number, float, and string are supported. In contrary to an array, the number of elements in a list is dynamic. Silk Performer provides a number of functions to work with lists. A list without initialization has the size 0. Adding elements increases the list size, removing elements decreases the size.
Note: Lists of lists are not supported.

Example

transaction TAList
var
  lstNumber:  list of number;
  lstBoolean: list of boolean;
  lstFloat:  list of float;
  lstString: list of string init "one", "two", "three";
  nrVal: number;
begin
  ListAdd(lstNumber, 1); // first element
  ListAdd(lstNumber, 2); // second element
  ListAdd(lstNumber, 3); // ...
  ListAdd(lstNumber, 5); // lstNumber == { 1, 2, 3, 5 }
  ListInsert(lstNumber, 4, 4); // lstNumber == { 1, 2, 3, 4, 5 }
  ListGetFirst(lstNumber, nrVal); // nrVal == 1
  Print("nrVal: " + string(nrVal));
  ListPrint(lstNumber);

  ListSetAt(lstNumber, 3, 33);
  ListRemoveFirst(lstNumber);
  ListremoveLast(lstNumber);
  Print("**************");
  ListPrint(lstNumber);

  Print("length of the string-list: " + string(ListGetLength(lstString)));
end TAList;

Output

nrVal: 1
element 1: 1
element 2: 2
element 3: 3
element 4: 4
element 5: 5
**************
element 1: 2
element 2: 33
element 3: 4
length of the string-list: 3
Parent topic: Data Types
Related concepts
List Functions


Arrays

An array is an ordered list of variables of the same type. Arrays of data type boolean, number, float and string are supported. Elements in an array are referenced via an index on the array beginning at one (1). The number of elements in an array must be set explicitly. Multidimensional arrays are not supported.

Example

dcltrans
  transaction TMain
  var
    nNumber : number;
    bBoolean : boolean;
    sString : string;
    aNumberArray :  array [10] of number;
    aBooleanArray :  array [10] of boolean;
    aStringArray :  array [5] of string(20);
  begin
    nNumber := 5;
    bBoolean := false;
    sString := "This is a string";
    aNumberArray[1] := 2;
    aBooleanArray[aNumberArray[1]] := true;
    aStringArray[nNumber] := simstr;
  end TMain;

Initialization of arrays

If you initialize an array, you need not specify the size of the array. The size is equivalent to the number of initial values. If an array is initialized and its size is specified, all array items not initialized are set to the null value of the data type of the array.

Example

const
  cStr := "Paul";
  cNumber := 8;
  cFloat := 2.5
var
  aStringArray : array [6] of string(9) init cStr, "Jim",
  "John", "George", "Ringo", cStr;
  aNumberArray1 : array of number init cNumber, 1, 2, 3, 4, 5, 6, 7, cNumber;
  aNumberArray2 : array of number init 1;
  aNumberArray3 : array [5] of number init 1, 2, 3;
  aFloatArray : array of float init cFloat, 1.0, 2.0, 3.3, 5.5, 6.6;
  aBooleanArray : array of boolean init true, false, true;
Parent topic: Variables Section


Initialization of Variables

Transaction variables of type boolean, number and string can be initialized the first time the transaction where they are declared is called. If you omit an init value, the variable is initialized with the null value of its data type (false for boolean, zero (0) for number, and the empty string "" for strings).

Note: You cannot use the keyword init with local variables of type BOOLEAN, NUMBER and FLOAT declared in functions. However, strings may be initialized in functions using the init keyword.

Example

dcltrans
  transaction TMain;
  var
    nNumber : number  init 10;
    fFloat : float  init 123.456;
    bBoolean : boolean  init true;
    sString : string  init "Hello world!";
  begin
    write("number = "); write(nNumber); writeln;
    write("float = "); write(fFloat); writeln;

    if bBoolean then
      write("boolean = true"); writeln
    else
      write("boolean = false"); writeln
    end;

    write("string = "); write(sString); writeln;
  end TMain;

Output

number = 10
float = 123.456
boolean = true
string = Hello world!
Parent topic: Variables Section


Compatibility of Data Types

Assignments, comparisons and computations are allowed only for variables (transaction variables, random variables, parameters) of the same data type. To assign variables of different data types, you must use the type conversion functions of Benchmark Description Language.

  • Type Conversion
    Lists the functions for converting data types to permit work with variables of different data types.
Parent topic: Variables Section


Type Conversion

To permit work with variables of different data types, Benchmark Description Language offers the following functions for converting data types:
Function | Parameter | Return value | Description
ord | character | ASCII code | Converts a single character to its ASCII value
chr | ASCII code | character | Converts an ASCII value to its corresponding character value
string
  • integer
  • float
  • boolean
 string Converts the value of an expression to a string
number
  • string
  • float
  • boolean
 integer Converts the characters of a string or a floating-point value to an integer value. A boolean value is converted to 0 for invalid expressions (false) or 1 for valid (true) expressions.
float
  • string
  • integer
  • boolean
 float Converts the characters of a string or an integer value to a floating-point value. A boolean value is converted to 0.0 for invalid expressions (false) or 1.0 for valid (true) expressions

Syntax

ConvertFunc = "chr" "(" Expr ")"
            | "ord" "(" Expr ")"
            | "string" "(" Expr ")"
            | "number" "(" Expr ")"
            | "float" "(" Expr ")"
            | "boolean" "(" Expr ")".
  • If number(string) cannot convert the string to a number, it returns zero (0).
  • If string contains a floating-point value, the digits after the decimal point are truncated.
  • If float(string) cannot convert the string to a floating-point number, it returns zero (0.0).

Alphanumeric characters after digits are ignored.

Example

dcltrans
  transaction TMain
  var
    I : number;
    f : float;
    s : string(14) init "ProductName";
    s1 : string(14);
    b1 : boolean;
  begin
    I := ord('x');          // --> i: 120
    s[1] := chr(I+1);       // --> s[1]: 'y'
    I := ord(s[2]);         // --> i: 114
    I := 123;
    s := string(I*10+1000); // --> s: "2230"
    I := number(s);         // --> i: 2230
    s := "-123.99";
    I := number(s);         // --> i: -123
    s := "123aby";
    I := number(s);         // --> i: 123
    s := "x123.99";
    I := number(s);         // --> i: 0
    s := "A" + string(I);   // --> s: "A0"
    s := "-129.77";
    f := float(s);          // --> f: -129.77
    I := 20500;
    f := float(I);          // --> f: 20500.0
    b1 := boolean("TRUE");  // --> b1: true
    s := string(b1);        // --> s: "TRUE"
    i := number(b1);        // --> i: 1
  end TMain;
Parent topic: Compatibility of Data Types
Related concepts
Syntax of Load Testing Scripts
Data Types
Related reference
Memory Requirements


Memory Requirements

Each transaction that a user calls consumes data memory for its transaction variables. Transactions not used by a certain user do not consume data memory. Every global object (such as a random variable), whether it is used or not, consumes data memory because of its global scope.

Type | Bytes
number | 4
boolean | 4
float | 8
string (n) | n+1
array [m] of number | 4*m
array [m] of boolean | 4*m
array [m] of string (n) | (n+1)*m
Parent topic: Variables Section
Related concepts
Data Types
Syntax of Load Testing Scripts


Sizeof Operator

Sizeof indicates the amount of storage, in bytes, associated with a type, variable, parameter or constant.

Note: The sizeof operator is utilized at compile time. Generally this operator can also be used with arrays. However, when used with function parameter arrays, this operator returns the size of arrays' data types.

Syntax

SizeOf = "sizeof" "(" Expr ")".

Example

dcltrans
  transaction TMain
  var
    nNumber : number;
    fFloat : float;
    sString1 : string(12) init "ProductName";
    sString2 : string;
  begin
    write(sizeof(nNumber));  // --> 4
    write(sizeof(fFloat));   // --> 8
    write(sizeof(sString1)); // --> 13
    write(sizeof(sString2)); // --> 254
    write(sizeof("abcde"));  // --> 5
  end TMain;
Note: The terminating null byte for strings is not included.
Parent topic: Variables Section
Related concepts
Data Types


Callback Operator

Use the callback operator to enable passing callback functions to API calls. In general, the callback operator can only be used on identifiers of functions that are defined with a callback function attribute such as <ASYNC_CALLBACK_FUNCTION>.

Example

dclfunc
  function asyncCallback <ASYNC_CALLBACK_FUNCTION>
  begin
    Print("callback");
  end AsyncCallback;

dcltrans
  transaction TMain
    begin
      WebAsyncPreparePush(callback(AsyncCallback));
  end TMain;

Parent topic: Variables Section


Bin Operator

Bin makes the runtime system interpret a string variable or the result of a string returning function as binary data. In this case not the Strlen() function is taken for length calculations but the Binlen() function, which returns the actual binary length of the data.

Syntax

Bin = "bin" "(" String | StringFunc ")".

Example

dclfunc
  function Assert(b : boolean) <API_FUNCTION>
  begin
    if b then
      Print("ok");
    else
      Print("failed");
    end
  end Assert;

  function RetString : string
  begin
    RetString := "\h11002233";
  end RetString;

dcltrans
  transaction TMain
  var
    s1, s2, s3 : string;
  begin
    s1 := "\h11002233";      // "\h11002233"
    s2 := "\h550066";        // "\h550066"
    s3 := s1; // "\h11"
    s3 := s1 + "\h770088";   // "\h11770088"
    s3 := "\h770088" + s1;   // "\h77008811"
    s3 := bin(s1);           // "\h11002233"
    s3 := s1 + s2;           // "\h1155"
    s3 := bin(s1) + s2;      // "\h1100223355"
    s3 := s1 + bin(s2);      // "\h11550066"
    s3 := bin(s1) + bin(s2); // "\h11002233550066"
    s3 := RetString();       // "\h11"
    s3 := bin(RetString());  // "\h11002233"

    // comparisons
    // "\h11" = "\h11"
    Assert(s1 = s1);
    // "\h11" = "\h11002233"
    Assert(not (s1 = bin(s1)));
    // "\h11002233" = "\h11002233"
    Assert(s1 + "\h002233" = bin(s1));

  end TMain;
Parent topic: Variables Section
Related concepts
Data Types


Parameters Section

Parameters used in load tests must be defined in the global section of Silk Performer test scripts. Generally, parameters are global variables that are re-used by visual customization wizards in Silk Performer and TrueLog Explorer. Parameters have global scope and global life span and therefore can be used in any transaction or function, as bind data, or in variables in SQL commands and Web forms.

Parameters used in scripts are defined using the keyword dclparam.

Syntax

ParamSection = "dclparam" VarDecl.

VarDecl     = TVar ";" { TVar ";" }.

TVar        = IdentList ":" (ExplicitSizedType | ImplicitSizedType).

ExplicitSizedType = [ "array" "[" number "]" "of" ] SimpleType.
// "[" [number] "]" is optional, but if not used, init is obligatory

SimpleType     = "number" [ "init" NumList ]
            | "float" [ "init" FloatList ]
            | "boolean" [ "init" BoolList ]
            | "string" [ "(" number ")" ]
                         [ "init" StringList ].

ImplicitSizedType = [ "array" "of" ] SimpleTypeInit).

SimpleTypeInit = "number" "init" NumList
            | "float" "init" FloatList
            | "boolean" "init" BoolList
            | "string" [ "(" number ")" ]
                         "init" StringList.

NumList     = signum { "," signum }.

FloatList   = float { "," float }.

BoolList    = boolean { "," boolean }.

StringList  = string { "," string }.
Parent topic: Program Structure of Load Testing Scripts


Random Variables Section

All random variables used in a Silk Performer test script are defined in the random variables section. Random variables are used for generating random input values, specifying random repetition factors, specifying the probability of running transaction components, and specifying random user times.

One script may include more than one random variables section, although each random variable must be defined before it is used.

Random variables are defined using the keyword dclrand.

Note: Certain random types can be used directly within transactions, without the need to define a random variable.

The scope of a random variable is the whole Silk Performer program (global scope). A random variable is defined by its type and its range of values. The type of a random variable is specified by using its random type (distribution type) in its declaration. The range of values of a random variable is specified by the parameters of its random type declaration. Each time a random variable is used, the random type of the random variable generates a new random value.

The use of random variables in BDL is very similar to function declaration and calling in high-level programming languages. Silk Performer distinguishes between two kinds of random types:
  • Random types based on continuous distribution functions
  • Random types based discrete distribution functions

Syntax

RandVarPart = RandVarDcl { RandVarDcl }.

RandVarDcl  = IdentList ":" RandVar ";".

IdentList   = ident { "," ident }.

RandVar     = RndExpF | RndUniF | RndUniN| RndUniI
            | RndStr | RndExpN | RndInd | RndBin
            | RndPerN | RndFile| RndStream.
  • Continuous Random Types
    Describes the continuous random types that generate random floating-point values.
  • Discrete Random Types
    Lists the available discrete random types that are used for generating random input values, specifying random repetition factors, and specifying the probability of running transaction components.
  • Uniform Random Type
    Describes the advantage of using the unique random type, RndUniN.
Parent topic: Program Structure of Load Testing Scripts
Related concepts
Random Functions


Continuous Random Types

Continuous random types generate random floating-point values. They are used solely in wait statements for generating random user times. The following continuous random types are available:
  • RndExpF: Random type with exponential distribution returning floating-point values.
  • RndUniF: Random type with uniform distribution returning floating-point values.
Parent topic: Random Variables Section
Related reference
RndExpF Random Type (exponential distribution)
RndUniF Random Type (for wait statements)


Discrete Random Types

Discrete Random types generate random discrete values of the discrete types integer, boolean or string. They are used for generating random input values, specifying random repetition factors, and specifying the probability of running transaction components. The following discrete random types are available:
  • RndBin: Random type with Bernoulli distribution (binomial distribution) generating boolean values
  • RndUniN: Random type with uniform distribution generating integer values
  • RndUniI: Random type with uniform distribution with intervals generating integer values
  • RndExpN: Random type with exponential distribution generating integer values
  • RndStr: Random type with uniform distribution for alphanumeric values generating string values
  • RndInd: Random type with user-defined distribution generating integer or string values
  • RndPerN: Random type with uniform distribution generating unique integer values
  • RndFile: Random type using a file of values for the generation of random values in which the selection of the values is random
  • RndStream: Sequential type using a file of values for the generation of random values in which the selection of the values is sequential.
Parent topic: Random Variables Section
Related reference
RndBin Random Type (binomial distribution)
RndUniN Random Type (uniform distribution)
RndUniI Random Type (uniform distribution with intervals)
RndExpN Random Type (exponential distribution)
RndStr Random Type (alphanumeric values)
RndInd Random Type (individual distribution)
RndPerN Random Type (unique uniform distribution)
RndFile Random Type (strings from a pattern file)
RndStream Random Type (sequential from a pattern file)


Uniform Random Type

The RndUniN type is a unique random type, because you can also use it inside transactions. The advantage of using the RndUniN random type within a transaction rather than in the random variables section is that you can specify variable boundaries for the random values instead of constant boundaries.

Syntax

RndFunc = "RndUniN" "(" Expr ".." Expr ")".

Example

dcltrans
  transaction TMain
  var
    I, j: number init -2;
  begin
    I := RndUniN(j..j*I); /* RndUniN(-2..4) */
  end TMain;
Parent topic: Random Variables Section


Functions Section

All functions used in a Silk Performer test script are defined in the functions section. Functions should be used to give your script more structure. The syntax of functions is identical to the syntax of transactions, except for the items mentioned below.
  • Functions are defined using the keyword dclfunc
  • One script may include more than one functions section, although each function must be defined before it is used.
  • You can specify an option optional for the parameters of external and internal functions. This option indicates that the parameter is optional. If an optional parameter has not been passed in, its value will be 0 on entry to the function. For the data types CURSOR, SQL and FORM a value of -1 is passed on entry to the function.
    Note: All parameters following the first optional parameter for a function must also be optional.

We distinguish between external and internal functions. External functions are the BDL functions that are readily available for use, like for example WebPageUrl. Internal functions are functions that are implemented within your script. Random variables can be used as parameters of internal and external functions. Both external and internal functions can also be used as parameters of other external and internal functions.

Syntax

FunctionSection = "DCLFUNC" { Function }.

Function        = [ @DEPRECATED [ "(" NewFuncName  ")" ] ] "FUNCTION" ident [ "(" TParList ")" ]
                  [ ":" RType ] [FuncAttribute]
                  [ "CONST" ConstDecl ]
                  [ "VAR" VarDecl ]
                  "BEGIN" StatSeq "END" [ ident ] ";".

TParList        = TParam { ";" TParam }.

TParam          = IdentList ":" PType PModifier.

PType           = ["ARRAY" | "LIST" "OF" ] "STRING" "(" number ")"
                  | ["ARRAY" | "LIST" "OF" ] "NUMBER"
                  | ["ARRAY" | "LIST" "OF" ] "BOOLEAN"
                  | ["ARRAY" | "LIST" "OF" ] "FLOAT"
                  | "SQL"
                  | "FORM".

PModifier       = "allownull" | "optional" [ ":=" (signum | float | boolean | ident)].

RType           = "STRING" "(" number ")"
                  | "NUMBER"
                  | "BOOLEAN"
                  | "FLOAT".

FuncAttribute   = "<" FuncAttributeValue ">"
Section | Description
ident | The name of the function.
ConstDecl | The declarations of the function constants.
VarDecl | The declarations of the function variables.
StatSeq | The statements of the function.
FuncAttributeValue Specifies attributes for the function. The following options are valid:
  • API_FUNCTION: The function behaves like an API function. If an error is raised within this function, the line number and file of the caller is reported.
  • ASYNC_CALLBACK_FUNCTION: The function is used as callback function for the async replay response handling. Whenever response data of an async call is available, the function is called by the replay engine. Functions specified as ASYNC_CALLBACK_FUNCTION must not have parameters.
  • BDL_FUNCTION: (Default) The function behaves like an ordinary BDL function. If an error is raised within this function, the line number and file of where the error occurred is reported.

Example

benchmark BenchmarkName
use "kernel.bdh"

const
  MAX_ARRAY := 5;
// Definition of global variables: string, number, float, boolean, array
var
  sa1 : array [MAX_ARRAY] of string init "string1", "string2",
"string3", "string4", "string5" ;
na1 : array [MAX_ARRAY] of number init 1,2,3,4,5 ;

dclfunc
  function foo1 (psa1 : array of string; pna1: array of number; len :
number):number
  var i : number;
  begin
    for i := 1 to len do
      Print(psa1[i]);
      Print(string(pna1[i]));
    end;
  end foo1;

  function Func1(p1: number; s: number optional): number
  var
    i, j: number;
  begin
    if s = 0 then
      j := 1
    else
      j := s
    end;
    for i := 1 to p1 do
      j := j*i;
    end;
    Func1 := j;
  end Func1;

  function Func2(p1: number)
  var
    i, j: number;
  begin
    j := 1;
    for i := 1 to p1 do
      j := j*i;
    end;
    p1 := j;
  end Func2;

  function Func3
  begin
    write( "TestFunc was sucessfull");
  end Func3;

dcluser
  user
    VirtUser
  transactions
    TestFunc : 1;  // Transactions

dcltrans
  transaction TestFunc
  var
    l, m: number;
  begin
    foo1(sa1,na1,MAX_ARRAY);
    l := Func1(10);
    m := Func1(l);
    Func2(l);
    Func3();
  end TestFunc;
  • Wrapper Functions
    Describes how to make a wrapper function behave like an external function.
  • Characteristics and Limitations of Functions
    Lists the characteristics and limitations of functions.
  • Callback Functions
    Use a callback function when you want a script to execute a part of BDL code to react to one or more particular situations.
Parent topic: Program Structure of Load Testing Scripts


Wrapper Functions

Situations may occur, when an external function need to be wrapped by a BDL function, e.g. if always the same modifications to a parameter must be done before the external function call.

Such a BDL function usually should behave like a real external function, which includes line and file reporting of the caller.

In order to make a wrapper function behave like an external, the function attribute <API_FUNCTION> must be specified.

Example

dll "some.dll"
  "ApiFunc"
    function ApiFunc(in dstring optional);

dclfunc
  function ApiFuncWrapper(theString : string optional)
                                      <API_FUNCTION>
  begin
    if StrIsEmpty(theString) then
      ApiFunc("default string");
    else
      ApiFunc(theString);
    end;
  end T1;

dcltrans
  transaction TMain
  var
    s1 : string;
  begin
    ApiFuncWrapper();
    ApiFuncWrapper("hello");
    ApiFuncWrapper(s1);
  end TMain;

In case of an error during the ApiWrapper() external function call, all reports including the output windows of Silk Performer show the line number of where the wrapper function has been called. If the function attribute <API_FUNCTION> has not been specified, the line number of the external function call would be reported.

Parent topic: Functions Section


Characteristics and Limitations of Functions

Keep in mind the following when working with functions:
  • You can call functions within transactions or within functions.
  • Variables declared within functions are automatic - not static as in transactions. They are allocated each time you call a function.
  • Only string variables can be initialized with the init keyword.
  • Parameters of functions are called by reference.
  • To return a value, assign the function call to an existing variable.
  • You call functions using the name of the function in an expression or by
  • using the name of the function as a single statement (when you are not interested in the return value of the function or when the function does not have a return value).
  • A return statement used in a function will always exit the function and the transaction that calls the function.
Parent topic: Functions Section


Callback Functions

During a script run, you may want the script to execute a part of BDL code to react to one or more particular situations. You can use a callback function to let the script execute that part of BDL code whenever the situation occurs.

Use the attribute ASYNC_CALLBACK_FUNCTION in a callback function for an asynchronous response handling.

Example

benchmark BenchmarkName
use "WebAPI.bdh"

dcluser
  user
    WebUser
  transactions
    TMain : 1;

dclfunc
  function AsyncCallback <ASYNC_CALLBACK_FUNCTION>
  begin
    Print("callback");
  end AsyncCallBack;

dcltrans
  transaction TMain
    begin
      WebAsyncPreparePush(callback(AsyncCallback));
      ...
  end TMain
Parent topic: Functions Section


Event Handler Section

During a script run, it is often desired to have the possibility to execute a portion of BDL code in order to react to one or more particular situations (also known as events). Such a portion of BDL code is called event handler function. A typical task of an event handler function is to e.g. perform clean-up statements after a transaction exit error, or generally catch an error or warning before it gets reported.

BDL offers the possibility to define an event handler function for one of the following set of pre-defined events:
BDL event constant | Description
EVENT_RAISE_INFORMATION | Informational message
EVENT_RAISE_WARNING | Warning message
EVENT_RAISE_ERROR | Error message
EVENT_RAISE_TRANS_EXIT | Transaction exit error
EVENT_RAISE_PROC_EXIT | Process exit error
EVENT_TRANS_BEGIN | Transaction begin (within transaction context)
EVENT_TRANS_END | Transaction end (within transaction context)
EVENT_TRANS_FINISHED | Transaction finished (not within transaction context)
EVENT_SUSPEND | Suspending
EVENT_RESUME | Resuming
EVENT_STOP | Stop
EVENT_CITRIXINTERRUPT | Custom Citrix event (see CitrixAddInterrupt)
EVENT_USER_FINISHED | End of test script

A handler function must be defined in an event handler section. Each event handler section begins with the keyword dclevent. There may be more than one dclevent sections in a BDL translation unit.

From the semantic point of view an event handler can be considered as a function without parameters, which is automatically called by the runtime system, if its associated event occurs.

Syntax

EventSection = "DCLEVENT" { Handler }.
Handler = "HANDLER" ident "<"EventConstant">"
          [ "CONST" ConstDecl ]
          [ "VAR" VarDecl ]
          "BEGIN" StatSeq "END" ident ";"
Section | Description
ident | The name of the function.
EventConstant | One of the above BDL event constants
ConstDecl | The declarations of the function constants.
VarDecl | The declarations of the function variables.
StatSeq | The statements of the function.

Example

dclevent
  handler Handler1 <EVENT_RAISE_ERROR>
  begin
    if GetErrorCode(GetLastError()) = 1060 then
      print("caught HTTP: 1060 - HTML Hyperlink not found");
    elseif GetErrorCode(GetLastError()) = 404 then
      print("caught HTTP: 404 - object not found");
    else
      throw;
    end;
  end Handler1;

dcltrans
  transaction TestTrans
  begin
    ...
  end TestTrans;
  • Characteristics and Limitations of Event Handler Functions
    Lists the characteristics and limitations of event handler functions.
Parent topic: Program Structure of Load Testing Scripts
Related reference
GetTransactionName Function
GetFunctionName Function
GetLastError Function
GetErrorMsg Function


Characteristics and Limitations of Event Handler Functions

Keep in mind the following when working with event handlers:
  • Variables declared within handler functions are automatic - not static as in transactions. They are allocated each time the handler is invoked.
  • Only string variables can be initialized with the init keyword.
  • You can explicitly call a handler function by using its name as a single statement within a transaction or function.
  • A return statement used in a handler function will always exit the transaction, in which the handler function was called.
  • During the execution of an event handler function, event handling is disabled.
  • A throw statement exits the handler function and returns execution control to the runtime system, which continues the default procedure for the event.
  • If a handler function is defined for one of the following events, the handler function behaves like an exception handler and catches the event. In this case no output is generated in the report files and monitor window.
    • EVENT_RAISE_INFORMATION
    • EVENT_RAISE_WARNING
    • EVENT_RAISE_ERROR
    • EVENT_RAISE_TRANS_EXIT
    • EVENT_RAISE_PROC_EXIT

However, in order to stop handling the event and transfer control to the runtime system for the default procedure of event (e.g. report an error), a throw statement can be used.

Parent topic: Event Handler Section


Workload Section

The users to be simulated are defined in the workload section of a test script. A user is described by the transactions to be called and the frequency of those transactions.

Note: The workload section in a script must be defined before the transactions section that defines the transactions used in the workload section.

The users to be simulated are defined using the keyword dcluser.

Syntax

Workload      = UserDcl { UserDcl }.

UserDcl       = "user" UserGroupList
                "transactions" TransCount { TransCount }.

UserGroupList = ident { "," ident }.

TransCount    = identifier [ "(" ActTParList ")" ]
                 ":" number ";".

ActParList    = ActPar { "," ActPar }.

ActPar       = identifier | string | signum | float |
                "true" | "false".

The workload section (Workload) of a Silk Performer test script consists of one or more workload descriptions for a user group (UserDcl). A workload description of a user group contains the names of the user groups (ident1), and finally the transactions to be invoked by the user group together with their calling frequency (TransCount).

  • Transactions
    Provides an overview and example of transactions.
  • Startup and Shutdown Transactions
    Describes the special initialization transactions which are called once at the beginning of the simulation of a user and once at the end of the simulation of a user.
Parent topic: Program Structure of Load Testing Scripts


Transactions

After the keyword transactions, the transactions a user invokes are specified with their calling frequency (TransCount). TransCount contains the name of the transaction (ident), the actual parameters of the transaction (ActParList), and how often the transaction should be invoked in the simulation time (number). Random variables returning type number, string, boolean or float and constants of these types are valid parameters of a transaction. Number, type and sequence of the actual parameters of a transaction must correspond to number, type and sequence of the formal parameters of the transaction specified in the transactions section of the Silk Performer program. You can use the parameters of a transaction to transfer to a transaction information that is specific to the user of the transaction. Each transaction specified in the workload section must be defined in the transactions section of the Silk Performer program.

Example

dclrand
  rArtNo1 : RndUniN(1..5000);
  rArtNo2 : RndUniN(5001..10000);

dcluser
  user
    User1
  transactions
    Selling(rArtNo1, "user 1") : 100;
    Order                      : 10;
  user
    User2
  transactions
    Selling(rArtNo2, "users 2") : 50;
    StockQuery                  : 20;

dcltrans
  transaction Selling(pArtNo: number; pUser: string)
  begin
    ...
  end Selling;

  transaction StockQuery
  begin
    ...
  end StockQuery;

  transaction Order
  begin
    ...
  end Order;

The example shows a portion of a Silk Performer program. Users belonging to the user group User1 call the transaction Selling 100 times and the transaction Order 10 times. The actual parameters rArtNo1, a random variable, and "user 1", a constant string, are assigned to the transaction Selling.

Users belonging to the user group User2 call the transaction StockQuery 20 times and the transaction Selling 50 times. The actual parameters rArtNo2, a random variable, and "users 2", a constant string, are assigned to the transaction Selling.

Parent topic: Workload Section


Startup and Shutdown Transactions

Silk Performer provides a special initialization transaction which is called once at the beginning of the simulation of a user. A transaction is set as a startup transaction by using the keyword begin instead of the transaction frequency parameter.

Silk Performer provides a special termination transaction which is called once at the end of the simulation of a user. A transaction is set as a shutdown transaction by using the keyword end instead of the transaction frequency parameter.

Note: There is a profile simulation setting called Call end transactions for stopped virtual users that, when disabled, prevents execution of the end transaction for stopped virtual users.

Example

dcluser
  user
    User1
  transactions
    TInit     : begin;
    TUpdate   : 10;
    TDelete   : 10;
    TPrint    : 10;
    TShutdown : end;
Parent topic: Workload Section


Transactions Section

The transactions that are referenced in the workload (dcluser) section, are defined in the transactions (dcltrans) section. Transactions define the actions of virtual users by submitting function calls in order to interact with the application under test, for example calling Web functions to access a Web application published by a Web server. Describing transactions is done using a Pascal-like syntax.

The transactions that are executed by the virtual users, which are specified in the workload section, are defined using the keyword dcltrans.

Syntax

TransSection = Transaction { Transaction }.

Transaction  = "transaction" ident1 [ "(" TParList ")" ]
               [ "const" ConstDecl ]
               [ "var" VarDecl ]
               [ "result" "set" IdentList ";"]
               "begin" StatSeq "end" [ ident1 ] ";".

The name of a transaction (ident1) is defined after the keyword transaction. In TParList the input parameters of the transaction are specified. Random variables and constants are valid input parameters of a transaction.

ConstDecl contains the declarations of the transaction constants. These constants can be used only inside the transaction where they are defined (transaction scope).

In VarDecl the variables of the transaction are declared. These variables can be used only inside the transaction where they are declared. Variables of the simple types number, float, string and boolean are allowed. You can also declare arrays or lists of simple types (ARRAY [numberOfArrayElements] OF simpleType, LIST OF simpleType).

StatSeq contains the statements of the transaction.

Example

transaction TMain
  begin
    WebPageUrl("http://myHost/ShopIt/");
    ...
    // more functions that describe the tasks of this TMain transaction
    ...
    WebPageLink("Products");
  end TMain;

For database load testing only

IdentList defines the scrollable database cursors of the transaction. Cursors that are not scrollable must not be defined after the keywords result set; they are defined implicitly. Result-set cursors and scroll forward cursors cannot share the same names.

  • Characteristics of Transactions
    Lists the characteristics of transactions.
  • Parameters of Transactions
    Specify input parameters for a transaction to send constant values or random variables specific for a user to the transaction.
  • Lifetime and Scope of Variables
    Defines the life span for transaction, random, and global variables.
Parent topic: Program Structure of Load Testing Scripts


Characteristics of Transactions

The structure of a transaction is comparable to the structure of a procedure or function of a high-level programming language. Transactions have the following characteristics:
  • Nested block structure is possible
  • Variables of the native types number, float, boolean and string and arrays of simple types (array of number, array of float, array of boolean, array of string) can be used
  • Variables of a transaction have local scope (can only be used inside the transaction) but global life span
  • Transactions cannot call other transactions or themselves
  • Random variables or constants can be used as input parameters of transactions
  • A transaction has no output parameters
  • Full hierarchy of expressions applies with the usual rules of precedence
  • You can use if, while, for and loop statements for flow control
  • SQL commands/FORM commands are not declared in the transactions directly but in their own section (SQL section/FORM section) and are used like variables of special data types
  • Wait statements can be used for specifying user times
  • Random variables can be used for generating random values
Parent topic: Transactions Section
Related concepts
Lifetime and Scope of Variables
Related reference
Parameters of Transactions


Parameters of Transactions

You can specify input parameters for a transaction to send constant values or random variables specific for a user to the transaction. A transaction has no output parameters. Inside the transaction the input parameters are treated like random variables or constants. Therefore transaction parameters cannot be placed on the left side of assignments.

Syntax

TParList = TParam { ";" TParam }.

TParam   = IdentList ":" PType.

PType    = "string" "(" number ")"
         | "number"
         | "boolean"
         | "float".

TParlist contains the formal input parameters of the transaction. The identifiers in IdentList are parameters of type PType. Random variables returning type number, string, boolean or float and constants of these types are valid parameters of a transaction. Number, type and sequence of the actual parameters of a transaction (defined in the workload section) must correspond to number, type and sequence of the formal parameters of the transaction. Parameters of transactions are passed by reference.

If the actual parameter is a random variable, you must specify the type of the return value of the random variable (number, string, boolean or float), but not the type of the random variable (RndUniN, RndUniI, RndExpF,...), as the type of the formal parameter (PType). The length of the actual parameter must be less than or equal to the length of the formal parameter. If you omit a length specification for a formal parameter of type string, a string parameter of length 253 is defined.

Example

dclrand
  rArtNo1 : RndUniN(1..5000);
  rArtNo2 : RndUniN(5001..10000);

dcluser
  user
    User1
  transactions
    Selling(rArtNo1, "User1") : 100;

  user
    User2
  transactions
    Selling(rArtNo2, "User2") : 50;

dcltrans
  transaction Selling(pArtNo: number; pUser: string)
  var
    i : number init 1;
    j : array [20] of number;
    sName : string;
  begin
    ...
    j[i] := pArtNo;
    sName := pUser;
    ...
    i := i+1;
  end Selling;

The example shows a portion of a Silk Performer program. User1 assigns the actual parameters rArtNo1 (a random variable) and "User1" (a constant string) to the formal parameters pArtNo and pUser of the transaction Selling. User2 assigns the random variable rArtNo2 and the constant string "User2" to the formal parameters pArtNo and pUser of the transaction Selling. The parameter pArtNo is treated like a random variable. Therefore each time pArtNo is used, a new random value is generated.

Parent topic: Transactions Section
Related concepts
Characteristics of Transactions
Lifetime and Scope of Variables


Lifetime and Scope of Variables

Variables of a transaction are of local scope (they can be used only inside the transaction) but have a global life span (they are created at the beginning of a simulation and are destroyed at the end of the simulation; compare defining a static variable in a C function). Therefore transaction variables are initialized once and can hold their values over multiple calls of the transaction. Global variables are of global scope and global life span.

Random variables are of global scope (they can be used in any transaction, SQL command or workload description). The value of a random variable is refreshed each time the variable is used.

Note: Global variables are of global scope to the script where they are defined but of local scope to the users defined in the workload section of the script.
Parent topic: Transactions Section
Related concepts
Characteristics of Transactions
Related reference
Parameters of Transactions


Web Forms Section

Web forms are the most important interface to exchange data with the Web server. The forms section can easily be randomized and is used by WebForm functions.

The Web forms used by the transactions are defined using the keyword dclform.

The following simple example shows a portion of a Silk Performer program for simulating a form submission. Random variables rsEmail and rsPlatform (RndFile and RndInd) are defined in the random variables section using two different random functions. With each subsequent call to WebFormPost and WebFormGet, the random variables are refreshed and so contain new random values. These random values are used to generate the URL-encoded form string that is automatically sent within the request to the Web server. WebFormPost adds the form content string at the end of the HTTP header, while WebFormGet adds the form content string at the end of the URL separated by an "?".

Example

dclrand
  rsEmail    : RndFile("elname.rnd", 20);
  rsPlatform : RndInd("Windows NT" = 0.4;
                      "Windows 95" = 0.2
                      "Unix"       = 0.3;
                      "other"      = 0.1);

dcltrans
  transaction TWebFormPost
  begin
    WebFormPost("http://www.comp.com/cgi/FormMail.pl",
                CGI_CUST_SUPPORT);
    WebFormGet("http://www.comp.com/cgi/form",
                CGI_CUST_SUPPORT);
    WebThreadWait(WAIT_FORALLTHREADS);
  end TWebFormPost;

dclform
  CGI_CUST_SUPPORT:
    "email"     := rsEmail,
    "sitetype"  := "business",
    "sitelang1" := "english",
    "sitelang2" := "",
    "platform"  := rsPlatform;
  • Web Form Declarations
    Provides an overview of window form declarations including the form name, attributes, and form fields.
Parent topic: Program Structure of Load Testing Scripts
Related concepts
Syntax of Load Testing Scripts
Related reference
Script Structure Sample
WebFormPost Function
WebFormGet Function


Web Form Declarations

A form declaration consists of a form name with an optional form attribute and a list of form fields.

The form name can be any valid identifier string, for example FORM_NAME. If an attribute is specified, it must consist of an identifier within angle brackets, for example < ENCODE_ESCAPE >. The form name must be separated by a colon from the list of form fields.

The subsequent list specifies the fields of a web form or the parameters of a URL string. The string or variable on the left specifies the name of the field or parameter. An empty string is allowed for nameless URL parameters, such as image map coordinates. The right value specifies the data value of the field or parameter; this can be any expression with return type 'string', 'number' or 'float'.

The expression may use global constants, variables and random variables, BDL functions or external functions.

The list of form fields may be empty, resulting in an empty form. However, if you need an empty form, you can use the predefined empty form called FORM_NULL from the kernel.bdh include file.

Syntax

FormsSection     = { FormsDeclaration }.

FormsDeclaration = ident [ Attr ] ":"
                   [ FormItem { "," FormItem } ] ";".

FormItem         = FormItemName ":="
                   FormItemValue [ Attr ].

FormItemName     = FormExpression.

FormItemValue    = FormExpression.

FormExpression   = numeric expression | string expression

Attr             = "<" ( numeric expressionident ) ">".

Attributes

The optional attributes of a form or a form field must evaluate to a number value. While the compiler accepts any value, only those described herein have an effect. These values are named constants, defined in the kernel.bdh include file. Sometimes it makes sense to combine two or more attribute values using the bitwise-or operator '|'.

There are two groups of attributes: Usage attributes (only applicable for form fields in forms that are used context-full) and encoding attributes. Named constants for attributes are defined in the kernel.bdh include file.

Usage attributes:

Usage attributes specify how the form value in the script is combined with the value from the HTML form on a context-full form submission (WebPageSubmit function). If none of the usage attributes is specified, USE_SCRIPT_VAL is the default. This guarantees backward compatibility for scripts generated with older versions of Silk Performer. Usage attributes are mutually exclusive, meaning it makes no sense to combine two or more of them.
  • USE_SCRIPT_VAL (default): Specifies that the value given in the script must be used.
  • USE_HTML_VAL: Specifies that the value given in the form definition in the HTML form must be used. This is especially useful to make Silk Performer handle session IDs in (hidden) form fields automatically. You can still specify a form field value in the script, but this value is not used.
  • SUPPRESS: Specifies that a form field with the given name must not be submitted, even if the HTML form definition contains such a field. This allows using HTML forms for a WebPageSubmit function call even when the HTML form is not exactly identical to the form that should be submitted, and thus taking advantage of the attribute USE_HTML_VAL for other form fields. This is useful for modeling form submission that are done by client-side JavaScript, and form fields that are removed from a form prior to submitting it. Any field value specified in the script is not used.

Encoding attributes:

Encoding attributes specify how the unsafe characters in a field name or field value must be encoded. This is important to accommodate different encoding strategies used by different browsers in different situations.

Encoding attributes are mutually exclusive. It does not make sense to specify more than one for one form field.
  • ENCODE_FORM (default): This is the default and is used when none of the encoding attributes is specified. ENCODE_FORM encodes unsafe characters according to the mime type "application/x-www-form-urlencoded', see also RFC 1866, chapter 8.2.1. All popular browsers use this encoding for form submissions.
  • ENCODE_ESCAPE: This encodes unsafe characters according to the JavaScript function escape. The main difference to ENCODE_FORM is that blanks are encoded with "%20" instead of "+".
  • ENCODE_BLANKS: This encodes blanks to "%20". No other characters are encoded. Most browsers do this when a link is clicked.
  • ENCODE_NONE: No characters are encoded. This may be useful to accurately simulate applications where client-side Javascript performs HTTP requests without conforming to established standards.
  • ENCODE_CUSTOM: This is a configurable encoding type for special purposes. Use the WebFormDefineEncodeCustom function to specify how this encoding type encodes individual characters.
  • ENCODE_URICOMPONENT: This encodes unsafe characters according to the Microsoft JScript function encodeURIComponent. See http://msdn.microsoft.com/en-us/library/ie/aeh9cef7%28v=vs.94%29.aspx.

Attribute of a form vs. attribute of a form field

The encoding attribute of a form (as a whole) specifies the default-encoding attribute for form fields that have no encoding attribute on their own.

For example, if all form fields should use the attribute ENCODE_ESCAPE, you can specify this attribute after the form name. This encoding attribute is then used for all form fields. You can still override the encoding attribute for individual form fields by specifying another attribute for some fields.

Example

dclform
  CGI_CUST_SUPPORT:
    "email"         := "support@company.com",
    "platform"      := "Windows NT";
  AD_SERVER_PARAMS <ENCODE_NONE>:
    "~userpref"     := "12|34|56",
    "~requesttime"  := "01/01/2002";
  FORM_REDIR_LOGIN <ENCODE_NONE> :
    "~language"     := "EN",
    "~logingroup"   := "GUEST",
    "~transaction"  := "TEST",
    "~exitUrl"      := "http://www.myserver.com/
goodbye.html";
  SHOPIT_KINDOFPAYMENT:
    "choice"        := "Cash",
    "price"         := ""5.90 <USE_HTML_VAL> ,
    "paymentButton" := "" <USE_HTML_VAL> ;
  CGI_BIN_001:
    "BV_SessionID"  := "" <USE_HTML_VAL>,
    "BV_EngineID"   := "" <USE_HTML_VAL>,
    "TargetOID"     := "" <USE_HTML_VAL>;
  LOGIN_FORM_001:
    "username"      := "testuser" + string(GetUserId()),
    "password"      := "testpassword",
    "hash" := "" <USE_HTML_VAL_ENCODE_NONE>,
    "platform"      := "OS: Win2000, Browser: IE5.5,
Timezone: GMT-0300" <ENCODE_NONE>;
Parent topic: Web Forms Section
Related concepts
Low-Level Web Functions
Related reference
WebFormDefineEncodeCustom Function


SQL Section

The SQL commands that are called by the transactions are defined in the SQL section. They present the reusable component of the Silk Performer program. The SQL commands should already exhibit the form in which they will be used in the transaction of the application program.

Silk Performer supports stored procedures in test scripts. The syntax of defining a stored procedure in the SQL section is very similar to defining a SQL command.

The SQL section is defined using the keyword sql.

Syntax

SqlSection = SqlStatement ";" { SqlStatement ";" }.

SQLStatement = ( ident ":" SqlCommand )
             | ( ident "(" "proc" ")" ":" SqlProcedure ).

An SQL section can contain several definitions of SQL commands or stored procedures (SqlStatement). ident is the name of the SQL command (stored procedure) you are using when calling the SQL command in a transaction. SQLCommand is the current SQL statement in SQL syntax of your DBMS. Each SQL statement must be a valid SQL statement of your DBMS.

SqlProcedure describes the calling conventions for Stored Database Procedures that you want to use in your Silk Performer script. The syntax for calling a stored procedure in a transaction is the same as the syntax for calling a SQL command. You do not write the stored procedure directly in your Silk Performer program; instead you define a call to the stored procedure using ODBC syntax in your SQL section.

The following example shows a portion of a Silk Performer program for simulating a workload. Two random variables (randvar1 and randvar2) with two different random functions (RndUniN and RndStr) are defined in the random variables section. Two users (usr1 and usr2) are defined in the workload section. During a simulation time slice of 3600 seconds, usr1 calls the transaction Selling 100 times and the transaction Order 10 times. usr2 calls the transaction StockQuery 20 times during a simulation time slice of 2000 seconds.

Example

dclrand
  randvar1: RndUniN(1..1000);
  randvar2: RndStr("abcde1234"; 10..20);

dcluser
  user
    usr1
  transactions
    Selling : 100;
    Order   : 10;

  user
    User2
  transactions
    TStockQuery : 20;

The transactions Selling, Order and StockQuery are defined in the transactions section of the Silk Performer program. The transaction Selling calls the SQL command SelArticle and InsSale to access the test database of the application system to be simulated. A transaction can bind a global variable or a random variable to a SQL command (:v_artno). R values of the SQL command can be passed on to other SQL commands (into :v_name,:v_price,:v_agr).

Example

var
  I, v_artno, v_price : number;
  v_name, v_agr       : string;

dcltrans
  transaction TSelling
  begin
    ...
    for I := 1 to 5 do
      artno := randvar1;
      c1: SelArticle();
      c2: InsSale(...);
    end;
  end TSelling;

  transaction TOrder
  begin
    ...
  end TOrder;

  transaction TStockQuery
  begin
    ...
  end TStockQuery

The SQL commands used by the transactions SelArticle and InsSale are defined in the SQL section. Global variables (v_artno, v_name, v_agr and v_price) and random variables can be used in SQL text as bind variables (with a preceding ":").

Example

dclsql
  SelArticle:
    SELECT article_name, price, article_group
    INTO :v_name, :v_price , :v_agr
    FROM article WHERE artno = :v_artno;
    InsSale(...):
    ...
  • Support For Stored Procedures
    Provides an overview of stored procedure support and describes where to use them within a test script.
  • Binding Data (bind variables)
    Describes bind variables and where to use them within atestscript.
  • Dynamic SQL
    Expand your bind values at run time every time a SQL statement is called.
  • Setting SELECT Buffers (into variables)
    Describes how to receive data from a SQL select command by setting areas within the Silk Performer program that will receive the data.
  • Compatibility With ODBC Data Types
    Lists the data type mapping for Silk Performer data types, ODBC C data types, and ODBC SQL data types and describes when to use mapping.
  • Access Cycle of ODBC Functions
    Describes the sequence ODBC operations must be executed in to perform a SQL command in an ODBC application.
  • Optimized Access Cycle of Silk Performer
    Explains the optimized access cycle, where Silk Performer calls only ODBC functions that are absolutely necessary to perform the SQL commands.
  • User-Controlled Access Cycle of Silk Performer
    Describes how the reprepare, autocommit, and dynamic SQL parameters control the ODBC access cycle.
Parent topic: Program Structure of Load Testing Scripts
Related concepts
Syntax of Load Testing Scripts
Related reference
RndUniN Random Type (uniform distribution)
RndStr Random Type (alphanumeric values)
Calling SQL Commands
Commit Statement


Support For Stored Procedures

Silk Performer supports stored procedures in your Silk Performer programs. You can use in, out and in/out parameters in your stored procedures. Likewise you can use fetchable procedures that use fetch statements to get multiple-row results of the procedure (similar to select commands returning multiple rows using into variables and fetch statements). The syntax of calling a stored procedure in a transaction is the same as the syntax of calling a SQL command. The syntax of defining a stored procedure in the SQL section is very similar to defining a SQL command. You define stored procedures (more precisely, calls to stored procedures) in the SQL section of your Silk Performer program. You do not write the stored procedure directly in your Silk Performer program; instead you write stored procedures in the environment of your DBMS and only call the stored procedure inside your Silk Performer script using ODBC syntax.

Syntax

StoredProc = ident "(" "proc" ")" ":" SqlProc.

SqlProc = "{" [ bindvar "=" ] "call" ProcName
          [ BindVar [ "in" | "out" | "inout" ]
          { "," BindVar [ "in" | "out" | "inout"] } ] "}"
          [ "into" BindVar { "," BindVar } ].

BindVar = ":" ident.

ProcName = [ ident "." ] ident.

Example

var
  v1, v2, v3, v4, v5, v6: number;

dcltrans
  transaction TestProc
  begin
    v1 := 1; v2 := 2;
    c1: SpTest();
    while not eos(c1) do
      fetch c1 next 1;
    end;
  end TestProc;

dclsql
  SpTest(proc):
    { :v3=CALL MyProc(:v1 IN, :v2 INOUT, :v4 OUT) }
    INTO :v5, :v6;
Parent topic: SQL Section
Related concepts
Database (DBMS) Functions
User-Controlled Access Cycle of Silk Performer
Optimized Access Cycle of Silk Performer
Related reference
Binding Data (bind variables)
Dynamic SQL
Setting SELECT Buffers (into variables)
Access Cycle of ODBC Functions


Binding Data (bind variables)

In a SQL command, you can use a bind variable to represent the value of a column. A bind variable in a SQL command indicates that data will be bound to (associated with) the command each time the command executes. A bind variable in a SQL command must be associated (bound) to a random variable defined in the random variables section or to a global variable of the Silk Performer test script. The bind variable name begins with a colon (:) and is followed by the name of the random variable or global variable associated with it.

Example

var
  v1, v_price : number;

dclrand
  r1 : RndSno(1);
  r2 : RndInd("trousers"  = 0.3; "jackets" = 0.1;
              "pullovers" = 0.1; "shirts" = 0.1;
              "stockings" = 0.1; "skirts" = 0.1;
              "gloves"    = 0.2);
  r3 : RndStr(10..40);
  r4 : RndExpN(10..5000:500.0);
  r5 : RndUniN(1..500);
  r6 : RndUniN(10..50);

dcltrans
  transaction TMain
  begin
    ...
    c1: InsArticle(
    ...
    price := r4;
    g1 := r5;
    c1: UpdArticle();
    ...
  end TMain;

dclsql
  InsArticle:
    INSERT INTO article(articlenumber, articlegroup,
                        articlename, price, stock, quantity)
    VALUES(:r1, :r2, :r3, :r4, 20, 100);

  UpdArticle:
    UPDATE article
    SET price = :v_price * 0.9, quantity = :r6
    WHERE articlenumber = :g1;
Parent topic: SQL Section
Related concepts
Database (DBMS) Functions
User-Controlled Access Cycle of Silk Performer
Optimized Access Cycle of Silk Performer
Related reference
Support For Stored Procedures
Dynamic SQL
Setting SELECT Buffers (into variables)
Access Cycle of ODBC Functions


Dynamic SQL

If you want to expand your bind values at run time every time a SQL statement is called, you can use the following feature of Silk Performer. If a program variable starts with two colons, Silk Performer detects dynamic binding and does not call the ODBC function SQLBindParameter for this program variable. The value of the program variable is copied into the SQL statement at run time every time the statement is called.

Examples

The following is an example of Dynamic SQL:

SELECT * FROM article
WHERE a_no >= ::vAno AND a_cat like '::vCat'
for
vAno = 99
vCat = 'trousers'
expands to
SELECT * FROM article
WHERE a_no >= 99 AND a_cat LIKE 'trousers'

The following is an example of Normal Binding:

SELECT * FROM article
WHERE a_no >= :vAno AND a_cat LIKE :vCat
expands to
SELECT * FROM article
WHERE a_no >= ? AND a_cat LIKE ?
plus two additional calls to the ODBC function SQLBindParameter.
Parent topic: SQL Section
Related concepts
Database (DBMS) Functions
User-Controlled Access Cycle of Silk Performer
Optimized Access Cycle of Silk Performer
Related reference
Support For Stored Procedures
Binding Data (bind variables)
Setting SELECT Buffers (into variables)
Access Cycle of ODBC Functions


Setting SELECT Buffers (into variables)

To be able to receive data from a SQL select command, you must set the areas within the Silk Performer program that will receive that data. These areas are called into variables. You must specify the into variables in the into clause of a SQL select command. An into variable in a SQL command must be associated with (bound to) a global variable. Into variable names begin with a colon (:) and are followed by the name of the corresponding global variable.

If certain columns specified in the select clause of the SQL select command will not be used in your transaction, you can use asterisks (*) instead of into variables to receive the values of these columns. Columns associated with an asterisk will be received in a special buffer of Silk Performer. You cannot use this buffer inside your transactions. Asterisks serve the purpose of place holders. You must not omit them, because you want to simulate and measure the performance of your final system. The number of into variables and asterisks in the into clause must match with the number of columns in the select clause of the SQL command.

The into clause of a select statement can be omitted if the Silk Performer program does not process result values. In this case all values of the select list are automatically bound to the internal buffer of Silk Performer.

Example

dclrand
  rArtNo: RndUniN(1..500);

var
  v_artno, v_stock, v_quant: number;

dcltrans
  transaction TMain
  begin
    v_artno := rArtNo;
    c1: SelArticle();
    if v_stock < v_quant then
      ...
    end
  end TMain;

dclsql
  SelArticle:
    SELECT articlename, articlegroup, quantity, stock
    INTO *, *, :v_quant, :v_stock
    FROM article WHERE articlenumber = :v_artno;

The example above shows the SQL SELECT command SelArticle selecting the database columns articlename, articlegroup, quantity and stock. The database columns articlename and articlegroup are associated with (bound to) with the Silk Performer data buffer (*) because their values will not be used in the transaction calling the SQL command. The database columns quantity and stock are associated with the into variables :v_quant and :v_stock.

Parent topic: SQL Section
Related concepts
Database (DBMS) Functions
User-Controlled Access Cycle of Silk Performer
Optimized Access Cycle of Silk Performer
Related reference
Support For Stored Procedures
Binding Data (bind variables)
Dynamic SQL
Access Cycle of ODBC Functions


Compatibility With ODBC Data Types

You can use the Silk Performer data types number, float and string to exchange values between a Silk Performer program and your DBMS. Silk Performer uses the following default data type mapping for Silk Performer data types, ODBC C data types, and ODBC SQL data types.

Silk Performer data type | ODBC C data type | ODBC SQL data type
number | SQL_C_LONG | SQL_INTEGER
float | SQL_C_DOUBLE | SQL_FLOAT
string <= 254 | SQL_C_CHAR | SQL_CHAR
string > 254 | SQL_C_CHAR | SQL_LONGVARCHAR

Silk Performer uses this mapping for binding input values into values with the ODBC functions SQLBindParameter and SQLBindCol.

You can use the Silk Performer data type number for associating with any numeric data types of your DBMS. The Silk Performer data type number represents integer values. Therefore floating-point values received from a DBMS data type like number, decimal, float or real are rounded to an integer value. To avoid this, you should bind numeric DBMS data types that are noninteger to the Silk Performer data type float.

You can use the Silk Performer data type string for associating with any numeric and non-numeric data type of your DBMS (for example., DATE data types). You need only assure that the values you want to exchange correspond to the type and length requirements of the Silk Performer and the DBMS data type. You can also associate any DBMS data type to the Silk Performer data buffer.

Parent topic: SQL Section


Access Cycle of ODBC Functions

To perform a SQL command in an ODBC application, the following sequence of ODBC operations must be executed:

  1. Connect to the data source (ODBC functions SQLAllocEnv,SQLAllocConnect, SQLConnect)
  2. Allocate a cursor/statement handle (ODBC function SQLAllocStmt)
  3. Prepare the SQL command (ODBC function SQLPrepare, orSQLExecDirect for direct prepare and execute)
  4. Bind program data to SQL data (ODBC functions SQLBindParameter for binding parameter markers to program data and SQLBindCol for binding selected columns to program data)
  5. Execute the SQL command (ODBC function SQLExecute orSQLExecDirect for direct prepare and execute)
  6. Fetch rows if the SQL command is a select (ODBC function SQLFetch or SQLExtendedFetch for scrollable cursors)
  7. Commit or roll back the transaction (ODBC function SQLTransact)
  8. Free the cursor/statement handle (ODBC function SQLFreeStmt)
  9. Disconnect from the database (ODBC functions SQLDisconnect, SQLFreeConnect, SQLFreeEnv)

The main steps in performing a SQL command are: connect to the database, prepare the SQL command, execute the SQL command, fetch the results if it is a SQL select command, and disconnect from the database.

To perform a SQL command repeatedly or to perform multiple SQL commands, it is not necessary (and not appropriate) to execute all operations listed above every time you want to perform a SQL command. The sequence of the ODBC functions for performing SQL commands repeatedly is called the access cycle of ODBC functions.

Parent topic: SQL Section
Related concepts
Database (DBMS) Functions
User-Controlled Access Cycle of Silk Performer
Optimized Access Cycle of Silk Performer
Related reference
Support For Stored Procedures
Binding Data (bind variables)
Dynamic SQL
Setting SELECT Buffers (into variables)


Optimized Access Cycle of Silk Performer

To perform a SQL command in a Silk Performer program, all you have to do is to call the SQL command at the position in the program where you want to execute it. Silk Performer manages all operations (ODBC function calls) necessary to process the SQL command for you. By default, Silk Performer uses an optimized access cycle (calling only ODBC functions that are absolutely necessary to perform the SQL commands).

Silk Performeruses the following access cycle of ODBC function calls:

The connection to the database is established once at the beginning of a simulation and is closed at the end of a simulation. Also, all cursors/statement handles used in a simulation are allocated at the beginning of the simulation and are freed at the end of the simulation. At the end of a transaction Silk Performer automatically performs a commit. A SQL command is prepared only if it is not already active on the related cursor (the related cursor is the cursor that preceded the call of the SQL statement).

A SQL command is active on a cursor if:

  • it already has been prepared on the same cursor

(and)

  • no other SQL command has been prepared and executed on the same cursor in the meantime.

(and)

  • there was no commit or rollback statement between the current call of the SQL command and the last call

(or)

  • there was a commit or a rollback and the two options of the DBMS are set to SQL_CB_CLOSE or SQL_CB_PRESERVE.
    • SQL_CURSOR_COMMIT_BEHAVIOR (and)
    • SQL_CURSOR_ROLLBACK_BEHAVIOR

Silk Performer is designed to remove ODBC overhead that could skew actual results on the database under test.

  • Cursor Behavior
    Describes how Silk Performer determines whether the SQL statement has to be prepared before it can be executed.
Parent topic: SQL Section
Related concepts
Database (DBMS) Functions
User-Controlled Access Cycle of Silk Performer
Related reference
Support For Stored Procedures
Binding Data (bind variables)
Dynamic SQL
Setting SELECT Buffers (into variables)
Access Cycle of ODBC Functions


Cursor Behavior

Silk Performer queries the cursor behavior of the DBMS to which it is connected, in order to be able to decide whether the SQL statement has to be prepared before it can be executed.

  • SQL_CURSOR_COMMIT_BEHAVIOR indicates how a commit operation affects cursors and prepared statements.
  • SQL_CURSOR_ROLLBACK_BEHAVIOR indicates how a rollback operation affects cursors and prepared statements.
  • SQL_CB_DELETE (0) indicates that the DBMS closes cursors and deletes prepared SQL statements. To use the cursor again, the application must reprepare and re-execute the SQL statement.
  • SQL_CB_CLOSE (1) indicates that the DBMS closes cursors. For prepared SQL statements, the application can execute the SQL statement without repreparing it.
  • SQL_CB_PRESERVE (2) indicates that the DBMS preserves cursors. The application can continue to fetch data or it can close the cursor and reexecute the SQL statement without re-preparing it.

For a detailed description of SQL_CURSOR_COMMIT_BEHAVIOUR and SQL_CURSOR_ROLLBACK_BEHAVIOUR, see your ODBC documentation.

Parent topic: Optimized Access Cycle of Silk Performer


User-Controlled Access Cycle of Silk Performer

You can control the ODBC access cycle of Silk Performer with the following parameters:

Reprepare

The reprepare parameter can be enabled/disabled in the Silk Performer ODBC settings (menu Settings/ODBC Settings/Reprepare SQL commands). If the reprepare parameter is enabled, Silk Performerprepares a SQL statement (using the ODBC function SQLPrepare) every time it is called, regardless of whether it is active. The setting of reprepare is effective over the whole Silk Performer script. On default the reprepare parameter is disabled.

Autocommit

The autocommit parameter can be enabled/disabled in the Silk PerformerODBC settings (menu Settings/ODBC Settings/Auto commit). If the autocommit parameter is enabled, the database is committed automatically after each SQL command. Otherwise, the database is committed only after an explicit commit statement or at the end of a Silk Performer transaction. The parameter setting is effective over the whole Silk Performer script.

Dynamic SQL

If you are using a dynamic SQL statement, Silk Performer uses the ODBC function SQLExecDirect to execute the SQL statement instead of using SQLPrepare and SQLExecute. For how to use dynamic SQL in Silk Performer, see Dynamic SQL.

Parent topic: SQL Section
Related concepts
Database (DBMS) Functions
Optimized Access Cycle of Silk Performer
Related reference
Support For Stored Procedures
Binding Data (bind variables)
Dynamic SQL
Setting SELECT Buffers (into variables)
Access Cycle of ODBC Functions


Expressions

An expression is a combination of constants, variables, random variables, functions, parentheses and operators that yields a single value. Silk Performer distinguishes among the following expressions:

  • Relational expressions
  • Boolean expressions
  • Numeric expressions
  • String expressions

The following special Silk Performer functions can be used in expressions:

  • Type conversion functions (chr, ord, string, number, float)
  • High-level database functions (rows, rc, eos)
  • Random types (RndUniN)
  • Operators
    Provides an overview of operators and lists the operator symbols, types, and types of operands.
  • Increment and Decrement Operators
    Describes the increment (--) and decrement (++) operators, which are supported for number varibles.
  • Precedence Rules
    Describes the precedence rules that apply to operators used in Silk Performer test scripts.
  • Concatenate Operator
    Use the + operator to concatenate strings and single characters.
  • Valid Expressions
    Lists the expressions that are valid for use in Silk Performer test scripts.
Parent topic: Program Structure of Load Testing Scripts


Operators

An operator is a symbol or word that represents an operation to be performed on one or more values.

Operator symbol | Operator type | Type of operands
+ - * / | numeric | number, float
| | bitwise or | number
& | bitwise and | number
mod | numeric | number
= <> > < >= <= | relational | number, string, char, boolean, float
and or not | boolean | boolean
+ | concatenate string | string, char, number, float, boolean
  • The operands of an operator must be of the same data type. Operands are casted automatically for string concatenations.
  • mod is the Modulo operator. The left operand of the mod operator is the dividend; the right operand is the divisor.
  • You cannot use arrays without an index in an expression.
  • Expressions with multiple and operators (or or operators) are evaluated from left to right. Evaluation for and/or stops as soon as the result is known.
Parent topic: Expressions
Related reference
Precedence Rules


Increment and Decrement Operators

For number variables, BDL supports an increment (--) and a decrement (++) operator. The increment operator increases a number by one, the decrement operator decreases a number by one.

Syntax

Stat = ident [ "[" Expr2 "]" ] [ "++" | "--" ] .

Example

transaction demo
var
  i : number init 2;
begin
  i++; // i is now 3
  i--; // i is now 2
end;
Parent topic: Expressions


Precedence Rules

The following precedence rules apply to operators used in Silk Performer test scripts:

  • *, /, MOD are evaluated before +,-.
  • AND is evaluated before OR.
  • *, /, MOD, +, -, AND, OR, NOT are evaluated before relational operators.
Parent topic: Expressions
Related reference
Operators


Concatenate Operator

You can use the + operator to concatenate strings, single characters, numbers, floats and boolean values.

Example

var
sString : string;
sString1, sString2 : string;
i : number init 42;
f : float init 23.5;
b : boolean init true;

begin
sString1 := "The ";
sString2 := "sun ";
sString  := sString1 + sString2 + "is " + "r" + 'I' +
            's' + "ing" + '.';
write(sString); writeln;
writeln("number: " + i);
println("float: " + f);
println("boolean: " + b);

end;

Output

The sun is rising.
number: 42
float: 23.50000
boolean: TRUE
Parent topic: Expressions


Valid Expressions

The following types of expression are valid in Silk Performer test scripts:

I > j
I <> p1
j >= r1

I * j = p1
I * j + 1

I mod j + 1
j / (I + k)

b1 = (I < j)
(I <= j) and b1 or not (b2 or b1)
((k+I*(I+1))/(k+k*a[2]))/199 <> (k+I*(j+1))/j-j

s1 = s2
s1[i] => s2[j+1]
as[2] = s2
as[3] = "tomorrow"
as[4] = r2
s1[1] = chr(r1)

ord(chr(r1))
ord(s1[a[i]])
ord('a') + 10
chr(ord('a'))

s1 + as[i] + r1 + "yesterday" + ';'
Parent topic: Expressions


Statements

Just as high-level programming languages do, Silk Performer offers statements for expressing sequences, selections, and iterations. The following statements are available:

  • Assignments
  • If statement
  • While statement
  • For statement
  • Loop statement
  • Exit statement
  • Return statement
  • Write statement

Special simulation statements

  • Wait statement
  • Halt statement
  • Throw statement

Database access statements

  • SQL call
  • Commit statement
  • Rollback statement
  • Fetch statement
  • Sequence of Statements
    Describes a sequence of statements.
  • Assignments
    Assigns a value (Expr1) to a variable (Ref) of a transaction.
  • Exit Statement
    Terminates the loop (while, for, or loop) in which it is directly nested.
  • For Statement
    Acts as a loop that repeats the statements in StatSeq until Ident is greater than Expr2.
  • If Statement
    Expresses branches.
  • Loop Statement
    Repeats the statements enclosed between loop and end until an exit or a return statement is executed.
  • Return Statement
    Terminates the execution of a transaction or the simulation of the user executing the current transaction.
  • Throw Statement
    Terminates the execution of an event handler function by passing execution control to the runtime system.
  • While Statement
    Acts as a loop that repeats the statements in StatSeq until the expression Expr becomes false.
  • Write Statement
    Outputs the value of Expr1 with field width Expr2 and precision Expr3 to the WRT file of the user executing the write statement.
  • Database Server Access Statements
    Lists the database server access statements and provides access to the related background information.
  • Special Simulation Statements
    Lists the special simulation statements that Silk Performer supports.
Parent topic: Scripting Language Structure and Statements


Sequence of Statements

A transaction consists of several statements. Statements are separated by semicolons and can be empty.

Syntax

StatSeq = Stat { ";" Stat }.

Example

dcltrans
  transaction TInit
  var
    bOk: boolean;
  begin
    write("initializing..."); writeln;
    bOk := InitBuffer(512);
    if bOk then
      writeln("successfully initialized")
    else
      writeln("failure")
    end
  end TInit;

Output

initializing...
successfully initialized
Parent topic: Statements


Assignments

The assignment statement assigns a value (Expr1) to a variable (Ref) of a transaction. If the variable is an array, you must reference the element of the array via an index. You can only assign elements of an array, not the whole array. If the variable is a string, you can assign single characters to the string by referencing the string variable via an index.

Syntax

Stat = Ref ":=" Expr1 .
Ref  = ident [ "[" Expr2 "]" ] .

For numerical variables additional assignment operators are allowed:

Stat = Ref [ "+=" | "-=" | "*=" | "/=" ] Expr1 .
Ref = ident [ "[" Expr2 "]" ] .

Example

The following assignments are valid:

dclrand
  r1 : RndUniN(0..255);
  r2 : RndStr(2..10);
  ...

dcltrans
  transaction t1(p1: number):
  var
    i, j, k : number init 1;
    a       : array[10] of number;
    b1, b2  : boolean;
    s1      : string(20);
    s2      : string(10);
    as      : array [5] of string(14);
    f       : float init 1.0;

  begin
    a[1] :=1;
    i := i*j+1;
    k := i modj+1;
    i := j/(i+k);
    i := ((k+i*(i+1))/(k+k*a[2]))/199;
    j := -j;
    i := ord(chr (r1));
    j := ord(s1[a[i]]);
    k := ord('a')+10;
    a[i] := p1;
    b2 := true;
    b1 := i>j;
    b2 := i<>p1;
    b1 := j>=r1;
    b2 := i*j=p1;
    b2 := b1=(i<j);
    b1 := (i<=j) and b1 or not (b2 or b1);
    s1 := s2;
    s2 := r2;
    s1[i] := s2[j+1];
    s2[10] :='x';
    as[2] := s2;
    as[3] :="Silk Performer";
    as[4] := r2;
    s1[1] :=chr(r1);
    s1[1] :=chr(ord('a'))

    j += 2; // is the same as j := j + 2;
    j -= 2; // is the same as j := j - 2;
    j *= 2; // is the same as j := j * 2;
    j /= 2; // is the same as j := j / 2;

    f += 2.0; // is the same as f := f + 2.0;
    f -= 2.0; // is the same as f := f - 2.0;
    f *= 2.0; // is the same as f := f * 2.0;
    f /= 2.0; // is the same as f := f / 2.0;

  end t1;
Parent topic: Statements
Related reference
Sequence of Statements


Exit Statement

Terminates the loop (while, for, or loop) in which it is directly nested.

Syntax

Stat = "exit".

Example

dcltrans
  transaction TInit
  var
    I : number;
    a : array[100] ofnumber;
  begin
    I := 1;
  loop
    a[i] := I;
    if I = 100 then exit end;
    I := I+1
    end;
  end TInit;
Parent topic: Statements
Related reference
Sequence of Statements


For Statement

Acts as a loop that repeats the statements in StatSeq until Ident is greater than Expr2. Expr1 and Expr2 are expressions of type number. Ident is a variable of type number. The first time the loop is entered, Ident is set to Expr1. Ident is incremented by 1 each time the loop is executed. Expr2 is only evaluated the first time the loop is entered.

Syntax

Stat = "for" [Ident | "var" Ident] ":=" Expr1 "to" Expr2 "do" StatSeq "end".

The for loop is equivalent to the following while loop:

Example

dcltrans
  transaction t1
  const
    MAX_IND := 100;
  var
    I : number;
    a : array [MAX_IND] of number;
  begin
    ...
    for I := 1 to MAX_IND do
      a[i] := i;
    end;
  end t1;
Parent topic: Statements
Related reference
Sequence of Statements


If Statement

Expresses branches. If Expr1 is true, SatSeq1 is executed; otherwise, if Expr2 is true, StatSeq2 is executed; if none of the expressions in the if statement is true, StatSeq3 is executed. Multiple elseif parts are allowed. The elseif part and the else part of the if statement are optional.

Syntax

Stat = "if" Expr1 "then" StatSeq1
       { "elseif" Expr2 "then" StatSeq2 }
       [ "else" StatSeq3 ]
       "end".

Example

dcltrans
  transaction TMain
  var
    I, j : number;
    a, b : boolean;
  begin
    if b then
      I := I+1;
      j := j*2
    elseif a then
      I := I-1
    else
      I := I-2
    end;

    if (I < j) and not b then
      b := true;
    end;
  end TMain;
Parent topic: Statements
Related reference
Sequence of Statements


Loop Statement

Repeats the statements enclosed between loop and end until an exit or a return statement is executed.

Syntax

Stat = "loop" StatSeq "end".

Example

dcltrans
transaction TCount
var
  i: number;
begin
  I := 0;
  loop
  if I >= 3 then exit end;
    I := I+1;
    write("hello world! "); write(I); writeln;
end;
end TCount

Output

hello world! 1
hello world! 2
hello world! 3
Parent topic: Statements
Related reference
Sequence of Statements


Return Statement

Terminates the execution of a transaction or the simulation of the user executing the current transaction. In conjunction with the execution of a return statement, Silk Performer executes a commit of the transaction unless a rollback was executed before when using Silk Performer's high-level database functions (implicitly, for example, because of a deadlock or explicitly because of a rollback statement in the transaction).

Executing a return statement in a Silk Performer function has the same effect: it terminates the transaction from which the function was called and not only the function itself.

Syntax

Stat = "return" [ ( number | "(" number ")"].

  • If number is 0, the termination status of the transaction is set to OK. The current transaction is terminated.

  • If number is 1, the termination status of the transaction is set to CA (=canceled). The current transaction is terminated.

  • If number is 2, the transaction will not be considered in the result report. The current transaction is terminated and the simulation of the user will be stopped immediately (equivalent to a halt statement).

Example

dcltrans
  transaction TMain
  var
    I : number;
    a : array [100] of number;
    badEvent : boolean;
  begin
    ...
    if badEvent then
      rollback;
      return 1
    end;

    I := 1;
    loop
    a[i] := I;
    if I=100 then return end;
      I := I+1
    end;
  end TMain;
Parent topic: Statements
Related reference
Sequence of Statements


Throw Statement

Terminates the execution of an event handler function by passing execution control to the runtime system. The runtime system continues with the default procedure for the event.

The throw keyword is only allowed in event handler functions. If the throw semantics is not applicable in a handler when called as a function, it finishes handler code execution.

Syntax

Stat = "throw".

Example

dclevent
  handler Handler1 <EVENT_RAISE_ERROR>
  begin
    if GetLastError() = 317 then
      writeln("Error 317 caught");
    else
      throw;
    end;
  end Handler1;

dcltrans
  transaction TestTrans
  begin
    ...
  end TestTrans;
Parent topic: Statements
Parent topic: Runtime Functions
Related concepts
Characteristics and Limitations of Event Handler Functions
Related reference
Sequence of Statements
Event Handler Section


While Statement

Acts as a loop that repeats the statements in StatSeq until the expression Expr becomes false.

Syntax

Stat = "while" Expr "do" StatSeq "end".

Example

dcltrans
transaction TMain
var
I : number;
a : array [100] of number;
begin
I := 1;
while I <= 100 do
a[i] := I;
I := I+1
end;
end TMain;
Parent topic: Statements
Related reference
Sequence of Statements


Write Statement

Outputs the value of Expr1 with field width Expr2 and precision Expr3 to the WRT file of the user executing the write statement. You can write expressions of type string, char, float or number. Specification of the field width and the precision is optional. The precession argument (Expr3) is only valid for floating-point values; it is a non-negative integer that specifies the number of decimal places to be printed. If the number of characters in the output value is greater than the width specification, output values of type string are truncated. Output values of type string and char are printed left-justified. Output values of type number and float are printed right-justified.

The writeln statement advances to a new line in the output file.

Syntax

Stat = "write" "(" Expr1 [ "," Expr2 [ ","Expr3 ] ] ")"
| "writeln" [ "(" Expr1 [ "," Expr2 [ ","Expr3 ] ] ")" ].

Example

dcltrans
  transaction TMain
  var
    I : number;
    a : array [10] of float;
  begin
    for I := 1 to 10 do
      a[i] := float(I)+0.5;

      if I mod 5 = 1 then
        writeln;
        write("Array a["); write(I, 2); write(" to ");
        write(I+4, 2); write("]: ");
      end;

      write(a[i], 6, 1);
    end;
  end TMain;

Output

Array a[ 1 to 5]: 1.5 2.5 3.5 4.5 5.5
Array a[ 6 to 10]: 6.5 7.5 8.5 9.5 10.5
Parent topic: Statements
Parent topic: Logging Functions Overview
Related concepts
Output Files
Related reference
Sequence of Statements


Database Server Access Statements

Silk Performer supports the following database server access statements:

  • Commit statements
  • Rollback statements
  • Fetch statements
  • Calling SQL Commands
    Explains how Silk Performer calls SQL commands.
  • Database Cursors
    Provides an overview of when database cursors are used.
  • Result Set Cursors (scrollable cursors)
    Declare a cursor for result set mode operation.
  • Commit Statement
    Performs a SQL commit command inside a transaction.
  • Rollback Statement
    Performs a SQL rollback command inside a transaction.
  • Fetch Statements
    Describes how Fetch statements work with result sets.
  • Querying the State of Database Operations
    Lists the functions for querying the state of database operations.
Parent topic: Statements


Calling SQL Commands

SQL commands are not embedded directly in the body of a transaction. In Silk Performer they are called like procedures. Silk Performer uses a calling mechanism for SQL commands that is quite similar to the calling mechanism of procedures in a high-level programming language like Pascal. To exchange values with SQL commands, you can use global variables or random variables.

Syntax

SQLCall = Ident1 ":" Ident2.

Ident1 is the name of the database cursor that the SQL command uses (for more information about database cursors, see Database cursors). Ident2 is the name of the SQL command that is declared in the SQL section of the .bdf file.

Example

dclrand
  rArtNo: RndUniN(1..1000);

var
  v_artno, v_stock, v_quantity: number;

dcltrans
  transaction TMain
  begin
    v_artno := rArtNo;
    c1: SelArticle();
    if v_stock = 0 then
      c2: InsOrder();
    end
  end TMain;

dclsql
  SelArticle:
  SELECT stock,quantity
  INTO :v_stock, :v_quantity
  FROM article
  WHERE articlenumber = :v_artno;
  InsOrder:
  INSERT INTO order(articlenumber, quantity)
  VALUES(:v_artno, :v_quantity);

The example above shows a portion of a Silk Performer program focusing on the use of SQL in Silk Performer. Transaction t1 calls the SQL command named SelArticle. SelArticle uses the database cursor named c1. The SQL command SelArticle is declared in the SQL section of the Silk Performer program. The global variable v_artno is used as a bind variable in the SQL command. The global variables v_stock and v_quantity are used as INTO variables (INTO :v_stock, :v_quantity) in the SQL command.

If the value of stock retrieved is equal to zero (0), the transaction executes the SQL command InsOrder using the global variables v_artno and v_quantity as bind variables. InsOrder uses the database cursor named c2.

Parent topic: Database Server Access Statements
Related concepts
Syntax of Load Testing Scripts
Related reference
SQL Section


Database Cursors

Database cursors are used in Silk Performer for the following tasks:

  • Establishing a connection to a database

  • Relating SQL commands to a database connection

  • Querying the results of database operation

  • Fetching result sets (scrollable cursors)

CURRENT-OF cursor operations

Database cursors as used in Silk Performer are equivalent to ODBC statement handles; we use the terms synonymously.

You need not declare a database cursor explicitly. Cursors are declared implicitly by using the cursor. The scope of a cursor is global. Transactions share cursors with identical names.

You cannot use the name of a cursor defined as a result-set cursor in any transaction other than a scroll forward cursor.

Silk Performer establishes as many ODBC statement handles to the database(s) as database cursors are applied by the transactions of the user.

Parent topic: Database Server Access Statements
Related reference
Result Set Cursors (scrollable cursors)
SQL Section


Result Set Cursors (scrollable cursors)

Direct positioning requires the cursor used with the query to be set to result-set mode (also called scroll mode). You can declare a cursor for result set mode operation as follows:

Example

dcltrans
  transaction TMain
  var
    i: number;
    result set c1;
  begin
    ...
    c1: SelArticle();
    ...
  end TMain;

If you are using result-set cursors in your Silk Performer script, the corresponding statement handles will be set with the ODBC function SQLSetStmtOption, thereby setting the options SQL_CONCURRENCY and SQL_CURSOR_TYPE. The values for these options are read from your ODBC settings (menu Settings/ODBC Settings).

Valid values for SQL_CONCURRENCY are:

  • SQL_CONCUR_READONLY: Read Only Cursor.

  • SQL_CONCUR_LOCK: Cursor uses the lowest level of locking.

  • SQL_CONCUR_ROWVER: Cursor uses optimistic concurrency control, comparing row versions (for example, ROWID).

  • SQL_CONCUR_VALUES: Cursor uses optimistic concurrency control, comparing values.

Valid values for SQL_CURSOR_TYPE are:

  • SQL_CURSOR_FORWARD_ONLY: The cursor only scrolls forward.

  • SQL_CURSOR_KEYSET_DRIVEN: The driver saves and uses the keys for the rows in the entire result set.

  • SQL_CURSOR_DYNAMIC: The driver saves and uses the keys for the rows in the row set; the row set size is 1.

  • SQL_CURSOR_STATIC: The data in the result set is static.

For result-set cursors, Silk Performer uses the ODBC function SQLExtendedFetch instead of SQLFetch for scrolling the result set.

Parent topic: Database Server Access Statements
Related concepts
Database Cursors
Database (DBMS) Functions
Related reference
SQL Section


Commit Statement

Performs a SQL commit command inside a transaction. You need not specify a commit statement at the end of a transaction because Silk Performer automatically executes a SQL commit at the end of a transaction. The commit statement permanently sets all changes to the database since the last commit; you cannot undo these changes with a rollback statement (just as you cannot rollback committed statements with any databases using native tools). The commit statement commits the work of all cursors (statement handles) that the transaction has connected to the database.

If you use a commit statement inside a transaction, you will not be able to undo (roll back) the whole transaction. Depending on the capabilities of your DBMS, result sets may be destroyed after a commit, and subsequent execution of a fetch statement without reselecting will cause an error.

Syntax

Stat = "commit".

Example

dclrand
  rArtNo: RndUniN(1..1000);

var
  v_artno, v_stock, v_quantity: number;

dcltrans
  transaction TMain
  begin
    v_artno := rArtNo;
    c1: SelArticle();
    if v_stock = 0 then
       c2: InsOrder();
    end;

    commit;
  end TMain;

dclsql
  SelArticle:
  SELECT stock,quantity
  INTO :v_stock, :v_quantity
  FROM article
  WHERE articlenumber = :v_artno;
  InsOrder:
  INSERT INTO order(articlenumber, quantity)
  VALUES(:v_artno, :v_quantity);
Parent topic: Database Server Access Statements
Related concepts
Database (DBMS) Functions
Related reference
Calling SQL Commands


Rollback Statement

Performs a SQL rollback command inside a transaction. The rollback statement rolls back all work done since the last SQL commit command for all cursors that the transaction has connected to the database.

Depending on the capabilities of your DBMS, result sets may be destroyed after rollbacks and subsequent execution of a fetch statement without reselecting will cause an error.

Syntax

Stat = "rollback".

Example

dclrand
rArtNo: RndUniN(1..1000);
var
v_artno, v_stock, v_quantity: number;
dcltrans
transaction TMain
begin
v_artno := rArtNo;
c1: SelArticle();
if v_stock = 0 then
c2: InsOrder();
end;
rollback;
end TMain;
dclsql
SelArticle:
SELECT stock,quantity
INTO :v_stock, :v_quantity
FROM article
WHERE articlenumber = :v_artno;
InsOrder:
INSERT INTO order(articlenumber, quantity)
VALUES(:v_artno, :v_quantity);
Parent topic: Database Server Access Statements
Related concepts
Database (DBMS) Functions
Related reference
SQL Section


Fetch Statements

A result set (or result table) is a set of table rows that is produced by a query (SQL SELECT command). Fetch statements are used to work with result sets. After the execution of a query in Silk Performer (the call of a SQL SELECT command), the result set is formed and the current position in the result set (cursor position) is set to the first row. We distinguish between two classes of fetch statements:

Fetch statements for sequentially fetching:

  • Fetch next
  • Fetch all

Fetch statements for direct positioning:

  • Fetch row
  • Fetch set
  • Fetch last
  • Fetch-All Statement
    Fetches all rows of a result set starting from the current row position in the result set and moving sequentially forward, and sets the row position behind the last row (eos condition is true).
  • Fetch-Next Statement
    Fetches sequentially forward beginning at the current position (cursor position) in the result set and sets the cursor position to the last row fetched.
  • Fetch-Last Statement (for scrollable cursors)
    Sets the current row position of the result set to the last row fetched by a previous sequential fetch-next statement.
  • Fetch-Row Statement (for scrollable cursors)
    Sets the row position of the result set to the position indicated by Expr and fetches the row.
  • Fetch-Set Statements (for scrollable cursors)
    Sets the row position to a randomly selected position within the set of rows actually fetched by fetch-next or fetch-last statements.
  • Expr Option
    Restrict the number of rows to be fetched to Expr rows.
  • Unique Option
    Ensures that no row will be fetched twice by the same fetch-set statement.
Parent topic: Database Server Access Statements
Related concepts
Database (DBMS) Functions
Related reference
Calling SQL Commands
Result Set Cursors (scrollable cursors)
SQL Section


Fetch-All Statement

Fetches all rows of a result set starting from the current row position in the result set and moving sequentially forward, and sets the row position behind the last row (eos condition is true). Ident is the name of the cursor used for the corresponding SQL SELECT command.

Syntax

Stat = "fetch" Ident "all".

Example

var
sArtname : string;
nArtno, nPrice : number;
dcltrans
transaction TMain
begin
c1: SelArticle();
fetch c1 all;
end TMain;
dclsql
SelArticle:
SELECT articlenumber, price, name
INTO :nArtno, :nPrice, :sArtname
FROM article WHERE price > 100
ORDER BY price DESC;

After execution of the SQL command SelArticle, a result set is created containing all articles where the price is greater than 100. The row position is set to the first row in the result set. At this time the values of the first row are bound to the variables v_artno, v_price and v_artname. The fetch c1 all statement fetches all rows of the result set sequentially forward starting from the current row position. The eos condition for the cursor used for the result set is set to true.

Parent topic: Fetch Statements
Related concepts
Database (DBMS) Functions
Related reference
SQL Section


Fetch-Next Statement

The fetch-next statement fetches sequentially forward beginning at the current position (cursor position) in the result set and sets the cursor position to the last row fetched. After the execution of a query (SQL SELECT command), the cursor position is set to the first row of the result set. Ident is the name of the cursor used with the respective SQL SELECT command. Expr is an integer expression that specifies the number of rows to be fetched sequentially. If no more rows can be fetched, the eos condition (end of selection) is set for the cursor used in the fetch statement.

Note: To fetch the first row of a result set, no fetch-next statement must be called. Silk Performer automatically fetches the first row when a SQL SELECT command is called.

Syntax

Stat = "fetch" Ident "next" Expr.

Example

var
  v_artname : string;
  v_artno, v_price : number;

dcltrans
  transaction TMain
  begin
    c1: SelArticle();
    fetch c1 next 5;
  end TMain;

dclsql
  SelArticle:
  SELECT articlenumber, price, name
  INTO :v_artno, :v_price, :v_artname
  FROM article
  WHERE price > 100
  ORDER BY price DESC;

After execution of the SQL command SelArticle, a result set is formed containing all articles where the price is greater than 100. The row position is set to the first row in the result set. At this time the values of the first row are bound to the variables v_artno, v_price and v_artname. The fetch c1 next 5 statement fetches 5 rows sequentially forward starting from the current row position. The row position after the fetch statement is set to the sixth row in the result set. At this time the values of the sixth row are bound to the variables v_artno, v_price and v_artname.

Parent topic: Fetch Statements
Related reference
SQL Section
Result Set Cursors (scrollable cursors)


Fetch-Last Statement (for scrollable cursors)

Syntax

Stat = "fetch" ident "last".

The fetch-last statement sets the current row position of the result set to the last row fetched by a previous sequential fetch-next statement. The fetch-last statement is needed to be able to continue with a fetch-next statement at the row position that was fetched last by a previous fetch-next statement. This must be done when fetch-next statements were interrupted by fetch-row or fetch-set statements that updated the current row position.

Example

pos: current row position in result set
max: last row in result set fetched by a
fetch-next statement
c1:SelArticle... /* max = 1; pos= 1 */
fetch c1 next 20; /* max = 21; pos= 21
*/
fetch c1 row 10; /* max = 21; pos= 10 */
fetch c1 last; /* max = 21; pos= 21 */
fetch c1 next 20; /* max = 41; pos= 41
*/
fetch c1 row 1; /* max = 41; pos= 1 */
fetch c1 next 20; /* max = 21; pos= 21
*/

Example: Fetch-all; Fetch-set

var
v_artname : string;
v_artno, v_price : number;
dcltrans
transaction TMain
var
artname : string;
artno, price : number;
result set c1;
begin
c1: SelArticle();
fetch c1 all;
fetch c1 set;
c2: UpdCurArticle();
end TMain;
dclsql
SelArticle:
SELECT articlenumber, price, name
INTO :v_artno, :v_price, :v_artname
FROM article
WHERE price > 1000
ORDER BY price DESC;
UpdCurArticle:
UPDATE article
SET price = price*0.9
WHERE CURRENT OF c1;

The example shows a transaction that simulates displaying all rows of the result set of the SQL SELECT command SelArticle (fetch c1 all). Subsequently one row of the result set is selected randomly (fetch c1 set) and the selected row is updated with the SQL UPDATE command UpdCurArticle.

Example: Fetch-all; Fetch-set-unique

var
v_artname : string;
v_artno, v_price : number;
dcltrans
transaction TMain
var
i: number;
result set c1;
begin
c1: SelArticle();
fetch c1 all;
for I := 1 to 3 do
fetch c1 set unique;
if eos(c1) then exit end;
c2: UpdCurArticle();
end;
end TMain;
dclsql
SelArticle:
SELECT articlenumber, price, name
INTO :v_artno, :v_price, :v_artname
FROM article
WHERE price > 1000
ORDER BY price DESC;
UpdCurArticle:
UPDATE article
SET price = price*0.9
WHERE CURRENT OF c1;

The example shows a transaction that simulates displaying all rows of the result set of the SQL SELECT command SelArticle (fetch c1 all). Subsequently three different rows of the result set are selected randomly (fetch c1 set) and the selected rows are updated with the SQL UPDATE command UpdCurArticle. If there are no rows left to update (eos(c1)=true), the for loop is canceled.

Example: Fetch-next; Fetch-set; Fetch-last

var
v_artname : string;
v_artno, v_price : number;
dcltrans
transaction TMain
var
I : number;
result set c1;
begin
c1: SelArticle();
while not eos(c1) do
fetch c1 next 20;
for I := 1 to 3 do
fetch c1 set 20 unique;
if eos(c1) then exit end;
c2: UpdCurArticle();
end;
end TMain;
dclsql
SelArticle:
SELECT articlenumber, price, name
INTO :v_artno, :v_price, :v_artname
FROM article
WHERE price > 1000
ORDER BY price DESC;
UpdCurArticle:
UPDATE article
SET price = price*0.9
WHERE CURRENT OF c1;

The example shows a transaction which simulates displaying 20 rows of the result set of the SQL SELECT command SelArticle (fetch c1 next 20). Subsequently three different rows of the displayed rows are selected randomly (fetch c1 set 20 unique) and the selected rows are updated with the SQL UPDATE command UpdCurArticle. Then the next 20 rows of the result set are displayed (fetch c1 next 20). This proceeding is repeated until no rows are left in the result set (while not eos(c1)).

Example: Updating/deleting multiple rows of a result set

dclrand
rUpdEvent: RndBin(0.25);
dcltrans
transaction TMain
var
i: number;
result set c1;
begin
c1: SelArticle();
fetch c1 all;
/* simulate time for user input actions
*/
wait 10.0;
for I := 1 to rows(c1) do
if rUpdEvent then
fetch c1 row I;
c2: UpdCurArticle();
end;
end;
end TMain;
dclsql
SelArticle:
SELECT articlenumber, price, name
INTO *, *, *
FROM article WHERE articlenumber <= 50
ORDER BY articlenumber;
UpdCurArticle:
UPDATE article
SET price = price*0.9
WHERE CURRENT OF c1;

The example shows a transaction that simulates displaying all rows of the result set formed by the SQL SELECT command SelArticle. Subsequently a wait statement is used to simulate user times for entering input data. The random variable rUpdEvent specifies the probability for updating a row in the result set (25% of all rows in the result set should be updated). If a row is to be updated (if rUpdEvent), the row position is set to the row to be updated (fetch c1 row I) and a SQL UPDATE command with a CURRENT OF cursor is executed (UpdCurArticle).

Example: Updating/deleting multiple rows without using scrollable cursors

dclrand
rDelEvent: RndBin(0.1);
var
v_artno: number;
dcltrans
transaction TMain
const
MAX_ROWS := 100;
var
rowCount, I : number;
anoArr : array[MAX_ROWS] of number;
begin
rowCount := 0;
c1: SelArticle2();
while not eos(c1) and (rowCount<MAX_ROWS)
do
rowCount := rowCount+1;
anoArr[rowCount] := v_artno;
fetch c1 next 1;
end;
wait 10.0; /* simulate user think time */
for I := 1 to rowCount do
if rDelEvent then
v_artno := anoArr[i];
c2: DelArticle();
end;
end;
end TMain;
dclsql
SelArticle2:
SELECT articlenumber, price, name
INTO :v_artno, *, *
FROM article
WHERE articlenumber <= 50
ORDER BY articlenumber;
DelArticle:
DELETE FROM article WHERE articlenumber
= :v_artno;

The example shows a transaction that simulates displaying up to MAX_ROWS rows of the result set formed by the SQL SELECT command SelArticle2. The transaction does not use scrollable cursors for result set operations. So the articlenumber of a row in the result set is used to reselect rows in the result set. The while loop fetches the article numbers for the rows into the array anoArr. Subsequently a wait statement is used to simulate user times for entering input data. The random variable rDelEvent specifies the probability for deleting a row in the result set (10% of all rows in the result set are to be deleted). To select the row to be deleted, use the array anoArr.

Parent topic: Fetch Statements
Related reference
SQL Section
Result Set Cursors (scrollable cursors)


Fetch-Row Statement (for scrollable cursors)

The fetch-row statement sets the row position of the result set to the position indicated by Expr and fetches the row. The first row in a result set is position 1. Ident is the name of the cursor used for the corresponding SQL SELECT command. The cursor used in the fetch-row statement must be declared in the same transaction as a scrollable cursor (result set cursorname). If no row with position Expr is in the result set, the eos condition is set to true.

Syntax

Stat = "fetch" Ident "row" Expr.

Example

var
v_artname : string;
v_artno, v_price : number;

dcltrans
transaction TMain
begin
c1: SelArticle();
fetch c1 next 5;
end TMain;

dclsql
SelArticle:
SELECT articlenumber, price, name
INTO :v_artno, :v_price, :v_artname
FROM article
WHERE price > 100
ORDER BY price DESC;

After execution of the SQL command SelArticle, a result set is formed containing all articles where the price is greater than 100. The row position is set to the first row in the result set. At this time the values of the first row are bound to the variables v_artno, v_price and v_artname. The fetch c1 next 5 statement fetches 5 rows sequentially forward starting from the current row position. The row position after the fetch statement is set to the sixth row in the result set. At this time the values of the sixth row are bound to the variables v_artno, v_price and v_artname.

Parent topic: Fetch Statements
Related reference
Result Set Cursors (scrollable cursors)
SQL Section


Fetch-Set Statements (for scrollable cursors)

The fetch-set statement sets the row position to a randomly selected position within the set of rows actually fetched by fetch-next or fetch-last statements. The cursor used in the fetch-set statement must be declared in the same transaction as a scrollable cursor (result set cursorname).

Fetch-set statements are only applicable to cursors that have previously executed fetch-next or fetch-all statements.

Syntax

Stat = "fetch" ident "set" [ Expr ] ["unique" ].
Parent topic: Fetch Statements
Related reference
SQL Section


Expr Option

With the optional specification of an integer expression (Expr) in a fetch-set statement, you can restrict the number of rows to be fetched to Expr rows. The last row of the restricted result set is the last row fetched by a previous sequential fetch-next or fetch-all statement. The first row of the restricted result set is calculated as follows:

first row in restricted result set := maximum(1, last row number sequentially fetched - Expr)

Thus fetch-set statements with the Expr option are only useful in conjunction with sequential fetch-next statements.

Parent topic: Fetch Statements
Related reference
SQL Section


Unique Option

If you specify the unique option in a fetch-set statement, no row will be fetched twice by the same fetch-set statement. If all rows have already been fetched with the fetch-set-unique statement, a subsequent call of the fetch-set-unique statement will set the eos condition and no row will be fetched.

Parent topic: Fetch Statements
Related reference
SQL Section


Querying the State of Database Operations

Silk Performer supports the following functions for querying the state of database operations:

  • EOS Function
    Returns the value of the end of selection condition of the last SQL SELECT command or the last fetch statement associated with a cursor.
  • RC Function
    Gets the return code of the most recent ODBC function call associated with a cursor.
  • Rows Function
    Returns the number of rows affected by the most recent SQL command if the SQL command executed with the cursor is an UPDATE, a DELETE or an INSERT command.
Parent topic: Database Server Access Statements


EOS Function

Action

Returns the value of the end of selection condition of the last SQL SELECT command or the last fetch statement associated with a cursor. This function returns true if the result set created by a SQL SELECT command is empty or if a fetch statement sets the current row position out of the result set.

Syntax

eos ( in cCursor : cursor ) : boolean

Return value

value of the end of selection condition

Parameter | Description
cCursor | Cursor with which the command or statement is associated

Example

var
  v_artno, v_stock, v_quantity:
number;

dcltrans
  transaction TMain
  begin
    c1: SelArticle();

    if eos (c1) then
      write("no articles found");
      return 1;
    end;

    while not eos (c1) do
      write(v_artno);
      ...
      fetch c1 next 1;
    end;
  end TMain;

dclsql
  SelArticle:
    SELECT stock, quantity
    INTO :v_stock, :v_quantity
    FROM article
    WHERE articlenumber = :v_artno;
Parent topic: Querying the State of Database Operations
Related concepts
Fetch Statements
Related reference
Calling SQL Commands
SQL Section


RC Function

Action

Gets the return code of the most recent ODBC function call associated with a cursor. If this function returns zero, the most recent SQL command or fetch statement was executed successfully; otherwise, rc returns a nonzero value.

Note: This function only works with Silk Performer's high-level database access interface. If you use it with the medium- or native-level interface, the return value of the rc-function will be undefined.

Syntax

rc( in cCursor : cursor ):number;

Return value

zero if the most recent SQL command or fetch statement was executed successfully, otherwise the return code of the most recent ODBC function call.

Parameter | Description
cCursor | Cursor with which the function call is associated

Example

var
v_artno, v_stock, v_quantity: number;

dcltrans
  transaction TMain
  begin
    c1: SelArticle();
    write("return code: ");
    write (rc(c1));
  end TMain;

dclsql
  SelArticle:
    SELECT stock, quantity
    INTO :v_stock, :v_quantity
    FROM article
    WHERE articlenumber = :v_artno;
Parent topic: Querying the State of Database Operations
Related concepts
Fetch Statements
Related reference
SQL Section
Calling SQL Commands


Rows Function

Action

Returns the number of rows affected by the most recent SQL command if the SQL command executed with the cursor is an UPDATE, a DELETE or an INSERT command.

Syntax

rows( in cCursor : cursor ):number;

Return value

Number of rows affected by the most recent SQL command.

If the most recent SQL command executed with the cursor ident is a SELECT command, it returns the number of rows actually fetched by fetch-next or fetch-all statements associated with the SELECT command.

This function does not return the number of rows in a result set unless the rows have previously been fetched.

Parameter | Description
cCursor | Cursor with which the SQL command is associated

Example

 var
  v_artno, v_stock, v_quantity: number;

dcltrans
  transaction TMain
  begin
    c1: SelArticle();
    fetch c1 all;
    write("number of articles found: ");
    write(rows(c1));
  end TMain;

dclsql
  SelArticle:
    SELECT stock,quantity
    INTO :v_stock, :v_quantity
    FROM article
    WHERE articlenumber = :v_artno;
Parent topic: Querying the State of Database Operations
Related concepts
Fetch Statements
Related reference
Calling SQL Commands
SQL Section


Special Simulation Statements

Silk Performer supports the following special simulation statements:

  • Halt Statement
    Terminates the simulation of the current user.
  • Wait Statement
    Simulates waiting periods produced by the user of a transaction (for example, the time for entering input data).
Parent topic: Statements


Halt Statement

Terminates the simulation of the current user.

Syntax

Stat = "halt".

Example

dcltrans
  transaction TMain
  begin
    gHdbc1 := DB_Connect(CONNECT_STRING);
    if gHdbc1 = 0 then
      halt;
    end;
  end TMain;
Parent topic: Special Simulation Statements
Parent topic: Runtime Functions
Related concepts
Statements
Related reference
Sequence of Statements


Wait Statement

Wait statements are used in Silk Performer test scripts to simulate waiting periods produced by the user of a transaction (for example, the time for entering input data). Expr is the waiting period in seconds. Expr is a constant floating-point value or a random variable returning a floating-point value.

Syntax

Stat = "wait" Expr.

Example

dclrand
  r1 : RndExpF(5.5);
  r2 : RndUniF(0.5..10.0);
  ...

dcluser
  user
    b1
  transactions
    TMain(r2) : 20;

dcltrans
  transaction TMain(p1: float)
  var
    artname : string(40);
    artno, price, I : number;
    result set c1;
  begin
    wait r1;
    c1: SelArticle();
    fetch c1 all;

    for I := 1 to 3 do
      wait p1;
      fetch c1 set unique;

      if eos(c1) then exit end;

      wait 2.5;
      c2: UpdCurArticle();
  end;
end TMain;
Parent topic: Special Simulation Statements
Parent topic: Runtime Functions
Related concepts
Statements
Related reference
Sequence of Statements


General Functions

Silk Performer provides specific functions to perform the following general operations:

  • Data Structure Functions
    Provides an introduction to the data structure functions.
  • Date Functions
    Lists the functions to get the current date and time from the operating system, and to generate random dates and time intervals.
  • Error-Handling Functions
    Provides an overview of error handling and lists the functions available.
  • File Functions
    Lists the functions to create, read, write, and delete files.
  • List Functions
    Lists the functions to work with the List data type.
  • Load Test Control Functions
    Lists the functions that retrieve information about the load test currently running.
  • Logging Functions Overview
    Provides an overview of the logging functions.
  • Measurement Functions
    Provides an overview of the measurement functions and a list of those functions.
  • Memory Functions
    Lists the predefined functions for the allocation of dynamic buffers.
  • Process Control Functions
    Lists the process control functions.
  • Synchronization Functions
    Provides an overview of the functions that serialize or synchronize transactions in your testing scripts in order to better control the timing of loads in your simulation.
  • Random Functions
    Lists the random functions that Silk Performer provides to use directly within transactions without having to define a random variable.
  • Random Types
    Lists the random types that Silk Performer provides.
  • Runtime Functions
    Lists the runtime functions including terminating users and the event handler and simulating thinking periods and waiting periods.
  • Simulation Setting Functions
    Lists the simulation setting functions.
  • String Functions
    Lists the string functions.
  • Regular Expressions
    Introduces an advanced technique for checking syntax of strings or for parsing values out of strings.
  • System Information Functions
    Lists functions for retrieving system information.
  • Attributes Manipulation Functions
    Lists the functions that set and retrieve values of user attributes.
  • XML Functions
    Lists the functions that allow you to work with XML documents and parse and verify XML values of web response documents.
Parent topic: Benchmark Description Language (BDL) Reference


Data Structure Functions

Unlike the programming language C, Benchmark Description Language (BDL) does not support structured data types. Instead, BDL uses a series of type-dependent Get and Set functions to access data in external C data structures.

The following example illustrates a C data structure:

typedef struct Struct1 {
  char myChar;       // size: 1 byte pos: 1
  short myShort;     // size: 2 bytes pos: 2
  long myLong;       // size: 4 bytes pos: 4
  double myDouble;   // size: 8 bytes pos: 8
  float myFloat;     // size: 4 bytes pos: 16
  ushort myUShort;   // size: 2 bytes pos: 20
  char myString[10]; // size: 10 bytes pos: 22
  uchar myUChar;     // size: 1 byte pos: 32
}
// size of Struct1: 32 bytes
Note: This data structure is used in all examples accompanying the help for the Get and Set functions that access C data structures.

To access the elements of a C data structure, you must first declare a corresponding BDL string as follows in order to map the C structure into BDL:

const
  SIZE_STRUCT := 32;
var
  myBDLstring: string(SIZE_STRUCT);

This allocates the same amount of storage space for the BDL string as for the original C data structure.

You can use BDL strings as actual parameters to external C functions where the external function expects a pointer to a data structure as parameter:

// C code
extern void ExtCFunc1(Struct1 *pStruct)
{
    pStruct->myChar = 1;
    ...
    ...
    pStruct->myUChar = 10;
}

// BDL function prototype
DLL "ExtFunc.DLL"
  "ExtCFunc1" function ExtCFunc(inout string);
// BDL usage
begin
  SetChar(myBDLstring, 1, ord('A'));
  ExtCFunc1(myBDLstring);
  ...
  ...
end;

In the examples, the starting positions for the function examples correspond to the respective data types in Struct1. The starting positions in the BDL string are given at the right next to “pos:” in the C data structure above.

  • SetChar Function
    Copies a one-byte signed character into a data structure at a specified position.
  • GetChar Function
    Retrieves a one-byte signed character from a specified data structure at a specified position.
  • SetDouble Function
    Copies a double value (8-byte floating-point value) into a data structure at a certain position.
  • GetDouble Function
    Retrieves a double value (8-byte floating-point value) from a specified data structure at a specified position.
  • SetFloat Function
    Copies a float value (4-byte floating-point value) into a data structure at a specified position.
  • GetFloat Function
    Retrieves a float value (4-byte floating-point value) from a specified data structure at a specified position.
  • SetLong Function
    Copies a long value (4-byte signed integer value) into a data structure at a specified position.
  • GetLong Function
    Retrieves a long value (4-byte signed integer value) from a specified data structure at a specified position.
  • SetMem Function
    Copies a specified number of bytes at a specified position into a string.
  • GetMem Function
    Copies a specified number of bytes from a specified position in a source string to a destination string.
  • SetShort Function
    Copies a short value (2-byte signed integer value) into a data structure at a specified position.
  • GetShort Function
    Retrieves a short value (2-byte signed integer value) from a specified data structure at a specified position.
  • SetString Function
    Copies a string at a specified position into a string.
  • GetString Function
    Extracts a substring starting at a specified position in a specified source string.
  • SetUChar Function
    Copies a one-byte unsigned character into a data structure at a specified position.
  • GetUChar Function
    Retrieves a one-byte unsigned character from a specified data structure at a specified position.
  • SetUShort Function
    Copies an unsigned short value (2-byte unsigned integer value) into a data structure at a specified position.
  • GetUShort Function
    Retrieves an unsigned short value (2-byte unsigned integer value) from a specified data structure at a specified position.
  • SetWideChars Function
    Copies a sequence of wide characters to a specified position within a buffer.
  • ZipCompressGzip Function
    Compresses a data buffer in gzip format.
  • ZipUncompressGzip Function
    Uncompresses a gzipped data buffer which was compressed with the ZipCompressGzip function.
  • ZipCompressGzip2 Function
    Compresses a data buffer in gzip format. The resulting zipped buffer can be unzipped with the ZipUncompressGzip2 function or any gzip unzipper tool.
  • ZipUncompressGzip2 Function
    Uncompresses a gzipped data buffer which was compressed with the ZipCompressGzip2 function.
  • ZipCompressZlib Function
    Compresses a data buffer in zLib format.
  • ZipCompressZlib2 Function
    Compresses a data buffer in zLib format.
  • ZipUncompressZlib Function
    Uncompresses a zipped data buffer, which was compressed with the ZipCompressZlib function.
  • ZipUncompressZlib2 Function
    Uncompresses a zipped data buffer, which was compressed with the ZipCompressZlib2 function.
Parent topic: General Functions


SetChar Function

Action

Copies a one-byte signed character into a data structure at a specified position. You must declare a BDL string before using this function.

Include file

Kernel.bdh

Syntax

SetChar( inout sString : string,
         in    nPos : number,
         in    nChar : number ) : boolean;

Return value

  • true if successful

  • false otherwise

Parameter | Description
sString | BDL string corresponding to the data structure
nPos | Insert position in the BDL string, where the first position is 1 (not 0)
nChar | Signed character, specified as ASCII code

Example

dcltrans
  transaction TSetChar
  const
    SIZE_STRUCT := 32;
  var
    myBDLstring : string(SIZE_STRUCT);
    bOk         : boolean;
  begin
    // Set a one-byte signed character at position 1
    // in the BDL string myBDLstring and thereby (through mapping)
    // set the element myChar in Struct1
    bOk := SetChar(myBDLstring, 1, ord('A'));
    if bOk then
      write("myChar successfully set to 'A'"); writeln;
    else
      write("error setting myChar"); writeln;
    end;
  end TSetChar;

Output

myChar successfully set to 'A'
Parent topic: Data Structure Functions
Related reference
GetChar Function


GetChar Function

Action

Retrieves a one-byte signed character (ASCII number) from a specified data structure at a specified position. You must declare a BDL string before using this function. Use the chr function to convert the retrieved ASCII number to a character.

Include file

Kernel.bdh

Syntax

GetChar( in sString : string, in nPos  : number ): number;

Return value

signed character (ASCII number)

Parameter | Description
sString | BDL string corresponding to the data structure
nPos | Position of character in the BDL string, where the first position is 1 (not 0)

Example

dcltrans
  transaction TGetChar
  const
    SIZE_STRUCT := 32;
  var
    myBDLstring : string(SIZE_STRUCT);
    nChar       : number;
  begin
    ...
    // Retrieve a one-byte signed character from position 1
    // in the BDL string myBDLstring and thereby (through mapping)
get
    // the element myChar in Struct1
    nChar := GetChar(myBDLstring, 1);
    write("myChar = "); write(chr(nChar)); writeln;
  end TGetChar;

Output

myChar = A
Parent topic: Data Structure Functions
Related reference
SetChar Function


SetDouble Function

Action

Copies a double value (8-byte floating-point value) into a data structure at a certain position. You must declare a BDL string before using this function.

Include file

Kernel.bdh

Syntax

SetDouble( inout sString :string,
             in    nPos    : number,
             in    fDouble : float ) : boolean;

Return value

  • true if successful

  • false otherwise

Parameter | Description
sString | BDL string corresponding to the data structure
nPos | Insert position in the BDL string, where the first position is 1 (not 0)
fDouble | Double value

Example

dcltrans
  transaction TSetDouble
  const
    SIZE_STRUCT := 32;
  var
    myBDLstring : string(SIZE_STRUCT);
    bOk         : boolean;
  begin
    // Set an 8-byte floating point value at position 8
    // in the BDL string myBDLstring and thereby (through mapping)
set
    // the element myDouble in Struct1
    bOk := SetDouble(myBDLstring, 8, 12345.99);
    if bOk then
      write("myDouble successfully set to 12345.99"); writeln;
    else
      write("error setting myDouble"); writeln;
    end;
  end TSetDouble;

Output

myDouble successfully set to 12345.99
Parent topic: Data Structure Functions
Related reference
GetDouble Function


GetDouble Function

Action

Retrieves a double value (8-byte floating-point value) from a specified data structure at a specified position. You must declare a BDL string before using this function.

Include file

Kernel.bdh

Syntax

GetDouble( in sString : string,in nPos : number ): float;

Return value

double value

Parameter | Description
sString | BDL string corresponding to the data structure
nPos | Starting position in the BDL string, where the first position is 1 (not 0)

Example

dcltrans
  transaction TGetDouble
  const    SIZE_STRUCT := 32;
  var    myBDLstring : string(SIZE_STRUCT);
    fValue : float;
  begin
    ...
    // Retrieve an 8-byte floating point value from position 8
    // in the BDL string myBDLstring and thereby (through mapping)
get
    // the element myDouble in Struct1
    fValue := GetDouble(myBDLstring, 8);
    write("myDouble = "); write(fValue); writeln;
  end TGetDouble;

Output

myDouble = 754.294000
Parent topic: Data Structure Functions
Related reference
SetDouble Function


SetFloat Function

Action

Copies a float value (4-byte floating-point value) into a data structure at a specified position. You must declare a BDL string before using this function.

Include file

Kernel.bdh

Syntax

SetFloat( inout sString : string,
            in    nPos    : number,
            in    fFloat  : float ) : boolean;

Return value

  • true if successful

  • false otherwise

Parameter | Description
sString | BDL string corresponding to the data structure
nPos | Insert position in the BDL string, where the first position is 1 (not 0)
fFloat | Float value

Example

dcltrans
  transaction TSetFloat  const
    SIZE_STRUCT := 32;
  var
    myBDLstring : string(SIZE_STRUCT);
    bOk         : boolean;
  begin
    // Set a 4-byte floating point value at position 16
    // in the BDL string myBDLstring and thereby (through mapping)
set
    // the element myFloat in Struct1
    bOk := SetFloat(myBDLstring, 16, 12345.99);
    if bOk then
      write("myFloat successfully set to 12345.99");writeln;
    else
      write("error setting myFloat"); writeln;
    end;
  end TSetFloat;

Output

myFloat successfully set to 12345.99
Parent topic: Data Structure Functions
Related reference
GetFloat Function


GetFloat Function

Action

Retrieves a float value (4-byte floating-point value) from a specified data structure at a specified position. You must declare a BDL string before using this function.

Include file

Kernel.bdh

Syntax

GetFloat( in sString : string,
          in nPos    : number ): float;

Return value

float value

Parameter | Description
sString | BDL string corresponding to the data structure
nPos | Starting position in the BDL string, where the first position is 1 (not 0)

Example

dcltrans
  transaction TGetFloat
  const    SIZE_STRUCT := 32;
  var
    myBDLstring : string(SIZE_STRUCT);
    fFloat : float;
  begin
    ...
    // Retrieve a 4-byte floating point value from position 16
    // in the BDL string myBDLstring and thereby (through mapping)
get
    // the element myFloat in Struct1
    fFloat := GetFloat(myBDLstring, 16);
    write("myFloat = "); write(fFloat); writeln;
  end TGetFloat;

Output

myFloat = 14.098000
Parent topic: Data Structure Functions
Related reference
SetFloat Function


SetLong Function

Action

Copies a long value (4-byte signed integer value) into a data structure at a specified position. You must declare a BDL string before using this function.

Include file

Kernel.bdh

Syntax

SetLong( inout sString    : string,
         in    nPos       : number,
         in    nLong      : number,
         in    nByteOrder : number optional ) :boolean;

Return value

  • true if successful

  • false otherwise

Parameter | Description
sString | BDL string corresponding to the data structure
nPos | Insert position in the BDL string, where the first position is 1 (not 0)
nLong | Long value
nByteOrder

Specifies the byte order that is applied when a value is set (optional). This parameter can be one of the following:

  • OPT_LITTLE_ENDIAN. Microsoft byte order (default).

  • OPT_BIG_ENDIAN. Network, Apple, Java byte order.

Example

dcltrans
  transaction TSetLong
  const
    SIZE_STRUCT := 32;
  var
    myBDLstring : string(SIZE_STRUCT);
    bOk         : boolean;
  begin
    // Set a 4-byte signed integer value at position 4
    // in the BDL string myBDLstring and thereby (through mapping)
set
    // the element myLong in Struct1
    bOk := SetLong(myBDLstring, 4, -12345);
    if bOk then
      write("myLong successfully set to -12345"); writeln;
    else
      write("error setting myLong"); writeln;
    end;
  end TSetLong;

Output

myLong successfully set to -12345
Parent topic: Data Structure Functions
Related reference
GetLong Function


GetLong Function

Action

Retrieves a long value (4-byte signed integer value) from a specified data structure at a specified position. You must declare a BDL string before using this function.

Include file

Kernel.bdh

Syntax

GetLong(in sString : string,
in nPos : number,
in nByteOrder : number optional): number;

Return value

number

Parameter | Description
sString | BDL string corresponding to the data structure
nPos | Starting position in the BDL string, where the first position is 1 (not 0)
nByteOrer

Specifies the byte order that is applied when a value is retrieved (optional). This parameter can be one of the following:

  • OPT_LITTLE_ENDIAN. Microsoft byte order (default).

  • OPT_BIG_ENDIAN. Network, Apple, Java byte order.

Example

dcltrans
transaction TGetLong
constSIZE_STRUCT := 32;
var
myBDLstring : string(SIZE_STRUCT);
nLong : number;
begin...// Retrieve a 4-byte signed integer value from position 4
// in the BDL string myBDLstring and thereby (through mapping) get
// the element myLong in Struct1
nLong := GetLong(myBDLstring, 4);
write("myLong = "); write(nLong); writeln;
end TGetLong;

Output

myLong = 497202
Parent topic: Data Structure Functions
Related reference
SetLong Function


SetMem Function

Action

Copies a specified number of bytes at a specified position into a string.

Include file

Kernel.bdh

Syntax

SetMem( inout sDest     : string,
        in    nPosition : number,
        in    sSource   : string,
        in    nLen      : number optional ): boolean;

Return value

  • true if successful

  • false otherwise

Parameter | Description
sDest | Identifies the destination string.
nPosition | Specifies the position where to copy into sDest, where the first position in a string is 1 (not 0)
sSource | Identifies the string to copy
nLen | Length to copy (optional).

Example

dcltrans
  transaction TSetMem
  const
    SIZE_STRUCT := 32; // hexadecimal notation
    CONST_VAL   := "\hAF0034F5FF01";// of 6 bytes
  var
    myBDLstring : string(SIZE_STRUCT);
    bOk         : boolean;
  begin
    // Copy sizeof(CONST_VAL) bytes = 6 from CONST_VAL
    // into myBDLstring starting at position 2 and thereby
    // (through mapping) set the elements myShort and myLong
    // in Struct1
    bOk := SetMem(myBDLstring, 2, CONST_VAL);
    if bOk then
      write("myShort and myLong successfully set");writeln;
    else
      write("error setting myShort and myLong"); writeln;
    end;
  end TSetMem;

Output

myShort and myLong successfully set
Parent topic: Data Structure Functions
Related reference
GetMem Function


GetMem Function

Action

Copies a specified number of bytes from a specified position in a source string to a destination string.

Include file

Kernel.bdh

Syntax

GetMem( in    sSource   : string,
        in    nPosition : number,
        inout sDest     : string,
        in    nLen      : number ): boolean;

Return value

  • true if successful

  • false otherwise

Parameter | Description
sSource | Contains the string to copy from
nPosition | Specifies the position to start copying from in sSource, where the first position in a string is 1 (not 0)
sDest | Contains the destination string
nLen | Length to copy

Example

dcltrans
  transaction TGetMem
  const
    SIZE_STRUCT := 32;
  var
    myBDLstring : string(SIZE_STRUCT);
    sString     : string(6);
    bOk         : boolean;
  begin
...
    // Copy sizeof(sString) = 6 bytes from myBDLString starting
    // at position 2 into sString and thereby (through mapping) get the
    // elements myShort and myLong in Struct1
    bOk := GetMem(myBDLstring, 2, sString, STRING_COMPLETE);

    if bOk then
      write("myShort and myLong successfully retrieved"); writeln;
    else
      write("error getting myShort and myLong"); writeln;
    end;
  end TGetMem;

Output

myShort and myLong successfully retrieved
Parent topic: Data Structure Functions
Related reference
SetMem Function


SetShort Function

Action

Copies a short value (2-byte signed integer value) into a data structure at a specified position. You must declare a BDL string before using this function.

Include file

Kernel.bdh

Syntax

SetShort( inout sString    : string,
          in    nPos       : number,
          in    nShort     : number,
          in    nByteOrder : number optional ) :boolean;

Return value

  • true if successful

  • false otherwise

Parameter | Description
sString | BDL string corresponding to the data structure
nPos | Insert position in the BDL string, where the first position is 1 (not 0)
nShort | Short value
nByteOrder

Specifies the byte order that is applied when a value is set (optional). This parameter can be one of the following:

  • OPT_LITTLE_ENDIAN. Microsoft byte order (default).

  • OPT_BIG_ENDIAN. Network, Apple, Java byte order.

Example

dcltrans
  transaction TSetShort
  const
    SIZE_STRUCT := 32;
  var
    myBDLstring : string(SIZE_STRUCT);
    bOk         : boolean;
  begin
    // Set a 2-byte signed integer value at position 2
    // in the BDL string myBDLstring and thereby (through mapping)
set
    // the element myShort in Struct1
    bOk := SetShort(myBDLstring, 2, -12);
    if bOk then
      write("myShort successfully set to -12"); writeln;
    else
      write("error setting myShort"); writeln;
    end;
  end TSetShort;

Output

myShort successfully set to -12
Parent topic: Data Structure Functions
Related reference
GetShort Function


GetShort Function

Action

Retrieves a short value (2-byte signed integer value) from a specified data structure at a specified position. You must declare a BDL string before using this function.

Include file

Kernel.bdh

Syntax

GetShort( in sString : string,
          in nPos : number,
          in nByteOrder : number optional ) : number;

Return value

short value

Parameter | Description
sString | BDL string corresponding to the data structure
nPos | Starting position in the BDL string, where the first position is 1 (not 0)
nByteOrder

Specifies the byte order that is applied when a value is retrieved (optional). This parameter can be one of the following:

  • OPT_LITTLE_ENDIAN. Microsoft byte order (default).

  • OPT_BIG_ENDIAN. Network, Apple, Java byte order.

Example

dcltrans
  transaction TGetShort
  const
    SIZE_STRUCT := 32;
  var
    myBDLstring : string(SIZE_STRUCT);
    nShort : number;
  begin
  ...
    // Retrieve a 2-byte signed integer value from position 2
    // in the BDL string myBDLstring and thereby (through mapping) get
    // the element myShort in Struct1
    nShort := GetShort(myBDLstring, 2);
    write("myShort = "); write(nShort); writeln;
  end TGetShort;

Output

myShort = 209
Parent topic: Data Structure Functions
Related reference
SetShort Function


SetString Function

Action

Copies a string at a specified position into a string.

Note: This function can be used to access pointers.

Include file

Kernel.bdh

Syntax

SetString( inout sDest     : string,
           in    nPosition : number,
           in    sSource   : string,
           in    nMaxLen   : number optional,
           in    sFillChar : string optional ):boolean;

Return value

  • true if successful

  • false if string to copy terminated or failure

Parameter | Description
sDest | Identifies the destination string
nPosition | Specifies the position to copy to in aSrcString, where the first position in a string is 1 (not 0)
sSource | Identifies the string to copy
nMaxLen | Maximum number of characters to copy (optional). If this parameter is omitted, the whole source string is copied to the destination string
sFillChar | Specifies a character sequence used to fill the remaining bytes if the copied string is shorter than nMaxLen (optional). If this parameter is passed to the function, no NULL termination is inserted into the destination string
Note: If the length of sSource is larger than nMaxLen, only nMaxLen bytes are copied to sDest, including a NULL termination byte. If the optional parameter sFillChar is passed to the function, then no NULL termination is inserted into sDest.

Example

dcltrans
  transaction TSetString
  const
    SIZE_STRUCT := 32;
  var
    myBDLstring    : string(SIZE_STRUCT);
    sString, sDest : string;
  begin
    // Copy a string from sString into myBDLstring starting
    // at position 22 and thereby (through mapping)set
    // the element myString in Struct1
    sString := "Holidays";
    SetString(myBDLstring, 22, sString);
    SetString(sDest, 1, sString, 20, "_");
    write(sDest);
  end TSetString;

Output

Holidays____________
Parent topic: Data Structure Functions
Related reference
GetString Function


GetString Function

Action

Extracts a substring starting at a specified position in a specified source string.
Note: This function can be used to access pointers.

Include file

Kernel.bdh

Syntax

GetString( in  sSource   : string,
           in  nPos      : number,
           out sDest     : string,
           in  nDestSize : number ): boolean;

Return value

  • true if successful

  • false = string to copy terminated or failure

Parameter | Description
sSource | Source string
nPos | Specifies the position to copy from in sSource, where the first position is 1 (not 0)
sDest | Destination string
nDestSize | Maximum number of characters to copy
Note: If nMaxLen extends beyond the end of sSource, the actual length of substring sValue is adjusted downward to stop at the end of sSource.

Example

dcltrans
  transaction TGetString
  const
    SIZE_STRUCT := 32;
  var
    myBDLstring : string(SIZE_STRUCT);
    sString     : string(9);
    bOk         : boolean;
  begin
    SetString(myBDLstring, 22, "hello");
    // Copy a string from myBDLstring starting at position 22
    // into sString and thereby (through mapping)get
    // the element myString in Struct1
    bOk := GetString(myBDLstring, 22, sString,STRING_COMPLETE);
    write("myString = "); write(sString); writeln;
  end TGetString;

Output

myString = hello
Parent topic: Data Structure Functions
Related reference
SetString Function


SetUChar Function

Action

Copies a one-byte unsigned character into a data structure at a specified position. You must declare a BDL string before using this function; see Data Structure Functions for further information.

This function can also be used to convert an ASCII representation of a hexadecimal string to a hexadecimal string by using a custom function. See the example below.

Include file

Kernel.bdh

Syntax

SetUChar( inout sString : string,
          in    nPos    : number,
          in    nChar   : number ) : boolean;

Return value

  • true if successful

  • false otherwise

Parameter | Description
sString | BDL string corresponding to the data structure
nPos | Insert position in the BDL string, where the first position is 1 (not 0)
nChar | Unsigned character

Example

dcltrans
  transaction TSetUChar
  const    SIZE_STRUCT := 32;
  var
    myBDLstring : string(SIZE_STRUCT);
    bOk         : boolean;
  begin
    // Set a one-byte unsigned character at position 32
    // in the BDL string myBDLstring and thereby (through mapping) set
    // the element myUChar in Struct1
    bOk := SetUChar(myBDLstring, 32, 255);
    if bOk then
      write("myUChar successfully set to 255"); writeln;
    else
      write("error setting myUChar"); writeln;
    end;
  end TSetUChar;

Output

myUChar successfully set to 255

Converting ASCII Representation of Hex String to Hex String Example

benchmark MyBenchmarkName

use "Kernel.bdh"

dcluser
  user
    VUser
  transactions
    TMain        : 1;

//converts each char to decimal value

dclfunc
  function GetDecFromAsciiHexStr(sAsciiHex: string): number
  var
    nDecPart : number;
    sTemp    : string;
    i, j     : number;
    nDec     : number;
    nFactor  : number;
  begin

    nDec := 0;
    for i:=1 to 2 do
      sTemp[1]:=sAsciiHex[i];

      if sTemp="0" then
        nDecPart := 0;
      elseif sTemp="1" then
        nDecPart := 1;
      elseif sTemp="2" then
        nDecPart := 2;
      elseif sTemp="3" then
        nDecPart := 3;
      elseif sTemp="4" then
        nDecPart := 4;
      elseif sTemp="5" then
        nDecPart := 5;
      elseif sTemp="6" then
        nDecPart := 6;
      elseif sTemp="7" then
        nDecPart := 7;
      elseif sTemp="8" then
        nDecPart := 8;
      elseif sTemp="9" then
        nDecPart := 9;
      elseif sTemp="A" then
        nDecPart := 10;
      elseif sTemp="B" then
        nDecPart := 11;
      elseif sTemp="C" then
        nDecPart := 12;
      elseif sTemp="D" then
        nDecPart := 13;
      elseif sTemp="E" then
        nDecPart := 14;
      elseif sTemp="F" then
        nDecPart := 15;
      end;

      if i=1 then
        nDecPart := nDecPart*16;
      end;

      nDec := nDec + nDecPart;
    end;

    GetDecFromAsciiHexStr := nDec;
  end GetDecFromAsciiHexStr;

dcltrans

  transaction TMain
  var
    sStringWithHexVal: string;
    nLengthS         : number;
    sAsciiHex        : string;
    sHex             : string;
    nDec             : number;
    i, j             : number;
  begin

    //example of string to convert
    sStringWithHexVal := "03CA00000041";

    print("sStringWithHexVal: "+ sStringWithHexVal);

    nLengthS := strlen(sStringWithHexVal);
    print("nLengthS: "+string(nLengthS));

    i := 1;
    j := 1;
    while i < nLengthS do   //rebuild string in hex using decimal values
      sAsciiHex := sStringWithHexVal[i]+sStringWithHexVal[i+1];
      nDec := GetDecFromAsciiHexStr(sAsciiHex);
      print(string(i)+": " + sAsciiHex + " -> " + string(nDec));
      SetUChar(sHex, j, nDec);
      j:= j + 1;
      i:= i + 2;
    end;

    writedata(sHex, BinLen(sHex), OPT_WRITEDATA_HEX); //result string

  end TMain;
Parent topic: Data Structure Functions
Related reference
GetUChar Function


GetUChar Function

Action

Retrieves a one-byte unsigned character from a specified data structure at a specified position. You must declare a BDL string before using this function.

Include file

Kernel.bdh

Syntax

GetUChar( in sBuffer : string,
          in nPos    : number ): number;

Return value

unsigned character

Parameter | Description
sBuffer | BDL string corresponding to the data structure
nPos | Starting position in the BDL string, where the first position is 1 (not 0)

Example

dcltrans
  transaction TGetUChar
  const
    SIZE_STRUCT := 32;
  var    myBDLstring : string(SIZE_STRUCT);
    nChar : number;
  begin
    ...
    // Retrieve a one-byte unsigned character from position 32
    // in the BDL string myBDLstring and thereby (through mapping) get
    // the element myUChar in Struct1
    nChar := GetUChar(myBDLstring, 32);
    write("myUChar = "); write(nChar); writeln;
  end TGetUChar;

Output

myUChar = 22
Parent topic: Data Structure Functions
Related reference
SetUChar Function


SetUShort Function

Action

Copies an unsigned short value (2-byte unsigned integer value) into a data structure at a specified position. You must declare a BDL string before using this function.

Include file

Kernel.bdh

Syntax

SetUShort( inout sString    :string,
           in    nPos       : number,
           in    nShort     : number,
           in    nByteOrder : number optional ): boolean;

Return value

  • true if successful

  • false otherwise

Parameter | Description
sString | BDL string corresponding to the data structure
nPos | Insert position in the BDL string, where the first position is 1 (not 0)
nShort | Unsigned short value
nByteOrder

Specifies the byte order that is applied when a value is set (optional). This parameter can be one of the following:

  • OPT_LITTLE_ENDIAN. Microsoft byte order (default).

  • OPT_BIG_ENDIAN. Network, Apple, Java byte order.

Example

dcltrans
  transaction TSetUShort
  const
    SIZE_STRUCT := 32;
  var
    myBDLstring : string(SIZE_STRUCT);
    bOk         : boolean;
  begin
    // Set a 2-byte unsigned character at position 20
    // in the BDL string myBDLstring and thereby (through mapping) set
    // the element myUShort in Struct1
    bOk := SetUShort(myBDLstring, 20, 64000);
    if bOk then
      write("myUShort successfully set to 64000");writeln;
    else
      write("error setting myUShort"); writeln;
    end;
  end TSetUShort;

Output

myUShort successfully set to 64000
Parent topic: Data Structure Functions
Related reference
GetUShort Function


GetUShort Function

Action

Retrieves an unsigned short value (2-byte unsigned integer value) from a specified data structure at a specified position. You must declare a BDL string before using this function.

Include file

Kernel.bdh

Syntax

GetUShort( in sBuffer    :string,
           in nPos       : number
           in nByteOrder : number optional ): number;

Return value

unsigned short value

Parameter | Description
sBuffer | BDL string corresponding to the data structure
nPos | Starting position in the BDL string, where the first position is 1 (not 0).
nByteOrder

Specifies the byte order that is applied when a value is retrieved (optional). This parameter can be one of the following:

  • OPT_LITTLE_ENDIAN. Microsoft byte order (default)

  • OPT_BIG_ENDIAN. Network, Apple, Java byte order.

Example

dcltrans
  transaction TGetUShort
  const
    SIZE_STRUCT := 32;
  var
    myBDLstring : string(SIZE_STRUCT);
    nShort      : number;
  begin
    ...
    // Retrieve a 2-byte unsigned character from position 20
    // in the BDL string myBDLstring and thereby (through mapping)
    // get the element myUShort in Struct1
    nShort := GetUShort(myBDLstring, 20);
    write("myUShort = "); write(nShort); writeln;
  end TGetUShort;

Output

myUShort = 189
Parent topic: Data Structure Functions
Related reference
SetUShort Function


SetWideChars Function

Action

Copies a sequence of wide characters to a specified position within a buffer.

Include file

tuxedo.bdh

Syntax

SetWideChars(
   in nBuffer    : number,
   in nStartPos  : number,
   in sSource    : string,
   in nMaxChars  : number,
   in nCharWidth : number,
   in nFillChar  : number optional ): boolean;

Return value

  • true if successful

  • false otherwise

Parameter | Description
nBuffer | Address of the destination buffer to which the sequence of wide characters should be copied.
nStartPos | Offset within the destination buffer to which the sequence of wide characters should be copied.
sSource | Sequence of characters that is to be copied to the destination buffer.
nMaxChars | Number of wide characters that should be copied to the destination buffer.
nCharWidth | Width of a wide character.
nFillChar | Character for filling the rest of the destination buffer (optional). This parameter is relevant if the amount of data you pass to the function is less than the number of wide characters you specify should be copied to the destination buffer.

Example

dcltrans
  transaction TMain
  var
    sSource, sDest, sResult : string;
    i : number;
  begin
    sSource := "Hello world!";
    SetWideChars(Adr(sDest),1, sSource,12,1);
    writeln(sDest);
    SetWideChars(Adr(sDest),1, sSource,12,2);
    sResult := "";
    for i := 1 to 24 do
      if sDest[i] = chr(0) then
        sResult := sResult + "_";
      else
        sResult := sResult + sDest[i];
      end;
    end;    writeln(sResult);
  end TMain;
Parent topic: Data Structure Functions


ZipCompressGzip Function

Action

Compresses a data buffer in gzip format. The resulting zipped buffer can be unzipped with the ZipUncompressGzip function or any gzip unzipper tool. The ZipCompressGzip function uses the deflate compression algorithm.

Include file

Zip.bdh

Syntax

ZipCompressGzip( in  sSource    : string,
                 in  nSrcLen    : number,
                 out sDest      : string,
                 in  nDstLen    : number optional,
                 out nOutLen    : number optional,
                 in  nCompLevel : number optional ) : boolean;

Return value

  • true if successful

  • false otherwise

Parameter | Description
sSource | Source buffer to be compressed in gzip format.
nSrcLen | Length of source buffer.
sDest | Destination buffer used to store the compressed data.
nDstLen | Length of destination buffer (optional).
nOutLen | Number of bytes used in the destination buffer to store the compressed data (optional).
nCompLevel

Level of compression. The compression level must be ZIP_COMPRESSION_DEFAULT, or between 0 and 9 (optional):

  • 1 gives best speed
  • 9 gives best compression
  • 0 gives no compression at all
  • ZIP_COMPRESSION_DEFAULT means a default compromise between speed and compression (currently equivalent to level 6).

Example

transaction TMain
var
  sUnzipped : string;
  sZipped   : string;
  i         : number;
  nUnzipped : number;
begin
  nUnzipped := sizeof(sUnzipped);
  for i := 1 to nUnzipped do
    sUnzipped[i] := chr(ord('a') + ((i-1) mod 26));
end;
  ZipCompressGzip(sUnzipped, STRING_COMPLETE, sZipped);
  WriteLn("Size of unzipped buffer: " + string(Binlen(sUnzipped)));
  WriteLn("Size of zipped buffer: " + string(Binlen(sZipped)));
  ZipUncompressGzip(sZipped, binlen(sZipped), sUnzipped);

  WriteData(sUnzipped);
end TMain;

Output:

Size of unzipped buffer: 254

Size of zipped buffer:   49

abcdefghijklmnopqrstuvwxyzabcdefghijklmnopqrstuvwxyzabcdefghijklmnopqrstuvwxyzabcdefghijklmnopqrstuvwxyz
abcdefghijklmnopqrstuvwxyzabcdefghijklmnopqrstuvwxyzabcdefghijklmnopqrstuvwxyzabcdefghijklmnopqrstuvwxyz
abcdefghijklmnopqrstuvwxyzabcdefghijklmnopqrst
Parent topic: Data Structure Functions
Related reference
ZipCompressGzip2 Function
ZipCompressZlib2 Function
ZipCompressZlib Function
ZipUncompressGzip2 Function
ZipUncompressGzip Function
ZipUncompressZlib2 Function
ZipUncompressZlib Function


ZipUncompressGzip Function

Action

Uncompresses a gzipped data buffer which was compressed with the ZipCompressGzip function.

Include file

Zip.bdh

Syntax

ZipUncompressGzip( in  sSource   : string,
                   in  nSrcLen   : number,
                   out sDest     : string,
                   in  nDstLen   : number optional,
                   out nOutLen   : number optional ) : boolean;

Return value

  • true if successful

  • false otherwise

Parameter | Description
sSource | Source buffer to be uncompressed.
nSrcLen | Length of source buffer.
sDest | Destination buffer used to store the uncompressed data.
nDstLen | Length of destination buffer (optional).
nOutLen | Number of bytes used in the destination buffer to store the uncompressed data (optional).

Example

transaction TMain
var
  sUnzipped: string;
  sZipped  : string;
  i        : number;
  nUnzipped: number;
  nZipped  : number;
begin
  nUnzipped := sizeof(sUnzipped);
  for i := 1 to nUnzipped do
    sUnzipped[i] := chr(ord('a') + ((i-1) mod 26));
end;
  ZipCompressGzip(sUnzipped, STRING_COMPLETE, sZipped);

  nZipped := sizeof(sZipped);
  WriteLn("Size of unzipped buffer: " + string(nUnzipped));
  WriteLn("Size of zipped buffer: " + string(nZipped));
  ZipUncompressGzip(sZipped, binlen (sZipped), sUnzipped);

  WriteData(sUnzipped);
end TMain;

Output:

Size of unzipped buffer: 254

Size of zipped buffer:   49

abcdefghijklmnopqrstuvwxyzabcdefghijklmnopqrstuvwxyzabcdefghijklmnopqrstuvwxyzabcdefghijklmnopqrstuvwxyz
abcdefghijklmnopqrstuvwxyzabcdefghijklmnopqrstuvwxyzabcdefghijklmnopqrstuvwxyzabcdefghijklmnopqrstuvwxyz
abcdefghijklmnopqrstuvwxyzabcdefghijklmnopqrst
Parent topic: Data Structure Functions
Related reference
ZipCompressGzip2 Function
ZipCompressGzip Function
ZipCompressZlib2 Function
ZipCompressZlib Function
ZipUncompressGzip2 Function
ZipUncompressZlib2 Function
ZipUncompressZlib Function


ZipCompressGzip2 Function

Action

Compresses a data buffer in gzip format. The resulting zipped buffer can be unzipped with the ZipUncompressGzip2 function or any gzip unzipper tool. The ZipCompressGzip2 function uses the deflate compression algorithm.

Include file

Zip.bdh

Syntax

ZipCompressGzip2( in  sSource    : string,
                  out sDest      : string,
                  in  nCompLevel : number optional ) : boolean;

Return value

  • true if successful

  • false otherwise

Parameter | Description
sSource | Source buffer to be compressed in gzip format.
sDest | Destination buffer used to store the compressed data.
nCompLevel

Level of compression. The compression level must be ZIP_COMPRESSION_DEFAULT, or between 0 and 9 (optional):

  • 1 gives best speed
  • 9 gives best compression
  • 0 gives no compression at all
  • ZIP_COMPRESSION_DEFAULT means a default compromise between speed and compression (currently equivalent to level 6).

Example

transaction TMain
var
  sUnzipped : string;
  sZipped   : string;
  i         : number;

begin
  for i := 1 to nUnzipped do
    sUnzipped[i] := chr(ord('a') + ((i-1) mod 26));
end;

  ZipCompressGzip2(sUnzipped, sZipped);
  WriteLn("Size of unzipped buffer: " + string(Binlen(sUnzipped)));
  WriteLn("Size of zipped buffer: " + string(Binlen(sZipped)));
  ZipUncompressGzip2(sZipped, binlen(sZipped), sUnzipped);

  WriteData(sUnzipped)
endTMain;

Output:

Size of unzipped buffer: 254

Size of zipped buffer:   49

abcdefghijklmnopqrstuvwxyzabcdefghijklmnopqrstuvwxyzabcdefghijklmnopqrstuvwxyzabcdefghijklmnopqrstuvwxyz
abcdefghijklmnopqrstuvwxyzabcdefghijklmnopqrstuvwxyzabcdefghijklmnopqrstuvwxyzabcdefghijklmnopqrstuvwxyz
abcdefghijklmnopqrstuvwxyzabcdefghijklmnopqrst
Parent topic: Data Structure Functions
Related reference
ZipCompressGzip Function
ZipCompressZlib2 Function
ZipCompressZlib Function
ZipUncompressGzip2 Function
ZipUncompressGzip Function
ZipUncompressZlib2 Function
ZipUncompressZlib Function


ZipUncompressGzip2 Function

Action

Uncompresses a gzipped data buffer which was compressed with the ZipCompressGzip2 function.

Include file

Zip.bdh

Syntax

ZipUncompressGzip2( in  sSource   : string,
                    out sDest     : string ) : boolean;

Return value

  • true if successful

  • false otherwise

Parameter | Description
sSource | Source buffer to be uncompressed.
sDest | Destination buffer used to store the uncompressed data.

Example

transaction TMain
var
  sUnzipped: string;
  sZipped  : string;
  i        : number;
  nUnzipped: number;
  nZipped  : number;

begin
  nUnzipped := sizeof(sUnzipped);
  for i := 1 to sizeof(sUnzipped) do
    sUnzipped[i] := chr(ord('a') + ((i-1) mod 26));
end;
  ZipCompressGzip2(sUnzipped, sZipped);

  nZipped := sizeof(sZipped);
  WriteLn("Size of unzipped buffer: " + string(nUnzipped));
  WriteLn("Size of zipped buffer: " + string(nZipped));
  ZipUncompressGzip2(sZipped,sUnzipped);

  WriteData(sUnzipped);
endTMain;

Output:

Size of unzipped buffer: 254

Size of zipped buffer:   49

abcdefghijklmnopqrstuvwxyzabcdefghijklmnopqrstuvwxyzabcdefghijklmnopqrstuvwxyzabcdefghijklmnopqrstuvwxyz
abcdefghijklmnopqrstuvwxyzabcdefghijklmnopqrstuvwxyzabcdefghijklmnopqrstuvwxyzabcdefghijklmnopqrstuvwxyz
abcdefghijklmnopqrstuvwxyzabcdefghijklmnopqrst
Parent topic: Data Structure Functions
Related reference
ZipCompressGzip2 Function
ZipCompressGzip Function
ZipCompressZlib2 Function
ZipCompressZlib Function
ZipUncompressGzip Function
ZipUncompressZlib2 Function
ZipUncompressZlib Function


ZipCompressZlib Function

Action

Compresses a data buffer in zLib format. The resulting zipped buffer can be unzipped with the ZipUncompressZlib function. The ZipCompressZlib function uses the deflate compression algorithm and prepends the zLib header.

Include file

Zip.bdh

Syntax

ZipCompressZLib( in  sSource    : string,
                 in  nSrcLen    : number,
                 out sDest      : string,
                 in  nDstLen    : number optional,
                 out nOutLen    : number optional,
                 in  nCompLevel : number optional ) : boolean;

Return value

  • true if successful

  • false otherwise

Parameter | Description
sSource | Source buffer to be compressed in zLib format.
nSrcLen | Length of source buffer.
sDest | Destination buffer used to store the compressed data.
nDstLen | Length of destination buffer (optional).
nOutLen | Number of bytes used in the destination buffer to store the compressed data (optional).
nCompLevel

Level of compression. The compression level must be ZIP_COMPRESSION_DEFAULT, or between 0 and 9 (optional):

  • 1 gives best speed
  • 9 gives best compression
  • 0 gives no compression at all
  • ZIP_COMPRESSION_DEFAULT means a default compromise between speed and compression (currently equivalent to level 6).

Example

transaction TMain
var
  sUnzipped: string;
  sZipped  : string;
  i        : number;
  nUnzipped: number;

begin
  nUnzipped := sizeof(sUnzipped);
  for i := 1 to nUnzipped do
    sUnzipped[i] := chr(ord('a') + ((i-1) mod 26));
end;
  ZipCompressZlib(sUnzipped, STRING_COMPLETE, sZipped);
  WriteLn("Size of unzipped buffer: " + string (Binlen(sUnzipped)));
  WriteLn("Size of zipped buffer: " + string (Binlen(sZipped)));
  ZipUncompressZlib(sZipped, binlen(sZipped), sUnzipped);

  WriteData(sUnzipped);
end TMain;

Output:

Size of unzipped buffer: 254

Size of zipped buffer:   37

abcdefghijklmnopqrstuvwxyzabcdefghijklmnopqrstuvwxyzabcdefghijklmnopqrstuvwxyzabcdefghijklmnopqrstuvwxyz
abcdefghijklmnopqrstuvwxyzabcdefghijklmnopqrstuvwxyzabcdefghijklmnopqrstuvwxyzabcdefghijklmnopqrstuvwxyz
abcdefghijklmnopqrstuvwxyzabcdefghijklmnopqrst
Parent topic: Data Structure Functions
Related reference
ZipCompressGzip2 Function
ZipCompressGzip Function
ZipCompressZlib2 Function
ZipUncompressGzip2 Function
ZipUncompressGzip Function
ZipUncompressZlib2 Function
ZipUncompressZlib Function


ZipCompressZlib2 Function

Action

Compresses a data buffer in zLib format. The resulting zipped buffer can be unzipped with the ZipUncompressZlib2 function. The ZipCompressZlib2 function uses the deflate compression algorithm and prepends the zLib header.

Include file

Zip.bdh

Syntax

ZipCompressZlib2( in  sSource    : string,
                  out sDest      : string,
                  in  nCompLevel : number optional ) : boolean;

Return value

  • true if successful

  • false otherwise

Parameter | Description
sSource | Source buffer to be compressed in zLib format.
sDest | Destination buffer used to store the compressed data.
nCompLevel

Level of compression. The compression level must be ZIP_COMPRESSION_DEFAULT, or between 0 and 9 (optional):

  • 1 gives best speed
  • 9 gives best compression
  • 0 gives no compression at all
  • ZIP_COMPRESSION_DEFAULT means a default compromise between speed and compression (currently equivalent to level 6).

Example

transaction TMain
var
  sUnzipped: string;
  sZipped  : string;
  i        : number;
begin
  for i := 1 to sizeof(sUnzipped) do
    sUnzipped[i] := chr(ord('a') + ((i-1) mod 26));
end;
  ZipCompressZlib2(sUnzipped, sZipped);
  WriteLn("Size of unzipped buffer: " + string(Binlen(sUnzipped)));
  WriteLn("Size of zipped buffer: " + string(Binlen(sZipped)));
  ZipUncompressZlib2(sZipped, sUnzipped);

  WriteData(sUnzipped)
endTMain;

Output:

Size of unzipped buffer: 254

Size of zipped buffer:   37

abcdefghijklmnopqrstuvwxyzabcdefghijklmnopqrstuvwxyzabcdefghijklmnopqrstuvwxyzabcdefghijklmnopqrstuvwxyz
abcdefghijklmnopqrstuvwxyzabcdefghijklmnopqrstuvwxyzabcdefghijklmnopqrstuvwxyzabcdefghijklmnopqrstuvwxyz
abcdefghijklmnopqrstuvwxyzabcdefghijklmnopqrst
Parent topic: Data Structure Functions
Related reference
ZipCompressGzip2 Function
ZipCompressGzip Function
ZipCompressZlib Function
ZipUncompressGzip2 Function
ZipUncompressGzip Function
ZipUncompressZlib2 Function
ZipUncompressZlib Function


ZipUncompressZlib Function

Action

Uncompresses a zipped data buffer, which was compressed with the ZipCompressZlib function.

Include file

Zip.bdh

Syntax

ZipUncompressZlib( in  sSource   : string,
                   in  nSrcLen   : number,
                   out sDest     : string,
                   in  nDstLen   : number optional,
                   out nOutLen   : number optional ) : boolean;

Return value

  • true if successful

  • false otherwise

Parameter | Description
sSource | Source buffer to be uncompressed.
nSrcLen | Length of source buffer.
sDest | Destination buffer used to store the uncompressed data.
nDstLen | Length of destination buffer (optional).
nOutLen | Number of bytes used in the destination buffer to store the uncompressed data (optional).

Example

transaction TMain
var
  sUnzipped: string;
  sZipped  : string;
  i        : number;
  nUnzipped: number;

begin
  nUnzipped := sizeof(sUnzipped);
  for i := 1 to nUnzipped do
    sUnzipped[i] := chr(ord('a') + ((i-1) mod 26));
end;
  ZipCompressZlib(sUnzipped, STRING_COMPLETE, sZipped);
  WriteLn("Size of unzipped buffer: " + string (Binlen(sUnzipped)));
  WriteLn("Size of zipped buffer: " + string (Binlen(sZipped)));
  ZipUncompressZlib(sZipped, binlen(sZipped), sUnzipped);

  WriteData(sUnzipped);
end TMain;

Output:

Size of unzipped buffer: 254

Size of zipped buffer:   37

abcdefghijklmnopqrstuvwxyzabcdefghijklmnopqrstuvwxyzabcdefghijklmnopqrstuvwxyzabcdefghijklmnopqrstuvwxyz
abcdefghijklmnopqrstuvwxyzabcdefghijklmnopqrstuvwxyzabcdefghijklmnopqrstuvwxyzabcdefghijklmnopqrstuvwxyz
abcdefghijklmnopqrstuvwxyzabcdefghijklmnopqrst
Parent topic: Data Structure Functions
Related reference
ZipCompressGzip2 Function
ZipCompressGzip Function
ZipCompressZlib2 Function
ZipCompressZlib Function
ZipUncompressGzip2 Function
ZipUncompressGzip Function
ZipUncompressZlib2 Function


ZipUncompressZlib2 Function

Action

Uncompresses a zipped data buffer, which was compressed with the ZipCompressZlib2 function.

Include file

Zip.bdh

Syntax

ZipUncompressZlib2( in  sSource   : string,
                    out sDest     : string ) : boolean;

Return value

  • true if successful

  • false otherwise

Parameter | Description
sSource | Source buffer to be uncompressed.
sDest | Destination buffer used to store the uncompressed data.

Example

transaction TMain
var
  sUnzipped: string;
  sZipped  : string;
  i        : number;

begin
  for i := 1 to sizeof(sUnzipped) do
    sUnzipped[i] := chr(ord('a') + ((i-1) mod 26));
end;
  ZipCompressZlib2(sUnzipped, sZipped);
  WriteLn("Size of unzipped buffer: " + string (Binlen(sUnzipped)));
  WriteLn("Size of zipped buffer: " + string (Binlen(sZipped)));
  ZipUncompressZlib2(sZipped, sUnzipped);

  WriteData(sUnzipped);
end TMain;

Output:

Size of unzipped buffer: 254

Size of zipped buffer:   37

abcdefghijklmnopqrstuvwxyzabcdefghijklmnopqrstuvwxyzabcdefghijklmnopqrstuvwxyzabcdefghijklmnopqrstuvwxyz
abcdefghijklmnopqrstuvwxyzabcdefghijklmnopqrstuvwxyzabcdefghijklmnopqrstuvwxyzabcdefghijklmnopqrstuvwxyz
abcdefghijklmnopqrstuvwxyzabcdefghijklmnopqrst
Parent topic: Data Structure Functions
Related reference
ZipCompressGzip2 Function
ZipCompressGzip Function
ZipCompressZlib2 Function
ZipCompressZlib Function
ZipUncompressGzip2 Function
ZipUncompressGzip Function
ZipUncompressZlib Function


Date Functions

Silk Performer provides a number of functions to get the current date and time from the operating system, and to generate random dates and time intervals.

  • FormatDate Function
    Converts a date into the specified format.
  • FormatDateTime Function
    Converts date and time into the specified format.
  • GetCurrentDate Function
    Returns the (local) current date in a YYYYMMDD format.
  • GetCurrentTime Function
    Returns the (local) time of the current day in seconds.
  • GetTime Function
    Returns the number of seconds elapsed since midnight (00:00:00), January 1, 1970 likewise as GMT or local time.
  • GetTimeStamp Function
    Returns the number of seconds or milliseconds elapsed since midnight (00:00:00), January 1, 1970 likewise as GMT or local time.
  • IncDate Function
    Adds a certain number of days to a date.
  • GetTickCount Function
    Retrieves the number of milliseconds that have elapsed since Windows was started.
  • IncFormatDate Function
    Adds a certain number of days to a date and converts it into the specified format.
  • RndDate Function
    Adds a random number of days between 0 and nDays to a date.
  • RndFormatDate Function
    Adds a random number of days between 0 and nDays to a date and formats this date into the specified format.
Parent topic: General Functions


FormatDate Function

Action

Converts a date into the specified format.

Include file

Kernel.bdh

Syntax

FormatDate( in nDate      :number,
            in sFormat    : string,
            in bLocalized : boolean optional) : string;

Return value

formatted date string

Parameter | Description
nDate | Integer input date with format YYYYMMDD, for example, 19980501 (May 1, 1998)
sFormat

Format control string. Possible format characters for date formatting:

  • %a. Abbreviated weekday name

  • %A. Full weekday name

  • %b. Abbreviated month name

  • %B. Full month name

  • %c. Locally appropriate date and time representation

  • %d. Day of month as decimal number (01 - 31)

  • %H. Hour in 24-hour format (00 - 23)

  • %I. Hour in 12-hour format (01 - 12)

  • %j. Day of year as decimal number (001 - 366)

  • %m. Month as decimal number (01 - 12)

  • %M. Minute as decimal number (00 - 59)

  • %p. Current locale’s A.M./P.M. indicator for 12-hour clock

  • %S. Second as decimal number (00 - 59)

  • %U. Week of year as decimal number, with Sunday as first day of week (00 - 51)

  • %w. Weekday as decimal number (0 - 6; Sunday is 0)

  • %W. Week of year as decimal number, with Monday as first day of week (00 - 51)

  • %x. Date representation for current locale

  • %X. Time representation for current locale

  • %y. Year without century, as decimal number (00 - 99)

  • %Y. Year with century, as decimal number

  • %z, %Z. Time-zone name or abbreviation; no characters if time zone is unknown

Default format strings:

  • DATE_YYYY_MM_DD = "%Y-%m-%d"

  • DATE_DEFAULT = "%x"

  • DATE_ODBC = "{d '%Y-%m-%d' }"

  • TIMESTAMP_ODBC = "{ts '%Y-%m-%d %H:%M:%S' }"

bLocalized | If True, returns the localized date format (optional).

Example

dcltrans
  transaction TFormatDate
  var
    nDate : number;
    sDate : string;
    sWeekday : string;
  begin
    nDate := GetCurrentDate();
    sDate := FormatDate(nDate, "%m/%d/%Y");
    sWeekday := FormatDate(nDate, "%A");
    print("Current Date: " + sDate);
    print("Today is " + sWeekday);
  end TFormatDate;

Output

Current Date: 08/27/2012
Today is Monday
Parent topic: Date Functions
Related reference
FormatDateTime Function


FormatDateTime Function

Action

Converts date and time into the specified format.

Include file

Kernel.bdh

Syntax

FormatDateTime( in  nDate      : number,
                in  nTime      : number,
                in  sFormat    : string,
                out sDate      : string,
                in  bLocalized : boolean optional ): string;

Return value

formatted date string

Parameter | Description
nDate | Input date with format YYYYMMDD.
nTime | Input time of current day in seconds.
sFormat | Format control string. See FormatDate function for a description of all format control strings.
sDate | Formatted date string.
bLocalized | If True, returns the localized date format (optional).

Example

dcltrans
  transaction TFormatDateTime
  var
  sDateTime: string;
begin
  FormatDateTime(19961015, 110, "%Y-%m-%d %H:%M:%S", sDateTime);
  write("datetime = "); write(sDateTime);
  writeln;
end TFormatDateTime;

Output

datetime = 1996-10-15 00:01:50

Sample scripts

MutexLogin.bdf

Parent topic: Date Functions
Related reference
FormatDate Function
GetCurrentDate Function


GetCurrentDate Function

Action

Returns the (local) current date in a YYYYMMDD format.

Include file

Kernel.bdh

Syntax

GetCurrentDate(): number;

Return value

Returns the (local) current date in a YYYYMMDD format.

Example

dcltrans
  transaction TGetCurrentDate
var
  nDate : number;
  sDateString : string;
begin
  nDate := GetCurrentDate();
  sDateString := FormatDate(nDate, DATE_DEFAULT);

  write("date = "); write(nDate); writeln;
  write("datestring = "); write(sDateString); writeln;
end TGetCurrentDate;

Output

date = 19980831datestring = 08/31/98
Parent topic: Date Functions
Related reference
GetCurrentTime Function
GetTickCount Function
FormatDateTime Function
GetTime Function
GetTimeStamp Function
IncDate Function
IncFormatDate Function
RndDate Function
RndFormatDate Function


GetCurrentTime Function

Action

Returns the (local) time of the current day in seconds.

Include file

Kernel.bdh

Syntax

GetCurrentTime(): number;

Return value

Returns the (local) time of the current day in seconds.

Example

dcltrans
  transaction TGetCurrentTime
var
  nDate, nTime : number;
  sDateTime : string;
begin
  nDate := GetCurrentDate();
  nTime := GetCurrentTime();
  FormatDateTime(nDate, nTime, "%x %X", sDateTime);

  write("date = "); write(nDate); writeln;
  write("time = "); write(nTime); writeln;
  write("datetime = "); write(sDateTime); writeln;
end TGetCurrentTime;

Output

date = 19980831
time = 37741
datetime = 08/31/98 10:29:01

Sample scripts

MutexLogin.bdf

Parent topic: Date Functions
Related reference
GetCurrentDate Function
GetTickCount Function
GetTime Function
GetTimeStamp Function


GetTime Function

Action

Returns the number of seconds elapsed since midnight (00:00:00), January 1, 1970 likewise as GMT or local time.

Include file

Kernel.bdh

Syntax

GetTime( in nFlags : number optional ): number;

Return value

The number of seconds elapsed since midnight, January 1, 1970.

Parameter Description
nFlags

This parameter can be one of the following flags (optional):

  • TIME_GMT: Returns GMT time (also known as UTC time; default).

  • TIME_LOCAL: Returns local time.

Example

transaction TTime
  var
    sTime : string;
    nTime : number;
  begin
    sTime := GetTimeStamp(TIMESTAMP_GMT | TIMESTAMP_IN_SEC);
    Print(sTime);
    nTime := GetTime(TIME_GMT);
    Print(string(nTime));
  end TTime;

Output

Number of seconds elapsed since January 1, 1970, GMT.

Parent topic: Date Functions
Related reference
GetTimeStamp Function
GetCurrentDate Function
GetCurrentTime Function


GetTimeStamp Function

Action

Returns the number of seconds or milliseconds elapsed since midnight (00:00:00), January 1, 1970 likewise as GMT or local time.

Include file

Kernel.bdh

Syntax

GetTimeStamp( in nFlags : number ): string;

Return value

String representation of the number of seconds or milliseconds.

Parameter Description
nFlags

Several combination of the following options are possible.

  • TIMESTAMP_GMT. Return GMT time.

  • TIMESTAMP_LOCAL. Return local time.

  • TIMESTAMP_IN_MS. Return time in milliseconds.

  • TIMESTAMP_IN_SEC. Return time in seconds.

  • TIMESTAMP_IN_HEX_LOWER. Return value in lowercase Hex. (for example: 0x0a)

  • TIMESTAMP_IN_HEX_UPPER. Return value in uppercase Hex. (for example: 0Ah)

Example

dcltrans
  transaction TRaiseError
  begin
    write(GetTimeStamp(TIMESTAMP_GMT | TIMESTAMP_IN_MS));
  end TRaiseError;
Parent topic: Date Functions
Related reference
GetTime Function
GetCurrentDate Function
GetCurrentTime Function


IncDate Function

Action

Adds a certain number of days to a date.

Include file

Kernel.bdh

Syntax

IncDate( in nDate: number,
         in nDays: number ): number;

Return value

increased date

Parameter | Description
nDate | Input date with format YYYYMMDD
nDays | Number of added days

Example

dcltrans
  transaction TIncDate
  var
    nNewDate: number;
  begin
    nNewDate := IncDate(19961015, 45);
    write("newdate = "); write(nNewDate); writeln;
  end TIncDate;

Output

newdate = 19961129
Parent topic: Date Functions
Related reference
IncFormatDate Function
GetCurrentDate Function


GetTickCount Function

Action

Retrieves the number of milliseconds that have elapsed since Windows was started. The function is limited to a resolution of about 25 milliseconds.

Include file

Kernel.bdh

Syntax

GetTickCount(): number;

Return value

number of milliseconds that have elapsed since Windows was started

Example

dcltrans
transaction TGetTickCount
var
nTickCount: number;
begin
nTickCount := GetTickCount();
write("Windows was started about "); write (nTickCount/60000);
write(" minutes ago.");
end TGetTickCount;

Output

Windows was started about 78 minutes ago.
Parent topic: Date Functions
Related reference
GetCurrentDate Function
GetCurrentTime Function


IncFormatDate Function

Action

Adds a certain number of days to a date and converts it into the specified format.

Include file

Kernel.bdh

Syntax

IncFormatDate( in nDate      :number,
                                  in nDays      :number,
                                  in sFormat    : string,
                                  in bLocalized : boolean optional ): string;

Return value

formatted date string

Parameter | Description
nDate | Input date with format YYYYMMDD
nDays | Number of added days
sFormat | Format control string (see FormatDate).
bLocalized | If True, returns the localized date format.

Example

dcltrans
  transaction TFormatDate
  var
    sNewDate: string;
  begin
    sNewDate := IncFormatDate(19961015, 45,
DATE_YYYY_MM_DD);
    write("newdate = "); write(sNewDate);
writeln;
  end TFormatDate;

Output

newdate = 1996-11-29
Parent topic: Date Functions
Related reference
IncDate Function
GetCurrentDate Function


RndDate Function

Action

Adds a random number of days between 0 and nDays to a date. The random values generated are distributed uniformly.

Include file

Kernel.bdh

Syntax

RndDate( in nDate : number,
         in nDays : number ): number;

Return value

increased date

Parameter | Description
nDate | Input date with format YYYYMMDD
nDays | Upper boundary of random interval for days to add

Example

dcltrans
  transaction TRndDate
  var
    nDate: number;
  begin
    // add 0 - 20 days to 19961015
    nDate := RndDate(19961015, 20);
    write("date = "); write(nDate); writeln;
  end TRndDate;

Output

date = 19961022
Parent topic: Date Functions
Related reference
RndFormatDate Function
GetCurrentDate Function


RndFormatDate Function

Action

Adds a random number of days between 0 and nDays to a date and formats this date into the specified format. The random values generated are distributed uniformly.

Include file

Kernel.bdh

Syntax

RndFormatDate( in nDate      : number,
               in nDays      : number,
               in sFormat    : string,
               in bLocalized : boolean optional ): string;

Return value

formatted date string

Parameter | Description
nDate | Input date with format YYYYMMDD
nDays | Upper boundary of random interval for days to add
sFormat | Format control string (see FormatDate)
bLocalized | If True, returns the localized date format (optional).

Example

dcltrans
  transaction TRndFormatDate
  var
    sNewDate: string;
  begin
    // add 0 - 20 days to 19961015 and format it to "1996-11-10"
    sNewDate := RndFormatDate(19961015, 20, DATE_YYYY_MM_DD);
    write("newdate = "); write(sNewDate); writeln;
  end TRndFormatDate;

Output

newdate = 1996-10-30

Sample scripts

OraSample.bdf, DBApi01.bdf

Parent topic: Date Functions
Related reference
RndDate Function
GetCurrentDate Function


Error-Handling Functions

Silk Performer offers several functions to handle unexpected situations during a load or verification test. Unexpected situations mostly end up in warnings or errors.

A commonly used mechanism to query the current state during a virtual user run is the last error. The last error describes not more than the last error that occurred.

If several errors occurred at about the same time, only the last one is stored and can therefore be retrieved. Silk Performer goes a step beyond and lets the user access not only the last error but also some relevant errors that occurred before the last error. Each virtual user holds a so-called error stack where it stores errors for each erroneous function call.

The error stack is per function call and enables you to retrieve not only the last error but all errors of one erroneous function call. A next function call clears that error stack of the last function.

To step through the error stack the following error functions are provided:

  • GetFirstError: Retrieves the first error from the error stack.
  • GetNextError: Retrieves the next error from the error stack.
  • GetLastError: Retrieves the last error from the error stack.

An error consists of an error code, a facility and a severity.

The severity of an error can be one of the following values:
  • SEVERITY_SUCCESS: Success; no error (numerical value: 0)
  • SEVERITY_INFORMATIONAL: Informational; no error (numerical value: 1)
  • SEVERITY_WARNING: Warning; no error (numerical value: 2)
  • SEVERITY_ERROR: (Default) Error; simulation continues (numerical value: 3)
  • SEVERITY_TRANS_EXIT: Error; the active transaction is aborted (numerical value: 4)
  • SEVERITY_PROCESS_EXIT: Error; the simulation is aborted (numerical value: 5)

The error facility is provided as a way to categorize errors in respect to the area or module in which they originate.

To retrieve further information about a particular error the following functions are provided:

  • GetErrorCode: Retrieves error number (code).
  • GetErrorFacility: Retrieves the name of the severity level.
  • GetErrorSeverity: Retrieves the severeness level of an error.
  • GetErrorMsg: Retrieves the error message corresponding to an error code.

To create an error code and raise an error use the following functions:

  • CreateErrorCode: Creates an error code using severity, facility, and error number within the facility as parameters.
  • RaiseError: This function can be used to raise an error.

Silk Performer offers the possibility to redefine (overwrite) the default severity of an error. This is useful in several scenarios. For example, the simulator is reporting an error with severity SEVERITY_ERROR but the user does not want to consider it to be a real error. In this case the user is able to overwrite the default severity with SEVERITY_INFORMATIONAL. This affects the simulator also, which does not increase the error count if this particular error occurs.

Functions, which allow severity manipulations, are:

  • ErrorAdd: Defines the severity of a particular problem.
  • ErrorRemove: Removes the custom severity definition for a particular problem.

Facility values:

Facility value | Numeric value
FACILITY_SILKPERFORMER | 1
FACILITY_WEBENGINE | 2
FACILITY_HTTP | 3
FACILITY_IIOP | 4
FACILITY_COMMONLIB | 5
FACILITY_WINSOCK | 6
FACILITY_SSL | 7
FACILITY_POP | 8
FACILITY_SMTP | 9
FACILITY_LDAP | 10
FACILITY_ODBC | 11
FACILITY_EVENTLOG | 13
FACILITY_SCRIPTENGINE | 14
FACILITY_PERFORB | 15
FACILITY_FTP | 16
FACILITY_SERVICE | 17
FACILITY_ORA | 20
FACILITY_PROXYENGINE | 21
FACILITY_PERFORMANCE | 22
FACILITY_TUXEDO | 23
FACILITY_OCI | 24
FACILITY_REPO | 25
FACILITY_RT | 26
FACILITY_PERFLM | 27
FACILITY_JOLT | 28
FACILITY_COM | 29
FACILITY_LTC | 30
FACILITY_PDH | 31
FACILITY_PERFSYSCONF | 32
FACILITY_RESERR | 33
FACILITY_COMERR | 34
FACILITY_RUNERR | 35
FACILITY_XML | 36
FACILITY_IPC | 37
FACILITY_PDCE | 38
FACILITY_COMREPLAY | 39
FACILITY_SAL | 40
FACILITY_TSD | 41
FACILITY_WAP | 42
FACILITY_REMOTESETUP | 43
FACILITY_EXECMANAGER | 44
FACILITY_CHARTENGINE | 45
FACILITY_XMLLAUNCHERLIB | 46
FACILITY_XMLDOMLIB | 47
FACILITY_DOTNETLIB | 48
FACILITY_RECORDERCONTROL | 49
FACILITY_PMI | 50
FACILITY_SILKVISION | 51
FACILITY_DBREPLAY | 52
FACILITY_PERFSERVLET | 53
FACILITY_CUSTOM_API | 54
FACILITY_ORACLE_FORMS | 55
FACILITY_CITRIXENGINE | 56
FACILITY_OCRLIB | 57
FACILITY_SHUNRALOADMANAGER | 58
FACILITY_SAPGUI | 59
FACILITY_MAPI | 60
FACILITY_COMPILER | 61
FACILITY_GUILEVEL_TESTING_REPLAY | 66
FACILITY_BROWSERENGINE | 71
FACILITY_NATIVE_HTTP | 1001
FACILITY_NATIVE_JAVA | 1002
FACILITY_NATIVE_JOLT | 1003
FACILITY_NATIVE_LDAP | 1004
FACILITY_NATIVE_MEDIASTREAM | 1005
FACILITY_NATIVE_OCI | 1006
FACILITY_NATIVE_WAP | 1007
FACILITY_NATIVE_REALSTREAM | 1008
FACILITY_NATIVE_ATMI | 1009
FACILITY_NATIVE_FML | 1010
  • ErrorAdd Function
    Defines the severity of a particular problem.
  • ErrorRemove Function
    Removes the custom severity definition for a particular problem.
  • GetErrorCode Function
    Retrieves error number (code).
  • GetErrorFacility Function
    Retrieves the facility of an error.
  • GetErrorSeverity Function
    Retrieves the severity level of an error.
  • GetErrorMsg Function
    Retrieves the error message corresponding to an error code.
  • GetFirstError Function
    Retrieves the first error from the error stack.
  • GetNextError Function
    Retrieves the next error from the error stack.
  • GetLastError Function
    Retrieves the last error from the error stack.
  • CreateErrorCode Function
    Creates an error code using severity, facility, and error number within the facility as parameters.
  • RaiseError Function
    Raises an error.
  • SetErrorsSeverity Function
    Sets the severity of a whole facility.
  • ResetErrorsSeverity Function
    Resets the severity of a facility to its default value.
Parent topic: General Functions
Related concepts
Logging Functions Overview
Error Message Overview


ErrorAdd Function

Action

Defines the severity of a particular problem. If the problem occurs during a test, Silk Performer terminates either the current transaction or the entire simulation, depending on the severity that you have defined for the problem.

Include file

Kernel.bdh

Syntax

ErrorAdd( in nFacility : number,
          in nCode     : number,
          in nSeverity : number );
Parameter | Description
nFacility | Specifies the module that can cause the problem for which you define the severity.
nCode | Error code of the problem for which you want to define the severity. For a list of error codes, select Settings/Active Profile from the Silk Performer menu bar, select the Replay category, click the Simulation icon, switch to the Errors tab, and click Add. In the ensuing dialog, select the respective module from the Module drop-down list to see a list of error codes.
nSeverity Severity of the error that is raised if the verification fails. Can be one of the following values:
  • SEVERITY_SUCCESS: Success; no error (numerical value: 0)
  • SEVERITY_INFORMATIONAL: Informational; no error (numerical value: 1)
  • SEVERITY_WARNING: Warning; no error (numerical value: 2)
  • SEVERITY_ERROR: Error; simulation continues (numerical value: 3)
  • SEVERITY_TRANS_EXIT: Error; the active transaction is aborted (numerical value: 4)
  • SEVERITY_PROCESS_EXIT: Error; the simulation is aborted (numerical value: 5)

Example

dcltrans
  transaction TMain
  begin
    ErrorAdd(FACILITY_HTTP,401, SEVERITY_INFORMATIONAL);
    WebPageUrl("http://standardhost/","Home");
    ErrorRemove(FACILITY_HTTP, 401);
  end TMain;
Parent topic: Error-Handling Functions


ErrorRemove Function

Action

Removes the custom severity definition for a particular problem.

Include file

Kernel.bdh

Syntax

ErrorRemove( in Facility : number,
                 in nCode    : number );
Parameter | Description
nFacility | Specifies the module that can cause the problem for which you remove the severity definition.
nCode | Error code of the problem for which you want to remove the severity definition. For a list of error codes, select Settings/Active Profile from the Silk Performer menu bar, select the Replay category, click the Simulation icon, switch to the Errors tab, and click Add. In the ensuing dialog, select the respective module from the Module drop-down list to see a list of error codes.

Example

dcltrans
  transaction TMain
  begin
    ErrorAdd(FACILITY_HTTP,401, SEVERITY_INFORMATIONAL);
    WebPageUrl("http://standardhost/","Home");
    ErrorRemove(FACILITY_HTTP,401);
  end TMain;
Parent topic: Error-Handling Functions


GetErrorCode Function

Action

Retrieves error number (code).

An error code consits of the following three units:

  • severity

  • facility

  • error number

This function returns the error number part of it.

Include file

Kernel.bdh

Syntax

GetErrorCode( in nError : number ): number;

Return value

The error number (code).

Parameter | Description
nError | Specifies the error code.

Example

dclfunc
  function PrintErrorStack
  var
    sError : string;
    sErrorNumber : string;
    sFacility : string;
    sSeverity : string;
    x : number;
    y : number;
  begin
    // get last error
    x := GetLastError();

    sErrorNumber := String(GetErrorCode(x));
    sFacility := String(GetErrorFacility(x));
    sSeverity := String(GetErrorSeverity(x));
    Print("Last Error: (Error Nr.: " + sErrorNumber + ", Facility: " + sFacility + ", Severity: " + sSeverity + ")");
    Print(" = " + GetErrorMsg(x));

    // get error stack
    x := GetFirstError(y, 0, 0, sError);
    while x <> 0 do
      Print("Stack: " + String(x) + "; " + sError + "; " + String(y));
      Print(" = " + GetErrorMsg(x));
      x := GetNextError(y, 0, 0, sError);
    end;
  end PrintErrorStack;

Output

Last Error: (Error Nr.: 5, Facility: 5, Severity: 3) = SYSTEM: 5 - The handle is incorrect.
Parent topic: Error-Handling Functions


GetErrorFacility Function

Action

Retrieves the facility of an error.

An error code consists of the following three units:

  • severity

  • facility

  • error number

This function returns the facility part of it.

Include file

Kernel.bdh

Syntax

GetErrorFacility( in nError : numbe ): number;

Return value

The facility of an error.

Parameter | Description
nError | Specifies the severity value (NOT the error code).

Example

dclfunc
  function PrintErrorStack
  var
    sError : string;
    sErrorNumber : string;
    sFacility : string;
    sSeverity : string;
    x : number;
    y : number;
  begin
    // get last error
    x := GetLastError();
    sErrorNumber := String(GetErrorCode(x));
    sFacility    := String(GetErrorFacility(x));
    sSeverity    := String(GetErrorSeverity(x));
    Print("Last Error: (Error Nr.: " + sErrorNumber + ", Facility: " + sFacility + ", Severity: " + sSeverity + ")");
    Print(" = " + GetErrorMsg(x));

    // get error stack
    x := GetFirstError(y, 0, 0, sError);
    while x <> 0 do
      Print("Stack: " + String(x) + "; " + sError + "; " + String(y));
      Print(" = " + GetErrorMsg(x));
      x := GetNextError(y, 0, 0, sError);
    end;
  end PrintErrorStack;

Output

Last Error: (Error Nr.: 5, Facility: 5, Severity: 3) = SYSTEM: 5 - The handle is incorrect.
Parent topic: Error-Handling Functions


GetErrorSeverity Function

Action

Retrieves the severity level of an error.

An error code consits of the following three units:

  • severity

  • facility

  • error number

This function returns the severity part of it.

Include file

Kernel.bdh

Syntax

GetErrorSeverity( in nError: number ): number;

Return value

The severity level of an error.

Parameter | Description
nError | Specifies the Error code (usually retrieved with GetLastError()).

Example

dclfunc
  function PrintErrorStack
  var
    sError : string;
    sErrorNumber : string;
    sFacility : string;
    sSeverity : string;
    x : number;
    y : number;
  begin
    // get last error
    x := GetLastError();

    sErrorNumber := String(GetErrorCode(x));
    sFacility := String(GetErrorFacility(x));
    sSeverity := String(GetErrorSeverity(x));
    Print("Last Error: (Error Nr.: " + sErrorNumber + ", Facility: " + sFacility + ", Severity: " + sSeverity + ")");
    Print(" = " + GetErrorMsg(x));

    // get error stack
    x := GetFirstError(y, 0, 0, sError);

    while x <> 0 do
      Print("Stack: " + String(x) + "; " + sError + "; " + String(y));
      Print(" = " + GetErrorMsg(x));
      x := GetNextError(y, 0, 0, sError);
    end;
  end PrintErrorStack;

Output

Last Error: (Error Nr.: 5, Facility: 5, Severity: 3) = SYSTEM: 5 - The handle is incorrect.
Parent topic: Error-Handling Functions


GetErrorMsg Function

Action

Retrieves the error message corresponding to an error code.

Include file

Kernel.bdh

Syntax

GetErrorMsg( in  nErrorCode   : number,
             out sErrorMsg    : string optional,
             in  nMaxErrorMsg : number optional): string;

Return value

Corresponding error message

Parameter | Description
nErrorCode | Error code
sErrorMsg | String buffer receiving the corresponding error message (optional)
nMaxErrorMsg | Length of the string buffer (optional)

Example

dcltrans
  transaction TMain
  var
    i : number;
    sErrorMsg : string;
  begin
    for i := 0 to 10 do
      write(GetErrorMsg(i)); writeln;
    end;

    for i := 11 to 20 DO
      GetErrorMsg(i, sErrorMsg);
      write(sErrorMsg); writeln;
    end;
  end TMain;

Output

System: 0 - The operation completed successfully.
System: 1 - Incorrect function.
System: 2 - The system cannot find the file specified.
System: 3 - The system cannot find the path specified.
System: 4 - The system cannot open the file.
System: 5 - Access is denied.
...

Sample scripts

WebRegularExpressions01.bdf

Parent topic: Error-Handling Functions
Related reference
Event Handler Section


GetFirstError Function

Action

Retrieves the first error from the error stack.

Certain conditions can be specified by the first two parameters for the retrieval of an error.

Include file

Kernel.bdh

Syntax

GetFirstError( out nCustomSeverity : number optional,
               in  nFacility       : number optional,
               in  nSeverityFlags  : number optional,
               out sAddInformation : string optional,
               in  nAddInfoSize    : number optional,
               out nLine           : number optional,
               out sFilename       : string optional,
               in  nFileNameSize   : number optional ) : number;

Return value

error code. 0 if no error could be found.

Parameter | Description
nCustomSeverity | Receives the custom level of severity. If the custom level was not set, then the original severity of the error is returned.
nFacility | If this parameter is > 0 then the facility of the returned error must match.
nSeverity Optional: Severity of the error that is raised if the verification fails. Can be one of the following values:
  • SEVERITY_SUCCESS: Success; no error (numerical value: 0)
  • SEVERITY_INFORMATIONAL: Informational; no error (numerical value: 1)
  • SEVERITY_WARNING: Warning; no error (numerical value: 2)
  • SEVERITY_ERROR: (Default) Error; simulation continues (numerical value: 3)
  • SEVERITY_TRANS_EXIT: Error; the active transaction is aborted (numerical value: 4)
  • SEVERITY_PROCESS_EXIT: Error; the simulation is aborted (numerical value: 5)
sAddInformation | Specifies the buffer to receive additional information.
nAddInfoSize | Specifies the length of the buffer, which receives the additional information.
nLine | Receives the line number in the script where the error occured.
sFilename | Specifies the buffer to receive the script file name.
nFileNameSize | Specifies the length of the buffer, which receives the script file name.

Example

dclfunc
  function PrintErrorStack
  var
    sError       : string;
    sErrorNumber : string;
    sFacility    : string;
    sSeverity    : string;
    nResult      : number;

    x : number;
    y : number;
  begin
    // get last error
    x := GetLastError();
    sErrorNumber := String(GetErrorCode(x));
    sFacility := String(GetErrorFacility(x));
    sSeverity := String(GetErrorSeverity(x));
    Print("Last Error: (Error Nr.: " + sErrorNumber + ", Facility: " + sFacility + ", Severity: " + sSeverity + ")");
    Print(" = " + GetErrorMsg(x));
    // get error stack
    WebVerifyTitle("Buy It");
    WebVerifyContent("Html", 3, "Right", WEB_VER_FLAG_CONTENT_SMALLER, SEVERITY_ERROR, true, nResult);
    WebPageUrl ("http://mycompany.com/frame/framea.html");
    x := GetFirstError(y, 0, 0, sError);

    while x <> 0 do
      Print("Stack: " + String(x) + "; " + sError + "; " + String(y));
      Print(" = " + GetErrorMsg(x));
      x := GetNextError(y, 0, 0, sError);
    end;
  end PrintErrorStack;

Output

Last Error: (Error Nr.: 5, Facility: 5, Severity: 3) = SYSTEM: 5 - The handle is incorrect.
Parent topic: Error-Handling Functions


GetNextError Function

Action

Retrieves the next error from the error stack.

Certain conditions can be specified by the first two parameters for the retieval of an error.

Include file

Kernel.bdh

Syntax

GetNextError( out nCustomSeverity : number optional,
              in  nFacility       : number optional,
              in  nSeverityFlags  : number optional,
              out sAddInformation : string optional,
              in  nAddInfoSize    : number optional,
              out nLine           : number optional,
              out sFilename       : string optional,
              in  nFileNameSize   : number optional ) : number;

Return value

error code. 0 if no error could be found.

Parameter | Description
nCustomSeverity | Receives the custom level of severity. If the custom level was not set, then the original severity of the error is returned.
nFacility | If this parameter is > 0 then the facility of the returned error must match.
nSeverity Optional: Severity of the error that is raised if the verification fails. Can be one of the following values:
  • SEVERITY_SUCCESS: Success; no error (numerical value: 0)
  • SEVERITY_INFORMATIONAL: Informational; no error (numerical value: 1)
  • SEVERITY_WARNING: Warning; no error (numerical value: 2)
  • SEVERITY_ERROR: (Default) Error; simulation continues (numerical value: 3)
  • SEVERITY_TRANS_EXIT: Error; the active transaction is aborted (numerical value: 4)
  • SEVERITY_PROCESS_EXIT: Error; the simulation is aborted (numerical value: 5)
sAddInformation | Specifies the buffer to receive additional information.
nAddInfoSize | Specifies the length of the buffer, which receives the additional information.
nLine | Receives the line number in the script where the error occured.
sFilename | Specifies the buffer to receive the script file name.
nFileNameSize | Specifies the length of the buffer, which receives the script file name.

Example

dclfunc
  function PrintErrorStack
  var
    sError       : string;
    sErrorNumber : string;
    sFacility    : string;
    sSeverity    : string;
    nResult      : number;

    x : number;
    y : number;
  begin
    // get last error
    x := GetLastError();
    sErrorNumber := String(GetErrorCode(x));
    sFacility := String(GetErrorFacility(x));
    sSeverity := String(GetErrorSeverity(x));
    Print("Last Error: (Error Nr.: " + sErrorNumber + ", Facility: " + sFacility + ", Severity: " + sSeverity + ")");
    Print(" = " + GetErrorMsg(x));
    // get error stack
    WebVerifyTitle("Buy It");
    WebVerifyContent("Html", 3, "Right", WEB_VER_FLAG_CONTENT_SMALLER, SEVERITY_ERROR, true, nResult);
    WebPageUrl ("http://mycompany.com/frame/framea.html");
    x := GetFirstError(y, 0, 0, sError);

    while x <> 0 do
      Print("Stack: " + String(x) + "; " + sError + "; " + String(y));
      Print(" = " + GetErrorMsg(x));
      x := GetNextError(y, 0, 0, sError);
    end;
  end PrintErrorStack;

Output

Last Error: (Error Nr.: 5, Facility: 5, Severity: 3) = SYSTEM: 5 - The handle is incorrect.
Parent topic: Error-Handling Functions
Related concepts
Error-Handling Functions
Logging Functions Overview


GetLastError Function

Action

Retrieves the last error from the error stack.

Certain conditions can be specified by the first two parameters for the retrieval of an error.

Include file

Kernel.bdh

Syntax

GetLastError( out nCustomSeverity : number optional,
              in  nFacility       : number optional,
              in  nSeverityFlags  : number optional,
              out sAddInformation : string optional,
              in  nAddInfoSize    : number optional,
              out nuLine          : number optional,
              out sFilename       : string optional,
              in  uFileNameSize   : number optional ) : number;

Return value

error code. 0 if no error could be found.

Parameter | Description
nCustomSeverity | Receives the custom level of severity. If the custom level was not set, then the original severity of the error is returned.
nFacility | If this parameter is > 0 then the facility of the returned error must match.
nSeverity Optional: Severity of the error that is raised if the verification fails. Can be one of the following values:
  • SEVERITY_SUCCESS: Success; no error (numerical value: 0)
  • SEVERITY_INFORMATIONAL: Informational; no error (numerical value: 1)
  • SEVERITY_WARNING: Warning; no error (numerical value: 2)
  • SEVERITY_ERROR: (Default) Error; simulation continues (numerical value: 3)
  • SEVERITY_TRANS_EXIT: Error; the active transaction is aborted (numerical value: 4)
  • SEVERITY_PROCESS_EXIT: Error; the simulation is aborted (numerical value: 5)
sAddInformation | Specifies the buffer to receive additional information.
nAddInfoSize | Specifies the length of the buffer, which receives the additional information.
nLine | Receives the line number in the script where the error occured.
sFilename | Specifies the buffer to receive the script file name.
uFileNameSize | Specifies the length of the buffer, which receives the script file name.

Example

dclfunc
  function PrintErrorStack
  var
    sError       : string;
    sErrorNumber : string;
    sFacility    : string;
    sSeverity    : string;
    nResult      : number;

    x : number;
    y : number;
  begin
    // get last error
    x := GetLastError();
    sErrorNumber := String(GetErrorCode(x));
    sFacility := String(GetErrorFacility(x));
    sSeverity := String(GetErrorSeverity(x));
    Print("Last Error: (Error Nr.: " + sErrorNumber + ", Facility: " + sFacility + ", Severity: " + sSeverity + ")");
    Print(" = " + GetErrorMsg(x));
    // get error stack
    WebVerifyTitle("Buy It");
    WebVerifyContent("Html", 3, "Right", WEB_VER_FLAG_CONTENT_SMALLER, SEVERITY_ERROR, true, nResult);
    WebPageUrl ("http://mycompany.com/frame/framea.html");
    x := GetFirstError(y, 0, 0, sError);

    while x <> 0 do
      Print("Stack: " + String(x) + "; " + sError + "; " + String(y));
      Print(" = " + GetErrorMsg(x));
      x := GetNextError(y, 0, 0, sError);
    end;
  end PrintErrorStack;

Output

Last Error: (Error Nr.: 5, Facility: 5, Severity: 3) = SYSTEM: 5 - The handle is incorrect.
Parent topic: Error-Handling Functions


CreateErrorCode Function

Action

Creates an error code using severity, facility, and error number within the facility as parameters.

Include file

Kernel.bdh

Syntax

CreateErrorCode( in nFacility : number,
                 in nCode     : number,
                 in nSeverity : number ) : number;

Return value

The created error code.

Parameter | Description
iFacility | Specifies the module that can cause the problem for which you define the error code.
nCode | Specifies the error code that you want to create.
nSeverity
Severity of the error that is raised if the verification fails. Can be one of the following values:
  • SEVERITY_SUCCESS: Success; no error (numerical value: 0)
  • SEVERITY_INFORMATIONAL: Informational; no error (numerical value: 1)
  • SEVERITY_WARNING: Warning; no error (numerical value: 2)
  • SEVERITY_ERROR: Error; simulation continues (numerical value: 3)
  • SEVERITY_TRANS_EXIT: Error; the active transaction is aborted (numerical value: 4)
  • SEVERITY_PROCESS_EXIT: Error; the simulation is aborted (numerical value: 5)

Example

dcltrans
  transaction TMain
  var
    hIiop0 : number;
  begin
    IiopObjectCreate(hIiop0, "IDL:Object:1.0", "1.2","someserver", 12345, "key", 3);
    IiopRequest(hIiop0, "ReturnNoData");
    IiopGetBoolean(hIiop0); // generates an "Out of data" error.
  end TMain;

dclevent
  handler OnError <EVENT_RAISE_WARNING>
  begin
    // catch "IIOP 21 - Out of data" and report a user friendly error message
    if GetLastError() = CreateErrorCode (FACILITY_IIOP, 21, SEVERITY_ERROR) then
      RaiseError(0, "IIOP stream parsing error.", SEVERITY_ERROR);
    else
      throw;
    end;
  end OnError;
Parent topic: Error-Handling Functions


RaiseError Function

Action

This function can be used to raise an error.

Include file

Kernel.bdh

Syntax

RaiseError( in nErrorCode      : number,
            in sMessage        : string optional,
            in nCustomSeverity : number optional := SEVERITY_ERROR );
Parameter | Description
nErrorCode

Specifies the error code that you want to raise. Specify 0 to refer to the last error. The following predefined error codes exist:

  • CUSTOM_MESSAGE: default severity ‘informational’

  • CUSTOM_ERROR: default severity ‘error’

Custom error codes can be created with the CreateErrorCode function.

sMessage | Specifies the message for the raised error. Optional parameter.
nCustomSeverity

Custom severity of the problem. Can be specified if the error should not use the standard severity for the specified error code (optional parameter).

  • SEVERITY_SUCCESS - Success, no error
  • SEVERITY_INFORMATIONAL - Informational
  • SEVERITY_WARNING - Warning
  • SEVERITY_ERROR - Error, simulation continues
  • SEVERITY_TRANS_EXIT - Error, the active transaction is aborted
  • SEVERITY_PROCESS_EXIT - Error, the simulation is aborted.

Example

dcltrans
  transaction TMain
  var
    hIiop0 : number;
  begin
    IiopObjectCreate(hIiop0, "IDL:Object:1.0", "1.2", "someserver", 12345, "key", 3);
    IiopRequest(hIiop0, "ReturnNoData");
    IiopGetBoolean(hIiop0); // generates an "Out of data" error.
  end TMain;

dclevent
  handler OnError <EVENT_RAISE_WARNING>
  begin
    // catch "IIOP 21 - Out of data" and report a user friendly error message
    if GetLastError() = CreateErrorCode (FACILITY_IIOP, 21, SEVERITY_ERROR) then
      RaiseError(0, "IIOP stream parsing error.", SEVERITY_ERROR);
    else
      throw;
    end;
  end OnError;
Parent topic: Error-Handling Functions


SetErrorsSeverity Function

Action

Sets the severity of a whole facility.

Include file

kernel.bdh

Syntax

SetErrorsSeverity( in eFacility    : number,
                   in eNewSeverity : number,
                   in eOldSeverity : number optional := SEVERITY_ERROR );
Parameter Description
eFacility The following facilities are valid:
  • FACILITY_SILKPERFORMER
  • FACILITY_WEBENGINE
  • FACILITY_HTTP
  • FACILITY_IIOP
  • FACILITY_COMMONLIB
  • FACILITY_WINSOCK
  • FACILITY_SSL
  • FACILITY_POP
  • FACILITY_SMTP
  • FACILITY_LDAP
  • FACILITY_ODBC
  • FACILITY_EVENTLOG
  • FACILITY_SCRIPTENGINE
  • FACILITY_PERFORB
  • FACILITY_FTP
  • FACILITY_SERVICE
  • FACILITY_ORA
  • FACILITY_PROXYENGINE
  • FACILITY_PERFORMANCE
  • FACILITY_TUXEDO
  • FACILITY_OCI
  • FACILITY_REPO
  • FACILITY_RT
  • FACILITY_JOLT
  • FACILITY_COM
  • FACILITY_LTC
  • FACILITY_PDH
  • FACILITY_PERFSYSCONF
  • FACILITY_RESERR
  • FACILITY_COMERR
  • FACILITY_RUNERR
  • FACILITY_XML
  • FACILITY_IPC
  • FACILITY_PDCE
  • FACILITY_COMREPLAY
  • FACILITY_SAL
  • FACILITY_TSD
  • FACILITY_WAP
  • FACILITY_REMOTESETUP
  • FACILITY_EXECMANAGER
  • FACILITY_CHARTENGINE
  • FACILITY_XMLLAUNCHERLIB
  • FACILITY_XMLDOMLIB
  • FACILITY_DOTNETLIB
  • FACILITY_RECORDERCONTROL
  • FACILITY_PMI
  • FACILITY_SILKVISION
  • FACILITY_DBREPLAY
  • FACILITY_PERFSERVLET
  • FACILITY_CUSTOM_API
  • FACILITY_ORACLE_FORMS
  • FACILITY_CITRIXENGINE
  • FACILITY_OCRLIB
  • FACILITY_SHUNRALOADMANAGER
  • FACILITY_SAPGUI
  • FACILITY_MAPI
  • FACILITY_COMPILER
  • FACILITY_GUILEVEL_TESTING_REPLAY
  • FACILITY_BROWSERENGINE
eNewSeverity The following severities are valid:
  • SEVERITY_SUCCESS
  • SEVERITY_INFORMATIONAL
  • SEVERITY_WARNING
  • SEVERITY_ERROR
  • SEVERITY_TRANS_EXIT
  • SEVERITY_PROCESS_EXIT
eOldSeverity The following severities are valid:
  • SEVERITY_SUCCESS
  • SEVERITY_INFORMATIONAL
  • SEVERITY_WARNING
  • SEVERITY_ERROR
  • SEVERITY_TRANS_EXIT
  • SEVERITY_PROCESS_EXIT
Parent topic: Error-Handling Functions


ResetErrorsSeverity Function

Action

Resets the severity of a facility to its default value.

Include file

kernel.bdh

Syntax

ResetErrorsSeverity( in eFacility : number );
Parent topic: Error-Handling Functions


File Functions

Silk Performer provides a number of functions to create, read, write, and delete files. For example, you can use these functions to read binary files and send them to a server.

When a file is created or opened, the corresponding function returns a handle that can be used as a reference to the file. Depending on the access options, data can be read from or written to any open file. Additional functions provide status information about a file, for example its size or whether it is currently open. Eventually each open file has to be closed.

  • EnableUNCAccess Function
    Enables a virtual user to access files that are located on UNC paths.
  • FAttribute Function
    Checks, sets, and removes attributes for the specified file.
  • FClear Function
    Clears all data of a file and sets the file size to zero.
  • FClose Function
    Closes a file.
  • FCurrentPositionGet Function
    Returns the current position of the file pointer.
  • FCurrentPositionSet Function
    Moves the file pointer of an open file.
  • FDelete Function
    Deletes the specified file.
  • FEOFSet Function
    Sets the end-of-file (EOF) position for a specified file to the current position of the file pointer.
  • FExists Function
    Checks whether a specified file exists.
  • FFindString Function
    Searches for the first occurrence of the specified string and, if found, sets the current position of the file pointer to the first character of the found string.
  • FFlush Function
    Flushes buffered data to the file.
  • FIsOpen Function
    Checks whether a specified file is currently open.
  • FlushResultFile Function
    Flushes the buffer of the specified result file.
  • FlushTrueLogOnError Function
    Writes the current, actual stored TrueLog to disk.
  • FOpen Function
    Opens or creates a file with the specified filename and returns a handle to the opened file.
  • FRead Function
    Reads data from a file, starting at the position indicated by the file pointer.
  • FRemoveNBytes Function
    Removes data at the current position of the file pointer.
  • FSizeGet Function
    Returns the size of a specified file.
  • FWrite Function
    Writes data to a file, starting at the position indicated by the file pointer.
  • Extended File Functions
    Provides an overview of the functions that you can use to read and access files in CSV format (comma-separated format) or a fixed-length format.
Parent topic: General Functions


EnableUNCAccess Function

Action

Enables a virtual user to access files that are located on UNC paths. Call this function in the initial transaction of your test script.

Include file

Kernel.bdh

Syntax

EnableUNCAccess( in sHost     : string,
                 in sUserName : string,
                 in sPassword : string ): boolean;

Return value

  • true if successful.

  • false otherwise.

Parameter | Description
sHost | Name of the computer where the file is located.
sUserName | Name of a Windows NT/2000 domain user. For remote access, a user who has appropriate permissions on the remote computer must be specified.
sPassword | Password of the Windows NT/2000 domain user.

Example

dcltrans
  transaction TInit
  begin
    EnableUNCAccess("lab13", "testdomain\\user1", "pass1");
  end TInit;

  transaction AccessUncPath
  var
    hFile : number;
    sOutput : string;
  begin
    // create new file
    FOpen(hFile, "\\\\lab13\\exportdir\\dummyfile.txt",
    OPT_FILE_ACCESS_READWRITE, OPT_FILE_CREATE);
    writeln("new file created");

    // write string to file
    sOutput := "Hello world!";
    FWrite(hFile, sOutput);
    writeln("string written to file");

    // close file
    FClose(hFile);
    writeln("file closed");
  end AccessUncPath;
Parent topic: File Functions


FAttribute Function

Action

Checks, sets, and removes attributes for the specified file.

If the file name includes a directory name, the file is opened in the specified directory. Otherwise, Silk Performer searches for the file in the directory where the test script is located, in the data directory, in the results directory, and in the project directory.

Include file

Kernel.bdh

Syntax

FAttribute( in sFileName   : string,
            in nAttributes : number,
            in nOperation  : number ): boolean;

Return value

  • true if the check operation was performed and the attribute was set or if the attribute was successfully added or removed.

  • false otherwise

Parameter | Description
sFileName | Name of the file
nAttributes

Attributes of the specified file. Any combination of the following flags is valid:

  • OPT_FILE_ATTRIB_ARCHIVE

  • OPT_FILE_ATTRIB_HIDDEN

  • OPT_FILE_ATTRIB_READONLY

  • OPT_FILE_ATTRIB_SYSTEM
nOperation

Specifies whether to check, set or remove attributes. Possible values are:

  • OPT_FILE_ATTRIB_GET

  • OPT_FILE_ATTRIB_ADD

  • OPT_FILE_ATTRIB_REMOVE

Example

dcltrans
  transaction TMain
  const
    scFileName := "c:\\temp\\dummyfile.txt";
  begin
    // check whether system file is hidden
    if FAttribute("c:\\io.sys",OPT_FILE_ATTRIB_HIDDEN, OPT_FILE_ATTRIB_GET) then
    write("hidden"); writeln;
    else
      write("visible"); writeln;
    end;

    // set read-only attribute for test file
    FAttribute(scFileName, OPT_FILE_ATTRIB_READONLY, OPT_FILE_ATTRIB_ADD);
    write("test file is now read-only"); writeln;
    // remove read-only attribute again
    FAttribute(scFileName, OPT_FILE_ATTRIB_READONLY, OPT_FILE_ATTRIB_REMOVE);
    write("read-only attribute removed"); writeln;
  end TMain;

Output

hidden
test file is now read-only
read-only attribute removed
Parent topic: File Functions


FClear Function

Action

Clears all data of a file and sets the file size to zero.

Include file

Kernel.bdh

Syntax

FClear( in hFile: number ): boolean;

Return value

  • true if successful

  • false otherwise

Parameter | Description
hFile | Valid handle to an open file. This handle must have been returned from a previous call to FOpen.

Example

dcltrans
  transaction TMain
  var
    hFile : number;
    sOutput : string;
  begin
    // create new file and write string to file
    FOpen(hFile, "c:\\temp\\dummyfile.txt", OPT_FILE_ACCESS_READWRITE, OPT_FILE_CREATE);
    sOutput := "Hello world!";
    FWrite(hFile, sOutput);
    write("new file created"); writeln;

    // clear file
    FClear(hFile);
    write("file cleared"); writeln;

    // close file
    FClose(hFile);
    write("file closed"); writeln;
  end TMain;

Output

new file created
file cleared
file closed
Parent topic: File Functions
Related reference
FRead Function
FRemoveNBytes Function
FWrite Function


FClose Function

Action

Closes a file.

Include file

Kernel.bdh

Syntax

FClose( inout hFile: number ): boolean;

Return value

  • true if successful

  • false otherwise

Parameter | Description
hFile | Valid handle to an open file. This handle must have been returned from a previous call to FOpen.

Example

dcltrans
  transaction TMain
  var
    hFile : number;
    sOutput : string;
  begin
    // create new file
    FOpen(hFile, "c:\\temp\\dummyfile.txt", OPT_FILE_ACCESS_READWRITE, OPT_FILE_CREATE);
    write("new file created"); writeln;

    // write string to file
    sOutput := "Hello world!";
    FWrite(hFile, sOutput);
    write("string written to file"); writeln;

    // close file
    FClose(hFile);
    write("file closed"); writeln;
  end TMain;

Output

new file created
string written to file
file closed

Sample scripts

WebFileUpload01.bdf

Parent topic: File Functions
Related reference
FIsOpen Function
FOpen Function
FFlush Function
FWrite Function


FCurrentPositionGet Function

Action

Returns the current position of the file pointer.

Include file

Kernel.bdh

Syntax

FCurrentPositionGet( in  hFile : number,
                     out nPos  : number ) : boolean;

Return value

  • true if successful

  • false otherwise

Parameter | Description
hFile | Valid handle to an open file. This handle must have been returned from a previous call to FOpen.
nPos | Variable receiving the current position of the file pointer

Example

dcltrans
  transaction TMain
  var
    hFile, nPos : number;
    sOutput     : string;
  begin
    // create new file and write string to file
    FOpen(hFile, "c:\\temp\\dummyfile.txt", OPT_FILE_ACCESS_READWRITE, OPT_FILE_CREATE);
    sOutput := "Hello world!";
    FWrite(hFile, sOutput);
    write("new file created"); writeln;

    // get current file position
    FCurrentPositionGet(hFile, nPos);
    write("current pos = "); write(nPos); writeln;

    // close file
    FClose(hFile);
    write("file closed"); writeln;
  end TMain;

Output

new file created
current pos = 12
file closed
Parent topic: File Functions
Related reference
FCurrentPositionSet Function
FSizeGet Function
FEOFSet Function


FCurrentPositionSet Function

Action

Moves the file pointer of an open file by a specified number of bytes from the start of the file or from the current position (thereby setting it to a given position), or moves the file pointer to the end of the file.

Include file

Kernel.bdh

Syntax

FCurrentPositionSet( in hFile       : number,
                     in nShift      : number,
                     in nMoveMethod : number ) : boolean;

Return value

  • true if successful

  • false otherwise

Parameter | Description
hFile | Valid handle to an open file. This handle must have been returned from a previous call to FOpen.
nShift | Number of bytes to shift the file position
nMoveMethod Specifies the start position of the move operation. Possible values are:

  • OPT_FILE_BEGIN. Beginning of the file

  • OPT_FILE_CURRENT. Current file position

  • OPT_FILE_END. End of the file

Example

dcltrans
  transaction TMain
  var
    hFile : number;
    sOutput : string;
  begin
    // create new file and write string to file
    FOpen(hFile, "c:\\temp\\dummyfile.txt", OPT_FILE_ACCESS_READWRITE, OPT_FILE_CREATE);
    sOutput := "Hello world!";
    FWrite(hFile, sOutput);
    write("new file created"); writeln;

    // set file position to end of word "Hello"
    FCurrentPositionSet(hFile, 5, OPT_FILE_BEGIN);
    write("current position set to 5"); writeln;

    // set EOF to current position
    FEOFSet(hFile);
    write("EOF set, file contains only the word 'Hello'"); writeln;

    // close file
    FClose(hFile);
    write("file closed"); writeln;

  end TMain;

Output

new file created
current position set to 5
EOF set, file contains only the word 'Hello'
file closed
Parent topic: File Functions
Related reference
FCurrentPositionGet Function
FSizeGet Function
FEOFSet Function


FDelete Function

Action

Deletes the specified file.

If the file name includes a directory name, the file is opened in the specified directory. Otherwise, Silk Performer searches for the file in the directory where the test script is located, in the data directory, in the results directory, and in the project directory.

Include file

Kernel.bdh

Syntax

FDelete( in sFileName: string ): boolean;

Return value

  • true if successful

  • false otherwise

Parameter | Description
sFileName | Name of the file

Example

dcltrans
  transaction TMain
  const
    scFileName := "c:\\temp\\dummyfile.txt";
  var
    hFile: number;
  begin
    // create new file
    FOpen(hFile, scFileName, OPT_FILE_ACCESS_READWRITE, OPT_FILE_CREATE);
    FClose(hFile);
    write("new file created"); writeln;
    // delete file
    FDelete(scFileName);
    write("file deleted"); writeln;
  end TMain;

Output

new file created
file deleted
Parent topic: File Functions
Related reference
FExists Function


FEOFSet Function

Action

Sets the end-of-file (EOF) position for a specified file to the current position of the file pointer.

Include file

Kernel.bdh

Syntax

FEOFSet( in hFile: number ): boolean;

Return value

  • true if successful

  • false otherwise

Parameter | Description
hFile | Valid handle to an open file. This handle must have been returned from a previous call to FOpen.

Example

dcltrans
  transaction TMain
  var
    hFile   : number;
    sOutput : string;
  begin
    // create new file and write string to file
    FOpen(hFile, "c:\\temp\\dummyfile.txt", OPT_FILE_ACCESS_READWRITE, OPT_FILE_CREATE);
    sOutput := "Hello world!";
    FWrite(hFile, sOutput, Strlen(sOutput));
    write("new file created"); writeln;

    // set file position to end of word "Hello"
    FCurrentPositionSet(hFile, 5, OPT_FILE_BEGIN);
    write("current position set to 5"); writeln;

    // set EOF to current position
    FEOFSet(hFile);
    write("EOF set, file contains only the word 'Hello'"); writeln;

    // close file
    FClose(hFile);
    write("file closed"); writeln;
  end TMain;

Output

new file created
current position set to 5
EOF set, file contains only the word 'Hello'
file closed
Parent topic: File Functions
Related reference
FCurrentPositionGet Function
FCurrentPositionSet Function
FSizeGet Function


FExists Function

Action

Checks whether a specified file exists.

If the file name includes a directory name, the file is opened in the specified directory. Otherwise, Silk Performer searches for the file in the directory where the test script is located, in the data directory, in the results directory and in the project directory.

Include file

Kernel.bdh

Syntax

FExists(in sFileName: string): boolean;

Return value

  • true if the file exists

  • false otherwise

Parameter | Description
sFileName | Name of the file

Example

dcltrans
  transaction TMain
  begin
    // check whether the file "autoexec.bat" exists
    // in the C root directory
    if FExists("c:\\autoexec.bat") then
      write("file autoexec.bat exists"); writeln;
    else
      write("no autoexec.bat file"); writeln;
    end;
  end TMain;

Output

file autoexec.bat exists
Parent topic: File Functions
Related reference
FDelete Function


FFindString Function

Action

Searches for the first occurrence of the specified string and, if found, sets the current position of the file pointer to the first character of the found string.

Include file

Kernel.bdh

Syntax

FFindString( in hFile      :number;
             in sSearchStr : string ): boolean;

Return value

  • true if the string was found

  • false otherwise

Parameter | Description
hFile | Valid handle to an open file. This handle must have been returned from a previous call to FOpen.
sSearchStr | String to search for

Example

dcltrans
  transaction TMain
  const
    scFileName := "c:\\temp\\dummyfile.txt";
  var
    hFile            : number;
    sOutput, sSearch : string;
  begin
    // create a file and store a string
    FOpen(hFile, scFileName, OPT_FILE_ACCESS_READWRITE, OPT_FILE_CREATE);
    sOutput := "Hope the weather will be fine tomorrow!";
    FWrite(hFile, sOutput);
    FClose(hFile);
    write("new file created"); writeln;

    // search for the word "weather" in the file
    FOpen(hFile, scFileName);
    sSearch := "weather";
    if FFindString(hFile, sSearch) then
      write("word found"); writeln;
    else
      write("word not found"); writeln;
    end;

    // close file
    FClose(hFile);
    write("file closed");
    writeln;
  end TMain;

Output

new file created
word found
file closed
Parent topic: File Functions


FFlush Function

Action

Flushes buffered data to the file.

Include file

kernel.bdh

Syntax

FFlush( in hFile : number ): boolean;

Return value

  • true if successful

  • false otherwise

Parameter | Description
hFile | Valid handle to an open file. This handle must have been returned from a previous call to FOpen.

Example

transaction TMain
var
  hFile : number;
begin
  // create new file and write string to file
  FOpen(hFile, "c:\\temp\\dummyfile.txt", OPT_FILE_ACESS_READWRITE, OPT_FILE_CREATE);
  FWrite(hFile, "Hello World");
  // flush data to file
  FFlush(hFile);
  // close file
  FClose(hFile);
end TMain;
Parent topic: File Functions
Related reference
FWrite Function
FClose Function


FIsOpen Function

Action

Checks whether a specified file is currently open.

If the file name includes a directory name, the file is opened in the specified directory. Otherwise, Silk Performer searches for the file in the directory where the test script is located, in the data directory, in the results directory, and in the project directory.

Include file

Kernel.bdh

Syntax

FIsOpen( in sFileName: string ): boolean;

Return value

  • true if the specified file is currently open

  • false otherwise

Parameter | Description
sFileName | Name of the file

Example

const
  scFileName := "c:\\temp\\dummyfile.txt";

dclfunc
  function DisplayFileStatus
  begin
    if FIsOpen(scFileName) then
      write("file is currently open"); writeln;
    else
      write("file is currently closed"); writeln;
    end;
  end DisplayFileStatus;

dcltrans
  transaction TMain
  var
    hFile: number;
  begin
    // check whether file is currently open
    DisplayFileStatus();
    // open file
    FOpen(hFile, scFileName, OPT_FILE_ACCESS_READWRITE, OPT_FILE_CREATE);
    write("file opened"); writeln;
    // check whether file is currently open
    DisplayFileStatus();
    // close file
    FClose(hFile);
    write("file closed"); writeln;
    // check whether file is currently open
    DisplayFileStatus();
  end TMain;

Output

file is currently closed
file opened
file is currently open
file closed
file is currently closed
Parent topic: File Functions


FlushResultFile Function

Action

Flushes the buffer of the specified result file.

Include file

Kernel.bdh

Syntax

FlushResultFile( in nResultFile : number,
                 in bClose      : boolean optional ): boolean;

Return value

  • true if the file could be flushed.

  • false otherwise.

Parameter Description
nResultFile

Following result files can be flushed.

  • RESULT_FILE_ERR. Flushes the error log.

  • RESULT_FILE_LOG. Flushes the log files.

  • RESULT_FILE_RPT. Flushes the report file.

  • RESULT_FILE_WRT. Flushes the user output file.

  • RESULT_FILE_XLG. Flushes the .xlg. result files.

  • RESULT_FILE_TSD. Flushes time series data.

  • RESULT_FILE_ALL. Flushes all result files.
bClose (optional)

Specifies whether the results file should be closed after flushing. The default value is FALSE.

Example

dcltrans
  transaction TRaiseError
  begin
    ...
    FlushResultFile(RESULT_FILE_RPT);
    FlushResultFile(RESULT_FILE_XLG);
  end TRaiseError;
Parent topic: File Functions


FlushTrueLogOnError Function

Action

Writes the current, actual stored TrueLog to disk.

Include file

WebAPI.bdh

Syntax

FlushTrueLogOnError();

Return value

  • none

Parent topic: File Functions


FOpen Function

Action

Opens or creates a file with the specified filename and returns a handle to the opened file.

If the file name includes a directory name, the file is opened in the specified directory. Otherwise, Silk Performer searches for the file in the directory where the test script is located, in the data directory, in the results directory and in the project directory.

If you are going to use remote agents for the load test, you should store your data files in the Data directory or in the directory where the test script is located. Note that in any case you have to add the data files to your load-testing project.

Include file

Kernel.bdh

Syntax

FOpen( out hFile       : number,
       in  sFileName   : string,
       in  nAccessMode : number optional,
       in  nOpenMode   : number optional,
       in  nShareMode  : number optional ):boolean;

Return value

  • true if successful

  • false otherwise

Parameter | Description
hFile | Variable receiving the file handle.
sFileName | Name of the file.
nAccessMode

Access options (optional). Possible values are:

  • OPT_FILE_ACCESS_READ. Open the file for reading (default).

  • OPT_FILE_ACCESS_READWRITE. Open the file for reading and writing.
nOpenMode

Specifies whether to create or open the file (optional). Possible values are:

  • OPT_FILE_CREATE. Create the file. If the file already exists, it is overwritten.

  • OPT_FILE_OPEN. Open the file (default).

  • OPT_FILE_OPENCREATE. Open the file and create it if it does not exist.
nShareMode

Share options (optional). Possible values are:

  • OPT_FILE_SHARE_NONE. No sharing.

  • OPT_FILE_SHARE_READ. Shared reading access (default).

  • OPT_FILE_SHARE_READWRITE. Shared reading and writing access.

Example

dcltrans
  transaction TMain
  var
    hFile   : number;
    sOutput : string;
  begin
    // create new file
    FOpen(hFile, "c:\\temp\\dummyfile.txt", OPT_FILE_ACCESS_READWRITE, OPT_FILE_CREATE);
    write("new file created"); writeln;

    // write string to file
    sOutput := "Hello world!";
    FWrite(hFile, sOutput);
    write("string written to file"); writeln;

    // close file
    FClose(hFile);
    write("file closed"); writeln;
  end TMain;

Output

new file created
string written to file
file closed

Sample scripts

WebFileUpload01.bdf

Parent topic: File Functions
Related reference
FClose Function
FIsOpen Function


FRead Function

Action

Reads data from a file, starting at the position indicated by the file pointer.

Include file

Kernel.bdh

Syntax

FRead(in hFile : number,
      out sData : string,
      in nDataSize : number,
      out nRead : number optional): boolean;

Return value

  • true if the number of bytes that were actually read is equal to the number of bytes that you specified should be read.

  • false otherwise

Parameter | Description
hFile | Valid handle to an open file. This handle must have been returned from a previous call to FOpen.
sData | Buffer that receives the data
nDataSize | Number of bytes to read
nRead | Variable receiving the number of bytes actually read (optional)

Example

dcltrans
  transaction TMain
  var
    hFile, nRead : number;
    sData : string;
  begin
    // open text file for reading
    FOpen(hFile, "c:\\temp\\dummyfile.txt");
    write("file opened"); writeln;
    // read the first 5 bytes and display them
    FRead(hFile, sData, 5, nRead);
    write(nRead); write(" bytes read"); writeln;
    write(sData); writeln;
    // close file
    FClose(hFile);
  end TMain;

Output

file opened
5 bytes read
Hello

Sample scripts

WebFileUpload01.bdf

Parent topic: File Functions
Related reference
FClear Function
FRemoveNBytes Function
FWrite Function


FRemoveNBytes Function

Action

Removes data at the current position of the file pointer.

Include file

Kernel.bdh

Syntax

FRemoveNBytes( in  hFile    : number,
               in  nBytes   : number,
               out nRemoved : number optional): boolean;

Return value

  • true if successful

  • false otherwise

Parameter | Description
hFile | Valid handle to an open file. This handle must have been returned from a previous call to FOpen.
nBytes | Number of bytes to remove. If this parameter contains a negative value, all characters between the current file position and the end of the file are removed. After the function call this parameter contains the number of bytes actually removed.
nRemoved | Variable receiving the actual number bytes removed from the file (optional)

Example

dcltrans
  transaction TMain
  var
    hFile   : number;
    sOutput : string;
  begin
    // create new file and write string to file
    FOpen(hFile, "c:\\temp\\dummyfile.txt", OPT_FILE_ACCESS_READWRITE, OPT_FILE_CREATE);
    sOutput := "Hello beautiful world!";
    FWrite(hFile, sOutput);
    write("new file created"); writeln;

    // remove word "beautiful"
    FCurrentPositionSet(hFile, 6, OPT_FILE_BEGIN);
    FRemoveNBytes(hFile, 10);
    write("word 'beautiful' removed"); writeln;

    // close file
    FClose(hFile);
    write("file closed"); writeln;
  end TMain;

Output

new file created
word 'beautiful' removed
file closed
Parent topic: File Functions
Related reference
FRead Function
FClear Function
FWrite Function


FSizeGet Function

Action

Returns the size of a specified file.

Include file

Kernel.bdh

Syntax

FSizeGet( in  hFile : number,
          out nSize : number): boolean;

Return value

  • true if successful

  • false otherwise

Parameter | Description
hFile | Valid handle to an open file. This handle must have been returned from a previous call to FOpen.
nSize | Variable receiving the file size

Example

dcltrans
  transaction TMain
  var
    hFile, nSize : number;
    sOutput      : string;
  begin
    // create a file and store a string
    FOpen(hFile, "c:\\temp\\dummyfile.txt", OPT_FILE_ACCESS_READWRITE, OPT_FILE_CREATE);
    sOutput := "Hello world!";
    FWrite(hFile, sOutput);
    write("new file created"); writeln;

    // display current file size
    FSizeGet(hFile, nSize);
    write("file size = "); write(nSize); writeln;

    // close file
    FClose(hFile);
    write("file closed"); writeln;
  end TMain;

Output

new file created
file size = 12
file closed

Sample scripts

WebFileUpload01.bdf

Parent topic: File Functions
Related reference
FCurrentPositionGet Function
FCurrentPositionSet Function
FEOFSet Function


FWrite Function

Action

Writes data to a file, starting at the position indicated by the file pointer.

Include file

Kernel.bdh

Syntax

FWrite( in  hFile      : number,
        in  sData      : string,
        in  nDataSize  : number optional,
        in  nWriteMode : number optional,
        out nWritten   : number optional ): boolean;

Return value

  • true if successful

  • false otherwise

Parameter | Description
hFile | Valid handle to an open file. This handle must have been returned from a previous call to FOpen.
sData | Buffer containing data to write
nDataSize | Number of bytes to write (optional, default = STRING_COMPLETE).
nWriteMode

Specifies how the data is written to the file (optional). Possible values are:

  • OPT_FILE_APPEND. Appends the data at the end of the file

  • OPT_FILE_INSERT. Inserts the data at the current position

  • OPT_FILE_OVERWRITE. Overwrites the data at the current position (default)
nWritten | Variable receiving the number of bytes actually written (optional)

Example

dcltrans
  transaction TMain
var
  hFile, nWritten  : number;
  sOutput          : string;
begin
  // create a file in the temporary directory
  FOpen(hFile, "c:\\temp\\dummyfile.txt", OPT_FILE_ACCESS_READWRITE, OPT_FILE_CREATE);
  write("new file created"); writeln;

  // write string to open file
  sOutput := "Hello world!";
  FWrite(hFile, sOutput, STRING_COMPLETE, OPT_FILE_APPEND, nWritten);
  write (nWritten); write(" bytes written to file"); writeln;

  // close file
  FClose(hFile);
  write("file closed"); writeln;
end TMain;

Output

new file created
12 bytes written to file
file closed
Parent topic: File Functions
Related reference
FRead Function
FClear Function
FRemoveNBytes Function
FFlush Function
FClose Function


Extended File Functions

Extended file functions read and access files in CSV format (comma-separated format) or a fixed-length format. You can use them to read multi-column values in sequential or random order. They are very useful when you want to parameterize your workload with values that are stored in files. For example, you can use these functions to read a Web Server log and use the URL strings stored in the log inside your Web transactions; or you can use them to load valid pairs of multi column data from a file to parameterize data values in your script (for example, valid user/password pairs).

  • FileCSVLoad Function
    Reads a file in CSV format (comma-separated format) into memory.
  • FileCSVLoadGlobal Function
    Reads a file in CSV format (comma-separated format) into memory.
  • FileFixedLoad Function
    Reads a file in a fixed-length ASCII format into memory.
  • FileFixedLoadGlobal Function
    Reads a file in a fixed-length ASCII format into memory.
  • FileGetCol Function
    Retrieves the value of the column specified by nColumn of the current row.
  • FileGetFirstRow Function
    Sets the current row pointer to the first row in the file.
  • FileGetNextRow Function
    Sets the row pointer to the row after the current row.
  • FileGetNextUniqueRow Function
    Sets the test-wide unique row pointer to the row after the current row.
  • FileGetNumRows Function
    Returns the number of rows of a file previously opened and read with a FileLoad function.
  • FileGetRndRow Function
    Sets the row pointer to a randomly selected row within a file.
  • FileGetRow Function
    Sets the current row pointer to the row number specified.
  • FileRemoveRow Function
    Removes the last returned unique row of a virtual user from the specified file.
  • FileUnload Function
    Closes a file handle previously opened with a FileLoad function.
  • GetFileContent Function
    Reads a file sFilename and returns its content as string.
Parent topic: File Functions


FileCSVLoad Function

Action

Reads a file in CSV format (comma-separated format) into memory. After the file has been read, the whole file is accessible without further I/O. The file is read into shared memory only once at a client machine, even if it is read by multiple virtual users. Usually you will use this function only once in your script for each file you load for example, in a start up transaction that initializes your simulation.

If the file name includes a directory name, the file is opened in the specified directory. Otherwise, Silk Performer searches for the file in the directory where the test script is located, in the data directory, in the results directory and in the project directory.

If you are going to use remote agents for the load test, you should store your data files in the Data directory or in the directory where the test script is located. Note that in any case you have to add the data files to your load-testing project.
Note: The values for sSeparator and sDelimiter may not be equal. The sSeparator parameter is used to separate data cells, while the sDelimiter parameter is used to encapsulate a data cell if the value used for the separator is used as data itself. If these parameters are set to the same value, the parser will fail.

Include file

Kernel.bdh

Syntax

FileCSVLoad( out hFile      : number,
             in  sFileName  : string,
             in  sSeparator : string optional,
             in  sDelimiter : string optional ): boolean;

Return value

  • true if successful

  • false otherwise

Parameter | Description
hFile | Variable receiving the file handle used to access the file
sFileName | Specifies the path and file name of the file to read. If you specify a file name without path information, Silk Performer searches for the file in the user data directory specified in the Directories tab of the System Settings - Workbench dialog.
sSeparator | Specifies the separator of the columns you want to use (optional). Usually the separator for CSV-formatted files is the comma (",").
sDelimiter | Specifies the delimiter you want to use for identifying a separator/delimiter sign within a data field (optional). By default the delimiter is the double quotes sign (").

Sample columns

Name | Nickname | Address | City
John Smith | John ““The Tester”” | “Fast Lane, 1432” | Test City

Since double quotes are the delimiter, the double quotes in the Nickname need to be preceded by the delimiter itself (in this case the delimiter has the same functionality as for example a backslash has in BDL code).

The address field includes a comma, which is usually the separator. To prevent FileCSVLoad from using this comma as a separator, the value of John Smith’s address must be encompassed by the delimiter (“…”).

Example

var
  hFile, r: number;
dcltrans
  transaction TInit
  begin
    ...
     FileCSVLoad(hFile, "login.csv", ",", "\"");
  end TInit;

  transaction TMain
  begin
    r := FileGetNextRow(hFile);
...
  end TMain;
Parent topic: Extended File Functions


FileCSVLoadGlobal Function

Action

Reads a file in CSV format (comma-separated format) into memory. The function is equivalent to the FileCSVLoad function except that the pointer to the current row is maintained globally between virtual users at one machine. This means that all virtual users of the file at one machine use the same global row pointer for the current row. Therefore you can sequentially access a file from multiple virtual users.

If the file name includes a directory name, the file is opened in the specified directory. Otherwise, Silk Performer searches for the file in the directory where the test script is located, in the data directory, in the results directory and in the project directory.

If you are going to use remote agents for the load test, you should store your data files in the Data directory or in the directory where the test script is located. Note that in any case you have to add the data files to your load-testing project.
Note: The values for sSeparator and sDelimiter may not be equal. The sSeparator parameter is used to separate data cells, while the sDelimiter parameter is used to encapsulate a data cell if the value used for the separator is used as data itself. If these parameters are set to the same value, the parser will fail.

Include file

Kernel.bdh

Syntax

FileCSVLoadGlobal( out hFile      :number,
                   in  sFileName  : string,
                   in  sSeparator : string optional,
                   in  sDelimiter : string optional ):boolean;

Return value

  • true if successful

  • false otherwise

Parameter | Description
hFile | Variable receiving the file handle used to access the file
sFileName | Specifies the path and file name of the file to read. If you specify a file name without path information, Silk Performer searches for the file in the user data directory specified in the Directories tab of the System Settings - Workbench dialog.
sSeparator | Specifies the separator of the columns you want to use (optional). Usually the separator for CSV-formatted files is the comma (",").
sDelimiter | Specifies the delimiter you want to use for identifying a separator/delimiter sign within a data field (optional). By default the delimiter is the double quotes sign (").

Sample columns

Name | Nickname | Address | City
John Smith | John ““The Tester”” | “Fast Lane, 1432” | Test City

Since double quotes are the delimiter, the double quotes in the Nickname need to be preceded by the delimiter itself (in this case the delimiter has the same functionality as for example a backslash has in BDL code).

The address field includes a comma, which is usually the separator. To prevent FileCSVLoad from using this comma as a separator, the value of John Smith’s address must be encompassed by the delimiter (“…”).

Sample scripts

RandomLogin.bdf

Parent topic: Extended File Functions
Related reference
FileCSVLoad Function


FileFixedLoad Function

Action

Reads a file in a fixed-length ASCII format into memory. Each row of the file is delimited with CR or CRLF (carriage return or carriage return + linefeed characters). After the file has been read, the whole file is accessible without further I/O. The file is read into shared memory only once at a client machine, even if it is read by multiple virtual users. Usually, you will use this function in only once in your script for each file you load for example, in a start up transaction that initializes your simulation.

If the file name includes a directory name, the file is opened in the specified directory. Otherwise, Silk Performer searches for the file in the directory where the test script is located, in the data directory, in the results directory and in the project directory.

If you are going to use remote agents for the load test, you should store your data files in the Data directory or in the directory where the test script is located. Note that in any case you have to add the data files to your load-testing project.
Note: This function assumes that a particular column has the same width in each row.

Include file

Kernel.bdh

Syntax

FileFixedLoad( out hFile         : number,
               in  sFileName     : string,
               in  sFormatString : string ): boolean;

Return value

  • true if successful

  • false otherwise

Parameter | Description
hFile | Variable receiving the file handle used to access the file
sFileName | Specifies the path and file name of the file to read. If you specify a file name without path information, Silk Performer searches for the file in the user data directory specified in the Directories tab of the System Settings - Workbench dialog.
sFormatString | Specifies the format of a row in the file. For each column in one row you specify the starting position and the ending position of the column (beginning with 1 as the first position in the row). You need not to specify all columns in a row, and you can specify columns that overlap with other columns. Syntax of the format string Format = Startpos ".." Endpos { ";" Startpos ".." Endpos }.

Example

var
  hFile, r: number;

dcltrans
  transaction TMain
  begin
    ...

    FileFixedLoad(hFile, "login.csv", "1..20;21..40");
  end TMain;

  transaction tra1
  begin
    r := FileGetNextRow(hFile);
    ...
  end tra1;
Parent topic: Extended File Functions


FileFixedLoadGlobal Function

Action

Reads a file in a fixed length ASCII format into memory. The function is equivalent to the FileFixedLoad function except that the pointer to the current row is maintained globally between virtual users at one machine. That means that all virtual users of the file at one machine use of the same global row pointer for the current row. Therefore you can sequentially access a file from multiple virtual users.

If the file name includes a directory name, the file is opened in the specified directory. Otherwise, Silk Performer searches for the file in the directory where the test script is located, in the data directory, in the results directory and in the project directory.

If you are going to use remote agents for the load test, you should store your data files in the Data directory or in the directory where the test script is located. Note that in any case you have to add the data files to your load-testing project.

Include file

Kernel.bdh

Syntax

FileFixedLoadGlobal( out hFile        : number,
                     in sFileName     : string,
                     in sFormatString : string): boolean;

Return value

  • true if successful

  • false otherwise

Parameter | Description
hFile | Variable receiving the file handle used to access the file
sFileName | Specifies the path and file name of the file to read. If you specify a file name without path information, Silk Performer searches for the file in the user data directory specified in the Directories tab of the System Settings - Workbench dialog.
sFormatString | Specifies the format of a row in the file. For each column in one row you specify the starting position and the ending position of the column (beginning with 1 as the first position in the row). You need not to specify all columns in a row, also you can specify columns that overlap with other columns. Syntax of the format string Format = Startpos ".." Endpos { ";" Startpos ".." Endpos }.
Parent topic: Extended File Functions
Related reference
FileFixedLoad Function


FileGetCol Function

Action

Retrieves the value of the column specified by nColumn of the current row.

Include file

Kernel.bdh

Syntax

FileGetCol( in hFile   : number,
            in nColumn : number,
            in nMaxLen : number optional ): string;

Return value

value of the column

Parameter | Description
hFile | Specifies the file handle that is used to access the file.
nColumn | Number of the column beginning with 1 for the first column. If you set nColumn to 0, the whole row is retrieved.
nMaxLen | (optional, default = STRING_COMPLETE) Maximum length of the return value including the terminating null character. If a column value including terminating null character is larger than this value, the return value is truncated accordingly.

Example

dcltrans
  transaction TMain
  const
    MAX_LEN := 254;
  var
    hFile, i : number;
    sRowBuffer, sColumn1, sColumn2 : string;
  begin
    ...
    FileFixedLoad(hFile, "login.csv", "1..20;21-40");

    for i := 1 to 100 do
      FileGetRow(hFile, i);
      sRowBuffer := FileGetCol(hFile, 0, MAX_LEN);
      sColumn1   := FileGetCol(hFile, 1, MAX_LEN);
      sColumn2   := FileGetCol(hFile, 2, MAX_LEN);
    end;
    ...
  end TMain;

Sample scripts

RandomLogin.bdf

Parent topic: Extended File Functions


FileGetFirstRow Function

Action

Sets the current row pointer to the first row in the file. After the current row pointer is set with FileGetFirstRow, you can access the columns of the row with the GetCol function. If the file is opened with a global FileLoad function (FileCSVLoadGlobal or FileFixedLoadGlobal), the current row pointer is set for all virtual users that access this file. Otherwise the current row pointer is set only for the virtual user calling the function.

Include file

Kernel.bdh

Syntax

FileGetFirstRow(in hFile: number): boolean;

Return value

  • true if successful

  • false otherwise

Parameter | Description
hFile | Specifies the file handle that is used to access the file

Example

dcltrans
  transaction TMain
  const
    MAX_LEN := 254;
  var
    hFile : number;
    sColumn : string;
  begin
    ...
    FileFixedLoad(hFile, "login.csv", "1..20;21-40");
    FileGetFirstRow(hFile);
    sColumn := FileGetCol(hFile, 1, MAX_LEN);
    ...
  end TMain;
Parent topic: Extended File Functions
Related reference
FileGetNextRow Function
FileGetNumRows Function
FileGetRndRow Function
FileGetRow Function
FileGetNextUniqueRow Function


FileGetNextRow Function

Action

Sets the row pointer to the row after the current row. If the current row is the last row in a file, then the current row is set to the first row of the file. After the current-row pointer is set with FileGetNextRow, you can access the columns of the row with the FileGetCol function. If the file is opened with a global FileLoad function (FileCSVLoadGlobal or FileFixedLoadGlobal), the current row pointer is set for all virtual users that access this file. Otherwise, the current row pointer is set only for the virtual user calling the function.

Note: You do not necessarily need to call the FileGetFirstRow function prior to the first FileGetNextRow function call. After a file has been opened, the file pointer is set to the first row automatically.

Include file

Kernel.bdh

Syntax

FileGetNextRow(in hFile: number): number;

Return value

row number for the current row (beginning with 1 for the first row of a file)

Parameter | Description
hFile | Specifies the file handle that is used to access the file

Example

dcltrans
  transaction TMain
  const
    MAX_LEN := 254;
  var
    hFile, i : number;
    sColumn : string;
  begin
    FileFixedLoad(hFile, "login.csv", "1..20;21-40");
    for i := 1 to 100 do
      FileGetNextRow(hFile);
      sColumn := FileGetCol(hFile, 1, MAX_LEN);
    end;
    ...
  end TMain;

Sample scripts

RandomLogin.bdf

Parent topic: Extended File Functions
Related reference
FileGetFirstRow Function
FileGetNumRows Function
FileGetRndRow Function
FileGetRow Function
FileGetNextUniqueRow Function


FileGetNextUniqueRow Function

Action

Sets the test-wide unique row pointer to the row after the current row. If the current row is the last row in a file, the unique row pointer will be reset to the first row. All rows that have not been removed through the function FileRemoveRow or through the parameter bRemoveUsedRow are again available. If no more rows are available, the requesting virtual user is stopped. After the current-row pointer is set with FileGetNextUniqueRow, you can access the columns of the row with the FileGetCol function.

The test-wide unique row pointer is maintained for all virtual users on all agents regardless of whether the file is opened with a regular (FileCSVLoad or FileFixedLoad) or global (FileCSVLoadGlobal or FileFixedLoadGlobal) function. Therefore, all virtual users are essentially sharing test-wide sequential access to the same data file, ensuring that every virtual user gets a unique data row on each FileGetNextUniqueRow function call.

Note: Do not use the FileGetFirstRow, FileGetRow or FileGetNextRow functions when using the FileGetNextUniqueRow function.

After a file has been opened, the file pointer is set to the first row in the first FileGetNextUniqueRow call of the virtual user who makes the call.

Note: Using FileGetRow or FileGetNextRow with FileGetNextUniqueRow may yield unexpected results.

Include file

Kernel.bdh

Syntax

FileGetNextUniqueRow( in hFile          : number
                      in bRemoveUsedRow : boolean optional ): number;

Return value

row number for the current row (beginning with 1 for the first row of a file)

Parameter | Description
hFile | Specifies the file handle that is used to access the file
bRemoveUsedRow | Optional: Specifies whether used data rows shall be removed. The default value is false. If this parameter is set to true, used data rows are removed in any case. Even if the test execution is stopped due to a lack of data rows. If the parameter is set to false, you can use the function FileRemoveRow to remove rows.

Example

dcltrans
  transaction TInit
  begin
    if FileCSVLoadGlobal(hFile,"login.csv",",")=false then
      write("File open error\n");
    end;

    FileGetNextUniqueRow(hFile);
    write("UserName: "+FileGetCol(hFile,1,20)+"\n");
    write("Password: "+FileGetCol(hFile,2,20)+"\n");
    // Insert here your connection code
  end TInit;

  transaction TMain
  begin
    // Insert here your transaction code
  end TMain;

Sample scripts

UniqueLogin.bdf

Parent topic: Extended File Functions
Related reference
FileGetFirstRow Function
FileGetNextRow Function
FileGetNumRows Function
FileGetRndRow Function
FileGetRow Function


FileGetNumRows Function

Action

Returns the number of rows of a file previously opened and read with a FileLoad function (FileCSVLoad, FileFixedLoad, FileCSVLoadGlobal or FileFixedLoadGlobal).

Include file

Kernel.bdh

Syntax

FileGetNumRows(in hFile: number): number;

Return value

number of rows in the file

Parameter | Description
hFile | Specifies the file handle that is used to access the file

Example

var
  hFile, nMaxRows: number;
dcltrans
  transaction TMain
  begin
    ...
    FileFixedLoad(hFile, "login.csv", "1..20;21-40");
    nMaxRows := FileGetNumRows(hFile);
    ...
  end TMain;
Parent topic: Extended File Functions
Related reference
FileGetFirstRow Function
FileGetNextRow Function
FileGetRndRow Function
FileGetRow Function
FileGetNextUniqueRow Function


FileGetRndRow Function

Action

Sets the current row pointer to a randomly selected row between the first row and the maximum rows of the file. After the current row pointer is set with FileGetRndRow you can access the columns of the row with the FileGetCol function.

Include file

Kernel.bdh

Syntax

FileGetRndRow(in hFile: number): number;

Return value

row number of the current row (beginning with 1 for the first row of a file)

Parameter | Description
hFile | Specifies the file handle that is used to access the file

Example

dcltrans
  transaction TMain
  const
    MAX_LEN := 254;
  var
    hFile, i : number;
    sColumn : string;
  begin
    ...
    FileFixedLoad(hFile, "login.csv", "1..20;21-40");
      for i := 1 to 100 do
      FileGetRndRow(hFile);
      sColumn := FileGetCol(hFile, 1, MAX_LEN);
    end;
    ...
  end TMain;
Parent topic: Extended File Functions
Related reference
FileGetFirstRow Function
FileGetNextRow Function
FileGetNumRows Function
FileGetRow Function
FileGetNextUniqueRow Function


FileGetRow Function

Action

Sets the current row pointer to the row number specified. After the current row pointer is set with FileGetRow you can access the columns of the row with the FileGetCol function.

Include file

Kernel.bdh

Syntax

FileGetRow(in hFile : number,
             in nRow  : number): number;

Return value

Row number of the current row (beginning with 1 for the first row of a file). If an invalid row number is specified, this function returns 0 and does not modify the row pointer.

Parameter | Description
hFile | Specifies the file handle that is used to access the file
nRow | Row number to be set

Example

dcltrans
  transaction TMain
  const
    MAX_LEN := 254;
  var
    hFile, i : number;
    sColumn : string;
  begin
    ...
    FileFixedLoad(hFile, "login.csv", "1..20;21-40");
    for i := 1 to 100 do
      FileGetRow(hFile, i);
      sColumn := FileGetCol(hFile, 1, MAX_LEN);
    end;
    ...
  end TMain;
Parent topic: Extended File Functions
Related reference
FileGetFirstRow Function
FileGetNextRow Function
FileGetNumRows Function
FileGetRndRow Function
FileGetNextUniqueRow Function


FileRemoveRow Function

Action

Removes the last returned unique row of a virtual user from the specified file. This function only takes effect if the parameter bRemoveUsedRows of the function FileGetNextUniqueRow is set to false. If this parameter is set to true, used rows are removed anyway.

Include file

Kernel.bdh

Syntax

FileRemoveRow( in hFile : long );

Parameter | Description
hFile | Specifies the file handle that is used to access the file

Example

transaction DemoTrans
begin
  FileGetNextUniqueRow(hWebProject_81, false);
  psWebProject_8Column11 := FileGetCol(hWebProject_81, 1, STRING_COMPLETE);

  if (GetUserId() mod 2 = 0) then
    FileRemoveRow(hWebProject_81);
  end;
end DemoTrans;
Parent topic: Extended File Functions


FileUnload Function

Action

Closes a file handle previously opened with a FileLoad function (FileCSVLoad, FileFixedLoad, FileCSVLoadGlobal or FileFixedLoadGlobal). If all file handles from all virtual users for a specific file are closed, the file is discarded from shared memory. When ending a simulation this function is performed automatically. Therefore you need not call this function if you want to close a file handle at the end of a simulation.

Include file

Kernel.bdh

Syntax

FileUnload( inout hFile: number );
Parameter | Description
hFile | Specifies the file handle that is used to access the file

Example

dcltrans
  transaction TFileUnload
  var
    hFile: number;
  begin
    FileFixedLoad(hFile, "login.csv", "1..20;21-40");
    FileUnload(hFile);
  end TFileUnload;

Sample scripts

RandomLogin.bdf

Parent topic: Extended File Functions


GetFileContent Function

Action

Reads a file sFilename and returns its content as string.

Include file

kernel.bdh

Syntax

GetFileContent( in sFilename : string ) : string;
Parameter | Description
sFilename | Absolute filename of file to read.
Parent topic: Extended File Functions


List Functions

A List is a container of variables of the same type, where the data types boolean, number, float, and string are supported. In contrary to an array, the number of elements in a list is dynamic. Silk Performer provides a number of functions to work with lists. A list without initialization has the size 0. Adding elements increases the list size, removing elements decreases the size.
Note: Lists of lists are not supported.
  • ListAdd Function
    Appends a value to a list.
  • ListClear Function
    Removes all elements of a list.
  • ListClone Function
    Makes a copy of a list.
  • ListConcat Function
    Concatenates two lists into a destination list.
  • ListContains Function
    Checks if a specific value is in a list or not.
  • ListExtract Function
    Copies a part of a list into another list.
  • ListGetAt Function
    Returns a copy of the element at a specified position of a list.
  • ListGetFirst Function
    Returns a copy of the first element of a list.
  • ListGetLast Function
    Returns a copy of the last element of a list.
  • ListGetLength Function
    Returns the length of a list.
  • ListGetType Function
    Returns the type of a list.
  • ListIndexOf Function
    Returns the index of the first occurrence of an element.
  • ListInsert Function
    Inserts a value into a list.
  • ListIsEqual Function
    Checks if two lists are identical.
  • ListLastIndexOf Function
    Returns the index of the last occurrence of an element.
  • ListPrint Function
    Prints all elements of a list.
  • ListRemoveAt Function
    Removes an element at a specific position of a list.
  • ListRemoveFirst Function
    Removes the first element of a list.
  • ListRemoveLast Function
    Removes the last element of a list.
  • ListReplaceAll Function
    Replaces all elements of a list with a specific value by another value.
  • ListSetAt Function
    Sets a specified value at a specific position of a list.
  • ListWriteBin Function
    Writes all elements of a string list to the .wrt file.
Parent topic: General Functions
Related reference
List


ListAdd Function

Action

Appends a value to a list.

Include file

List.bdh

Syntax

ListAdd(
   inout theList: list,
   in element: union) : boolean;
Parameter | Description
theList | List of number, boolean, float or string, which contains a copy of the newly added element as an out parameter.
element | Number, boolean, float or string. Has to conform with the type of theList.

Return value

  • true if successful
  • false otherwise

Example

transaction TAListAdd
var
  lstNumber: list of number init 1, 2, 3, 4, 5;
  retVal1, retVal2: boolean;
  nr: number;
begin
  nr := 6;
  retVal1 := ListAdd(lstNumber, nr);
  retVal2 := ListAdd(lstNumber, 7);
  if(retVal1 = true) and (retVal2 = true) then
    ListGetAt(lstNumber, 6, nr);
    writeln("element at position 6: " + string(nr));
    writeln("length of list: " + string(ListGetLength(lstNumber)));
  else
    writeln("ListAdd did not work!");
  end;
end TAListAdd;

Output

element at position 6: 6
length of list: 7
Parent topic: List Functions


ListClear Function

Action

Removes all elements of a list.

Include file

List.bdh

Syntax

ListClear(
   inout theList: list) : boolean;
Parameter | Description
theList | List of number, boolean, float or string, which is empty as an out parameter.

Return value

  • true if successful
  • false otherwise

Example

transaction TAListClear
var
  lstNumber: list of number init 1, 2, 3, 4, 5, 6;
  retVal1: boolean;
begin
  retVal1 := ListClear(lstNumber);
  if(retVal1 = true) then
    writeln("length of list: " + string(ListGetLength(lstNumber)));
  else
    writeln("ListClear did not work!");
  end;
end TAListClear;

Output

length of list: 0
Parent topic: List Functions


ListClone Function

Action

Makes a copy of a list. The origin and the target list parameters have to be of the same type. The elements of the target list are removed before the elements of the origin list are copied.

Include file

List.bdh

Syntax

ListClone(
   in theList: list,
   inout resultList: list) : boolean;
Parameter | Description
theList | List of number, boolean, float or string.
resultList | List of number, boolean, float or string. The type of this list must be the same as the type of theList. resultList contains a copy of all elements of theList as an out parameter.

Return value

  • true if successful
  • false otherwise

Example

transaction TAListClone
var
  lstNumber: list of number init 1, 2, 3, 4, 5, 6;
  lstCopy: list of number init 33, 44, 55;
  retVal1: boolean;
begin
  retVal1 := ListClone(lstNumber, lstCopy);
  if(retVal1 = true) then
    ListPrint(lstCopy);
  else
    writeln("ListClone did not work!");
  end;
end TAListClone;

Output

element 1: 1
element 2: 2
element 3: 3
element 4: 4
element 5: 5
element 6: 6
Parent topic: List Functions


ListConcat Function

Action

Concatenates two lists into a destination list. All three lists must be of the same type. All elements of the destination list are deleted before the elements of the other lists are copied into it.

Include file

List.bdh

Syntax

ListConcat(
   in firstList: list,
   in secondList: list,
   inout resultList: list) : boolean;
Parameter | Description
firstList | List of number, boolean, float or string.
secondList | List of number, boolean, float or string.
resultList | List of number, boolean, float or string, which contains all elements of firstList and secondList as an out parameter.

Return value

  • true if successful
  • false otherwise

Example

transaction TAListConcat
var
  lstFirst: list of number init 1, 2, 3;
  lstSecond: list of number init 4, 5, 6;
  lstResult: list of number init 33, 44, 55;
  retVal1: boolean;
begin
  retVal1 := ListConcat(lstFirst, lstSecond, lstResult);
  if(retVal1 = true) then
    ListPrint(lstResult);
  else
    writeln("ListConcat did not work!");
  end;
end TAListConcat;

Output

element 1: 1
element 2: 2
element 3: 3
element 4: 4
element 5: 5
element 6: 6
Parent topic: List Functions


ListContains Function

Action

Checks if a specific value is in a list or not.

Include file

List.bdh

Syntax

ListContains(
   in theList: list,
   in element: union) : boolean;
Parameter | Description
theList | List of number, boolean, float or string.
element | Element to be searched in theList.

Return value

  • true if the element is found
  • false otherwise

Example

transaction TAListContains
var
  lstNumber: list of number init 1, 2, 3;
  retVal1: boolean;
  nrVal: number init 2;
begin
  retVal1 := ListContains(lstNumber, nrVal);
  writeLn("2 is element of the list: " + string(retVal1));
  retVal1 := ListContains(lstNumber, 4);
  writeLn("4 is element of the list: " + string(retVal1));
end TAListContains;

Output

2 is element of the list: TRUE
4 is element of the list: FALSE
Parent topic: List Functions


ListExtract Function

Action

Copies a part of a list, defined by two indices, from one list to another. The elements of the target list are removed before the elements of the origin list are copied.

Include file

List.bdh

Syntax

ListExtract(
   in listFrom: list,
   in fromIndex: number,
   in toIndex: number,
   inout listExtracted: list) : boolean;
Parameter | Description
listFrom | List of number, boolean, float or string.
fromIndex | Number, defining the first element to be copied.
toIndex | Number, defining the last element to be copied.
listExtracted | List of number, boolean, float or string, which contains the specified elements of listFrom as an out parameter.

Return value

  • true if successful
  • false otherwise

Example

transaction TAListExtract
var
  lstNumber: list of number init 1, 2, 3, 4, 5, 6;
  lstResult: list of number init 555, 555;
  retVal: boolean;
begin
  retVal := ListExtract(lstNumber, 2, 5, lstResult);
  if(retVal) then
    ListPrint(lstResult);
  end;
end TAListExtract;

Output

element 1: 2
element 2: 3
element 3: 4
element 4: 5
Parent topic: List Functions


ListGetAt Function

Action

Returns a copy of the element at a specified position of a list.

Include file

List.bdh

Syntax

ListGetAt(
   in theList: list,
   in index: number,
   inout retElement: union) : boolean;
Parameter | Description
theList | List of number, boolean, float or string.
index | Index of theList.
retElement | Number, boolean, float or string, which contains a copy of the element at position index of theList as an out parameter. Has to conform with the type of theList.

Return value

  • true if successful
  • false otherwise

Example

transaction TAListGetAt
var
  lstNumber: list of number init 10, 20, 30;
  numberElem: number;
  stringElem: string;
  retVal: boolean;
begin
  retVal := ListGetAt(lstNumber, 2, numberElem);
  if((retVal = true) and (numberElem = 20)) then
    writeln("ListGetAt worked! Value of numberElem: " + string(numberElem));
  end;
  retVal := ListGetAt(lstNumber, 2, stringElem);
  if(retVal = false) then
    writeln("ListGetAt did not work, the types do not match!");
  end;
  retVal := ListGetAt(lstNumber, 4, numberElem);
  if(retVal = false) then
    writeln("ListGetAt did not work. Index does not exist!");
  end;
end TAListGetAt;

Output

ListGetAt worked! Value of numberElem: 20
ListGetAt did not work, the types do not match!
ListGetAt did not work. Index does not exist!
Parent topic: List Functions


ListGetFirst Function

Action

Returns a copy of the first element of a list.

Include file

List.bdh

Syntax

ListGetFirst(
   in theList: list,
   inout retElement: union) : boolean;
Parameter | Description
theList | List of number, boolean, float or string.
retElement | Number, boolean, float or string, which contains a copy of the first element of theList as an out parameter. Has to conform with the type of theList.

Return value

  • true if successful
  • false otherwise

Example

transaction TAListGetFirst
var
  lstNumber: list of number init 10, 20, 30;
  numberElem: number;
  stringElem: string;
  retVal: boolean;
begin
  retVal := ListGetFirst(lstNumber, numberElem);
  if((retVal = true) and (numberElem = 10)) then
    writeln("ListGetFirst worked! Value of numberElem: " + string(numberElem));
  end;
  retVal := ListGetFirst(lstNumber, stringElem);
  if(retVal = false) then
    writeln("ListGetFirst did not work, the types do not match!");
  end;
end TAListGetFirst;

Output

ListGetFirst worked! Value of numberElem: 10
ListGetFirst did not work, the types do not match!
Parent topic: List Functions


ListGetLast Function

Action

Returns a copy of the last element of a list.

Include file

List.bdh

Syntax

ListGetLast(
   in theList: list,
   inout retElement: union) : boolean;
Parameter | Description
theList | List of number, boolean, float or string.
retElement | Number, boolean, float or string, which contains a copy of the last element of theList as an out parameter. Has to conform with the type of theList.

Return value

  • true if successful
  • false otherwise

Example

transaction TAListGetLast
var
  lstNumber: list of number init 10, 20, 30;
  numberElem: number;
  stringElem: string;
  retVal: boolean;
begin
  retVal := ListGetLast(lstNumber, numberElem);
  if((retVal = true) and (numberElem = 30)) then
    writeln("ListGetLast worked! Value of numberElem: " + string(numberElem));
  end;
  retVal := ListGetLast(lstNumber, stringElem);
  if(retVal = false) then
    writeln("ListGetLast did not work, the types do not match!");
  end;
end TAListGetLast;

Output

ListGetLast worked! Value of numberElem: 30
ListGetLast did not work, the types do not match!
Parent topic: List Functions


ListGetLength Function

Action

Returns the length of a list.

Include file

List.bdh

Syntax

ListGetLength(
   in theList: list) : number;
Parameter | Description
theList | List of number, boolean, float or string.

Return value

  • the length of the list

Example

transaction TAListGetLength
var
  lstNumber:  list of number init 10, 20, 30;
  lstBoolean: list of boolean init true, false, true, false;
  lstFloat:   list of float init 1.1, 2.2, 3.3, 4.4, 5.5;
  lstString:  list of string init "one", "two", "three", "four", "five", "six";
begin
  writeln("ListGetLength(lstNumber)  == " + string(ListGetLength(lstNumber)));
  writeln("ListGetLength(lstBoolean) == " + string(ListGetLength(lstBoolean)));
  writeln("ListGetLength(lstFloat)   == " + string(ListGetLength(lstFloat)));
  writeln("ListGetLength(lstString)  == " + string(ListGetLength(lstString)));
end TAListGetLength;

Output

ListGetLength(lstNumber)  == 3
ListGetLength(lstBoolean) == 4
ListGetLength(lstFloat)   == 5
ListGetLength(lstString)  == 6
Parent topic: List Functions


ListGetType Function

Action

Returns the type of a list as a number, where the return values represent the following list types:
  • 1: number
  • 2: float
  • 3: boolean
  • 4: string

Include file

List.bdh

Syntax

ListGetType(
   in theList) : number;
Parameter | Description
theList | List of number, boolean, float or string.

Return value

  • data type of theList (1, 2, 3, or 4)

Example

transaction TAListGetType
var
  lstNumber: list of number;
  lstFloat:  list of float;
  lstBoolean: list of boolean;
  lstString:  list of string;
begin
  writeln("number:  " + string(ListGetType(lstNumber)));
  writeln("float:   " + string(ListGetType(lstFloat)));
  writeln("boolean: " + string(ListGetType(lstBoolean)));
  writeln("string:  " + string(ListGetType(lstString)));
  writeln("number-constant:  " + string(LIST_TYPE_NUMBER));
  writeln("float-constant:   " + string(LIST_TYPE_FLOAT));
  writeln("boolean-constant: " + string(LIST_TYPE_BOOLEAN));
  writeln("string-constant:  " + string(LIST_TYPE_STRING));
end TAListGetType;

Output

number:  1
float:   2
boolean: 3
string:  4
number-constant:  1
float-constant:   2
boolean-constant: 3
string-constant:  4
Parent topic: List Functions


ListIndexOf Function

Action

Returns the index of the first occurrence of an element.

Include file

List.bdh

Syntax

ListIndexOf(
   in theList: list,
   in element: union): number;
Parameter | Description
theList | List of number, boolean, float or string.
element | Number, boolean, float or string. Has to conform with the type of theList.

Return value

  • the index of the first occurrence of element

Example

transaction TAListIndexOf
var
  lstNumber: list of number init 111, 2, 3, 111, 2, 3;
  retVal: number;
begin
  retVal := ListIndexOf(lstNumber, 111);
  writeLn("index of 111: " + string(retVal));

  ListRemoveAt(lstNumber, 1);
  retVal := ListIndexOf(lstNumber, 111);
  writeLn("index of 111: " + string(retVal));
end TAListIndexOf;

Output

index of 111: 1
index of 111: 3
Parent topic: List Functions


ListInsert Function

Action

Inserts a value into a list at a specific position.

Include file

List.bdh

Syntax

ListInsert(
   inout theList: list,
   in index: number,
   in element: union) : boolean;
Parameter | Description
theList | List of number, boolean, float or string, which contains a copy of element at position index as an out parameter.
index | The position at which element will be inserted.
element | Number, boolean, float or string. Has to conform with the type of theList.

Return value

  • true if successful
  • false otherwise

Example

transaction TAListInsert
var
  lstNumber: list of number init 1, 2, 4, 5;
  retVal1: boolean;
  nr: number;
begin
  nr := 3;
  retVal1 := ListInsert(lstNumber, 3, nr);
  if(retVal1 = true) then
    nr := -1;
    ListGetAt(lstNumber, 3, nr);
    writeln("element at position 3: " + string(nr));
    writeln("length of list: " + string(ListGetLength(lstNumber)));
  else
    writeln("ListInsert did not work!");
  end;
end TAListInsert;

Output

element at position 3: 3
length of list: 5
Parent topic: List Functions


ListIsEqual Function

Action

Checks if two lists have the same elements, the same type, and the same length.

Include file

List.bdh

Syntax

ListIsEqual(
   in leftList: list,
   in rightList: list): boolean;
Parameter | Description
leftList | List of number, boolean, float or string.
rightList | List of number, boolean, float or string.

Return value

  • true if successful
  • false otherwise

Example

transaction TAListIsEqual
var
  lstNumber: list of number init 1, 2, 3;
  lstNumber2: list of number init 1, 2, 3;
  retVal1: boolean;
begin
  retVal1 := ListIsEqual(lstNumber, lstNumber2);
  writeLn("the lists are equal: " + string(retVal1));
  ListAdd(lstNumber, 4);
  retVal1 := ListIsEqual(lstNumber, lstNumber2);
  writeLn("the lists are equal: " + string(retVal1));
end TAListIsEqual;

Output

the lists are equal: TRUE
the lists are equal: FALSE
Parent topic: List Functions


ListLastIndexOf Function

Action

Returns the index of the last occurrence of an element.

Include file

List.bdh

Syntax

ListLastIndexOf(
   in theList: list,
   in element: union): number;
Parameter | Description
theList | List of number, boolean, float or string.
element | Number, boolean, float or string. Has to conform with the type of theList.

Return value

  • the index of the last occurrence of element

Example

transaction TAListLastIndexOf
var
  lstNumber: list of number init 1, 2, 333, 4, 5, 333;
  retVal: number;
begin
  retVal := ListLastIndexOf(lstNumber, 333);
  writeLn("index of 333: " + string(retVal));

  ListRemoveAt(lstNumber, 6);
  retVal := ListLastIndexOf(lstNumber, 333);
  writeLn("index of 333: " + string(retVal));
end TAListLastIndexOf;

Output

index of 333: 6
index of 333: 3
Parent topic: List Functions


ListPrint Function

Action

Prints all elements of a list.

Include file

List.bdh

Syntax

ListPrint(
   theList: list) : boolean;
Parameter | Description
theList | List of number, boolean, float or string.

Return value

  • true if successful
  • false otherwise

Example

transaction TAListPrint
var
  lNumber: list of number init 1, 2, 3;
  lString: list of string init "one", "two", "three";
  b: boolean;
begin
  b := ListPrint(lNumber);
  Print(string(b));
  b := ListPrint(lString);
  Print(string(b));
end TAListPrint;

Output

element 1: 1
element 2: 2
element 3: 3
TRUE
element 1: one
element 2: two
element 3: three
TRUE
Parent topic: List Functions


ListRemoveAt Function

Action

Removes an element at a specific position of a list.

Include file

List.bdh

Syntax

ListRemoveAt(
   inout theList: list,
   in index: number) : boolean;
Parameter | Description
theList | List of number, boolean, float or string, which contains one element less as an out parameter.
index | Index of theList.

Return value

  • true if successful
  • false otherwise

Example

transaction TAListRemoveAt
var
  lstNumber: list of number init 1, 2, 3, 666, 4, 5;
  retVal1: boolean;
  nr: number;
begin
  retVal1 := ListRemoveAt(lstNumber, 4);
  if(retVal1 = true) then
    nr := -1;
    ListGetAt(lstNumber, 4, nr);
    writeln("element at position 4: " + string(nr));
    writeln("length of list: " + string(ListGetLength(lstNumber)));
  else
    writeln("ListRemoveAt did not work!");
  end;
end TAListRemoveAt;

Output

element at position 4: 4
length of list: 5
Parent topic: List Functions


ListRemoveFirst Function

Action

Removes the first element of a list.

Include file

List.bdh

Syntax

ListRemoveFirst(
   inout theList: list) : boolean;
Parameter | Description
theList | List of number, boolean, float or string, which contains one element less as an out parameter.

Return value

  • true if successful
  • false otherwise

Example

transaction TAListRemoveFirst
var
  lstNumber: list of number init 111, 1, 2, 3, 4, 5;
  retVal1: boolean;
  nr: number;
begin
  retVal1 := ListRemoveFirst(lstNumber);
  if(retVal1 = true) then
    nr := -1;
    ListGetFirst(lstNumber, nr);
    writeln("element at position 1: " + string(nr));
    writeln("length of list: " + string(ListGetLength(lstNumber)));
  else
    writeln("ListRemoveFirst did not work!");
  end;
end TAListRemoveFirst;

Output

element at position 1: 1
length of list: 5
Parent topic: List Functions


ListRemoveLast Function

Action

Removes the last element of a list.

Include file

List.bdh

Syntax

ListRemoveLast(
   inout theList: list) : boolean;
Parameter | Description
theList | List of number, boolean, float or string, which contains one element less as an out parameter.

Return value

  • true if successful
  • false otherwise

Example

transaction TAListRemoveLast
var
  lstNumber: list of number init 1, 2, 3, 4, 5, 555;
  retVal1: boolean;
  nr: number;
begin
  retVal1 := ListRemoveLast(lstNumber);
  if(retVal1 = true) then
    nr := -1;
    ListGetLast(lstNumber, nr);
    writeln("element at last position: " + string(nr));
    writeln("length of list: " + string(ListGetLength(lstNumber)));
  else
    writeln("ListRemoveLast did not work!");
  end;
end TAListRemoveLast;

Output

element at last position: 5
length of list: 5
Parent topic: List Functions


ListReplaceAll Function

Action

Replaces all elements of a list with a specific value by another value.

Include file

List.bdh

Syntax

ListReplaceAll(
   inout theList: list,
   in elementFromVal: union,
   in elementToVal: union) : boolean;
Parameter | Description
theList | List of number, boolean, float or string, which contains elements with value elementToVal instead of elementFromVal as an out parameter.
elementFromVal | Number, boolean, float or string to be replaced.
elementToVal | Number, boolean, float or string to replace elementFromVal with. Has to conform with the type of elementFromVal and theList

Return value

  • true if successful
  • false otherwise

Example

transaction TAListReplaceAll
var
  lstNumber: list of number init 111, 2, 3, 111, 2, 3, 111;
  retVal: boolean;
begin
  retVal := ListReplaceAll(lstNumber, 111, 1);
  if(retVal) then
    ListPrint(lstNumber);
  end;
end TAListReplaceAll;

Output

element 1: 1
element 2: 2
element 3: 3
element 4: 1
element 5: 2
element 6: 3
element 7: 1
Parent topic: List Functions


ListSetAt Function

Action

Sets a specified value at a specific position of a list.

Include file

List.bdh

Syntax

ListSetAt(
   in theList: list,
   in index: number,
   in val: union) : boolean;
Parameter | Description
theList | List of number, boolean, float or string.
index | Position of theList at which to replace the value.
val | Number, boolean, float or string value to replace at index. Has to conform with the type of theList.

Return value

  • true if successful
  • false otherwise

Example

transaction TAListSetAt
var
  lstNumber: list of number init 1, 2, 3, 4, 5;
  retVal1, retVal2: boolean;
  nr: number;
begin
  retVal1 := ListSetAt(lstNumber, 3, 333);
  retVal2 := ListGetAt(lstNumber, 3, nr);
  if(retVal1 = true) and (retVal2 = true) then
    writeln("element at position 3: " + string(nr));
  else
    writeln("ListSetAt or ListGetAt did not work!");
  end;
end TAListSetAt;

Output

element at position 3: 333
Parent topic: List Functions


ListWriteBin Function

Action

Writes all elements of a string list to the .wrt file.

Include file

List.bdh

Syntax

ListWriteBin(
   theList: list of string) : boolean;
Parameter | Description
theList | List of string.

Return value

  • true if successful
  • false otherwise

Example

transaction TAListWriteBin
var
  lStringBin: list of string init "\h001122", "\h334455", "\h667788";
  lString: list of string init "abc", "ABC";
begin
  ListWriteBin(lStringBin);
  ListWriteBin(lString);
end TAListWriteBin;

Output

00000000  ++"               00 11 22
00000000  3DU               33 44 55
00000000  fw+               66 77 88
00000000  abc               61 62 63
00000000  ABC               41 42 43
Parent topic: List Functions


Load Test Control Functions

Silk Performer provides a number of functions that retrieve information about the currently active load test. For example, to get the user name, or the name of the computer where the simulation of the user has been started.

  • GetAgent Function
    Retrieves the agent name.
  • GetAgentId Function
    Retrieves a unique agent ID.
  • GetController Function
    Retrieves the controller name for the current simulation.
  • GetDataFilePath Function
    Returns the absolute path to a file in the data files section of a load-test script.
  • GetDefinedUserTypeVus Function
    Returns the maximum number of virtual users defined for the specified user type in the current workload.
  • GetDirectory Function
    Retrieves the directory where specified types of Silk Performer files are located.
  • GetFunctionName Function
    Returns the name of the currently executing BDL function.
  • GetLoadtest Function (Deprecated)
    Retrieves the number of the load test generated for the current simulation.
  • GetLoadtestName Function
    Returns the output directory name specified on starting the load test.
  • GetProfile Function
    Retrieves the name of the settings profile that the current virtual user uses.
  • GetProject Function
    Retrieves the name of the current load-test project.
  • GetRuntimes Function
    Retrieves the number of virtual users scheduled for the load test.
  • GetScriptName Function
    Returns the name of the currently executing BDL script.
  • GetTransactionName Function
    Returns the name of the currently executing transaction.
  • GetUser Function
    Retrieves the user name.
  • GetUsergroup Function
    Retrieves the name of the user group to which the current virtual user belongs.
  • GetUserId Function
    Retrieves a unique ID (number) for each current virtual user in a load-test.
  • GetUserIdOnAgent Function
    Retrieves a unique ID (number) per current virtual user on an agent (machine).
  • GetWorkload Function
    Retrieves the name of the active workload which the current virtual user executes.
  • GetWorkloadModel Function
    Retrieves the name of the active workload which the current virtual user executes.
Parent topic: General Functions


GetAgent Function

Action

Retrieves the agent name. The agent name is the name of the computer where the simulation for the current user has been started.

Include file

Kernel.bdh

Syntax

GetAgent(): string;

Return value

The name of the agent.

Example

dcltrans
  transaction TGetAgent
  var
    sAgent: string;
  begin
    sAgent := GetAgent();
    write("agent = "); write(sAgent); writeln;
  end TGetAgent;

Output

agent = LocalHost
Parent topic: Load Test Control Functions


GetAgentId Function

Action

Retrieves a unique ID for the agent running the benchmark.

Include file

Kernel.bdh

Syntax

GetAgentId() : number;

Return value

Unique identification number for the agent running the benchmark. The ID is 0 for the first agent, 1 for the second agent, and n-1 for the nth agent.

Example

dcltrans
  transaction TMain
  var
    nAgentId: number;
  begin
    nAgentId := GetAgentId();
    write("agent ID = "); write(nAgentId); writeln;
  end TMain;
Parent topic: Load Test Control Functions


GetController Function

Action

Retrieves the controller name for the current simulation. The controller name is the name of the controller computer from which all agents were started.

Include file

Kernel.bdh

Syntax

GetController(): string;

Return value

The name of the controller.

Example

dcltrans
  transaction TGetController
  var
    sController: string;
    beginsController := GetController();write("controller = "); write(sController); writeln;
  end TGetController;

Output

controller = BEATLE
Parent topic: Load Test Control Functions


GetDataFilePath Function

Action

This method returns the absolute path to a file in the data files section of a load-test script. As there are different locations for the data files depending on where the load-test is executed (localhost or agent) this function always returns the absolute path to a data file.

Include file

Kernel.bdh

Syntax

GetDataFilePath( in  sDataFile  : string,
                 out sPath      : string,
                 in  nSize      : number optional ): boolean;

Return value

  • true if successfully

  • false otherwise

Parameter | Description
sDataFile | Name of the data file of which the absolute path should be returned.
sPath | String buffer that will receive the absolute path of the file.
nSize | Size of the string buffer passed in sPath (optional).

Example

dcltrans
  transaction TMain
  var
    sPath : string;
    hFile : number;
  begin
    GetDataFilePath("testdata.txt", sPath);
    FileCSVLoad(hFile, sPath, ",");
    ...
  end TMain;
Parent topic: Load Test Control Functions


GetDefinedUserTypeVus Function

Action

Returns the maximum number of virtual users defined for the specified user type in the current workload, specified by script name, user group name, and profile name. The function returns 0 if the user type is disabled in the workload.

Include file

Kernel.bdh

Syntax

GetDefinedUserTypeVus(ScriptName    : in string,
                      UsergroupName : in string,
                      ProfileName   : in string) : number;

Return value

Maximum number of virtual users defined for the specified user type in the current workload

Parameter | Description
ScriptName | Script name as defined in the user type.
UsergroupName | User group name as defined in the user type.
ProfileName | Profile name as defined in the user type.

Example

dcltrans
  transaction TMain
  var
  begin
    Print(string(GetDefinedUserTypeVus("DefaultScript.bdf", "VUser", "Profile1")));
  end TMain;

Output

40
Parent topic: Load Test Control Functions


GetDirectory Function

Action

Retrieves the directory where specified types of Silk Performer files are located. Do not use GetDirectory to locate data files that are referenced by the project. Use the function GetDataFilePath instead.

Include file

Kernel.bdh

Syntax

GetDirectory( in  nDirectory : number,
              out sDir       : string,
              in  nDirSize   : number optional );
Parameter | Description
nDirectory

Specifies which directory setting to retrieve. This parameter can be one of the following flags:

  • DIRECTORY_HOME. Retrieves the Silk Performer home directory.

  • DIRECTORY_SOURCE. Retrieves the default directory for opening and saving load-test scripts.

  • DIRECTORY_RESULT. Retrieves the directory where all result files are saved.

  • DIRECTORY_INCLUDE. Retrieves the directory where all include files are located.

  • DIRECTORY_CUSTOM_INCLUDE. Retrieves the directory where all the custom include files are located.

  • DIRECTORY_DATA. Retrieves the directory where all user data files, certificate files and random data files are located.

  • DIRECTORY_CUSTOM_DATA. Retrieves the directory where all custom user data files, certificate files and random data files are located.

  • DIRECTORY_PROJECT. Retrieves the directory where the project file is located. This location is different on controller and agent machine.

  • DIRECTORY_TEMP. Retrieves the directory where temporary files can be stored during a load test. This directory will be automatically deleted after the test run.

Note: Agent computers create temporary directories for load test execution. Only the parameters DIRECTORY_HOME, DIRECTORY_SOURCE, and DIRECTORY_INCLUDE will return the same results from an agent as from the controller computer.
sDir | String receiving the directory.
nDirSize | Number of characters to copy into sDir. (optional, default is STRING_COMPLETE)

Example

dcltrans
  transaction TMain
  var
    sDirectory: string;
  begin
    GetDirectory(DIRECTORY_HOME, sDirectory);
    writeln(sDirectory),
  end TMain;
Parent topic: Load Test Control Functions


GetFunctionName Function

Action

Returns the name of the currently executing BDL function. If it is called within an error handler, it will return the name of the function where the error was raised.

Include file

Kernel.bdh

Syntax

GetFunctionName( ) : string;

Return value

The name of the function.

Example

dclevent
  handler ErrorHandler <EVENT_RAISE_ERROR>
  var
    sTrac : string;
    sFunc : string;
  begin
    sTrac := GetTransactionName();
    sFunc := GetFunctionName();
    write("error raised in transaction " + sTrac + " in function " + sFunc);
    throw;
  end ErrorHandler;

dclfunc
  function f1
  begin
    // WebPageUrl will raise an error
    WebPageUrl("http://Does.not.exist");
  end f1;

dcltrans
  transaction TRaiseError
  var
    sBuf : string;
  begin
    f1();
  end TRaiseError;

Output

Error raised in transaction TRAISEERROR in function F1.
Parent topic: Load Test Control Functions
Related reference
Event Handler Section
GetTransactionName Function


GetLoadtest Function (Deprecated)

Action

Retrieves the number of the load test generated for the current simulation. All results in the repository of the current load test are associated with this ID number.
Note: This function only returns a valid number if the Silk Performer repository (deprecated) is installed, otherwise it returns 0, since the ID number of a load test is repository-specific. To retrieve a list of the load test names however, you can use the GetDirectory function with the DIRECTORY_RESULT parameter. This function only returns meaningful results when used on the controller machine.

Include file

Kernel.bdh

Syntax

GetLoadtest() : number;

Return value

The ID number of the load test.

Example

dcltrans
  transaction TGetLoadtest
  var
    nLoadtest : number;
  begin
    nLoadtest := GetLoadtest();
    write("load test = "); write(nLoadtest); writeln;
  end TGetLoadtest;

Output

load test = 57
Parent topic: Load Test Control Functions


GetLoadtestName Function

Action

Returns the output directory name specified on starting the load test.

If the test runs on the local machine, this info could be extracted from the result of GetDirectory(DIRECTORY_RESULT). On an agent machine, however, GetDirectory(DIRECTORY_RESULT) returns a local directory on the agent machine.

Include file

Kernel.bdh

Syntax

GetLoadtestName( out sName     : string,
                 in  nNameSize : number optional );
Parameter | Description
sName | String receiving the load test name.
nNameSize | Number of characters to copy into sDir (optional, default is STRING_COMPLETE).

Example

dcltrans
  transaction TMain
  var
    sName: string;
  begin
    GetLoadtestName(sName);
    writeln(sName),
  end TMain;
Parent topic: Load Test Control Functions


GetProfile Function

Action

Retrieves the name of the settings profile that the current virtual user uses.

Include file

Kernel.bdh

Syntax

GetProfile(): string;

Return value

The name of the profile.

Example

dcluser
  user
    TestUser
  transactions
    TGetProfile : 1;
  dcltrans

  transaction TGetProfile
  var
    sProfile: string;
  begin
    sProfile := GetProfile();
    write("profile = "); write(sProfile); writeln;
  end TGetProfile;

Output

profile = Loadtest
Parent topic: Load Test Control Functions


GetProject Function

Action

Retrieves the name of the current load-test project.

Include file

Kernel.bdh

Syntax

GetProject(): string;

Return value

The name of the project.

Example

dcltrans
  transaction TGetProject
  var
    sProject: string;
  begin
    sProject := GetProject();
    write("project = "); write(sProject); writeln;
  end TGetProject;
Parent topic: Load Test Control Functions


GetRuntimes Function

Action

Retrieves the number of virtual users scheduled for the load test. The number is not decreased when a virtual user is stopped or finished.

Include files

Kernel.bdh

Syntax

GetRuntimes(): number;

Return value

The number of virutal users scheduled for the load test.

Example

dcluser
  user
    TestUser
  transactions
    TMain : 1;
  dcltrans
  transaction TMain
  var
    nRuntimes: number;
  begin
    nRuntimes := GetRuntimes();
    write("number of simulators started: ");
    write(nRuntimes); writeln;
  end TMain;
Parent topic: Load Test Control Functions


GetScriptName Function

Action

Returns the name of the currently executing BDL script with the path and the extension.

Include file

Kernel.bdh

Syntax

GetScriptName( in uOptions : number optional ): string;

Return value

The name of the currently executing BDL script.

Parameter Description
uOptions

(optional)

  • FILENAME_FULL: (default) Returns expanded absolute filename of the script.

  • FILENAME_NOPATH: Returns script filename without path.

  • FILENAME_NOEXTENSION: Returns absolute filename without the BDF extension.

  • FILENAME_SIMPLE: Returns script filename without path and extension.

Example

dclevent
  handler ErrorHandler <EVENT_RAISE_ERROR>
  var
    sTrac   : string;
    sFunc   : string;
    sScript : string;
  begin
    sTrac   := GetTransactionName();
    sFunc   := GetFunctionName();
    sScript := GetScriptName();
    print("error raised in transaction " + sTrac + " in function " + sFunc + " in script " + sScript);
    throw;
  end ErrorHandler;

dclfunc
  function f1
  begin
    //WebPageUrl will raise an error
    WebPageUrl("http://Does.not.exist");
  end f1;

dcltrans
  transaction TRaiseError
  begin
    f1();
  end TRaiseError;

Output

error raised in transaction TRaiseError in function f1 in script c:\tests\ScriptName\ScriptName.bdf
Parent topic: Load Test Control Functions


GetTransactionName Function

Action

Returns the name of the currently executing transaction. If it is called within an error handler, it will return the name of the transaction where the error was raised.

Include file

Kernel.bdh

Syntax

GetTransactionName(  ): string;

Return value

The name of the transaction.

Example

dclevent
  handler ErrorHandler <EVENT_RAISE_ERROR>
  var
    sBuf : string;
  begin
    sBuf := GetTransactionName();
    write("error raised in transaction " + sBuf);
    throw;
  end ErrorHandler;

dcltrans
  transaction TRaiseError
  begin
    // WebPageUrl will raise an error
    WebPageUrl("http://Does.not.exist");
  end TRaiseError;

Output

Error raised in transaction TRaiseError.
Parent topic: Load Test Control Functions
Related reference
Event Handler Section
GetFunctionName Function


GetUser Function

Action

Retrieves the name of the current user. The user name returned consists of the name of the user group defined in the workload section of the script concatenated with a serial number indicating the number of the user within the user group, with the two joined by an underscore character.

Include file

Kernel.bdh

Syntax

GetUser(): string;

Return value

The name of the current user.

Example

dcluser
  user
    TestUser
  transactions
    TGetUser : 1;

dcltrans
  transaction TGetUser
  var
    sUser: string;
  begin
    sUser := GetUser();
    write("user = "); write(sUser); writeln;
  end TGetUser;

Output

user = TestUser-<ProfileName>_1
Parent topic: Load Test Control Functions


GetUsergroup Function

Action

Retrieves the name of the user group to which the current virtual user belongs.

Include file

Kernel.bdh

Syntax

GetUsergroup(): string;

Return value

The name of the user group.

Example

dcluser
  user
    TestUser
  transactions
    TGetUsergroup : 1;
  dcltrans

  transaction TGetUsergroup
  var
    sUsergroup: string;
  begin
    sUsergroup := GetUsergroup();
    write("user group = "); write(sUsergroup); writeln;
  end TGetUsergroup;

Output

user group = TestUser
Parent topic: Load Test Control Functions


GetUserId Function

Action

Retrieves a unique ID (number) for each current virtual user in a load-test. The ID is 1 for the first virtual user, 2 for the second and n for the nth virtual user.

Include file

Kernel.bdh

Syntax

GetUserId(): number;

Return value

The unique identification number of the user.

Example

dcluser
  user
    TestUser
  transactions
    TGetUserId : 1;
dcltrans
  transaction TGetUserId
  var
    nUserId: number;
  begin
    nUserId := GetUserId();
    write("user ID = "); write(nUserId); writeln;
  end TGetUserId;

Output

user ID = 1
Parent topic: Load Test Control Functions


GetUserIdOnAgent Function

Action

Retrieves a unique ID (number) per current virtual user on an agent (machine). The ID is 1 for the first virtual user, 2 for the second and n for the nth virtual user. The number is unique per agent, but not across agents.

Include file

Kernel.bdh

Syntax

GetUserIdOnAgent(): number;

Return value

The unique identification number of the user.

Example

dcluser
  user
    TestUser
  transactions
    TGetUserIdOnAgent : 1;
dcltrans
  transaction
    TGetUserIdOnAgent
  var
    nUserIdOnAgent: number;
  begin
    nUserIdOnAgent := GetUserIdOnAgent();
    write("user ID on agent = "); write(nUserIdOnAgent); writeln;
  end TGetUserIdOnAgent;

Output

user ID on agent = 1
Parent topic: Load Test Control Functions


GetWorkload Function

Action

Retrieves the name of the active workload which the current virtual user executes.

Include file

Kernel.bdh

Syntax

GetWorkload(): string;

Return value

The name of the workload.

Example

dcluser
  user
    TestUser
  transactions
    TGetWorkload : 1;
dcltrans
  transaction TGetWorkload
  var
    sWorkload: string;
  begin
    sWorkload := GetWorkload();
    write("active workload = "); write(sWorkload); writeln;
  end TGetWorkload;

Output

active workload = LoadTest
Parent topic: Load Test Control Functions
Related reference
GetWorkloadModel Function


GetWorkloadModel Function

Action

Retrieves the type of the active workload which the current virtual user executes.

Include file

Kernel.bdh

Syntax

GetWorkloadModel( out sWorkloadType :string optional,
                  in  nCopy         : number ptional ): number;

Return value

The workload model type as a numeric constant value. Possible return values are:

  • WORKLOAD_STEADYSTATE

  • WORKLOAD_INCREASING

  • WORKLOAD_DYNAMIC

  • WORKLOAD_QUEUING

  • WORKLOAD_MONITORING

  • WORKLOAD_ALLDAY

  • WORKLOAD_VERIFICATION

  • WORKLOAD_SINGLEUSER

Parameter | Description
sWorkloadType | Buffer to receive the workload type string.
nCopy | Number of characters to copy to the buffer (optional, default is STRING_COMPLETE).
Note: If GetWorkloadModel returns WORKLOAD_QUEUING, the inout parameter sWorkloadType may not always carry the string "Queuing". The workload models "Try-Script" and "Baseline Test" are as well handled as a queuing workload.

Example

dcluser
  user
    TestUser
  transactions
    TGetWorkload : 1;

dcltrans
  transaction TGetWorkload
  var
    sWorkload: string;
  begin
    if GetWorkloadModel(sWorkload) = WORKLOAD_QUEUING then
      write("active workload type = "); write (sWorkload); writeln;
    else
      write("No queuing workload set.")
    end
  end TGetWorkload;

Output

active workload type = Try Script
Parent topic: Load Test Control Functions
Related reference
GetWorkload Function


Logging Functions Overview

Depending on how you configure Silk Performer, log files can be generated during a test. These files report all function calls invoked by the transactions during the simulation and can be useful for debugging your test scripts. Each user writes a separate log file. These files are text files named as follows:

<agentname>_<usergroupname>_<usernumber>.log

A log file may contain the following types of session and error information:

  • Session ID

  • Data received in Kb

  • Elapsed session time

  • Function / Error / Comment

  • Checkpoint Function
    Defines a checkpoint in a script to facilitate the monitoring of the success of a single user during a load test.
  • GetLogLevel Function
    Retrieves the simulation log level.
  • GetLogOption Function
    Retrieves the current logging options.
  • Print Function
    Prints additional information to the output.
  • PrintData Function
    Prints additional information (data) to the output.
  • PrintFunction Function
    Prints additional information to the output.
  • PrintInfo Function
    Prints additional information to the output.
  • RepMessage Function
    Writes a message to the repository.
  • SetLogOption Function
    Specifies logging options.
  • SetLogLevel Function
    Sets the simulation log level.
  • TrueLogInfo Function
    Logs an informational string to a synthetic TrueLog node of the virutal users TrueLog file.
  • TrueLogSection Function
    Adds additional structure to complex scripts.
  • Write Statement
    Outputs the value of Expr1 with field width Expr2 and precision Expr3 to the WRT file of the user executing the write statement.
  • WriteData Function
    Writes a specified number of bytes to the output file (.wrt) of the current virtual user.
  • WriteErr Function
    Writes to the error file of the current virtual user.
  • WriteLog Function
    Writes to the log file of the current user.
Parent topic: General Functions
Related concepts
Error-Handling Functions


Checkpoint Function

Action

To monitor the progress and success of a single user during a load test in a more precise manner than viewing the full output of the virtual user, checkpoints are used to divide transactions into user-defined sections. Checkpoint messages are visible in the output window during Try Scripts, and during load tests when the output of a single virtual user is enabled. The output of checkpoint messages can be enabled and disabled via the Checkpoint button on the monitor toolbar.

You can specify a message that the checkpoint displays in the output window. Additionally, you can set a timer for a checkpoint, which measures the time between the preceding checkpoint and the call of the checkpoint function. The first checkpoint in a transaction measures the time between the beginning of the transaction and the call of the checkpoint function. If an error, warning, or success message occurs between the preceding checkpoint and the call of the checkpoint function, the checkpoint message icon highlights the highest severity of all messages raised during the interval (error > warning > success).
Important: Checkpoint names must be unique across load tests.

Include file

kernel.bdh

Syntax

    Checkpoint(
      sCheckpointName : in string,
      sMessage : in string optional,
      bUseTimer : in boolean optional) : boolean;

Parameter | Description
sCheckpointName | The name of the checkpoint. Must be unique across the entire load test.
sMessage | An additional message that is displayed in the output window and the log file.
bUseTimer | If true, a timer with the checkpoint's name is created. The timer measures the time between the preceding checkpoint and the call of the checkpoint function. The first checkpoint in a transaction measures the time between the beginning of the transaction and the call of the checkpoint function.

Return value

  • true if successful
  • false otherwise

Example

benchmark BenchmarkName

use "kernel.bdh"
use "webapi.bdh"

dcluser
  user
    VirtUser
  transactions
    TMain       : 1;

dcltrans

  transaction TMain
  begin
    Checkpoint("checkpoint1s", "Hello World!", true);

    PrintData("hello", "the data");
    PrintFunction("func", "info");

    RaiseError(CUSTOM_ERROR, "This is a warning!", SEVERITY_WARNING);
    ThinkTime(2.0);

    MeasureStart("commonMeasure");
    Wait(0.5);
    MeasureStop("commonMeasure");

    Checkpoint("checkpoint2w", "2", true);

    ThinkTime(3.0);

    RaiseError(CUSTOM_ERROR, "This is an error!", SEVERITY_ERROR);

    Checkpoint("checkpoint3e", "this line should be displayed in red", true);

    ThinkTime(0.5);

    Checkpoint("checkpoint4s", "");

  end TMain;
Parent topic: Logging Functions Overview


GetLogLevel Function

Action

Retrieves the actual simulation log level. The log level determines the level of detail of information written to .log files. Values between 0 (no logging) and 4 (logging all details) are valid.

Note: This function will be removed in future versions and therefore should not be used.

Include file

Kernel.bdh

Syntax

GetLogLevel(): number;

Return value

current logging level (see Logging Levels)

Example

dcltrans
  transaction TGetLogLevel
  var
    nLogLevel: number;
  begin
    nLogLevel := GetLogLevel();
    write("log level = "); write(nLogLevel); writeln;
  end TGetLogLevel;

Output

log level = 2
Parent topic: Logging Functions Overview


GetLogOption Function

Action

Retrieves the current setting whether to generate log files (.log), and if so, which kind of information to write to the files. Log files contain information about timers, transactions performed by a user, and function calls invoked by the transactions.

Include file

Kernel.bdh

Syntax

GetLogOption(): number;

Return value

Current logging option. See the SetLogOption function for a description of all flags this function may return.

Example

dcltrans
  transaction TMain
  var
    nOption: number;
  begin
    nOption := GetLogOption();
    if nOption & OPT_LOG_TRANSACTIONS = OPT_LOG_TRANSACTIONS then
      write("transactions are included in the log file")
    else
      write("transactions are not included in the log file")
    end;
  writeln;
end TMain;
Parent topic: Logging Functions Overview
Related reference
SetLogOption Function


Print Function

Action

Prints additional information to the output that displays on the Virtual User tab in the Output pane. Additionally, the data is written to the log file.

Include file

Kernel.bdh

Syntax

Print( in sMsg         : string,
       in nDisplayType : number optional,
       in nColor       : number optional);
Parameter | Description
sMsg | The information (message) that is printed in the Text column of the Virtual User tab in the Output pane.
nDisplayType

Specifies which option(s) must be set in the upper part of the Monitor window so that the information is generated (optional). If the message does not display on the Virtual User tab in the Output pane, make sure to enable all respective filters.

  • OPT_DISPLAY_ERRORS

  • OPT_DISPLAY_TRANSACTIONS

  • OPT_DISPLAY_TIMERS

  • OPT_DISPLAY_FUNCTIONS

  • OPT_DISPLAY_INFO

  • OPT_DISPLAY_DATA

  • OPT_DISPLAY_ALL. Generates the message independent of the Monitor window settings (default).

nColor

Color used to print the information (optional). Defined colors are:

  • TEXT_BLUE

  • TEXT_RED

  • TEXT_BLACK

  • TEXT_MAGENTA (default)

  • TEXT_GREEN

  • TEXT_GRAY

Example

dcltrans
  transaction TPrint
  begin
    ...
    // display the message in red
    Print("Error executing SQL command", OPT_DISPLAY_ALL, TEXT_RED);
  end TPrint;

Output

Error executing SQL command

Sample scripts

Trans.bdf, MutexLogin.bdf

Parent topic: Logging Functions Overview


PrintData Function

Action

Prints additional information (data) to the output that displays on the Virtual User tab in the Output pane. Additionally, the data is written to the log file.

Include file

Kernel.bdh

Syntax

PrintData( in sFuncName : string,
           in sData     : string );
Parameter | Description
sFuncName | The function name that is printed in the Text column of the Virtual User tab in the Output pane.
sData | The information that is printed in the Info column of the Virtual User tab in the Output pane.

Example

dcltrans
  transaction TMain
  begin
    ...
    PrintFunction("MyFunction", "function info in green");
    PrintInfo("MyFunction", "additional info in magenta");
    PrintData("MyFunction", "additional info in blue");
  end TMain;
Parent topic: Logging Functions Overview


PrintFunction Function

Action

Prints additional information to the output that displays on the Virtual User tab in the Output pane. Additionally, the data is written to the log file.

Include file

Kernel.bdh

Syntax

PrintInfo( in sFuncName  : string,
           in sInfo      : string );
Parameter | Description
sFuncName | The function name that is printed in the Text column of the Virtual User tab in the Output pane.
sInfo | The information that is printed in the Info column of the Virtual User tab in the Output pane.

Example

dcltrans
  transaction TMain
  begin
    ...
    PrintFunction("MyFunction", "function info in green");
    PrintInfo("MyFunction", "additional info in magenta");
    PrintData("MyFunction", "additional info in blue");
  end TMain;
Parent topic: Logging Functions Overview


PrintInfo Function

Action

Prints additional information to the output that displays on the Virtual User tab in the Output pane. Additionally, the data is written to the log file.

Include file

Kernel.bdh

Syntax

PrintInfo( in sFuncName  : string,
           in sInfo      : string );
Parameter | Description
sFuncName | The function name that is printed in the Text column of the Virtual User tab in the Output pane.
sInfo | The information that is printed in the Info column of the Virtual User tab in the Output pane.

Example

dcltrans
  transaction TMain
  begin
    ...
    PrintFunction("MyFunction", "function info in green");
    PrintInfo("MyFunction", "additional info in magenta");
    PrintData("MyFunction", "additional info in blue");
  end TMain;
Parent topic: Logging Functions Overview


RepMessage Function

Action

Writes a message to the following files:

  • .ERR file (if severity is SEVERITY_ERROR, SEVERITY_TRANS_EXIT, or SEVERITY_PROCESS_EXIT)

  • .LOG file

  • .RPT file

The message will be counted as an error if SEVERITY_ERROR is the selected severity.

Include file

Kernel.bdh

Syntax

RepMessage( in sMessage  : string,
            in nSeverity : number optional := SEVERITY_ERROR );
Parameter | Description
sMessage | Message that will be written to the file.
nSeverity Optional: Severity of the error that is raised if the verification fails. Can be one of the following values:
  • SEVERITY_SUCCESS: Success; no error (numerical value: 0)
  • SEVERITY_INFORMATIONAL: Informational; no error (numerical value: 1)
  • SEVERITY_WARNING: Warning; no error (numerical value: 2)
  • SEVERITY_ERROR: (Default) Error; simulation continues (numerical value: 3)
  • SEVERITY_TRANS_EXIT: Error; the active transaction is aborted (numerical value: 4)
  • SEVERITY_PROCESS_EXIT: Error; the simulation is aborted (numerical value: 5)

Example

transaction TMain
  begin
    ...
    RepMessage("Data successfully transferred", SEVERITY_SUCCESS);
  end TMain;
Parent topic: Logging Functions Overview


SetLogOption Function

Action

Specifies whether to generate log files (.log), and if so, which kind of information to write to the files. Log files contain information about timers, transactions performed by a user, and function calls invoked by the transactions. A separate log file is generated for each virtual user.

Note: This function overrides the settings in the General tab of the Profile Settings - Results dialog.

Include file

Kernel.bdh

Syntax

SetLogOption( in nOption : number );
Parameter Description
nOption

Logging option. If this parameter is set to 0, no log files are generated. Otherwise, if any combination of the following flags is passed to the function, a separate log file for each virtual user is generated.

  • OPT_LOG_ALL. Include all available types of information

  • OPT_LOG_TRANSACTIONS. Include an overview of all transactions a user performs

  • OPT_LOG_TIMERS. Include information of automatic and custom timers

  • OPT_LOG_APICALLS. Include an overview of all Silk Performer API calls a user performs

  • OPT_LOG_INFORMATIONAL. Include additional information, for example, connection information

  • OPT_LOG_DATA. Include data exchanged with the server

  • OPT_LOG_NONPRINTABLECHAR. Display in the log file all nonprintable characters as dots.

Example

dcltrans
  transaction TInit
  begin
    // include in the log file all transaction and
    // API function calls a user performs
    SetLogOption(OPT_LOG_TRANSACTIONS | OPT_LOG_APICALLS);
  end TInit;
Parent topic: Logging Functions Overview
Related reference
GetLogOption Function


SetLogLevel Function

Action

Sets the simulation log level. The log level determines the level of detail of information written to .log files. Values between 0 (no logging) and 4 (logging all details) are valid.

Note: This function will be removed in future versions and therefore should not be used.

Include file

Kernel.bdh

Syntax

SetLogLevel( in nLogLevel : number );
Parameter | Description
nLogLevel | Logging level (see Logging Levels)

Example

dcltrans
  transaction TSetLogLevel
  begin
    SetLogLevel(2);
    write("log level set to 2"); writeln;
  end TSetLogLevel;

Output

log level set to 2
Parent topic: Logging Functions Overview


TrueLogInfo Function

Action

Logs an informational string to a synthetic TrueLog node of the virtual users TrueLog file. You can specify the name of the TrueLog node with the sNodeName parameter. When the node is selected in TrueLog Explorer, the informational string is analyzed and TrueLog Explorer automatically chooses the rendering method for the informational string. For example: When passing XML data to the function, TrueLog Explorer will use the XML view to display the string.

The informational string is used for logging to the TrueLog, like the print or write functions. It is especially useful for debugging and visualization purposes.

Include file

kernel.bdh

Syntax

TrueLogInfo( in sInfo     : string,
             in sNodeName : string optional ): boolean;

Return value

  • true if successful

  • false otherwise

Parameter | Description
sInfo | Informational string displayed by TrueLog Explorer
sNodeName | The name of the node in the TrueLog Explorer tree

Example

benchmark SilkPerformerRecorder

use "WebAPI.bdh"

dcluser
  user
    VUser
  transactions
    TMain           : 1;

dcltrans
  transaction TMain
  var
    sData: string;
  begin

    TrueLogInfo("some information");

    TrueLogInfo("some more information", "more information");

    TrueLogInfo("<Object>"
                  "<Array>"
                    "<Integer>1</Integer>"
                    "<Integer>2</Integer>"
                    "<Integer>3</Integer>"
                    "<Integer>4</Integer>"
                  "</Array>"
                "</Object>", "xml data");

    WebParseDataBoundEx(sData);
    WebPageUrl("http://demo.borland.com/");
    TrueLogInfo(sData, "html data");

  end TMain;
Parent topic: Logging Functions Overview


TrueLogSection Function

Action

Adds structure to complex scripts and helps to logically divide scripts into smaller named parts. These named parts can be individually expanded and collapsed in the TrueLog Explorer tree, hereby reducing complexity and simplifying the visual structure of a TrueLog file.

Additionally, a comment and/or screenshot can be added to a TrueLogSection. This additional content will also be rendered by TrueLog Explorer. TrueLogSection names do not need to be unique. Silk Performer automatically adds TrueLog sections during recording.

To manually add a TrueLog section, click Insert TrueLog Section on the Silk Performer Recorder. To add a recording screenshot, check the Store screenshot check box in the TrueLog Section dialog, and click OK. When you close the dialog, a screenshot with a unique ID is stored in the Record TrueLog. During replay, a reference to this screenshot is stored in the Replay TrueLog.

Include file

kernel.bdh

Syntax

TrueLogSection( in sSectionName  : string,
                in sComment      : string optional,
                in sScreenshotId : string optional ): boolean;

Return value

  • true if successful

  • false otherwise

Parameter | Description
sSectionName | The name of the TrueLog section.
sComment | An optional message that is displayed in the output window and the log file.
sScreenshotId | Id of a screenshot that was taken during recording.

Example

benchmark SilkPerformerRecorder

use "WebAPI.bdh"

dcluser
  user
    VUser
  transactions
    TMain           : 1;

dcltrans
  transaction TMain
  var
  begin
    WebPageUrl("http://demo.borland.com/", "Unnamed page");

    TrueLogSection("Section: Web Service", "The Borland sample Web Service\r\n");

    WebPageLink("Borland Sample Web Service", "Service1 Web Service");
    WebPageLink("A_ReadMeFirst", "Service1 Web Service (#1)");

    WebPageBack(2);

    TrueLogSection("Section: Test Sites", "entering test sites", "Screenshot_6133563");

    WebPageLink("Test Sites", "SilkPerformer Test Site");
    WebPageLink("ShopIt V 6.0", "ShopIt - Greetings");
  end TMain;
Parent topic: Logging Functions Overview


WriteData Function

Action

Writes a specified number of bytes to a new line of the output file (.wrt) of the virtual user. This function can be used to write binary data in a readable notation.

Note: Output files (.wrt) are generated only if the generation of these files is enabled in the General tab of the Profile Settings - Results dialog.

Include file

Kernel.bdh

Syntax

WriteData( in sData    : string,
           in nDataLen : number optional,
           in nOption  : number optional ): boolean;

Return value

  • true if successful

  • false otherwise

Parameter | Description
sData | String buffer containing the data to write to the output file.
nDataLen | Number of bytes to be written to the output file (optional).
nOption

Specifies the format used for writing (optional). Can be one of the following:

  • OPT_WRITEDATA_PRINTABLE (default). If the string buffer contains only printable characters, the ASCII representation of the data is printed. Otherwise, a mixed notation is used

  • OPT_WRITEDATA_HEX. A mixed notation is used for writing

  • OPT_WRITEDATA_HEXONLY. The data is printed in hexadecimal notation

Example

transaction TMain
  var
    s1: string;
  begin
    SetMem(s1, 1, "\h20212223243040414243444546" "Micro Focus Software Corporation", 27);
    write("Default: <");
    WriteData(s1);
    writeln(">");
    write("OPT_WRITEDATA_PRINTABLE: <");
    WriteData(s1, STRING_COMPLETE, OPT_WRITEDATA_PRINTABLE);
    writeln(">");
    write("OPT_WRITEDATA_HEX: <");
    WriteData(s1, STRING_COMPLETE, OPT_WRITEDATA_HEX);
    writeln(">");
    write("OPT_WRITEDATA_HEXONLY: <");
    WriteData(s1, STRING_COMPLETE, OPT_WRITEDATA_HEXONLY);
    writeln(">");
  end TMain;
Parent topic: Logging Functions Overview
Related reference
Write Statement


WriteErr Function

Action

Writes to the .err file of the current virtual user.

Note: Error files (.err) are written only if the Virtual user report on error files (.rpt) option is enabled in the General tab of the Profile Settings - Results dialog.

Include file

Kernel.bdh

Syntax

WriteErr( in sErrMsg : string );
Parameter | Description
sErrMsg | String containing the message to write to the .err file

Example

WriteErr("Function MyFunc failed");
Parent topic: Logging Functions Overview


WriteLog Function

Action

Writes to the .log file of the current user.

Note: Log files (.log) are written only if the generation of these files is enabled in the General tab of the Profile Settings - Results dialog.

Include file

Kernel.bdh

Syntax

WriteLog( in sLogMsg : string );
Parameter | Description
sLogMsg | String containing the message to write to the .log file

Example

WriteLog("Info: Successfully connected");
Parent topic: Logging Functions Overview


Measurement Functions

Measures and timers are user-defined measurement periods for which time measurements are included in the results repository and individual result files. You should create measures or timers for each component of a transaction of which you wish to analyze performance.

Measures and timers enable you to analyze the following:

  • Throughput information. The rate at which a given measure or timer is processed on average by the server. This allows you to analyze performance from the point of view of the server.

  • Response time information. The total time to process a given measure or timer. This provides application performance information from the point of view of the client computer.

Silk Performer automatically performs time measurements for transactions, Web forms, Web errors, SQL commands, and SQL errors.

  • Measure Function
    Specifies whether to perform measurements.
  • MeasureStart Function
    Starts a custom time measure in a transaction or a function.
  • MeasurePause Function
    Pauses a custom time measure.
  • MeasureResume Function
    Restarts a custom time measure.
  • MeasureStop Function
    Stops a custom time measure.
  • MeasureInc Function
    Increments a custom counter.
  • MeasureIncFloat Function
    Increments the value of a custom counter by a floating-point value.
  • MeasureGet Function
    Retrieves a specified value from a Silk Performer simulation measurement or a user-defined measure.
  • MeasureSet Function
    Sets the value of a counter/time.
  • MeasureSetBound Function
    Sets the bound values for a user-defined time measure.
  • MeasureSetFloat Function
    Sets the value of a counter/timer.
  • MeasureSetOption Function
    Set different options for a measure or measure group.
  • MeasureSetRaw Function
    Sets the raw values of a counter/timer.
  • MeasureSetTimer Function
    Sets the value of a timer.
  • MeasureTimeseries Function
    Determines whether to generate time series data for specific Silk Performer simulation measurements.
  • MeasureCalculateRawPercentiles Function
    Enables the collection of quantile data for the measure.
  • MeasureCalculatePercentiles Function (Deprecated)
    Calls the MeasureCalculateRawPercentiles function.
  • MeasureGetPercentile Function
    Retrieves the quantile value of a measure.
  • MeasureCollectRawData Function
    Enables the collection of raw data for a certain measure.
Parent topic: General Functions


Measure Function

Action

Specifies whether to perform measurements. This function turns the generation of results that are written to report files and the result repository on or off. Calling this function is only successful if neither a warm-up time nor a measurement time is specified in the workload settings.
Note: This function does not affect the creation of time series data files.

Include file

Kernel.bdh

Syntax

Measure( in nStatus: number ): boolean;

Return value

  • true if successful

  • false otherwise

Parameter Description
nStatus

Specifies whether to enable or disable measurements. This parameter must contain one of the following flags:

  • MEASURE_ON. Enables measurements

  • MEASURE_OFF. Disables measurements

Example

dclrand
  rWait: RndUniF(0.0 .. 1.0);

dcltrans
  transaction TInit
  begin
    Measure(MEASURE_OFF);
  end TInit;

  transaction TMain
  var
    nCount: number init 0;
  begin
    nCount := nCount + 1;
    if nCount = 10 then Measure(MEASURE_ON) end;
    if nCount = 20 then Measure(MEASURE_OFF) end;
  end TMain;
Parent topic: Measurement Functions


MeasureStart Function

Action

Starts a custom time measure in a transaction or a function with a specified measure name.

The results of the time measurements are reported in the result files and the result database of Silk Performer. You need not define time measures for SQL commands, Web forms, entire transactions, and wait statements because Silk Performer automatically measures the time for these statements.

Include file

Kernel.bdh

Syntax

MeasureStart( in sMeasure : string ): boolean;

Return value

  • true if successful

  • false otherwise

Parameter | Description
sMeasure | Measure name used to identify the measure when calling additional measure functions and when analyzing the results written to both the results repository and individual result files

Example

dcltrans
  transaction TMain
  var
    fValue : float;
    nTime : number;
  begin
    MeasureStart("TimeMeasure");
    wait 1.0;
    MeasurePause("TimeMeasure");
    wait 2.0;
    MeasureResume("TimeMeasure");
    wait 3.0;
    nTime := MeasureStop("TimeMeasure");
    MeasureGet("TimeMeasure", MEASURE_TIMER_RESPONSETIME, MEASURE_KIND_SUM, fValue);
    write("time = "); write(nTime); writeln;
    write("value = "); write(fValue); writeln;
  end TMain;

Sample scripts

Measure01.bdf, Measure02.bdf, Measure03.bdf, OraArrayFetch.bdf, OraSample.bdf, DBApi01.bdf, Trans.bdf, MutexLogin.bdf, WebMeasure01.bdf, WebTimer01.bdf

Parent topic: Measurement Functions
Related reference
MeasureStop Function
MeasurePause Function
MeasureResume Function


MeasurePause Function

Action

Pauses a custom time measure until the MeasureResume function is called, and returns the current value of the time measure.

Include file

Kernel.bdh

Syntax

MeasurePause( in sMeasure : string ): number;

Return value

Current value of the custom time measure in 1/1000 secs.

Parameter | Description
sMeasure | Measure name identifying the custom time measure to pause

Example

dcltrans
  transaction TMain
  var
    fValue : float;
    nTime : number;
  begin
    MeasureStart("TimeMeasure");
    wait 1.0;
    MeasurePause("TimeMeasure");
    wait 2.0;
    MeasureResume("TimeMeasure");
    wait 3.0;
    nTime := MeasureStop("TimeMeasure");
    MeasureGet("TimeMeasure", MEASURE_TIMER_RESPONSETIME,
    MEASURE_KIND_SUM, fValue);
    write("time = "); write(nTime); writeln;
    write("value = "); write(fValue); writeln;
  end TMain;
Parent topic: Measurement Functions
Related reference
MeasureStart Function
MeasureStop Function
MeasureResume Function


MeasureResume Function

Action

Restarts a custom time measure that was paused with the MeasurePause function. The time will be added to the time measured before the MeasurePause function was called.

Include file

Kernel.bdh

Syntax

MeasureResume( in sMeasure : string ): number;

Return value

Current value of the custom time measure in 1/1000 secs.

Parameter | Description
sMeasure | Measure name identifying the custom time measure to resume

Example

dcltrans
  transaction TMain
  var
    fValue : float;
    nTime : number;
  begin
    MeasureStart("TimeMeasure");
    wait 1.0;
    MeasurePause("TimeMeasure");
    wait 2.0;
    MeasureResume("TimeMeasure");
    wait 3.0;
    nTime := MeasureStop("TimeMeasure");
    MeasureGet("TimeMeasure", MEASURE_TIMER_RESPONSETIME, MEASURE_KIND_SUM, fValue);
    write("time = "); write(nTime); writeln;
    write("value = "); write(fValue); writeln;
  end TMain;
Parent topic: Measurement Functions
Related reference
MeasurePause Function
MeasureStart Function
MeasureStop Function


MeasureStop Function

Action

Stops a custom time measure started with the MeasureStart function and returns the value of the time measure. It waits for all running threads (WebThreadWait) and stops the page timer.

The results of the measurements are reported in the result files and the result database of Silk Performer. You need not define measures for SQL commands, Web forms, entire transactions, or wait statements because Silk Performer automatically measures the time for these statements.

Include file

Kernel.bdh

Syntax

MeasureStop( in sMeasure       :string
             in bIgnoreOnError : boolean optional ): number;

Return value

Final value of the custom time measure in 1/1000 secs.

Parameter | Description
sMeasure | Measure name identifying the custom time measure to stop
bIgnoreOnError | When enabled, measured time is included in calculations if no error has occurred since the timer started (optional). The default value is false.

Example

dcltrans
  transaction TMain
  var
    fValue : float;
    nTime : number;
  begin
    MeasureStart("TimeMeasure");
    wait 1.0;
    MeasurePause("TimeMeasure");
    wait 2.0;
    MeasureResume("TimeMeasure");
    wait 3.0;
    nTime := MeasureStop("TimeMeasure");
    MeasureGet("TimeMeasure", MEASURE_TIMER_RESPONSETIME,
    MEASURE_KIND_SUM, fValue);
    write("time = "); write(nTime); writeln;
    write("value = "); write(fValue); writeln;
  end TMain;

Sample scripts

Measure01.bdf, Measure02.bdf, Measure03.bdf, OraArrayFetch.bdf, OraSample.bdf, DBApi01.bdf, Trans.bdf, MutexLogin.bdf, WebMeasure01.bdf, WebTimer01.bdf

Parent topic: Measurement Functions
Related reference
MeasureStart Function
MeasurePause Function
MeasureResume Function


MeasureInc Function

Action

Increments the value of a custom counter. When this function is called for a specified custom counter for the first time, the counter is automatically allocated and initialized. You do not need to call any other measure functions when using a Silk Performer measure for counting purposes.

Include file

Kernel.bdh

Syntax

MeasureInc( in sMeasure : string,
            in nInc     : number optional,
            in nType    : number optional): number;

Return value

The value of the custom counter after the increment operation.

Parameter | Description
sMeasure | Measure name identifying the custom counter to increment
nInc

Increment value (optional). If this parameter is omitted, the custom counter is incremented by 1.

This parameter must not be negative or zero.
nType

Specifies the type of the custom counter. By default, this function adds up all values that are passed on successive calls.

Pass the MEASURE_KIND_AVERAGE flag to the function to calculate the average value instead of the sum. In this case, treat the custom counter as an average counter when you retrieve its value with the MeasureGet function.

Example

dcluser
  user
    TestUser
  transactions
    TInit : begin;
    TMain : 10;
    TShutdown : end;

dcltrans
  transaction TInit
  begin
    // start custom time measurement
    MeasureStart("TimeMeasure");
  end TInit;

  transaction TMain
  begin
    // increment custom counter
    MeasureInc("TranCounter");
    wait 0.3;
  end TMain;

  transaction TShutdown
  var
    fValue: float;
  begin
    // stop custom time measurement
    MeasureStop("TimeMeasure");
    MeasureGet("TimeMeasure", MEASURE_TIMER_RESPONSETIME, MEASURE_KIND_SUM, fValue);
    write("Transaction execution took "); write(fValue);
    write(" seconds"); writeln;
    MeasureGet("TINIT", MEASURE_TRANS_TRANSOK, MEASURE_KIND_COUNT, fValue);
    write("TInit transaction was executed "); write(fValue);
    write(" times"); writeln;
    MeasureGet("TranCounter", MEASURE_COUNTER_CUSTOMCOUNTER, MEASURE_KIND_SUM, fValue);
    write("TMain transaction was executed "); write(fValue);
    write(" times"); writeln;
  end TShutdown;

Sample scripts

Measure02.bdf

Parent topic: Measurement Functions
Related reference
MeasureGet Function


MeasureIncFloat Function

Action

Increments the value of a custom counter by a floating-point value. When this function is called for a specified custom counter for the first time, the counter is automatically allocated and initialized. You do not need to call any other measure functions when using a Silk Performer measure for counting purposes.

Include file

Kernel.bdh

Syntax

MeasureIncFloat( in sMeasure : string,
                 in fValue   : float,
                 in sUnit    : string optional,
                 in nUsage   : number optional ):float;

Return value

The value of the custom counter after the increment operation.

Parameter | Description
sMeasure | Measure name identifying the custom counter to increment.
fValue | Increment value. This parameter may be negative or zero.
sUnit | String that specifies the measurement unit (optional). The length of this string is limited to 19 characters.
nUsage

Defines the way in which Performance Explorer displays the counter by default (optional). This parameter can be one of the following.

  • MEASURE_USAGE_TIMER. The average value is displayed by default.

  • MEASURE_USAGE_SUM_COUNTER: The sum is displayed by default (default).

  • MEASURE_USAGE_AVG_COUNTER: The average value is displayed by default.

  • MEASURE_USAGE_SUMONLY_COUNTER: The sum is displayed as default. In this case you cannot choose a different data source.

  • MEASURE_USAGE_EVENT_COUNTER: The count value is displayed by default.

  • MEASURE_USAGE_AVGONLY_COUNTER: The average is displayed by default. In this case you cannot choose a different data source.

Example

dcltrans
  transaction TMain
  begin
    ...
    MeasureIncFloat("Custom Counter", 0.5, NULL, MEASURE_USAGE_SUMONLY_COUNTER);
    ...
  end TMain;
Parent topic: Measurement Functions
Related reference
MeasureInc Function


MeasureGet Function

Action

Retrieves a specific Silk Performer measure value, for example, the maximum, the minimum or the average value of a specified measure performed during the simulation of the current virtual user, or the standard deviation of the collected measure values.

Using this function, you can do the following:

  • Retrieve the value of a custom time measurement performed using the MeasureStart and the MeasureStop function.

  • Retrieve the counter value of a custom counter accessed using the MeasureInc function.

  • Check how often specific transactions have been executed successfully, and how often given transactions have been canceled.

  • Retrieve response times and throughput information concerning SQL commands, Web forms, CORBA objects, and TUXEDO services.

Include file

Kernel.bdh

Syntax

MeasureGet( in  sName  : string,
            in  nClass : number,
            in  nKind  : number,
            out fTime  : float,
            in  bAll   : boolean optional):boolean;

Return value

  • true if successful

  • false otherwise

Parameter | Description
sName

Name of the object concerned with the measurement. Must be one of the following:

  • Custom time measure. Pass to the function exactly the same name as to the MeasureStart and the MeasureStop function

  • Custom counter. Pass to the function exactly the same name as to the MeasureInc function

  • Transaction. Specify the transaction name as declared in the load testing script.

  • SQL command. Make sure to specify the SQL command identifier (defined in the dclsql section of the test script) in capital letters.

  • Web form. Make sure the specify the Web form identifier (defined in the dclform section of the test script) in capital letters.

  • CORBA object

  • TUXEDO service

nClass

Specifies the type of measure to retrieve.

To retrieve the value of a custom time measure, pass the MEASURE_TIMER_RESPONSETIME parameter to the function.

To retrieve the value of a custom counter, pass the MEASURE_COUNTER_CUSTOMCOUNTER parameter to the function.

To retrieve the value of an average counter, pass the MEASURE_COUNTER_AVERAGE parameter to the function.

In any other case, pass any of the following parameters to the function, depending on the type of information you are interested in.

  • MEASURE_PAGE_PAGETIME (for protocol-level load testing)

  • MEASURE_PAGE_ACTIONTIME (for browser-driven load testing)

  • MEASURE_PAGE_PAGEBYTES

  • MEASURE_PAGE_EMBEDDEDBYTES

  • MEASURE_PAGE_DOCDOWNLOAD

  • MEASURE_PAGE_SERVERBUSY

  • MEASURE_IIOP_ROUNDTRIP

  • MEASURE_IIOP_SERVERBUSY

  • MEASURE_SQL_SQLPARSE

  • MEASURE_SQL_SQLEXEC

  • MEASURE_SQL_SQLEXECDIRECT

  • MEASURE_TRANS_TRANSOK

  • MEASURE_TRANS_TRANSERR

  • MEASURE_TRANS_TRANSCA

  • MEASURE_FORM_BYTESSENT

  • MEASURE_FORM_BYTESRECEIVED

  • MEASURE_FORM_HITSOK

  • MEASURE_FORM_HITSERR

  • MEASURE_FORM_ROUNDTRIP

  • MEASURE_FORM_SERVERBUSY

  • MEASURE_TUXEDO_BYTESSENT

  • MEASURE_TUXEDO_BYTESRECEIVED

  • MEASURE_TUXEDO_RESPONSETIME

nKind

Specifies the type of measure value to retrieve. The following options are possible:

  • MEASURE_KIND_SUM. Retrieves the sum of all measure values, for example, the total time for executing all transactions

  • MEASURE_KIND_COUNT. Retrieves the number how often an action was performed, for example, how often a counter was incremented, or how often a transaction was executed

  • MEASURE_KIND_AVERAGE. Returns the average of all measure values, for example, the average time required for a CORBA operation call.

  • MEASURE_KIND_MIN. Returns the minimum of all measure values

  • MEASURE_KIND_MAX. Returns the maximum of all measure values

  • MEASURE_KIND_LAST. Returns the last value set for the measure

  • MEASURE_KIND_SQSUM. Calculates for each measure value the square value, and sums up all square values.

  • MEASURE_KIND_STDEVIATION. Returns the standard deviation of all measured values

fTime | Variable receiving the measure value
bAll

Specifies the time interval used for measurement value calculation (optional).

  • If this parameter is set to true, the measure value is calculated based on all measurements performed during the simulation.

  • Otherwise, if this parameter is set to false, the measure value is calculated based only on the measurements performed during the measurement interval (default).

Example

dcluser
  user
    TestUser
  transactions
    TInit : begin;
    TMain : 10;
    TShutdown : end;

dcltrans
  transaction TInit
  begin
    // start custom time measurement
    MeasureStart("TimeMeasure");
  end TInit;

  transaction TMain
  begin
    // increment custom counter
    MeasureInc("TranCounter");
    wait 0.3;
  end TMain;

  transaction TShutdown
  var
    fValue: float;
  begin
    // stop custom time measurement
    MeasureStop("TimeMeasure");
    MeasureGet("TimeMeasure", MEASURE_TIMER_RESPONSETIME, MEASURE_KIND_SUM, fValue);
    write("Transaction execution took "); write(fValue);
    write(" seconds"); writeln;
    MeasureGet("TInit", MEASURE_TRANS_TRANSOK, MEASURE_KIND_COUNT, fValue);
    write("TInit transaction was executed ");
    write(fValue);
    write(" times"); writeln;
    MeasureGet("TranCounter", MEASURE_COUNTER_CUSTOMCOUNTER, MEASURE_KIND_COUNT, fValue);
    write("TMain transaction was executed ");
    write(fValue);
    write(" times"); writeln;
  end TShutdown;

Sample scripts

Measure01.bdf, WebMeasure01.bdf

Parent topic: Measurement Functions
Related reference
MeasureStart Function
MeasureStop Function
MeasureSetFloat Function
MeasureSet Function


MeasureSet Function

Action

Sets the value of a counter/timer identified by sName and nClass. When this function is called for a specified counter/timer for the first time, the counter is automatically allocated and initialised.

Predefined measures are using following units:

  • for timers: milliseconds.

  • for capacities: bytes.

Include file

Kernel.bdh

Syntax

MeasureSet(in sName     :string,
           in nClass    : number,
           in nValue    : number): boolean;

Return value

  • true if successful

  • false otherwise

Parameter Description
sName

Name of the object concerned with the measurement. Must be one of the following:

  • Custom time measure.

  • Custom counter.

  • Transaction. Specify the transaction name as declared in the load testing script.

  • SQL command. Make sure to specify the SQL command identifier (defined in the dclsql section of the test script) in capital letters.

  • Web form. Make sure that the specified Web form identifier (defined in the dclform section of the test script) is in capital letters.

  • CORBA object

  • TUXEDO service

nClass

Specifies the type of measure to set.

To set the value of a custom time measure, pass the MEASURE_TIMER_RESPONSETIME parameter to the function.

To set the value of a custom counter, pass the MEASURE_COUNTER_CUSTOMCOUNTER parameter to the function.

To set the value of an average counter, pass the MEASURE_COUNTER_AVERAGE parameter to the function.

In any other case, pass any of the following parameters to the function, depending on the type of information you are interested in.

  • MEASURE_PAGE_PAGETIME (for protocol-level load testing)

  • MEASURE_PAGE_ACTIONTIME (for browser-driven load testing)

  • MEASURE_PAGE_PAGEBYTES

  • MEASURE_PAGE_EMBEDDEDBYTES

  • MEASURE_PAGE_DOCDOWNLOAD

  • MEASURE_PAGE_SERVERBUSY

  • MEASURE_IIOP_ROUNDTRIP

  • MEASURE_IIOP_SERVERBUSY

  • MEASURE_SQL_SQLPARSE

  • MEASURE_SQL_SQLEXEC

  • MEASURE_SQL_SQLEXECDIRECT

  • MEASURE_TRANS_TRANSOK

  • MEASURE_TRANS_TRANSERR

  • MEASURE_TRANS_TRANSCA

  • MEASURE_FORM_BYTESSENT

  • MEASURE_FORM_BYTESRECEIVED

  • MEASURE_FORM_HITSOK

  • MEASURE_FORM_HITSERR

  • MEASURE_FORM_ROUNDTRIP

  • MEASURE_FORM_SERVERBUSY

  • MEASURE_TUXEDO_BYTESSENT

  • MEASURE_TUXEDO_BYTESRECEIVED

  • MEASURE_TUXEDO_RESPONSETIME

nValue

Value to set. Predefined measures are using following units:

  • for timers: milliseconds.

  • for capacities: bytes.

Example

dcltrans
  transaction TMain
  var
    fValue :  float;
  begin
    MeasureSet("measure2", MEASURE_COUNTER_CUSTOMCOUNTER, 22);
    ...
    MeasureSet("measure2", MEASURE_COUNTER_CUSTOMCOUNTER, 22);
    ...
    MeasureGet("measure2", MEASURE_COUNTER_CUSTOMCOUNTER,
               MEASURE_KIND_SUM, fValue);
    Print("Val: " + string(fValue)); // expected value: 44
  end TMain;
Parent topic: Measurement Functions
Related reference
MeasureGet Function
MeasureSetFloat Function
MeasureSetBound Function
MeasureSetRaw Function
MeasureSetTimer Function


MeasureSetBound Function

Action

Determines the bound value for a specified time measure or the default bound value for a specified time measure type. Result reports list the percentage of all time measure values within the time bound specified. A time bound is commonly set to the amount of time that represents the goal for the completion of, for example, the transaction being tested. An optional severity level value may be specified for a bound exceeding message, which is reported whenever this bound is exceeded by a value.

Ideally, this function is called before a measure is created and/or used.

Include file

Kernel.bdh

Syntax

MeasureSetBound( in sName     : string allownull,
                 in nClass    : number,
                 in nBound    : number,
                 in fValue    : float,
                 in nSeverity : number optional := SEVERITY_ERROR ): boolean;

Return value

  • true if successful

  • false otherwise

Parameter | Description
sName | Measure name identifying the measure. If this parameter is set to NULL or "" the default bound is set for the provided measure type.
nClass Measure class or measure type, must be one of the following:

  • MEASURE_PAGE_PAGETIME (for protocol-level load testing)

  • MEASURE_PAGE_ACTIONTIME (for browser-driven load testing)

  • MEASURE_PAGE_PAGEBYTES

  • MEASURE_PAGE_EMBEDDEDBYTES

  • MEASURE_PAGE_DOCDOWNLOAD

  • MEASURE_PAGE_SERVERBUSY

  • MEASURE_IIOP_ROUNDTRIP

  • MEASURE_IIOP_SERVERBUSY

  • MEASURE_TIMER_RESPONSETIME

  • MEASURE_COUNTER_CUSTOMCOUNTER

  • MEASURE_SQL_SQLPARSE

  • MEASURE_SQL_SQLEXEC

  • MEASURE_SQL_SQLEXECDIRECT

  • MEASURE_TRANS_TRANSOK

  • MEASURE_TRANS_TRANSERR

  • MEASURE_TRANS_TRANSCA

  • MEASURE_FORM_BYTESSENT

  • MEASURE_FORM_BYTESRECEIVED

  • MEASURE_FORM_HITSOK

  • MEASURE_FORM_HITSERR

  • MEASURE_FORM_ROUNDTRIP

  • MEASURE_FORM_SERVERBUSY

  • MEASURE_TUXEDO_BYTESSENT

  • MEASURE_TUXEDO_BYTESRECEIVED

  • MEASURE_TUXEDO_RESPONSETIME

nBound

Number of the measure bound specified through the fValue parameter.

If this parameter is set to 1, measure bound 1 will be set to fValue. Otherwise, if this parameter is set to 2, measure bound 2 will be set to fValue

fValue

Bound value for the specified measure (in seconds)

Note: If the value for bound 1 is higher than the value for bound 2, the measure is regarded with inverse logic: the higher the measured value the better.

For example: If a measure monitors a resource pool, a healthy value is one above bound 1. If the value falls below bound 1 but still is above bound 2, a warning might be triggered.

As a consequence, always define both bounds to avoid unwanted reporting behavior.

nSeverity Optional: Severity of the error that is raised if the verification fails. Can be one of the following values:
  • SEVERITY_SUCCESS: Success; no error (numerical value: 0)
  • SEVERITY_INFORMATIONAL: Informational; no error (numerical value: 1)
  • SEVERITY_WARNING: Warning; no error (numerical value: 2)
  • SEVERITY_ERROR: (Default) Error; simulation continues (numerical value: 3)
  • SEVERITY_TRANS_EXIT: Error; the active transaction is aborted (numerical value: 4)
  • SEVERITY_PROCESS_EXIT: Error; the simulation is aborted (numerical value: 5)

Example

dcltrans
  transaction TMain
  begin
    MeasureSetBound("Bank/AccountManager",
                    MEASURE_IIOP_ROUNDTRIP, 1, 5.0);
    MeasureSetBound("Bank/AccountManager",
                    MEASURE_IIOP_ROUNDTRIP, 2, 10.0,
                    SEVERITY_WARNING);
    MeasureSetBound("Bank/AccountManager",
                    MEASURE_IIOP_SERVERBUSY, 1, 3.0,
                    SEVERITY_WARNING);
    MeasureSetBound("Bank/AccountManager",
                    MEASURE_IIOP_SERVERBUSY, 2, 5.0,
                    SEVERITY_ERROR);

    ...
  end TMain;

Sample scripts

Measure03.bdf, WebMeasure01.bdf

Parent topic: Measurement Functions
Related reference
MeasureGet Function
MeasureSetFloat Function
MeasureSet Function
MeasureSetRaw Function
MeasureSetTimer Function


MeasureSetFloat Function

Action

Sets the value of a counter/timer identified by sName and nClass. When this function is called for a specified counter/timer for the first time, the counter is automatically allocated and initialised.

Predefined measures are using following units:

  • for timers: milliseconds.

  • for capacities: bytes.

Include file

Kernel.bdh

Syntax

MeasureSetFloat( in sName  : string,
                 in nClass : number,
                 in fValue : float ): boolean;

Return value

  • true if successful

  • false otherwise

Parameter Description
sName

Name of the object concerned with the measurement. Must be one of the following:

  • Custom time measure.

  • Custom counter.

  • Transaction. Specify the transaction name as declared in the load testing script.

  • SQL command. Make sure to specify the SQL command identifier (defined in the dclsql section of the test script) in capital letters.

  • Web form. Make sure that the specified Web form identifier (defined in the dclform section of the test script) is in capital letters.

  • CORBA object

  • TUXEDO service

nClass

Specifies the type of measure to set.

To set the value of a custom time measure, pass the MEASURE_TIMER_RESPONSETIME parameter to the function.

To set the value of a custom counter, pass the MEASURE_COUNTER_CUSTOMCOUNTER parameter to the function.

To set the value of an average counter, pass the MEASURE_COUNTER_AVERAGE parameter to the function.

In any other case, pass any of the following parameters to the function, depending on the type of information you are interested in.

  • MEASURE_PAGE_PAGETIME (for protocol-level load testing)

  • MEASURE_PAGE_ACTIONTIME (for browser-driven load testing)

  • MEASURE_PAGE_PAGEBYTES

  • MEASURE_PAGE_EMBEDDEDBYTES

  • MEASURE_PAGE_DOCDOWNLOAD

  • MEASURE_PAGE_SERVERBUSY

  • MEASURE_IIOP_ROUNDTRIP

  • MEASURE_IIOP_SERVERBUSY

  • MEASURE_SQL_SQLPARSE

  • MEASURE_SQL_SQLEXEC

  • MEASURE_SQL_SQLEXECDIRECT

  • MEASURE_TRANS_TRANSOK

  • MEASURE_TRANS_TRANSERR

  • MEASURE_TRANS_TRANSCA

  • MEASURE_FORM_BYTESSENT

  • MEASURE_FORM_BYTESRECEIVED

  • MEASURE_FORM_HITSOK

  • MEASURE_FORM_HITSERR

  • MEASURE_FORM_ROUNDTRIP

  • MEASURE_FORM_SERVERBUSY

  • MEASURE_TUXEDO_BYTESSENT

  • MEASURE_TUXEDO_BYTESRECEIVED

  • MEASURE_TUXEDO_RESPONSETIME

fValue

Value to set. Predefined measures are using following units:

  • for timers: milliseconds.

  • for capacities: bytes.

Example

dcltrans
  transaction TMain
  var
    fValue : float;
  begin
    MeasureSetFloat("measure2", MEASURE_COUNTER_CUSTOMCOUNTER, 22.2);
    ...
    MeasureSetFloat("measure2", MEASURE_COUNTER_CUSTOMCOUNTER, 22.2);
    ...
    MeasureGet("measure2", MEASURE_COUNTER_CUSTOMCOUNTER,
               MEASURE_KIND_SUM, fValue);
    Print("Val: " +string(fValue)); // expected value: 44.4
  end TMain;

Sample scripts

Measure03.bdf, WebMeasure01.bdf

Parent topic: Measurement Functions
Related reference
MeasureGet Function
MeasureSet Function


MeasureSetOption Function

Action

Set different options for a measure or measure group. You can enable or disable raw measure data or time series data collection. In addition, you can enable and configure the generation of quantile data, and you can enable real-time data collection so that you can see the measures in Performance Explorer during a test in real-time.

Include file

Kernel.bdh

Syntax

MeasureSetOption( in sName   : string,
                  in eClass  : number,
                  in eOption : number,
                  in uValue  : union): boolean;

Return value

  • true if successful

  • false otherwise

Parameter | Description
sName | Measure name that identifies the measure. When this parameter is set to NULL or "", the option is set for all measures of the provided measure type.
eClass Specifies the type of measure type.
  • MEASURE_IIOP_ROUNDTRIP
  • MEASURE_IIOP_SERVERBUSY
  • MEASURE_TIMER_RESPONSETIME
  • MEASURE_COUNTER_CUSTOMCOUNTER
  • MEASURE_SQL_SQLPARSE
  • MEASURE_SQL_SQLEXEC
  • MEASURE_SQL_SQLEXECDIRECT
  • MEASURE_TRANS_TRANSOK
  • MEASURE_TRANS_TRANSERR
  • MEASURE_TRANS_TRANSCA
  • MEASURE_FORM_BYTESSENT
  • MEASURE_FORM_BYTESRECEIVED
  • MEASURE_FORM_HITSOK
  • MEASURE_FORM_HITSERR
  • MEASURE_FORM_ROUNDTRIP
  • MEASURE_FORM_SERVERBUSY
  • MEASURE_TUXEDO_BYTESSENT
  • MEASURE_TUXEDO_BYTESRECEIVED
  • MEASURE_TUXEDO_RESPONSETIME
  • MEASURE_COUNTER_AVERAGE
  • MEASURE_PAGE_PAGETIME (for protocol-level load testing)
  • MEASURE_PAGE_DOCDOWNLOAD
  • MEASURE_PAGE_SERVERBUSY
  • MEASURE_PAGE_PAGEBYTES
  • MEASURE_PAGE_EMBEDDEDBYTES
  • MEASURE_PAGE_ACTIONTIME (for browser-driven load testing)
  • MEASURE_TRANS_TRANSBUSYOK
  • MEASURE_TRANS_TRANSBUSYERR
  • MEASURE_TRANS_TRANSBUSYCA
eOption Specifies the option which a value is set for.
  • MEASURE_OPT_REALTIME: Set the uValue parameter to true or false to enable or disable the collection of measure data for real-time view in Performance Explorer. The real-time measure data collection is disabled for all measures by default.
    Note: To enable real-time measure data in general, make sure to check the Enable real-time measures check box on the Workload Configuration dialog.
  • MEASURE_OPT_PERCENTILES: Set the uValue parameter to true or false to enable or disable percentile reporting for the specified measure or measure group.
  • MEASURE_OPT_PERCENTILES_GRANULARITY: Set the uValue parameter to the percentile granularity for the specified measure or measure group. The default value is OPT_PERCENTILES_GRANULARITY_10_PER_MIL. For a full list of granularity values see the topic MeasureCalculateRawPercentiles Function.
  • MEASURE_OPT_TIMESERIES: Set the uValue parameter to true or false to enable or disable time series data collection for the specified measure or measure group. The default value is defined by the corresponding profile setting.
  • MEASURE_OPT_RAWDATA: Set the uValue parameter to true or false to enable or disable raw data collection for the specified measure or measure group. The default value is defined by the corresponding profile setting.
uValue

The value related to the selected option. See the description of the eOption parameter for valid values.

Example

dcltrans
  transaction TMain
  var
    fValue :  float;
  begin
      MeasureSetOption("Measure1", MEASURE_PAGE_PAGETIME, MEASURE_OPT_REALTIME, true);

      MeasureSetOption("", MEASURE_PAGE_PAGETIME, MEASURE_OPT_RAWDATA, true);

      MeasureSetOption("", MEASURE_ALL, MEASURE_OPT_TIMESERIES, false);

      MeasureSetOption("Measure1", MEASURE_COUNTER_CUSTOMCOUNTER, MEASURE_OPT_PERCENTILES, true);
      MeasureSetOption("Measure1", MEASURE_COUNTER_CUSTOMCOUNTER, MEASURE_OPT_PERCENTILES_GRANULARITY, OPT_PERCENTILES_GRANULARITY_1_PER_MIL);

  end TMain;
Parent topic: Measurement Functions
Related reference
MeasureCalculateRawPercentiles Function
MeasureTimeseries Function
MeasureCollectRawData Function


MeasureSetRaw Function

Action

Sets the raw values of a counter/timer identified by sName and nClass. When this function is called for a specified counter/timer for the first time, the counter/timer is automatically allocated and initialised.

Predefined measures are using following units:

  • for timers: milliseconds.

  • for capacities: bytes.

Include file

Kernel.bdh

Syntax

MeasureSetRaw( in sName        : string,
               in nClass       : number,
               in nCount       : number,
               in fSum         : float,
               in fSqSum       : float,
               in fMin         : float,
               in fMax         : float,
               in nBelowBound1 : number optional,
               in nBelowBound2 : number optional ): boolean;

Return value

  • true if successful

  • false otherwise

Parameter | Description
sName

Name of the object concerned with the measurement. Must be one of the following:

  • Custom time measure.

  • Custom counter.

  • Transaction. Specify the transaction name as declared in the load testing script.

  • SQL command. Make sure to specify the SQL command identifier (defined in the dclsql section of the test script) in capital letters.

  • Web form. Make sure that the specified Web form identifier (defined in the dclform section of the test script) is in capital letters.

  • CORBA object

  • TUXEDO service

nClass

Specifies the type of measure to set.

To set the value of a custom time measure, pass the MEASURE_TIMER_RESPONSETIME parameter to the function.

To set the value of a custom counter, pass the MEASURE_COUNTER_CUSTOMCOUNTER parameter to the function.

To set the value of an average counter, pass the MEASURE_COUNTER_AVERAGE parameter to the function.

In any other case, pass any of the following parameters to the function, depending on the type of information you are interested in.

  • MEASURE_PAGE_PAGETIME (for protocol-level load testing)

  • MEASURE_PAGE_ACTIONTIME (for browser-driven load testing)

  • MEASURE_PAGE_PAGEBYTES

  • MEASURE_PAGE_EMBEDDEDBYTES

  • MEASURE_PAGE_DOCDOWNLOAD

  • MEASURE_PAGE_SERVERBUSY

  • MEASURE_IIOP_ROUNDTRIP

  • MEASURE_IIOP_SERVERBUSY

  • MEASURE_SQL_SQLPARSE

  • MEASURE_SQL_SQLEXEC

  • MEASURE_SQL_SQLEXECDIRECT

  • MEASURE_TRANS_TRANSOK

  • MEASURE_TRANS_TRANSERR

  • MEASURE_TRANS_TRANSCA

  • MEASURE_FORM_BYTESSENT

  • MEASURE_FORM_BYTESRECEIVED

  • MEASURE_FORM_HITSOK

  • MEASURE_FORM_HITSERR

  • MEASURE_FORM_ROUNDTRIP

  • MEASURE_FORM_SERVERBUSY

  • MEASURE_TUXEDO_BYTESSENT

  • MEASURE_TUXEDO_BYTESRECEIVED

  • MEASURE_TUXEDO_RESPONSETIME

nCount | Number of values for this measure that are set with this call.
fSum | Sum of the measure values.
fSqSum | Sqare sum of the measure values.
fMin | The minimum measure value.
fMax | The maximum measure value.
nBelowBound1 | Number of values for this measure that are below the time bound 1.
nBelowBound2 | Number of values for this measure that are below the time bound 2.

Example

transaction TMeasure
var
  fValue : float;
begin
  MeasureSetRaw("measure1", MEASURE_COUNTER_CUSTOMCOUNTER,
                10, 100.0, 1000.0, 9.0, 10.0);
  ...
  MeasureSetRaw("measure1", MEASURE_COUNTER_CUSTOMCOUNTER,
                2, 6.0, 12.0, 1.0, 4.0);
  ...
  MeasureGet("measure1", MEASURE_COUNTER_CUSTOMCOUNTER, MEASURE_KIND_COUNT, fValue);
  // expected value: 12
  Print("Measure Count: " + string(fValue));
  MeasureGet("measure1", MEASURE_COUNTER_CUSTOMCOUNTER, MEASURE_KIND_SUM, fValue);
  // expected value: 106
  Print("Sum of all measures: " + string(fValue));
  MeasureGet("measure1", MEASURE_COUNTER_CUSTOMCOUNTER, MEASURE_KIND_MIN, fValue);
  // expected value: 1
  Print("Minimum value of all measures: " + string(fValue));
end TMeasure;
Parent topic: Measurement Functions
Related reference
MeasureGet Function
MeasureSetFloat Function
MeasureSet Function
MeasureSetBound Function
MeasureSetTimer Function
MeasureSet Function


MeasureSetTimer Function

Action

Sets the value of a timer identified by sName. When this function is called for a specified timer for the first time, the counter is automatically allocated and initialized.

Include file

Kernel.bdh

Syntax

MeasureSetTimer( in sName  : string,
                 in nValue : number): boolean;

Return value

  • true if successful

  • false otherwise

Parameter | Description
sName | Name of the timer concerned with the measurement.
nValue | Value to set. In milliseconds.

Example

dcltrans
  transaction TMain
  var
    fValue : float;
  begin
    MeasureSetTimer("TimeMeasure", 2000);
    ...
    MeasureGet("TimeMeasure", MEASURE_TIMER_RESPONSETIME,
               MEASURE_KIND_SUM, fValue);
    Print("Val: " + string(fValue));
  end TMain;
Parent topic: Measurement Functions
Related reference
MeasureGet Function
MeasureSetFloat Function
MeasureSet Function
MeasureSetBound Function
MeasureSetRaw Function
MeasureSet Function


MeasureTimeseries Function

Action

Determines whether to generate time series data for a specified Silk Performer measurement.

If time series data generation is enabled, data will be written to the corresponding file (.tsd) and can be analyzed with Silk Performer Performance Explorer.

Include file

Kernel.bdh

Syntax

MeasureTimeseries( in nType : number,
                   in bTimeseries : boolean ): boolean;

Return value

  • true if successful

  • false otherwise

Parameter | Description
nType

Specifies the type of measurement for which to generate time series data. Silk Performer measure types are:

  • MEASURE_IIOP

  • MEASURE_TIMER

  • MEASURE_COUNTER

  • MEASURE_SQL

  • MEASURE_TRANS

  • MEASURE_FORM

  • MEASURE_TUXEDO

  • MEASURE_ALL

  • MEASURE_IIOP_ROUNDTRIP

  • MEASURE_IIOP_SERVERBUSY

  • MEASURE_TIMER_RESPONSETIME

  • MEASURE_COUNTER_CUSTOMCOUNTER

  • MEASURE_SQL_SQLPARSE

  • MEASURE_SQL_SQLEXEC

  • MEASURE_SQL_SQLEXECDIRECT

  • MEASURE_TRANS_TRANSOK

  • MEASURE_TRANS_TRANSERR

  • MEASURE_TRANS_TRANSCA

  • MEASURE_FORM_BYTESSENT

  • MEASURE_FORM_BYTESRECEIVED

  • MEASURE_FORM_HITSOK

  • MEASURE_FORM_HITSERR

  • MEASURE_FORM_ROUNDTRIP

  • MEASURE_FORM_SERVERBUSY

  • MEASURE_TUXEDO_BYTESSENT

  • MEASURE_TUXEDO_BYTESRECEIVED

  • MEASURE_TUXEDO_RESPONSETIME

bTimeseries | If this parameter is set to true, Silk Performer generates time series data for the specified measure type.

Example

dcltrans
  transaction TInit
  begin
    // generate time series data for CORBA operation calls
    MeasureTimeseries(MEASURE_IIOP, true);
    // generate time series data for executed SQL commands
    MeasureTimeseries(MEASURE_SQL, true);
    // no time series data for anything else
    MeasureTimeseries(MEASURE_TIMER, false);
    MeasureTimeseries(MEASURE_COUNTER, false);
    MeasureTimeseries(MEASURE_TRANS, false);
    MeasureTimeseries(MEASURE_FORM, false);
    MeasureTimeseries(MEASURE_TUXEDO, false);
    MeasureTimeseries(MEASURE_ALL, false);
  end TInit;
Parent topic: Measurement Functions
Related reference
MeasureSetOption Function
MeasureCalculateRawPercentiles Function
MeasureCollectRawData Function


MeasureCalculateRawPercentiles Function

Action

Enables the collection of quantile data for the measure identified by sName and nClass. Collected quantile data is shown in the overview report.

This function can be used before a measure is created and/or used, and must be located in the TInit transaction.

Due to memory limitations, Silk Performer does not collect absolute measurements. Instead, a limited set of categories is created and Silk Performer counts how often a certain category is hit. The size of a category is 1 millisecond for small measurements, for bigger measurements the upper boundary of the categories increases. To calculate the upper boundaries, the following formula is used (B stands for boundary):

B(n) = B(n-1) x (1+uGranularity)

This is the whole formula:

B(1) = 1ms
B(n) = max(B(n-1) + 1ms, B(n-1) x (1+uGranularity))

For example: If the granularity is 1 percent and the upper boundary of a certain category is 1000 milliseconds, the next category will range from 1000 to 1010 milliseconds.

The maximum error of a measurement of 1000 milliseconds is 1 percent or 10 milliseconds.

Include file

Kernel.bdh

Syntax

MeasureCalculateRawPercentiles( in sName        : string allownull,
                                in nClass       : number,
                                in bDisable     : boolean optional,
                                in uGranularity : number optional ): boolean;

Return value

  • true if successful

  • false otherwise

Parameter | Description
sName | Measure name that identifies the measure. When this parameter is set to NULL or "", quantile data collection is enabled for all measures of the provided measure type.
nClass Specifies the type of measure to retrieve.

To retrieve the value of a custom time measure, pass the MEASURE_TIMER_RESPONSETIME parameter to the function.

To retrieve the value of a custom counter, pass the MEASURE_COUNTER_CUSTOMCOUNTER parameter to the function.

To retrieve the value of an average counter, pass the MEASURE_COUNTER_AVERAGE parameter to the function.

In any other case, pass any of the following parameters to the function, depending on the type of information you are interested in.

  • MEASURE_PAGE_PAGETIME (for protocol-level load testing)
  • MEASURE_PAGE_ACTIONTIME (for browser-driven load testing)
  • MEASURE_PAGE_PAGEBYTES
  • MEASURE_PAGE_EMBEDDEDBYTES
  • MEASURE_PAGE_DOCDOWNLOAD
  • MEASURE_PAGE_SERVERBUSY
  • MEASURE_IIOP_ROUNDTRIP
  • MEASURE_IIOP_SERVERBUSY
  • MEASURE_SQL_SQLPARSE
  • MEASURE_SQL_SQLEXEC
  • MEASURE_SQL_SQLEXECDIRECT
  • MEASURE_TRANS_TRANSOK
  • MEASURE_TRANS_TRANSERR
  • MEASURE_TRANS_TRANSCA
  • MEASURE_FORM_BYTESSENT
  • MEASURE_FORM_BYTESRECEIVED
  • MEASURE_FORM_HITSOK
  • MEASURE_FORM_HITSERR
  • MEASURE_FORM_ROUNDTRIP
  • MEASURE_FORM_SERVERBUSY
  • MEASURE_TUXEDO_BYTESSENT
  • MEASURE_TUXEDO_BYTESRECEIVED
  • MEASURE_TUXEDO_RESPONSETIME
bDisable | Optional: Specifies whether percentiles calculation should be disabled or enabled (default is FALSE).
uGranularity Optional: Precision of the quantile measurement in per mil. Can be one of the following values:
  • OPT_PERCENTILES_GRANULARITY_1_PER_MIL
  • OPT_PERCENTILES_GRANULARITY_3_PER_MIL
  • OPT_PERCENTILES_GRANULARITY_5_PER_MIL
  • OPT_PERCENTILES_GRANULARITY_10_PER_MIL
  • OPT_PERCENTILES_GRANULARITY_30_PER_MIL
  • OPT_PERCENTILES_GRANULARITY_50_PER_MIL
Lower granularity enables a more precise percentile calculation, but consumes more memory on each agent computer. The default setting of OPT_PERCENTILES_GRANULARITY_10_PER_MIL (1 percent) consumes up to 8kb memory per measure and virtual user container executable.
Important: With lower granularity settings, memory consumption grows exponentially.

Example

benchmark MeasureBenchmarkName
use "kernel.bdh"

dclrand
  r2 : RndUniF(5.0..55.0);

dcluser
  user
    User1
  transactions
    TInit        : begin;
    TMain        : 1;

dcltrans
  transaction TInit
  begin
    // enable quantile data for a custom measure
    MeasureCalculateRawPercentiles("measure1", MEASURE_COUNTER_CUSTOMCOUNTER,
    false, OPT_PERCENTILES_GRANULARITY_1_PER_MIL);
  end TInit;

  transaction TMain
  var
    i      : number;
    f, fV  : float;
  begin
    // get 500 random numbers in the range of 5.0 to 55.0
    for i := 1 to 500 do
      MeasureSetFloat("measure1", MEASURE_COUNTER_CUSTOMCOUNTER , r2);
    end;

    // show percentile estimation for 10%, 20%, 30%, 40%, 50%, 60%, 70%, 80%, 90%, 100%
    f:= 0.1;
    while f < 1.01 do
      MeasureGetPercentile("measure1", MEASURE_COUNTER_CUSTOMCOUNTER, f, fV);
      Print(string(f) + " = " + string(fV));
      f := f + 0.1;
    end;
  end TMain;
Parent topic: Measurement Functions
Related reference
MeasureCalculatePercentiles Function (Deprecated)
MeasureGetPercentile Function
MeasureGet Function
MeasureSetFloat Function
MeasureSet Function
MeasureSetBound Function
MeasureSetRaw Function
MeasureSetTimer Function
MeasureSetOption Function
MeasureTimeseries Function
MeasureCollectRawData Function


MeasureCalculatePercentiles Function (Deprecated)

Action

This function has been deprecated. If you use this function in a script, it will internally call the MeasureCalculateRawPercentiles function with default parameters instead.

Parent topic: Measurement Functions
Related reference
MeasureCalculateRawPercentiles Function


MeasureGetPercentile Function

Action

Retrieves the quantile value of a measure identified by sName and nClass for a given percentage (3rd parameter).
Note: The function returns the percentile value aggregated by the process that hosts the virtual user(s). This process is the perfRun.exe. Thus, the returned percentile value is based on all virtual users running in that process.

Include file

Kernel.bdh

Syntax

MeasureGetPercentile( in  sName  : string,
                      in  nClass : number,
                      in  fP     : float,
                      out fValue : float ) : boolean;

Return value

  • true if successful

  • false otherwise

Parameter | Description
sName | Measure name that identifies the measure.
nClass

Specifies the type of measure to retrieve.

To retrieve the value of a custom time measure, pass the MEASURE_TIMER_RESPONSETIME parameter to the function.

To retrieve the value of a custom counter, pass the MEASURE_COUNTER_CUSTOMCOUNTER parameter to the function.

To retrieve the value of an average counter, pass the MEASURE_COUNTER_AVERAGE parameter to the function.

In any other case, pass any of the following parameters to the function, depending on the type of information you are interested in.

  • MEASURE_PAGE_PAGETIME (for protocol-level load testing)

  • MEASURE_PAGE_ACTIONTIME (for browser-driven load testing)

  • MEASURE_PAGE_PAGEBYTES

  • MEASURE_PAGE_EMBEDDEDBYTES

  • MEASURE_PAGE_DOCDOWNLOAD

  • MEASURE_PAGE_SERVERBUSY

  • MEASURE_IIOP_ROUNDTRIP

  • MEASURE_IIOP_SERVERBUSY

  • MEASURE_SQL_SQLPARSE

  • MEASURE_SQL_SQLEXEC

  • MEASURE_SQL_SQLEXECDIRECT

  • MEASURE_TRANS_TRANSOK

  • MEASURE_TRANS_TRANSERR

  • MEASURE_TRANS_TRANSCA

  • MEASURE_FORM_BYTESSENT

  • MEASURE_FORM_BYTESRECEIVED

  • MEASURE_FORM_HITSOK

  • MEASURE_FORM_HITSERR

  • MEASURE_FORM_ROUNDTRIP

  • MEASURE_FORM_SERVERBUSY

  • MEASURE_TUXEDO_BYTESSENT

  • MEASURE_TUXEDO_BYTESRECEIVED

  • MEASURE_TUXEDO_RESPONSETIME

fP | The percentage must be in the range of 0.0 to 1.0.
fValue | Retrieves the quantile value.

Example

benchmark MeasureBenchmarkName
use "kernel.bdh"

dclrand
  r2 : RndUniF(5.0..55.0);

dcluser
  user
    User1
  transactions
    TInit        : begin;
    TMain        : 1;

dcltrans
  transaction TInit
  begin
    // enable quantile data for a custom measure
    MeasureCalculatePercentiles("measure1", MEASURE_COUNTER_CUSTOMCOUNTER);
  end TInit;

  transaction TMain
  var
    i      : number;
    f, fV  : float;
  begin
    // get 500 random numbers in the range of 5.0 to 55.0
    for i := 1 to 500 do
      MeasureSetFloat("measure1", MEASURE_COUNTER_CUSTOMCOUNTER, r2);
    end;

    // show percentile estimation for 10%, 20%, 30%, 40%, 50%, 60%, 70%, 80%, 90%, 100%
    f:= 0.1;
    while f < 1.01 do
      MeasureGetPercentile("measure1", MEASURE_COUNTER_CUSTOMCOUNTER, f, fv);
      Print(string(f) + " = " + string(fV));
      f := f + 0.1;
    end;
  end TMain;
Parent topic: Measurement Functions
Related reference
MeasureCalculateRawPercentiles Function


MeasureCollectRawData Function

Action

Enables the collection of raw measure data for the measure identified by sName and eType. Raw measure data will be stored in CSV files in the result directory of the corresponding load test.

Include file

Kernel.bdh

Syntax

MeasureCollectRawData( in bEnable : boolean,
                       in sName   : string optional,
                       in eType   : number optional ): boolean;
Parameter | Description
bEnable | true/false
sName | The measure name
eType Specifies the measure type:
  • MEASURE_IIOP_ROUNDTRIP
  • MEASURE_IIOP_SERVERBUSY
  • MEASURE_TIMER_RESPONSETIME
  • MEASURE_COUNTER_CUSTOMCOUNTER
  • MEASURE_SQL_SQLPARSE
  • MEASURE_SQL_SQLEXEC
  • MEASURE_SQL_SQLEXECDIRECT
  • MEASURE_TRANS_TRANSOK
  • MEASURE_TRANS_TRANSERR
  • MEASURE_TRANS_TRANSCA
  • MEASURE_FORM_BYTESSENT
  • MEASURE_FORM_BYTESRECEIVED
  • MEASURE_FORM_HITSOK
  • MEASURE_FORM_HITSERR
  • MEASURE_FORM_ROUNDTRIP
  • MEASURE_FORM_SERVERBUSY
  • MEASURE_TUXEDO_BYTESSENT
  • MEASURE_TUXEDO_BYTESRECEIVED
  • MEASURE_TUXEDO_RESPONSETIME
  • MEASURE_COUNTER_AVERAGE
  • MEASURE_PAGE_PAGETIME (for protocol-level load testing)
  • MEASURE_PAGE_DOCDOWNLOAD
  • MEASURE_PAGE_SERVERBUSY
  • MEASURE_PAGE_PAGEBYTES
  • MEASURE_PAGE_EMBEDDEDBYTES
  • MEASURE_PAGE_ACTIONTIME (for browser-driven load testing)
  • MEASURE_TRANS_TRANSBUSYOK
  • MEASURE_TRANS_TRANSBUSYERR
  • MEASURE_TRANS_TRANSBUSYCA

Return value

  • true if successful

  • false otherwise

Example

benchmark BenchmarkName

use "kernel.bdh"
use "webapi.bdh"

dcluser
  user
    VirtUser
  transactions
    TRawDataAll : 1;
    TRawDataName : 1;
    TRawDataType : 1;
    TRawDataNameType : 1;

dcltrans
  transaction TRawDataAll
  begin
    // enable generation of raw data for default measures
    MeasureCollectRawData(true);

    WebPageUrl("http://www.borland.com/"); // raw data will be collected
  end TRawDataAll;

  transaction TRawDataName
  begin
    // enable generation of raw data for measures with specific name "MyMeasure"
    MeasureCollectRawData(true, "MyMeasure");

    WebPageUrl("http://www.borland.com/", "MyMeasure"); // raw data will be collected
    WebPageUrl("http://demo.borland.com/", "MyWebSite"); // raw data will NOT be collected
  end TRawDataName;

  transaction TRawDataType
  begin
    // enable generation of raw data for measures of type
    MeasureCollectRawData(true, "", MEASURE_PAGE_EMBEDDEDBYTES);

    WebPageUrl("http://www.borland.com/", "MyMeasure"); // only raw data of type MEASURE_PAGE_EMBEDDEDBYTES will be collected
    WebPageUrl("http://demo.borland.com/", "MyWebSite"); // only raw data of type MEASURE_PAGE_EMBEDDEDBYTES will be collected
  end TRawDataType;

  transaction TRawDataNameType
  begin
    // enable generation of raw data for measures with specific name "MyMeasure" and of type MEASURE_PAGE_EMBEDDEDBYTES
    MeasureCollectRawData(true, "MyMeasure", MEASURE_PAGE_EMBEDDEDBYTES);

    WebPageUrl("http://www.borland.com/", "MyMeasure"); // only raw data of MEASURE_PAGE_EMBEDDEDBYTES will be collected
    WebPageUrl("http://demo.borland.com/", "MyWebSite"); // raw data will NOT be collected
  end TRawDataNameType;
Parent topic: Measurement Functions
Related tasks
Enabling Raw Measure Data Capturing
Related reference
MeasureSetOption Function
MeasureCalculateRawPercentiles Function
MeasureTimeseries Function
Raw Measure Data File Size Statistics


Memory Functions

Silk Performer provides some predefined functions for the allocation of dynamic buffers. A buffer can only be allocated in this way, using the Malloc function (beside that, it is obviously possible to re-use a previously initialized buffer). Finally, when allocated memory is not needed any longer, it has to be release by using the Free function.

  • Adr Function
    Retrieves the memory address of a variable or string constant
  • Free Function
    Releases allocated memory
  • Malloc Function
    Allocates memory blocks
  • Memcpy Function
    Copies characters between two memory pointers.
  • Memset Function
    Sets a number of characters of a memory buffer to a specified character
Parent topic: General Functions


Adr Function

Action

Retrieves the memory address of a variable or string constant. Therefore it acts like the “&” operator in C.

Include file

Kernel.bdh

Syntax

Adr( in sString : string ): number;

Return value

address of variable

Parameter | Description
sString | Variable or string constant

Example

dcltrans
  transaction TAdr
  var
    sString : string(10);
    nAddress : number;
  begin
    // nAddress receives the address of the string sString
    nAddress := Adr(sString);
    Memset(nAddress, 0, 10);
    write("address = "); write(nAddress); writeln;
  end TAdr;

Output

address = 8721488
Parent topic: Memory Functions


Free Function

Action

Releases memory that was allocated with Malloc.

Include file

Kernel.bdh

Syntax

Free( in hMem : number );
Parameter | Description
hMem | Pointer to allocated memory

Example

dcltrans
  transaction TFree
  var
    nBuffer: number;
  begin
    // allocate a buffer of 10 bytes
    nBuffer := Malloc(10);
    write("memory successfully allocated"); writeln;

    // free memory referenced by nBuffer
    Free(nBuffer);
    write("memory released"); writeln;
  end TFree;

Output

memory successfully allocated
memory released
Parent topic: Memory Functions
Related reference
Malloc Function


Malloc Function

Action

Allocates memory blocks.

Include file

Kernel.bdh

Syntax

Malloc (in nSize : number ): number;

Return value

Pointer to the allocated space. Unless Silk Performer is able to allocate the specified amount of memory, the simulation is aborted.

Parameter | Description
nSize | Size of allocated space in bytes

Example

dcltrans
  transaction TMalloc
  var
    nBuffer: number;
  begin
    // allocate a buffer of 10 bytes
    nBuffer := Malloc(10);
    write("memory successfully allocated"); writeln;

    // free memory referenced by nBuffer
    Free(nBuffer);
    write("memory released"); writeln;
  end TMalloc;

Output

memory successfully allocated
memory released
Parent topic: Memory Functions
Related reference
Free Function
Memcpy Function
Memset Function


Memcpy Function

Action

Copies characters between two memory pointers.
Note: This function is obsolete. It can still be used, although it's recommended to use the SetMem function instead.

Include file

Kernel.bdh

Syntax

Memcpy( inout sDest   : string,
        in    sSource : string,
        in    nCount  : number ): number;

Return value

value of nDest

Parameter | Description
sDest | Pointer to destination buffer
sSource | Pointer to buffer to copy from
nCount | Number of bytes to copy

Example

dcltrans
  transaction TMemcpy
  var
    sSource, sDest : string;
  begin
    sSource := Malloc(10);
    sDest   := Malloc(10);

    Memset(sSource, ord('*'), 10);
    write("source buffer initialized"); writeln;
    Memcpy(sDest, sSource, 10);
    write("buffer copied"); writeln;
    Free(sSource); Free(sDest);
  end TMemcpy;

Output

source buffer initialized
buffer copied
Parent topic: Memory Functions
Related reference
Free Function
Memset Function


Memset Function

Action

Sets nCount characters of a memory buffer to a specified character.

Include file

Kernel.bdh

Syntax

Memset( in hDest  : number,
        in nChar  : number,
        in nCount : number ): number;

Return value

address of the destination memory pointer

Parameter | Description
hDest | Pointer to destination buffer
nChar | ASCII value of the copied character
nCount | Number of characters

Example

dcltrans
  transaction TMemset
  var
    nBuffer: number;
  begin
    nBuffer := Malloc(10);
    Memset(nBuffer, ord('*'), 10);
    write("buffer initialized"); writeln;
    Free(nBuffer);
  end TMemset;

Output

buffer initialized
Parent topic: Memory Functions
Related reference
Memcpy Function
Free Function
Malloc Function


Process Control Functions

Silk Performer provides the following process control functions:

  • ProcessGetEnv Function
    Gets the value for an environment variable key.
  • ProcessGetState Function
    Returns the state of the specified process.
  • ProcessWait Function
    Waits for a running detached process.
  • ProcessInitialize Function
    Initializes a process that is started later with the ProcessStart function.
  • ProcessKill Function
    Kills a single process (PROCESS_KILLSINGLE) or a list of processes (PROCESS_KILLALL).
  • ProcessSetEnv Function
    Sets an environment variable for a process.
  • ProcessSetErrorBuffer Function
    Saves the error output of the process to a string buffer.
  • ProcessSetOutputBuffer Function
    Save the output of the process to a string buffer.
  • ProcessSetStdInFile Function
    Sets a standard input file before starting a process.
  • ProcessStart Function
    Creates a new operating-system process and executes it.
  • ProcessFree Function
    Frees the memory allocated by ProcessInitialize for a process specified by its handle, hProc.
Parent topic: General Functions


ProcessGetEnv Function

Action

Gets the value for an environment variable key.

Important: This function must be called before the ProcessStart function and after the ProcessInitialize function.
Note: This function can be called more than once (for every environment variable).

Include file

Kernel.bdh

Syntax

ProcessGetEnv( in  hProc      : number,
               in  sKey       : string,
               out sValue     : string,
               in  nValueSize : number ): boolean;

Return value

  • true if successful.

  • false in case of an error. The GetLastError function may be used to retrieve the system error code.

Parameter | Description
hProc | The handle that identifies the process. It is returned by the ProcessInitialize function.
sKey | Specifies the environment variable whose value is being retrieved (e.g. "temp" or "path").
sValue | This parameter retrieves the value of the specified environment variable.
nValueSize | Length of the string that receives the value for the environment variable.

Example

dcltrans
  transaction TMain
  var
    hFile      : number;
    hProcessId : number;
    nStatus    : number;
    nRead      : number;
    sData      : string;
    sPath      : string;
  begin
    // Create process and start it up...
    hProcessId := ProcessInitialize("application1.exe", PROCESS_DETACHED,
                     "", "c:\\temp\\", "c:\\temp\\out.txt");

    // set environment variable "path"
    ProcessGetEnv(hProcessId, "path", sPath, STRING_COMPLETE);
    sPath := sPath + "c:\\application1\\;";
    ProcessSetEnv(hProcessId, "path", sPath);
    RepMessage(sPath,SEVERITY_ERROR);

    // start the process
    ProcessStart(hProcessId);

    // Wait for process to finish
    Wait(25.0);

    // Kill the process if it hasn't finished yet
    nStatus := ProcessGetState(hProcessId);
    if (nStatus <> PROCESS_STATE_FINISHED) then
      ProcessKill(hProcessId, PROCESS_KILLSINGLE);
    end;

    // Read the output of the process, written to a file
    FOpen(hFile, "c:\\temp\\out.txt", OPT_FILE_ACCESS_READ, OPT_FILE_OPEN);
    while FRead(hFile, sData, 1, nRead) do
      Write(sData);
    end;

    FClose(hFile);
    ProcessFree(hProcessID);
  end TMain;
Parent topic: Process Control Functions
Related reference
ProcessGetState Function
ProcessKill Function
ProcessSetEnv Function
ProcessInitialize Function


ProcessGetState Function

Action

Returns the state of the specified process.

Important: This function must be called after the ProcessInitialize function.
Note: This function can be called more than once (for every environment variable).

Include file

Kernel.bdh

Syntax

ProcessGetState( in hProc : number ): number;

Return value

If the function is successful, the status of the process is returned, which can be one of the following:

  • PROCESS_STATE_INITIALIZED : The process is initialized, but not started yet.

  • PROCESS_STATE_EXECUTING : The process was started and is now running.

  • PROCESS_STATE_FINISHED : The process has finished successfully.

  • PROCESS_STATE_TIMEDOUT : The process has timed out, which means that it was started attached (or piped) and did not respond within a finite time.

In case of an error 0 is returned.

Parameter | Description
hProc | The handle that identifies the process. It is returned by the ProcessInitialize function.

Example

dcltrans
  transaction TMain
  var
    hFile      : number;
    hProcessId : number;
    nStatus    : number;
    nRead      : number;
    sData      : string;
  begin
    // Create process and start it up...
    hProcessId := ProcessInitialize ("application1.exe", PROCESS_DETACHED,
                        "", "c:\\temp\\", "c:\\temp\\out.txt");
    ProcessSetEnv(hProcessId, "temp", "c:\\temp\\");
    ProcessStart(hProcessId);

    // Wait for process to finish
    Wait(25.0);

    // Kill the process if it hasn't finished yet
    nStatus := ProcessGetState(hProcessId);
    if (nStatus <> PROCESS_STATE_FINISHED) then
      ProcessKill(hProcessId,PROCESS_KILLSINGLE);
    end;

    // Read the output of the process, written to a file
    FOpen(hFile, "c:\\temp\\out.txt", OPT_FILE_ACCESS_READ, OPT_FILE_OPEN);
    while FRead(hFile, sData, 1, nRead) do
      Write(sData);
    end;

    FClose(hFile);
    ProcessFree(hProcessID);
  end TMain;
Parent topic: Process Control Functions
Related reference
ProcessGetEnv Function
ProcessKill Function
ProcessSetEnv Function
ProcessInitialize Function


ProcessWait Function

Action

Waits for a running detached process.

Include file

Kernel.bdh

Syntax

ProcessWait(
     in hProc    : number,
     in nTimeout : number optional ): number;

Return value

If the function is successful, the status of the process is returned, which can be :

  • PROCESS_FINISHED (8) : The process has finished.

  • PROCESS_TIMED_OUT (-1) : The process is still running, timeout occured.

  • PROCESS_WAIT_FAILED (-2) : The process is not running, wrong handle etc.

Parameter | Description
hProc | The handle which identifies the process. The handle is returned by ProcessInitialize and must have been started by ProcessStart.
nTimeout | Maximum wait time in milliseconds.
Note: ProcessWait must be called after ProcessStart and after ProcessInitialize.
Note: ProcessWait can be called more than once (for every environment variable).

Parent topic: Process Control Functions


ProcessInitialize Function

Action

Initializes a process that is started later with the ProcessStart function.

To avoid memory leaks, make sure to call the ProcessFree function at the end of the script.

Include file

Kernel.bdh

Syntax

ProcessInitialize( in sCmdLine    :string,
                   in nFlags      : number optional,
                   in sParams     : string optional,
                   in sWorkingDir : string optional,
                   in sStdOutFile : string optional,
                   in sStdErrFile : string optional,
                   in nTimeOut    : number optional,
                   in sUser       : string optional,
                   in sPwd        : string optional ): number;

Return value

If the function is successful, a handle to the process is returned (the handle is greater than zero). This handle must be used for the other functions with the prefix Process.

In case of an error 0 is returned. The GetLastError function may be used to retrieve the system error code.

Parameter | Description
sCmdLine | Command line of the application to be started.
nFlags

Process related flags. You can use the following flags to influence the behavior of the executed application:

  • PROCESS_ATTACHED: The started application is a child of the current process. If the current process is killed, the started process is automatically killed (e.g. when pressing "Stop" the process that was started with the function ProcessStart, is killed). Silk Performer waits for the child process to complete.

  • PROCESS_DETACHED: The started process is not attached to the process that called it. Silk Performer waits for the new process to complete (you must use ProcessWait).

  • PROCESS_PIPED: The output of the started process is sent to the Silk Performer GUI. The started process is automatically attached. If the current process is killed, the started process is automatically killed (e.g. when pressing "Stop" the process that was started with the function ProcessStart, is killed).
sParams | Parameters for the executed application.
sWorkingDir | Specifies the current drive and directory for the started process. If this parameter is NULL, the new process will have the same current drive and directory as the calling process.
sStdOutFile | The file where the output is sent to.
sStdErrFile | The file where the error output is sent to.
nTimeOut | TimeOut for the process in seconds. This parameter is only of importance when the process is started attached or piped. If the process doesn’t end within this time interval (in seconds), it will be terminated. If this parameter is not set or is set to zero, then the ProcessStart function will wait for the termination of the started process.
sUser

Account used to run the new process. If the account is not specified, the new process takes up the account of it's creator.

Note: It is only possible to start the process in the context of another account if no other user is logged in. But it is possible to start a process if the script is executed in the context of a special account which is called system account. When running a test then under normal circumstances the system account is used.

The user account of the process must have the SE_TCB_NAME privilege (in User Manager, this is the "Act as part of the Operating System" right). The SE_TCB_NAME privilege is very powerful and should not be granted to any arbitrary user just so that they can run an application that needs to validate credentials.
sPwd | Password for the account.

Example

dcltrans
  transaction TMain
  var
    hFile      : number;
    hProcessId : number;
    nStatus    : number;
    nRead      : number;
    sData      : string;
  begin
    // Create process and start it up...
    hProcessId := ProcessInitialize ("application1.exe", PROCESS_DETACHED,
                  "", "c:\\temp\\", "c:\\temp\\out.txt");
    ProcessSetEnv(hProcessId, "temp", "c:\\temp\\");
    ProcessStart(hProcessId);

    // Wait for process to finish
    Wait(25.0);

    // Kill the process if it hasn't finished yet
    nStatus := ProcessGetState(hProcessId);

    if (nStatus <> PROCESS_STATE_FINISHED) then
      ProcessKill(hProcessId, PROCESS_KILLSINGLE);
    end;

    // Read the output of the process, written to a file
    FOpen(hFile, "c:\\temp\\out.txt", OPT_FILE_ACCESS_READ, OPT_FILE_OPEN);

    while FRead(hFile, sData, 1, nRead) do
      Write(sData);
    end;

    FClose(hFile);
    ProcessFree(hProcessID);
  end TMain;
Parent topic: Process Control Functions
Related reference
ProcessFree Function
ProcessGetEnv Function
ProcessGetState Function
ProcessKill Function
ProcessSetEnv Function


ProcessKill Function

Action

Kills a single process (PROCESS_KILLSINGLE) or a list of processes (PROCESS_KILLALL).

Include file

Kernel.bdh

Syntax

ProcessKill( in hProc  : number,
             in nFlags : number optional ):nboolean;

Return value

  • true if successful.

  • false in case of an error. The GetLastError function may be used to retrieve the system error code.

Parameter | Description
hProc | The handle that identifies the process. It is returned by the ProcessInitialize function.
nFlags

Can be one of following values :

  • PROCESS_KILLSINGLE : Only the process specified by hProc is killed.

  • PROCESS_KILLALL : All processes that were started after the process (specified by hProc ) are killed.

Example

dcltrans
  transaction TMain
  var
    hFile      : number;
    hProcessId : number;
    nStatus    : number;
    nRead      : number;
    sData      : string;
  begin
    // Create process and start it up...
    hProcessId := ProcessInitialize ("application1.exe", PROCESS_DETACHED,
                      "", "c:\\temp\\", "c:\\temp\\out.txt");
    ProcessSetEnv(hProcessId, "temp", "c:\\temp\\");
    ProcessStart(hProcessId);

    // Wait for process to finish
    Wait(25.0);

    // Kill the process if it hasn't finished yet
    nStatus := ProcessGetState(hProcessId);
    if (nStatus <> PROCESS_STATE_FINISHED) then
      ProcessKill(hProcessId, PROCESS_KILLSINGLE);
    end;

    // Read the output of the process, written to afile
    FOpen(hFile, "c:\\temp\\out.txt", OPT_FILE_ACCESS_READ, OPT_FILE_OPEN);
    while FRead(hFile, sData, 1, nRead) do
      Write(sData);
    end;

    FClose(hFile);
    ProcessFree(hProcessID);
  end TMain;
Parent topic: Process Control Functions
Related reference
ProcessGetEnv Function
ProcessGetState Function
ProcessSetEnv Function
ProcessInitialize Function
ProcessStart Function
GetLastError Function


ProcessSetEnv Function

Action

Sets an environment variable for a process.

Important: This function must be called before the ProcessStart function and after the ProcessInitialize function.
Note: This function can be called more than once (for every environment variable).

Include file

Kernel.bdh

Syntax

ProcessSetEnv( in hProc  : number,
               in sKey   : string,
               in sValue : string optional): boolean;

Return value

  • true if successful.

  • false in case of an error. The GetLastError function may be used to retrieve the system error code.

Parameter | Description
hProc | The handle that identifies the process. It is returned by the ProcessInitialize function.
sKey | Specifies the environment variable of which the value is being set.
sValue | This parameter contains the new value of the specified environment variable (optional). If this parameter is NULL, the variable is deleted from the environment of the current process.

Example

dcltrans
  transaction TMain
  var
    hFile      : number;
    hProcessId : number;
    nStatus    : number;
    nRead      : number;
    sData      : string;
  begin
    // Create process and start it up...
    hProcessId := ProcessInitialize ("application1.exe", PROCESS_DETACHED,
                    "", "c:\\temp\\","c:\\temp\\out.txt");
    ProcessSetEnv(hProcessId, "temp","c:\\temp\\");
    ProcessStart(hProcessId);

    // Wait for process to finish
    Wait(25.0);

    // Kill the process if it hasn't finished yet
    nStatus := ProcessGetState(hProcessId);

    if (nStatus <> PROCESS_STATE_FINISHED) then
      ProcessKill(hProcessId, PROCESS_KILLSINGLE);
    end;

    // Read the output of the process, written to a file
    FOpen(hFile, "c:\\temp\\out.txt", OPT_FILE_ACCESS_READ, OPT_FILE_OPEN);

    while FRead(hFile, sData, 1, nRead) do
      Write(sData);
    end;

    FClose(hFile);
    ProcessFree(hProcessID);
  end TMain;
Parent topic: Process Control Functions
Related reference
ProcessGetEnv Function
ProcessGetState Function
ProcessKill Function
ProcessInitialize Function
GetLastError Function
ProcessStart Function


ProcessSetErrorBuffer Function

Action

Saves the error output of the process to a string buffer.

Important: This function must be called before the ProcessStart function and after the ProcessInitialize function.
Note: Does only work if the process is started PIPED. For this the parameter nFlag of the function ProcessInitialize must be set to PROCESS_PIPED.

Include file

Kernel.bdh

Syntax

ProcessSetErrorBuffer( in hProc          :number,
                       in sBuffer        :string,
                       in nBufferLen     :number optional,
                       in sLineSeparator :stringoptional ): boolean;

Return value

  • true if successful.

  • false in case of an error. The GetLastError function may be used to retrieve the system error code.

Parameter | Description
hProc | The handle that identifies the process. It is returned by the ProcessInitialize function.
sBuffer | Pointer to the buffer used for writing the error output of the process.
sBufferLen | Maximum size of the string buffer (optional).
sLineSeparator | The line separator which is placed between every line in the string buffer. If it is null, nothing is placed between the particular lines (optional).

Example

dcltrans
  transaction TMain
  var
    hProcessId   : number;
    sBuffer      : string(4096);
    sErrorBuffer : string(2048);
  begin
    // Create process and start it up...
    hProcessId := ProcessInitialize("application1.exe", PROCESS_PIPED,
                                     "","c:\\temp\\","", "c:\\temp\\out.txt");
    ProcessSetEnv(hProcessId, "temp", "c:\\temp\\");
    ProcessSetOutputBuffer(hProcessId, sBuffer, STRING_COMPLETE, ";");
    ProcessSetErrorBuffer(hProcessId, sErrorBuffer);
    ProcessStart(hProcessId);
    Print("StdOut: " + sBuffer);
    Print("ErrorOut: " + sErrorBuffer);

    ProcessFree(hProcessID);
  end TMain;
Parent topic: Process Control Functions
Related reference
ProcessGetState Function
ProcessKill Function
ProcessStart Function
ProcessInitialize Function
GetLastError Function


ProcessSetOutputBuffer Function

Action

Saves the output of the process to a string buffer.

Important: This function must be called before the ProcessStart function and after the ProcessInitialize function.
Note: Does only work if the process is started PIPED. For this the parameter nFlag of the function ProcessInitialize must be set to PROCESS_PIPED.

Include file

Kernel.bdh

Syntax

ProcessSetOutputBuffer( in hProc          :number,
                        in sBuffer        :string,
                        in nBufferLen     :number optional,
                        in sLineSeparator :string optional ): boolean;

Return value

  • true if successful.

  • false in case of an error. The GetLastError function may be used to retrieve the system error code.

Parameter | Description
hProc | The handle that identifies the process. It is returned by the ProcessInitialize function.
sBuffer | Pointer to the buffer used for writing the process output.
sBufferLen | Maximum size of the string buffer (optional).
sLineSeparator | The line separator which is placed between every line in the string buffer. If it is null, nothing is placed between the particular lines (optional).

Example

dcltrans
  transaction TMain
  var
    hProcessId : number;
    sBuffer : string(4096);
    sErrorBuffer : string(2048);
  begin
    // Create process and start it up...
    hProcessId := ProcessInitialize("application1.exe", PROCESS_PIPED,
                                      "", "c:\\temp\\", "c:\\temp\\out.txt");
    ProcessSetEnv(hProcessId, "temp", "c:\\temp\\");
    ProcessSetOutputBuffer(hProcessId, sBuffer, STRING_COMPLETE, ";");
    ProcessSetErrorBuffer(hProcessId, sErrorBuffer);
    ProcessStart(hProcessId);
    Print("StdOut: " + sBuffer);
    Print("ErrorOut: " + sErrorBuffer);

    ProcessFree(hProcessID);
  end TMain;
Parent topic: Process Control Functions
Related reference
GetLastError Function
ProcessKill Function
ProcessStart Function
ProcessInitialize Function
ProcessGetState Function


ProcessSetStdInFile Function

Action

Sets a standard input file before starting a process.

Setting an input file is sometimes necessary (undocumented Windows requirement) when redirecting output, for example xcopy.

Include file

kernel.bdh

Syntax

ProcessSetStdInFile(
      in hProcess       : number,
      in sStdInFileName : string ): boolean;

Return value

  • true if successful

  • false otherwise

Parameter | Description
hProcess | The handle which identifies the process. The handle is returned by ProcessInitialize.
sStdInFileName | Name of the input file.
Note: ProcessSetStdInFile only works if the process is initialized with the flags PROCESS_PIPED or PROCESS_ATTACHED, and must be called before ProcessStart and after ProcessInitialize.

Example

transaction TmyTrans1
  var
    iProcess : number;
    iStatus  : number;
  begin
    iProcess := ProcessInitialize("cmd",
      PROCESS_ATTACHED,
      "/C xcopy \\bin\\debug \\temp /y",
      "T:\\bin\\release",
      "T:\\temp\\xcopyout.log",
      "T:\\temp\\xcopyerr.log");
    ProcessSetStdInFile(iProcess,"T:\\temp\\xcopyin.log");
    ProcessStart(iProcess);
    iStatus := PROCESS_STATE_EXECUTING;
    while (iStatus = PROCESS_STATE_EXECUTING) do
      wait 1.0;
      iStatus := ProcessGetState(iProcess);
    end;

    ProcessFree(iProcess);
  end TmyTrans1;

Parent topic: Process Control Functions


ProcessStart Function

Action

Creates a new operating-system process and executes it.

Include file

Kernel.bdh

Syntax

ProcessStart( in hProc : number ): boolean;

Return value

  • true if successful.

  • false in case of an error. The GetLastError function may be used to retrieve the system error code.

Parameter | Description
hProc | The handle that identifies the process. It is returned by the ProcessInitialize function.

Example

dcltrans
  transaction TMain
  var
    hFile      : number;
    hProcessId : number;
    nStatus    : number;
    nRead      : number;
    sData      : string;
  begin
    // Create process and start it up...
    hProcessId := ProcessInitialize("application1.exe", PROCESS_DETACHED,
                        "", "c:\\temp\\", "c:\\temp\\out.txt");
    ProcessSetEnv(hProcessId, "temp", "c:\\temp\\");
    ProcessStart(hProcessId);

    // Wait for process to finish
    Wait(25.0);

    // Kill the process if it hasn't finished yet
    nStatus := ProcessGetState(hProcessId);

    if (nStatus <> PROCESS_STATE_FINISHED) then
      ProcessKill(hProcessId, PROCESS_KILLSINGLE);
    end;

    // Read the output of the process, written to a file
    FOpen(hFile, "c:\\temp\\out.txt", OPT_FILE_ACCESS_READ, OPT_FILE_OPEN);

    while FRead(hFile, sData, 1, nRead) do
      Write(sData);
    end;

    FClose(hFile);
    ProcessFree(hProcessID);
  end TMain;
Parent topic: Process Control Functions
Related reference
ProcessKill Function
ProcessSetEnv Function
ProcessGetState Function


ProcessFree Function

Action

Frees the memory allocated by ProcessInitialize for a process specified by its handle, hProc.

Include file

Kernel.bdh

Syntax

ProcessFree( in hProc  : number ): boolean;

Return value

  • true if successful

  • false in the case of errors. The GetLastError function may be used to retrieve system error code.

Parameter | Description
hProc | The handle that identifies the process. It is returned by the ProcessInitialize function.

Example

dcltrans
  transaction TMain
  var
    hFile      : number;
    hProcessId : number;
    nStatus    : number;
    nRead      : number;
    sData      : string;
  begin
    // Create process and start it up...
    hProcessId := ProcessInitialize("application1.exe", PROCESS_DETACHED,
                         "", "c:\\temp\\", "c:\\temp\\out.txt");
    ProcessSetEnv(hProcessId, "temp","c:\\temp\\");
    ProcessStart(hProcessId);

    // Wait for process to finish
    Wait(25.0);

    // Kill the process if it hasn't finished yet
    nStatus := ProcessGetState(hProcessId);

    if (nStatus <> PROCESS_STATE_FINISHED) then
      ProcessKill(hProcessId, PROCESS_KILLSINGLE);
    end;

    // Read the output of the process, written to a file
    FOpen(hFile, "c:\\temp\\out.txt", OPT_FILE_ACCESS_READ, OPT_FILE_OPEN);

    while FRead(hFile, sData, 1, nRead) do
      Write(sData);
    end;

    FClose(hFile);
    ProcessFree(hProcessID);
  end TMain;
Parent topic: Process Control Functions
Related reference
ProcessInitialize Function
ProcessStart Function


Synchronization Functions

A number of Silk Performer functions allow you to either serialize or synchronize transactions in your testing scripts in order to better control the timing of loads in your simulation. Serialization enables you to test the effects of transactions executed one at a time. For example, this could be useful to serialize logging into a Web application if the application is not able to handle a huge number of concurrent logins. Synchronization is useful in testing the effects of a large number of simultaneously called transactions. This allows you to create stress on your system in order to test specific concurrency issues.

The following functions maintain information across agents. Each call to one of the functions initiates a call from the local user to the local agent and finally to the controller. Since each call produces network traffic, these functions should be used carefully.

  • GlobalWaitFor
  • GlobalResourceEnter
  • GlobalResourceRelease
  • GlobalVarSet
  • GlobalVarGet
  • GlobalVarInc
The following functions can be used to serialize and synchronize user actions on a particular agent computer.
  • WaitFor
  • CreateMutex
  • ReleaseMutex
  • CreateEvent
  • PulseEvent
  • WaitForSingleObject
  • CreateEventEx
  • CloseHandle
  • CreateMutexEx
  • CreateSemaphore
  • ReleaseSemaphore
  • GlobalWaitFor Function
    Defines a checkpoint (rendezvous point) and blocks the calling user.
  • GlobalResourceEnter Function
    Defines a resource that can be occupied by only a limited number of users.
  • GlobalResourceRelease Function
    Releases a global resource.
  • GlobalVarSet Function
    Sets the value of a global integer variable.
  • GlobalVarGet Function
    Gets the value of a global integer variable.
  • GlobalVarInc Function
    Increments the value of a global integer variable.
  • WaitFor Function
    Waits for a number of users to call this function
  • CreateEvent Function
    Uses the Win32 CreateEventEx function to create a named event object.
  • CreateEventEx Function
    Creates a named or unnamed event object (Win32 function)
  • CreateMutex Function
    Uses the CreateMutexEx function to create a named mutex object.
  • CreateMutexEx Function
    Creates a mutex object (Win32 function).
  • PulseEvent Function
    Provides a single operation that sets (to signaled) the state of a specified event object and then resets it (to nonsignaled) after releasing the appropriate number of waiting threads.
  • ReleaseMutex Function
    Releases ownership of the specified mutex object.
  • WaitForSingleObject Function
    Waits until an object is in the signaled state or the specified timeout interval elapses
  • CloseHandle Function
    Closes an open object handle
  • CreateSemaphore Function
    Creates a named or unnamed semaphore object.
  • ReleaseSemaphore Function
    Increases the value of a given semaphore object.
  • SetEvent Function
    Sets the specified event object to the signaled state.
  • ResetEvent Function
    Resets the specified event object to a non-signaled state.
  • UserSignal Function
    Is used to notify a virtual user, which is in a waiting state as a result of having called the UserWaitFor function.
  • UserWaitFor Function
    Pauses the execution of a virtual user until notified to continue.
Parent topic: General Functions


GlobalWaitFor Function

Action

Defines a checkpoint (rendezvous point) and blocks the calling user. The caller waits until a specified number of users (himself inclusive) have reached or passed the checkpoint, or until the specified timeout occurs. The checkpoint is identified by name and is visible for all users, including those running on various remote agents.

A waiting user continues when the specified timeout is reached or the given number of users have called the function for a checkpoint. A user who was timed out has passed the checkpoint and is also regarded as a user who has passed this checkpoint.

Note: The time that a virtual user spends in this synchronization function does not influence the transaction busy time.

Include file

Kernel.bdh

Syntax

GlobalWaitFor( in sName    : string,
               in nCount   : number optional,
               in nTimeout : number optional ): number;

Return value

  • GLOBAL_ERROR if an error like an invalid number of users at the checkpoint occurred. To get more information, call the GetLastError function.
  • GLOBAL_CANCELED if the waiting period was canceled by the controller computer.
  • GLOBAL_TIMEOUT if the waiting period exceeded the defined timeout and the user continues the simulation.
  • GLOBAL_PASSED if all users have reached the checkpoint the user was waiting for and the user continues the simulation.
  • GLOBAL_SYNCHRONIZED if all users have reached the checkpoint the user was waiting for. The user was the last one to enter the checkpoint and continues the simulation.
Parameter | Description
sName | Name to identify the checkpoint
nCount | Number of users who must reach or pass the checkpoint (optional). To specify to wait for all users, omit this parameter or specify ALL_USERS.
nTimeout | Maximum waiting time in seconds before a timeout occurs (optional). If this parameter is omitted, the timeout is set to INFINITE.

Example

var
  hConnection: number;
dcltrans
  transaction TLogon
  var
    nRet: number;
begin
  OraLogon(hConnection, "user", "password", "orclnet2");
  nRet := GlobalWaitFor("All are logged in", ALL_USERS, 300);
  if nRet = GLOBAL_SYNCHRONIZED then
    Print("I am the last user at the checkpoint");
  end;
end TLogon;
Parent topic: Synchronization Functions
Related reference
GlobalResourceEnter Function
GlobalResourceRelease Function


GlobalResourceEnter Function

Action

Defines a resource that can be occupied by only a limited number of users. The caller has to wait until the number of users who occupy the resource is less than the maximum number of users who are allowed to occupy the resource. To releases a resource, call the GlobalResourceRelease function.

Note: The time that a virtual user spends in this synchronization function does not influence the transaction busy time.

Include file

Kernel.bdh

Syntax

GlobalResourceEnter( in sName    : string,
                     in nCount   : number optional,
                     in nTimeout : number optional ): number;

Return value

  • GLOBAL_ERROR if an error like an invalid number of users for the resource occurred. To get more information, call the GetLastError function.
  • GLOBAL_CANCELED if the waiting period was canceled by the controller.
  • GLOBAL_TIMEOUT if the waiting period exceeded the defined timeout and the user continues the simulation.
  • GLOBAL_PASSED if the user has occupied the resource and continues the simulation.
Parameter | Description
sName | Name to identify a resource.
nCount | Number of users who are allowed to enter the resource (optional). If this parameter is omitted, only one user is allowed to enter the resource.
nTimeout | Maximum waiting time in seconds before a timeout occurs (optional). If this parameter is omitted, the timeout is set to INFINITE.

Example

var
  hConnection: number;

dcltrans
  transaction TLogon
  var
    nRet: number;
  begin
    GlobalResourceEnter("Max 5 logins at a time", 5);
    OraLogon(hConnection, "user", "password", "orclnet2");
    GlobalResourceRelease("Max 5 logins at a time");
    GlobalWaitFor("All are logged in");
  end TLogon;
Parent topic: Synchronization Functions
Related reference
GlobalWaitFor Function
GlobalResourceRelease Function
GetLastError Function


GlobalResourceRelease Function

Action

Releases a resource that was occupied with the GlobalResourceEnter function. If there are any users waiting for the resource, the next user in the queue resumes the simulation.

Note: The time that a virtual user spends in this synchronization function does not influence the transaction busy time.

Include file

Kernel.bdh

Syntax

GlobalResourceRelease( in sName: string );
Parameter | Description
sName | Name that identifies a resource.

Example

var
  hConnection: number;

dcltrans
  transaction TLogon
  var
    nRet: number;
  begin
    GlobalResourceEnter("Max 5 logins at a time", 5);
    OraLogon(hConnection, "user", "password", "orclnet2");
    GlobalResourceRelease("Max 5 logins at a time");
    GlobalWaitFor("All are logged in");
  end TLogon;
Parent topic: Synchronization Functions
Related reference
GlobalResourceEnter Function
GlobalWaitFor Function


GlobalVarSet Function

Action

Sets the value of a global integer variable. Global variables are accessible for all users running on all agents.

Include file

Kernel.bdh

Syntax

GlobalVarSet( in sVariable : string,
              in nValue    : number,
              in nTimeout  : number optional ): boolean;

Return value

  • true if successful

  • false otherwise

Parameter | Description
sVariable | Name of the global variable whose value is to be set.
nValue | Value that is assigned to the global variable.
nTimeout | Optional: Timeout for setting the value in seconds. If the specified time period is exceeded, Silk Performer indicates an error. The function’s default behavior is to wait until the set operation is done.

Example

dcltrans
  transaction TInit
  begin
    if GetUserID() = 1 then
      GlobalVarSet("global counter", 1000);
    end;
    GlobalWaitFor("All", ALL_USERS);
  end TInit;
Parent topic: Synchronization Functions
Related reference
GlobalVarGet Function
GlobalVarInc Function


GlobalVarGet Function

Action

Gets the value of a global integer variable. Global variables are accessible for all users on all agents.

Include file

Kernel.bdh

Syntax

GlobalVarGet( in  sVariable : string,
              out nValue    : number,
              in  nTimeout  : number optional ): boolean;

Return value

  • true if successful

  • false otherwise

Parameter | Description
sVariable | Name of the global variable whose value is to be retrieved.
nValue | Variable receiving the value of the global variable.
nTimeout | Optional: Timeout for getting the value in seconds. If the specified time period is exceeded, Silk Performer indicates an error. The function’s default behavior is to wait until the get operation is done.

Example

dcltrans
  transaction TInit
  begin
    if GetUserID() = 1 then
      GlobalVarSet("global counter", 1000);
    end;
    GlobalWaitFor("All", ALL_USERS);
  end TInit;

  transaction TMain
  var
    nCount: number;
  begin
    GlobalVarGet("global counter", nCount);
    writeln(nCount);
  end TMain;
Parent topic: Synchronization Functions
Related reference
GlobalVarSet Function
GlobalVarInc Function


GlobalVarInc Function

Action

Increments the value of a global integer variable. Global variables are accessible for all users on all agents.

Note: You do not need to initialize a global variable before you increment it for the first time. This is done automatically, in the course of which the value of the variable is set to 0.

Include file

Kernel.bdh

Syntax

GlobalVarInc( in  sVariable : string,
              in  nInc      : number,
              out nValue    : number,
              in  nTimeout  : number optional ): boolean;

Return value

  • true if successful

  • false otherwise

Parameter | Description
sVariable | Name of the global variable whose value is to be incremented.
nInc | Number that is added to the value of the specified global variable.
nValue | Variable receiving the value of the global variable after the increment operation.
nTimeout | Optional: Timeout for incrementing the value in seconds. If the specified time period is exceeded, Silk Performer indicates an error. The function’s default behavior is to wait until the increment operation is done.

Example

dcltrans
  transaction TInit
  begin
    if GetUserID() = 1 then
      GlobalVarSet("global counter", 1000);
    end;
    GlobalWaitFor("All", ALL_USERS);
  end TInit;

  transaction TMain
  var
    nCount: number;
  begin
    GlobalVarInc("global counter", 10, nCount);
    writeln(nCount);
  end TMain;
Parent topic: Synchronization Functions
Related reference
GlobalVarGet Function
GlobalVarSet Function


WaitFor Function

Action

Waits for a number of users that call this function. It only synchronizes virtual users on one agent.

Note: The time that a virtual user spends in this synchronization function does not influence the transaction busy time.

Include file

Kernel.bdh

Syntax

WaitFor( in sName    : string,
         in nCount   : number optional,
         in nTimeout : number optional ): boolean;

Return value

  • true if successful

  • false otherwise

Parameter | Description
sName | Name of the synchronization point
nCount | Number of users to wait for (optional). If this parameter is omitted, the function waits for all simulated users
nTimeout | Timeout of wait period in seconds (optional). If this parameter is omitted, the functions does not report a timeout

Example

dcltrans
  transaction TMain
  const
    WAITFOR_TIME_OUT := 10;
  begin
    ...
    // waits for 5 users rendezvousing at this point in the script
    if not WaitFor("Rendezvous", 5, WAITFOR_TIME_OUT) then
      write("time out\n"); halt;
    end;
    ...
  end TMain;

Sample scripts

Trans.bdf

Parent topic: Synchronization Functions
Related reference
WaitForSingleObject Function


CreateEvent Function

Action

Uses the Win32 CreateEventEx function to create a named event object.

Include file

Kernel.bdh

Syntax

CreateEvent(in sEvtName: string): number;

Return value

handle to the event object

Parameter | Description
sEvtName | Name of the event object

Example

dcluser
user
Starter
transactions
TMain : begin;
EventStarter : 20;
CleanUp : end;
user
Seller(5)
transactions
TMain : begin;
Selling : 20;
CleanUp : end;
var
hEventGo: number; // handle for starting event
dcltrans
transaction TMain
begin
// creates a named event object
hEventGo := CreateEvent("MyStarterEvent");
...
...
end TMain;
transaction EventStarter
begin
wait 10.0;
// every 10 seconds the starter event forces all seller users
// to execute the selling transaction at the same time
PulseEvent(hEventGo);
end EventStarter;
transaction Selling
begin
WaitForSingleObject(hEventGo,12000); // wait maximal 12 sec.
...
end Selling;
transaction CleanUp
begin
CloseHandle(hEventGo);
end CleanUp;

Sample scripts

Trans.bdf

Parent topic: Synchronization Functions
Related reference
CreateEventEx Function
CloseHandle Function


CreateEventEx Function

Action

Creates a named or unnamed event object (Win32 function).

Include file

Kernel.bdh

Syntax

CreateEventEx( in sSecAttr     : string,
               in bManualReset : boolean,
               in bInitSignal  : boolean,
               in sName        : string ): number;

Return value

Handle to event object.

Parameter | Description
sSecAttr | Specifies the security attributes for the event object
bManualReset

Specifies whether a manual-reset or auto-reset event object is created:

  • true for manual-reset

  • false for auto-reset
bInitSignal

Specifies the initial state of the event object:

  • true for signaled

  • false for unsignaled
sName | Name of the event object

Example

hEvent := CreateEventEx(NULL, true, false, "MyStarterEvent");
Parent topic: Synchronization Functions
Related reference
CreateEvent Function
CloseHandle Function


CreateMutex Function

Action

Uses the Win32 CreateMutexEx function to create a named mutex object. Mutex objects are used to serialize access to critical sections inside transactions for multiple concurrent users.

Include file

Kernel.bdh

Syntax

CreateMutex( in sMtxName: string ): number;

Return value

handle to the mutex object

Parameter | Description
sMtxName | Name of the mutex object

Example

dcltrans
  transaction TCloseHandle
  var
    hMutex: number;
  begin
    hMutex := CreateMutex("MutexObject");
    write("mutex object created"); writeln;
    WaitForSingleObject(hMutex, INFINITE);
    ReleaseMutex(hMutex);
    write("mutex object released"); writeln;
    CloseHandle(hMutex);
    write("handle to mutex object closed"); writeln;
  end TCloseHandle;

Output

mutex object created
mutex object released
handle to mutex object closed

Sample scripts

MutexLogin.bdf

Parent topic: Synchronization Functions
Related reference
CloseHandle Function
CreateMutexEx Function
ReleaseMutex Function


CreateMutexEx Function

Action

Creates a named or unnamed mutex object (Win32 function).

Include file

Kernel.bdh

Syntax

CreateMutexEx( in sSecAttr : string,
               in bInitOwn : boolean,
               in sMtxName : string): number;

Return value

handle to mutex object

Parameter | Description
sSecAttr | Specifies the security attributes for the mutex object
bInitOwn

Specifies the initial owner of the mutex object:

  • true for calling thread requests immediate ownership

  • false if the mutex is not owned
sMtxName | Name of the mutex object

Example

hMutex := CreateMutexEx(NULL, false, "MyConnectMutex");
Parent topic: Synchronization Functions
Related reference
CreateMutex Function
ReleaseMutex Function
CloseHandle Function


PulseEvent Function

Action

Provides a single operation that sets (to signaled) the state of a specified event object and then resets it (to nonsignaled) after releasing the appropriate number of waiting threads.

Include file

Kernel.bdh

Syntax

PulseEvent( in hEvent : number ): boolean;

Return value

  • true if successful
  • false otherwise
Parameter | Description
hEvent | Handle of event object

Example

var
  hEventGo : number; // handle for starting event

dcltrans
  transaction TInit
  begin
    hEventGo := CreateEvent("MyStarterEvent");
  end TInit;

  transaction TStarter
  begin
    wait 10.0;
    // every 10 seconds the starter event forces all users
    // to execute a transaction at the same time
    PulseEvent(hEventGo);
  end TStarter;

Sample scripts

Trans.bdf

Parent topic: Synchronization Functions
Related reference
CreateEvent Function


ReleaseMutex Function

Action

Releases ownership of the specified mutex object.

Include file

Kernel.bdh

Syntax

ReleaseMutex(in hMutex: number): boolean;

Return value

  • true if successful

  • false otherwise

Parameter | Description
hMutex | Handle of the mutex object

Example

dcltrans
transaction TCloseHandle
var
hMutex: number;
begin
hMutex := CreateMutex("MutexObject");
write("mutex object created"); writeln;
WaitForSingleObject(hMutex, INFINITE);
ReleaseMutex(hMutex);
write("mutex object released"); writeln;
CloseHandle(hMutex);
write("handle to mutex object closed"); writeln;
end TCloseHandle;

Output

mutex object created
mutex object released
handle to mutex object closed

Sample scripts

Trans.bdf, MutexLogin.bdf

Parent topic: Synchronization Functions
Related reference
CreateMutex Function


WaitForSingleObject Function

Action

Waits until the specified object is in the signaled state or until the time-out interval elapses.

Include file

Kernel.bdh

Syntax

WaitForSingleObject( in hHandle    : number,
                     in nTimeoutMs : number ): number;

Return value

  • WAIT_ABANDONED. The specified object is a mutex object that was not released by the thread that owned the mutex object before the owning thread terminated. Ownership of the mutex object is granted to the calling thread, and the mutex is set to nonsignaled.

  • WAIT_OBJECT_0. The state of the specified object is signaled.

  • WAIT_TIMEOUT. The time-out interval has elapsed and the object's state is nonsignaled.

Parameter | Description
hHandle | Handle of the object
nTimeoutMs

Specifies the time-out interval, in milliseconds

  • 0 = test object's state and return immediately

  • INFINITE = Time out interval never elapses

Example

dcltrans
  transaction TCloseHandle
  var
    hMutex: number;
  begin
    hMutex := CreateMutex("MutexObject");
    write("mutex object created"); writeln;
    WaitForSingleObject(hMutex, INFINITE);
    ReleaseMutex(hMutex);
    write("mutex object released"); writeln;
    CloseHandle(hMutex);
    write("handle to mutex object closed"); writeln;
  end TCloseHandle;

Output

mutex object created
mutex object released
handle to mutex object closed

Sample scripts

Trans.bdf, MutexLogin.bdf

Parent topic: Synchronization Functions
Related reference
CreateMutex Function


CloseHandle Function

Action

Closes an open object handle previously opened with CreateEvent, CreateEventEx, CreateMutex or CreateMutexEx.

Include file

Kernel.bdh

Syntax

CloseHandle(in hHandle: number): boolean;

Return value

  • true if successful

  • false otherwise

Parameter | Description
hHandle | Object handle to close

Example

dcltrans
transaction TCloseHandle
var
hMutex: number;
begin
hMutex := CreateMutex("MutexObject");
write("mutex object created"); writeln;
WaitForSingleObject(hMutex, INFINITE);
ReleaseMutex(hMutex);
write("mutex object released"); writeln;
CloseHandle(hMutex);
write("handle to mutex object closed"); writeln;
end TCloseHandle;

Output

mutex object created
mutex object released
handle to mutex object closed
Parent topic: Synchronization Functions
Related reference
CreateMutex Function
CreateEventEx Function
CreateEvent Function


CreateSemaphore Function

Action

Creates a named or unnamed semaphore object.

Include file

Kernel.bdh

Syntax

CreateSemaphore(in nSecurity : number,
in nInitCount : number,
in nMaxCount : number,
in sName : string): number;

Return value

handle to the semaphore object

Parameter | Description
nSecurity | Security attributes for the semaphore object. This parameter must always be set to NULL.
nInitCount | Initial count for the semaphore object. This value must be greater than or equal to zero and less than or equal to nMaxCount. The initial count value is not set if the specified semaphore object already exists.
nMaxCount | Maximum count for the semaphore object. This value must be greater than zero. The maximum count value is not set if the specified semaphore object already exists.
sName | Name of the semaphore object.

Example

dcltrans
transaction TMain
constMAX_USERS := 25;
var
hSemaphore: number;
begin
hSemaphore := CreateSemaphore(NULL, MAX_USERS,
MAX_USERS, "semaphore");
...
WaitForSingleObject(hSemaphore, INFINITE);
// perform critical work
...
ReleaseSemaphore(hSemaphore, 1);
...
end TMain;
Parent topic: Synchronization Functions
Related reference
ReleaseSemaphore Function


ReleaseSemaphore Function

Action

Increases the value of a given semaphore object by a specified amount.

Include file

Kernel.bdh

Syntax

ReleaseSemaphore(in hSemaphore : number,
in nIncrease : number,
out nValue : number optional): boolean;

Return value

  • true if successful

  • false otherwise

Parameter | Description
hSemaphore | Handle to a semaphore object
nIncrease | Amount by which the semaphore object's current value is increased
nValue | Variable receiving the semaphore object's value before the value is incremented (optional)

Example

dcltrans
transaction TMain
const
MAX_USERS := 25;
var
hSemaphore: number;
begin
hSemaphore := CreateSemaphore(NULL, MAX_USERS,
MAX_USERS, "semaphore");
...
WaitForSingleObject(hSemaphore, INFINITE);
// perform critical work
...
ReleaseSemaphore(hSemaphore, 1);
...
end TMain;
Parent topic: Synchronization Functions
Related reference
CreateSemaphore Function


SetEvent Function

Action

Sets the specified event object to the signaled state. Execute this function on an event that was created with CreateEvent(). In contrast to the function PulseEvent(), SetEvent() raises an event but does not reset it automatically. Use the function ResetEvent() to reset the event manually.

Include file

kernel.bdh

Syntax

SetEvent( in hEvent : long ): boolean;
Parameter | Description
hEvent | event handle returned by CreateEvent()

Return value

  • true if successful

  • false otherwise

Parent topic: Synchronization Functions


ResetEvent Function

Action

Resets the specified event object to a non-signaled state. Execute this function on an event that was created with CreateEvent().

Include file

kernel.bdh

Syntax

ResetEvent( in hEvent : long ): boolean;
Parameter | Description
hEvent | event handle returned by CreateEvent()

Return value

  • true if successful

  • false otherwise

Parent topic: Synchronization Functions


UserSignal Function

Action

Is used to notify a virtual user, which is in a waiting state as a result of having called the UserWaitFor function. UserSignal is typically called from within a callback function in order to notify a virtual user about a particular event. The function takes a name as parameter to identify an event object to be signaled.

The scope of this function is the virtual user context, which means that virtual users that use the same event object do not interfere with each other.

Include file

kernel.bdh

Syntax

UserSignal( in sWaitObjectName : string ): boolean;
Parameter | Description
sWaitObjectName | Name to identify the event object to be signaled.

Return value

  • True if the event object was signaled.
  • False otherwise. The virtual user logs an error message.

Example

dclfunc
  function FAsyncCallback(sResponseBody : string) <ASYNC_CALLBACK_FUNCTION>
  begin
    RepMessage("MESSAGE: '" + sResponseBody + "'", SEVERITY_INFORMATIONAL);
    if (StrSearch(sResponseBody, "last message", STR_SEARCH_FIRST) <> 0) then
      UserSignal("LastMessage");
    end;
  end FAsyncCallback;

dcltrans
  transaction TMainListen
  var
    nAsyncChannel : number;
  begin
    WebPageUrl("http://lnz-testsite:8080/atmosphere-meteor-pubsub-2.0.3/", "/atmosphere-meteor-pubsub-2.0.3/");
    nAsyncChannel := WebAsyncPreparePush(callback(FAsyncCallback));
    WebFormGet("http://lnz-testsite:8080/atmosphere-meteor-pubsub-2.0.3/pubsub/mychannel_1234",
      METEOR_PUB_SUB_FORM);

    UserWaitFor("LastMessage", 60);

    WebAsyncStop(nAsyncChannel);

  end TMainListen;
Parent topic: Synchronization Functions


UserWaitFor Function

Action

Pauses the execution of a virtual user until notified to continue. The notification is typically sent from within a callback function. UserWaitFor takes a name as parameter to identify an event object that can be signaled by the UserSignal function.

The scope of this function is the virtual user context, which means that virtual users that use the same event object, do not interfere with each other.

Include file

kernel.bdh

Syntax

UserWaitFor( in sWaitObjectName : string
             in nTimeout        : number optional ): boolean;
Parameter | Description
sWaitObjectName | Name to identify the event object, which a virtual user is waiting to be signaled for
nTimeout | Optional: Timeout for setting the value in seconds. If the specified time period is exceeded, the virtual user indicates an error and continues execution. The function's default behaviour is to wait forever.

Return value

  • True if the event object was signaled within the specified timeout.
  • False otherwise. If an error other than a timeout occurred, the virtual user logs an error message.

Example

dclfunc
  function FAsyncCallback(sResponseBody : string) <ASYNC_CALLBACK_FUNCTION>
  begin
    RepMessage("MESSAGE: '" + sResponseBody + "'", SEVERITY_INFORMATIONAL);
    if (StrSearch(sResponseBody, "last message", STR_SEARCH_FIRST) <> 0) then
      UserSignal("LastMessage");
    end;
  end FAsyncCallback;

dcltrans
  transaction TMainListen
  var
    nAsyncChannel : number;
  begin
    WebPageUrl("http://lnz-testsite:8080/atmosphere-meteor-pubsub-2.0.3/", "/atmosphere-meteor-pubsub-2.0.3/");
    nAsyncChannel := WebAsyncPreparePush(callback(FAsyncCallback));
    WebFormGet("http://lnz-testsite:8080/atmosphere-meteor-pubsub-2.0.3/pubsub/mychannel_1234",
      METEOR_PUB_SUB_FORM);

    UserWaitFor("LastMessage", 60);

    WebAsyncStop(nAsyncChannel);

  end TMainListen;
Parent topic: Synchronization Functions


Random Functions

Random variables are used for generating random input values, specifying random repetition factors, specifying the probability of running transaction sections, and specifying random user times. You can use certain random functions directly within transactions without having to define a random variable. All random variables are defined in the dclrand section of a test script.

Silk Performer includes the following random functions:

  • Reset Function for RndPerN
    Re-initializes a random variable
  • Reset Function for RndStream
    Re-initializes a random variable.
  • RndSeed Function
    Initializes the random number generator.
  • RndFormatDate Function
    Adds a random number of days to a date and converts the date into a specified format.
  • SetRandomTransactions Function
    Specifies whether to perform all transactions in random or sequential order.
  • GetRandomTransactions Function
    Retrieves the current setting that determines whether to perform all transactions in random or sequential order.
  • SetSmoothArrivalRate Function
    Determines whether to force each virtual user to perform all transactions within the specified simulation interval.
  • GetSmoothArrivalRate Function
    Retrieves the current settings that determines whether to force each virtual user to perform all transactions within the specified simulation interval.
  • SetRandomThinkTime Function
    Enables randomization for the thinktime periods specified in several functions.
  • GetRandomThinkTime Function
    Reads state of randomization using an exponential distribution for the thinking periods specified in several functions.
  • SetThinkTimeFactor Function
    Manipulate think times on a global basis.
  • GetThinkTimeFactor Function
    Retrieves the active think time factor.
Parent topic: General Functions
Related concepts
Random Variables Section


Reset Function for RndPerN

Action

Re-initializes a random variable using the RndPerN random type or RndStream type. This Reset function restores all or a part of the drawn values of the random variable.

Syntax

Reset( inout rvar,
       in    nMaximum : number optional );
Parameter | Description
rvar | Random variable using the RndPerN random type or RndStream type
nMaximum | New maximum value of the random variable (optional); all values up to this value are restored. If nMaximum is omitted, all values up to the specified maximum value of the random type are restored.

Example

var
  vArtNo: number;

dclrand
  rArtNo : RndPerN(1..10000);
  rVenNo : RndPerN(100);

dcltrans
  transaction t1
  var
    i: number;
  begin
    vArtNo := rArtNo;
    c1: InsArticle();
    for i := 1 to 10 do
      c1: InsArtVen();
    end;
    Reset(rVenNo, 50);
    ...
  end t1;

dclsql
  InsArticle:
    INSERT INTO article (articlenumber, ...)
    VALUES (:vArtNo, ...
  InsArtVen:
    INSERT INTO artven (articlenumber, vendornumber, ...)
    VALUES (:vArtNo, :rVenNo, ...)

The random variable rArtNo is used to generate unique article numbers between 1 and 10000. To ensure that the article numbers generated are unique, the RndPerN random type is used instead of RndUniN. The random variable rVenNo is used to generate unique vendor numbers for each article. To allow the same vendor number for different articles, rVenNo is re-initialized at the and of the transaction. After the first call of transaction t1, only vendor numbers between 1 and 50 have been used.

Parent topic: Random Functions
Related reference
RndPerN Random Type (unique uniform distribution)
RndStream Random Type (sequential from a pattern file)
RndUniN Random Type (uniform distribution)


Reset Function for RndStream

Action

Re-initializes a random variable using the RndStream type. After invocation of this Reset function, a subsequent call of RndStream starts at the beginning of the file again.

Syntax

Reset( inout rvar );
Parameter | Description
rvar | Random variable using the RndStream type
Parent topic: Random Functions


RndSeed Function

Action

Initializes the random number generator. If you use the same number for initialization, you will get the same sequence of random accesses for all randomly generated actions (for example, random variables, transaction sequences, ...). By using the same initialization values for the random generator, you can repeatedly reproduce a simulation exactly.

Include file

Kernel.bdh

Syntax

RndSeed( in nSeed : number );
Parameter | Description
nSeed | Initialization value

Example

dcltrans
  transaction TRndSeed
  begin
    RndSeed(123);
    write("random number generator initialized"); writeln;
  end TRndSeed;

Output

random number generator initialized
Parent topic: Random Functions


RndFormatDate Function

Action

Adds a random number of days between 0 and nDays to a date and formats this date into the specified format. The random values generated are distributed uniformly.

Include file

Kernel.bdh

Syntax

RndFormatDate( in nDate      : number,
               in nDays      : number,
               in sFormat    : string
               in bLocalized  : boolean optional ): string;

Return value

formatted date string

Parameter | Description
nDate | Input date with format YYYYMMDD
nDays | Upper boundary of random interval for days to add
sFormat | Format control string (FormatDate)
bLocalized | If True, returns the localized date format (optional).

Example

dcltrans
  transaction TRndFormatDate
  var
    sNewDate: string;
  begin
    // add 0 - 20 days to 19961015 and format it to "1996-11-10"
    sNewDate := RndFormatDate(19961015, 20, DATE_YYYY_MM_DD);
    write("newdate = "); write(sNewDate); writeln;
  end TRndFormatDate;

Output

newdate = 1996-10-30

Sample scripts

OraSample.bdf, DBApi01.bdf

Parent topic: Random Functions
Related concepts
Date Functions
Related reference
RndDate Function
FormatDate Function
GetCurrentDate Function


SetRandomTransactions Function

Action

Specifies whether the simulation engine has to perform all transactions defined in the workload section of the script in random or sequential order.

Note: This function overrides the setting specified in the Simulation tab of the Profile Settings - Simulation dialog.

Include file

Kernel.bdh

Syntax

SetRandomTransactions( in bRandom : boolean );
Parameter | Description
bRandom | If this parameter is set to true, the simulation engine performs all transactions defined in the workload section in random order. If this parameter is set to false, all transactions are executed in sequential order.

Example

dcluser
  user
    UserGrp(5)
  transactions
    TB : begin;
    T1 : 2;
    T2 : 2;
    TE : end;

dcltrans
  transaction TB
  begin
    SetRandomTransactions(false);
    write("TB ");
  end TB;

  transaction T1
  begin
    write("T1 ");
  end T1;

  transaction T2
  begin
    write("T2 ");
  end T2;

transaction TE
  begin
    write("TE ");
  end TE;

Output

TB T1 T1 T2 T2 TE
Parent topic: Random Functions
Parent topic: Simulation Setting Functions
Related reference
GetRandomTransactions Function


GetRandomTransactions Function

Action

Retrieves the current setting that determines whether the simulation engine has to perform all transactions defined in the workload section of the load testing script in random or sequential order.

Include file

Kernel.bdh

Syntax

GetRandomTransactions(): boolean;

Return value

  • true if the simulation engine currently performs all transactions defined in the workload section of the load testing script in random order

  • false otherwise

Example

dcltrans
  transaction TMain
  begin
    write ("transaction order: ");
    if GetRandomTransactions() then
      writeln("random")
    else
      writeln("sequential")
  end;
end TMain;
Parent topic: Random Functions
Parent topic: Simulation Setting Functions
Related reference
SetRandomTransactions Function


SetSmoothArrivalRate Function

Action

Determines whether to force each virtual user to perform all transactions within the specified simulation interval.

If this option is disabled, Silk Performer calculates the delay of the arrival of each transaction randomly. In this case, the simulation time period and the total number of transactions to be called determine the mean arrival interval of the transactions.

Note: This function overrides the setting specified in the Simulation tab of the Profile Settings - Simulation dialog.

Include file

Kernel.bdh

Syntax

SetSmoothArrivalRate( in bSmooth : boolean );
Parameter Description
bSmooth

If this parameter is set to true, each user tries to execute all transactions within the simulation interval

If this parameter is set to false, Silk Performer calculates the delay of the arrival of each transaction randomly.

Example

dcluser
  user
    WebUser
  transactions
    T1 : begin;
    T1 : 5;
    T2 : 4;

dclrand
  rThinkingTime: RndUniF(35.0..55.0);

dcltrans
  transaction T1
  begin
    SetSmoothArrivalRate(true);
    ThinkTime(rThinkingTime);
  end T1;
  transaction T2
  begin
    ThinkTime(rThinkingTime);
  end T2;
Parent topic: Random Functions
Parent topic: Simulation Setting Functions
Related reference
GetSmoothArrivalRate Function


GetSmoothArrivalRate Function

Action

Retrieves the current setting that determines whether each virtual user is forced to perform all transactions within the specified simulation interval.

Include file

Kernel.bdh

Syntax

GetSmoothArrivalRate(): boolean;

Return value

  • true if each virtual user is currently forced to perform all transactions within the specified simulation interval

  • false otherwise

Example

dcltrans
transaction TMain
begin
write ("transaction arrival rate: ");
if GetSmoothArrivalRate() then
writeln("smooth");
else
writeln("randomly distributed");
end;
end TMain;
Parent topic: Random Functions
Parent topic: Simulation Setting Functions
Related reference
SetSmoothArrivalRate Function


SetRandomThinkTime Function

Action

Enables randomization for the thinktime periods specified in several functions. If randomization is enabled you can choose between exponential distribution and uniform distribution (parameter eOption). The seed value of the random number generator may be set using the RndSeed function.

Note: This function overrides the setting specified in the Simulation tab of the Profile Settings - Simulation dialog.

Include file

Kernel.bdh

Syntax

SetRandomThinkTime( in bRandom    : boolean
                    in eOption    : number optional,
                    in nDeviation : number optional );
Parameter | Description
bRandom | If this parameter is set to true, randomization for thinktime periods is enabled
eOption

Can be either:

  • OPT_THINKTIME_EXPONENTIAL : For exponential distribution (default).

  • OPT_THINKTIME_UNIFORM : For uniform distribution. You have to specify also the deviation factor (3rd parameter) that has to be a value between 1 and 100%.
nDeviation | The deviation factor used if OPT_THINKTIME_UNIFORM is set (in %).

Example

dcltrans
  transaction TMain
  begin
    SetRandomThinkTime(true, OPT_THINKTIME_EXPONENTIAL);
    WebUrl("http://standardhost/index.html", 2.1);
    // 2.1 is the mean value of the
    // exponential distributed thinking period
  end TMain;
Parent topic: Random Functions
Parent topic: Simulation Setting Functions
Related reference
GetRandomThinkTime Function
GetThinkTimeFactor Function
RndSeed Function
ThinkTime Function


GetRandomThinkTime Function

Action

Reads the state of randomization for the thinktime periods specified in several functions.

Include file

Kernel.bdh

Syntax

GetRandomThinkTime( out eOption    : numberoptional,
                    out nDeviation : number optional ): boolean;

Return value

  • true if randomization is enabled

  • false otherwise

Parameter | Description
eOption

Can be either:

  • OPT_THINKTIME_EXPONENTIAL: For exponential distribution (default).

  • OPT_THINKTIME_UNIFORM: For uniform distribution. You have to specify also the deviation factor (3rd parameter) that has to be a value between 1 and 100%.
nDeviation | The deviation factor used if OPT_THINKTIME_UNIFORM is set (in %).

Example

dcltrans
  transaction Tinit
  var
    nDistribution : number;
    nDeviation    : number;
  begin
    write("Random thinking time: ");
    if GetRandomThinkTime(nDistribution, nDeviation) then
      write("true – distribution: ");
      if nDistribution = OPT_THINKTIME_EXPONENTIAL then
        write("exponential");
      else
        write("uniform");
      end;
    else
      write("false");
    end;
    writeln;
  end TInit;
Parent topic: Random Functions
Parent topic: Simulation Setting Functions
Related reference
SetRandomThinkTime Function
ThinkTime Function


SetThinkTimeFactor Function

Action

Think time factors can be defined to manipulate think times on a global basis. When enabled, factors are multiplied to all think times that are included in scripts. Think time manipulation can be enabled/disabled and manipulation factors are adjusted using the SetThinkTimeFactor function. When random think time is enabled, manipulation factors are applied after randomization.

Note: Adjusting think time factors is not available if running a stress test or performing a Try Script run, because Silk Performer ignores think times with those workload settings. Note that Silk Performer will report an error when executing a stress test or Try Script run with adjusted think time factors.

An error also occurrs if think times are adjusted manually to stress test or none, which Silk Performer sets implicitly for a given workload:

SetThinktimeAdjustment(OPT_TTA_NONE); // or

SetThinktimeAdjustment(OPT_TTA_STRESSTEST);

To avoid error messages in verification test runs, you may manually set think time adjustments in a script:

SetThinktimeAdjustment(OPT_TTA_STATIC, 1.0); // or

SetThinktimeAdjustment(OPT_TTA_DYNAMIC, 3.0, 9.0);

Include file

kernel.bdh

Syntax

SetThinkTimeFactor( in bEnable          : boolean,
                    in fThinkTimeFactor : float optional );
Parameter | Description
bEnable | Specifies whether think time manipulation using a think time factor should be activated.
fThinkTimefactor | The think-time factor that is applied when think time manipulation is enabled. This parameter may be omitted, in which case the currently adjusted factor will be reapplied.

Example

dcltrans
  transaction TmyTrans1
  var
    fTTF : float;
  begin
    SetThinkTimeFactor(true, 1.2);
    ThinkTime(1.0);
    SetThinkTimeFactor(false, 1.2);
    ThinkTime(1.0);
    SetThinkTimeFactor(true);
    ThinkTime(1.0);

    if GetThinkTimeFactor(fTTF) then
      Print("Think Time Factor: " + string(fTTF));
    end;
    ThinkTime(1.0);
  end TmyTrans1;

Output

Think Time Factor: 1.2
Parent topic: Random Functions
Related reference
GetThinkTimeFactor Function
ThinkTime Function
GetRandomThinkTime Function


GetThinkTimeFactor Function

Action

Think time factors can be defined to manipulate think times on a global basis. When enabled, factors are multiplied to all think times that are included in scripts. The GetThinkTimeFactor function retrieves the active think time factor.

Include file

kernel.bdh

Syntax

GetThinkTimeFactor( out fThinkTimefactor : float optional ): boolean;

Return value

  • true if think time adaptation using the think time factor is enabled

  • false otherwise

Parameter | Description
fThinkTimefactor | The float variable that will receive the currently defined think time factor.

Example

dcltrans
  transaction TmyTrans1
  var
    fTTF : float;
  begin
    SetThinkTimeFactor(true, 1.2);

    ThinkTime(1.0);

    if GetThinkTimeFactor(fTTF) then
      Print("Think Time Factor: " + string(fTTF));
    end;
    ThinkTime(1.0);
  end TmyTrans1;

Output

Think Time Factor: 1.2
Parent topic: Random Functions
Related reference
SetThinkTimeFactor Function
SetRandomThinkTime Function
GetRandomThinkTime Function
ThinkTime Function


Random Types

Silk Performer includes the following random types:

  • RndBin Random Type (binomial distribution)
    Declares a random variable that contains a boolean value that is generated following a binomial (Bernoulli) distribution.
  • RndExpF Random Type (exponential distribution)
    Declares a random variable that contains a floating-point value that is generated following an exponential distribution.
  • RndExpN Random Type (exponential distribution)
    Declares a random variable that contains a random integer value that is generated following an exponential distribution.
  • RndFile Random Type (strings from a pattern file)
    Declares a random variable that contains a random string value following a uniform distribution.
  • RndInd Random Type (individual distribution)
    Declares a random variable that contains a random value whose type is either string or integer, depending on the syntax of your declaration.
  • RndPerN Random Type (unique uniform distribution)
    Declares a random variable that contains a unique random integer value that is generated following a uniform distribution.
  • RndSno Random Type (serial numbers)
    Generates serial numbers of type integer. For each call, the RndSno type returns a value incremented by one over the previous call.
  • RndStr Random Type (alphanumeric values)
    Declares a random variable that contains a random string value.
  • RndStream Random Type (sequential from a pattern file)
    Declares a random variable that contains a string value selected in sequential order from a pattern file.
  • RndUniF Random Type (for wait statements)
    Declares a random variable that can be used solely in wait statements for generating random user times.
  • RndUniI Random Type (uniform distribution with intervals)
    Creates a variable that contains a value that is generated following a uniform distribution with intervals.
  • RndUniN Random Type (uniform distribution)
    Declares a random variable of type RndUniN. With each access, such a variable contains a value that is generated following a uniform distribution.
  • Normal Distribution
    Generate random values following a normal distribution.
Parent topic: General Functions


RndBin Random Type (binomial distribution)

Action

Declares a random variable of type RndBin. With each access, such a variable contains a boolean value that is generated following a binomial (Bernoulli) distribution. The parameter of the RndBin random type specifies the probability of returning true. For example, you can use a random variable using the RndBin random type to specify the probability of running transaction components.

Syntax

RndBin( in p : float ): boolean;

Return value

  • true or

  • false

Parameter | Description
p | Probability of returning true Condition: 0.0 <= p <= 1.0

Example

dclrand
  rEvent1, rEvent2: RndBin(0.25);

dcltrans
  transaction TMain
  begin
    if rEvent1 then ... end;

    while not rEvent2 do ... end;
  end TMain;

The example shows two random variables with Bernoulli distribution (rEvent1 and rEvent2). In both cases the probability of returning true is 0.25. This means that on average rEvent1 will be set to true in 25% of all cases, and the same applies for rEvent2.

Note: As each use of a random variable generates a new random value, you must assign the value of a random variable to a transaction variable in order to be able to reuse this value.

Sample scripts

OraSample.bdf, DBApi01.bdf

Parent topic: Random Types


RndExpF Random Type (exponential distribution)

Action

Declares a random variable of type RndExpF. With each access, such a variable contains a floating-point value that is generated following an exponential distribution. The parameter of the RndExpF function constitutes the mean value of the exponential distribution.

Syntax

RndExpF( in fMean : float ): float;

Return value

float

Parameter | Description
fMean | Mean value of the exponential distribution

Example

dclrand
  rEvent1, rEvent2 : RndBin(0.25);
  rTime1 : RndExpF(5.5); /* waiting period in seconds */
  ...

dcltrans
  transaction t1
  begin
    if rEvent1 then ... end;
    wait rTime1;

    while not rEvent2 do ... end;
  end t1;
Note: The example shows a random variable rTime1 with exponential distribution with a mean value of 5.5. rTime1 is used in a wait statement of a transaction for simulation of a random waiting period.

Sample scripts

OraSample.bdf, DBApi01.bdf

Parent topic: Random Types
Related reference
RndExpN Random Type (exponential distribution)


RndExpN Random Type (exponential distribution)

Action

Declares a random variable of type RndExpN. With each access, such a variable contains a random integer value that is generated following an exponential distribution. The floating-point values of the exponential distribution are rounded to integer values (1.5 —>—> 2, 1.4 —>—> 1, ...).

Syntax

RndExpN( l..u: m ): number;

Return value

number

Parameter | Description
l | Lower boundary of the integer interval of random values (number)
u | Upper boundary of the integer interval of random values (number)
m | Mean value of the exponential distribution (float) Condition: l <= m <= u

If a generated random value is outside the interval of integer values declared, it is replaced by the value of the respective boundary.

Example

dclrand
  rEvent1, rEvent2 : RndBin(0.25);
  rTime1           : RndExpF(5.5);
  rTime2           : RndUniF(0.5..12.5);
  rCube            : RndUniN(1..6);
  rPrice           : RndUniN(10..2000);
  rArtNo           : RndExpN(1..10000: 100.0);
  ...

dclsql
  UpdArticle:
    UPDATE article SET price = :rPrice
    WHERE articlenumber = :rArtNo;

The random variable rArtNo is used in a SQL command to access an article with a random article number of type integer. The generated random integer values follow an exponential distribution with a mean value of 100.0. Values outside the interval 1 to 10000 are replaced by the respective boundary of the interval.

Sample scripts

OraSample.bdf, DBApi01.bdf

Parent topic: Random Types
Related reference
RndExpF Random Type (exponential distribution)


RndFile Random Type (strings from a pattern file)

Action

Declares a random variable of type RndFile. With each access, such a variable contains a random string value that is generated following a uniform distribution. The strings are selected randomly from a pattern file. The values in the pattern file must be separated with semicolons (;). Leading blanks, tabs and newline characters are ignored. Trailing blanks, tabs or new line characters are part of the value. Each position in the pattern file has the same probability of being chosen. The position in the pattern file is generated randomly. The value located at the randomly generated position is chosen to be the next value of the random type.

If the file name includes a directory name, the file is opened in the specified directory. Otherwise, Silk Performer looks for the file in the folder where the test script is located. If Silk Performer does not find the file there, it looks for the file in the Data folder.

If you are going to use remote agents for the load test, you should store your data files in the Data directory or in the directory where the load-test script is located. Note that in any case you have to add the data files to your project.

Syntax

RndFile( in sFileName : string,
         in nMaxLen   : number ): string;

Return value

First random value: Martin

Second random value: Tom

Parameter | Description
sFileName | String constant specifying the path and file name of the pattern file. The pattern file defines the values to be used by the random type. If the path is omitted, the file must be in the current directory.
nMaxLen | Maximum length of the random string. If a value in the pattern file is longer than the maximum length, the value is truncated to the maximum length.

Example

Pattern File: <public user documents>\Silk Performer 21.0\Data\Efname.rnd

First random value: Martin

Second random value: Tom

dclrand
  rACat      : RndStr("AABBCCDDEEFF0123456789", 3..4);
  rName      : RndStr(10..40);
  rFirstName : RndFile("<Silk Performer installpath>\\Working\\Data\\Efname.rnd", 20);
  ...

dclsql
  InsArticle:
    INSERT INTO article (category, name, firstname)
    VALUES (:rACat, :rName, :rFirstName);

The random variable rFirstName is used in a SQL command to generate random values for the database field firstname. The generated values are alphanumeric values. The pattern values are stored in the file <public user documents>\Silk Performer 21.0\Data\Efname.rnd containing the values "Tom", "Ron", "Martin" and "Paul".

The pattern files are loaded into memory for each user when a simulator initializes at the beginning of a load test. For large pattern files and multi column random values, we recommend using the new, more flexible random file functions FileCSVLoad, FileFixedLoad and FileGetRndRow.

Note: There are a number of pattern files in your Silk Performer Include directory; you can use these to generate realistic random names, states, zip codes and cities. Look for files with file extension rnd.
Parent topic: Random Types
Related reference
FileCSVLoadGlobal Function
FileFixedLoadGlobal Function
FileUnload Function
FileGetNumRows Function
FileGetFirstRow Function
FileGetNextRow Function
FileGetRow Function
FileGetCol Function


RndInd Random Type (individual distribution)

Action

Declares a random variable of type RndInd. With each access, such a variable contains a random value whose type is either string or integer, depending on the syntax of your declaration. All possible values of the random variable along with their probabilities/weights must be declared. You cannot mix integer and string values.

Note: Not only probalities which must sum up to 1.0 are allowed as parameters. Also weights can be used; but they are internally also used as probabilities."

Sytax

RndInd( s1=p1, ..., sn=pn ): string;
RndInd( u1=p1, ..., un=pn ): number;

Return value

  • string or

  • number

Parameter | Description
s1 | First random value (string)
u1 | First random value (number)
p1 | Probability/weight of the first random value (float)
sn | nth random value (string)
un | nth random value (number)
pn | Probability/weight of the nth random value (float) Condition: p i = 1;

Example

dclrand
  rMaritalStat : RndInd("single" =0.4, "married"=0.3,
                        "divorced"=0.2, "widowed"=0.1);
  rMark : RndInd(1=0.1, 2=0.2, 3=0.3, 4=0.2, 5=0.2);
  ...

dclsql
  InsPerson:
    INSERT INTO person (name, maritalstatus)
    VALUES (:rName, :rMaritalStat);
  InsExam:
    INSERT INTO exam (name, mark)
    VALUES (:rName, :rMark);

The random variable rMaritalStat is used in a SQL command to generate random values for the database field marital status. The probabilities/weights of the values for marital status are: 40% "single", 30% "married", 20% "divorced", and 10% "widowed". The random variable rMark is used in a SQL command to generate random values for the database field mark. The probabilities/weights of the values for mark are: 10% 1, 20% 2, 30% 3, 20% 4 and 20% 5.

Sample scripts

OraArrayFetch.bdf, OraSample.bdf, DBApi01.bdf

Parent topic: Random Types


RndPerN Random Type (unique uniform distribution)

Action

Declares a random variable of type RndPerN. With each access, such a variable contains a unique random integer value that is generated following a uniform distribution. The parameter of the RndPerN function specifies the maximum value of the uniform distribution. The minimum random value is 1. Within these boundaries (and including the boundaries) all integer values have the same probability of being selected. No value in the specified interval is selected twice. If all values have been selected, the maximum value+1 is returned. You can compare the RndPerN function with a drawing of lots where no lot is put back.

Syntax

RndPerN( in nMax : number ): number;

Return value

number

Parameter | Description
nMax | Maximum value Condition: nMax <= 500000

Sample scripts

OraSample.bdf

Parent topic: Random Types


RndSno Random Type (serial numbers)

Action

Generates serial numbers of type integer. For each call, the RndSno type returns a value incremented by one over the previous call.

Syntax

RndSno( in nStart : number ): number;

Return value

number

Parameter | Description
nStart | Starting value of the function

Example

dclrand
  rCube  : RndUniN(1..6);
  rPrice : RndUniN(10..2000);
  rArtNo : RndExpN(1..10000: 100.0);
  rACat  : RndStr("AABBCCDDEEFF0123456789", 3..4);
  rName  : RndStr(10..40);
  rLfdNo : RndSno(1);

dclsql
  InsArticle:
    INSERT INTO article (articlenumber, category, name)
    VALUES (:rLfdNo, :rACat, :rName);

The random variable rLfdNo is used in a SQL command to generate serial number values for the database field articlenumber. The first value generated is 1.

Parent topic: Random Types


RndStr Random Type (alphanumeric values)

Action

Declares a random variable of type RndStr. With each access, such a variable contains a random string value. The characters of the string and the length of the string are generated randomly following a uniform distribution.

Syntax

RndStr( s, l..u ): string;

Return value

string

Parameter | Description
s | Pattern string - optional (string) The pattern string defines the characters to be used in the random string. Each character in the pattern string has the same probability of being chosen. If the pattern string is omitted, the standard pattern string "ABCDEFGHIJKLMNOPQRSTUVWXYZ" is used.
l | Minimum length of random string (number)
u | Maximum length of random string (number) Condition: l <= u

Example

dclrand
  rEvent1, rEvent2 : RndBin(0.25);
  rTime1 : RndExpF(5.5);
  rTime2 : RndUniF(0.5..12.5);
  rCube  : RndUniN(1..6);
  rPrice : RndUniN(10..2000);
  rArtNo : RndExpN(1..10000: 100.0);
  rACat  : RndStr("AABBCCDDEEFF0123456789", 3..4);
  rName  : RndStr(10..40);

dclsql
  InsArticle:
    INSERT INTO article (category, name)
    VALUES (:rACat, :rName);

The random variable rACat is used in a SQL command to generate random values for the database field category. The generated values are alphanumeric values with a length of 3 or 4 characters. The pattern string consists of the digits 0 to 9 and the characters A to F. The probability of the characters A to F is twice the probability of the digits. The random variable rName is used in a SQL command to generate random values for the database field name. The generated values are alphanumeric values with a length of 10 to 40 characters. The standard pattern string (A to Z) is used.

Sample scripts

OraSample.bdf

Parent topic: Random Types


RndStream Random Type (sequential from a pattern file)

Action

Declares a random variable of type RndStream. With each access, such a variable contains a string value selected in sequential order from a pattern file. RndStream reads the values of a file sequentially starting at the beginning of the file. If the end of the file is reached, the next call of RndStream starts at the beginning of the file again. The Silk Performer Reset function has the same effect. The values in the pattern file must be separated with semicolons (;). Leading blanks, tabs and new-line characters are ignored.

Trailing blanks, tabs and new-line characters are part of the value.

If the file name includes a directory name, the file is opened in the specified directory. Otherwise, Silk Performer looks for the file in the folder where the test script is located. If Silk Performer does not find the file there, it looks for the file in the Data folder.

If you are going to use remote agents for the load test, you should store your data files in the Data directory or in the directory where the test script is located. Note that in any case you have to add the data files to your load-testing project.

Syntax

RndStream( in sFileName : string,
           in nMaxLen   : number ): string;

Return value

string

Parameter | Description
sFileName | String constant specifying the path and file name of the pattern file. The pattern file defines the values to be used by the type. If the path is omitted, the file must be in the current directory.
nMaxLen | Maximum length of the return string. If a value in the pattern file is longer than the maximum length, it is truncated to the maximum length.

Example

Pattern File: <public user documents>\Silk Performer 21.0\Data\Efname.rnd

dclrand
  rACat      : RndStr("AABBCCDDEEFF0123456789", 3..4);
  rName      : RndStr(10..40);
  rFirstName : RndStream("<Silk Performer installpath>\\Working\\Data\\Efname.rnd", 20);

dclsql
  InsArticle:
    INSERT INTO article (category, name, firstname)
    VALUES (:rACat, :rName, :rFirstName);

The random variable rFirstName is used in a SQL command to generate sequential values for the database field firstname. The generated values are alphanumeric values. The pattern values are stored in the file <public user documents>\Silk Performer 21.0\Data\Efname.rnd containing the values "Tom", "Ron", "Martin", and "Paul".

The pattern files are loaded into memory for each user when a simulator initializes at the beginning of a test. For large pattern files and multi column random values, we recommend using the new, more flexible random file functions FileCSVLoad, FileFixedLoad and FileGetRndRow.

Note: There are a number of pattern files in your Silk Performer Include directory you can use to generate realistic random names, states, zip codes, cities. Look for files with file extension rnd.
Parent topic: Random Types
Related concepts
Extended File Functions
Related reference
FileCSVLoad Function
FileFixedLoad Function
Reset Function for RndStream


RndUniF Random Type (for wait statements)

Action

Declares a random variable of type RndUniF. With each access, such a variable contains a value that is generated following a uniform distribution. The parameters of the RndUniF function specify the minimum value and the maximum value of the uniform distribution. Random variables of type RndUniF can be used solely in wait statements for generating random user times.

Syntax

RndUniF( l..u ): float;

Return value

float

Parameter | Description
l | Lower boundary (float)
u | Upper boundary (float) Condition: l <= u

Example

dclrand
  rEvent1, rEvent2 : RndBin(0.25);
  rTime1           : RndExpF(5.5);
  rTime2           : RndUniF(0.5..12.5);

dcltrans
  transaction t1
  begin
    if rEvent1 then ... end;
    wait rTime2;
    while not rEvent2 do ... end;
  end t1;

The example shows a random variable with uniform distribution (rTime2). The lower boundary of this random variable is 0.5 and the upper boundary is 12.5. In the interval 0.5 to 12.5 all floating-point values have the same probability. rTime2 is used in a wait statement of a transaction for simulating a random waiting period.

Sample scripts

RandomLogin.bdf, Measure01.bdf, Measure03.bdf, DBApi01.bdf

Parent topic: Random Types
Related reference
RndUniI Random Type (uniform distribution with intervals)
RndUniN Random Type (uniform distribution)


RndUniI Random Type (uniform distribution with intervals)

Action

Declares a random variable of type RndUniI. With each access, such a variable contains a value that is generated following a uniform distribution with intervals. With a random variable of type RndUniI you can define multiple intervals of random integer values.

Syntax

RndUniI( l1..u1=p1, ..., ln..un=pn ): number;

Return value

number

Parameter | Description
l1 | Lower boundary of the first interval of random values (number)
u1 | Upper boundary of the first interval of random values (number)
p1 | Probability of choosing the first interval of values (float)
ln | Lower boundary of the nth interval of random values (number)
un | Upper boundary of the nth interval of random values (number)
pn | Probability of choosing the nth interval of values (float) Condition: pi = 1; i : li <= ui

Example

dclrand
  rEvent1, rEvent2 : RndBin(0.25);
  rTime1           : RndExpF(5.5);
  rTime2           : RndUniF(0.5..12.5);
  rCube            : RndUniN(1..6);
  rPrice           : RndUniN(10..2000);
  rArtNo           : RndUniI(1..50=0.6, 51..100=0.3, 101..10000=0.1);

dclsql
  UpdArticle:
    UPDATE article SET price = :rPrice
    WHERE articlenumber = :rArtNo;

The random variable rArtNo is used in a SQL command to access an article with a random article number. 60% of all integer random values are between 1 and 50, 30% are between 51 and 100 and 10% are between 101 and 10000.

Sample scripts

OraSample.bdf, DBApi01.bdf, Trans.bdf

Parent topic: Random Types
Related reference
RndUniF Random Type (for wait statements)
RndUniN Random Type (uniform distribution)


RndUniN Random Type (uniform distribution)

Action

Declares a random variable of type RndUniN. With each access, such a variable contains a value that is generated following a uniform distribution. The parameters of the RndUniN function specify the minimum value and the maximum value of the uniform distribution. Within these boundaries all integer values have the same probability (including the boundaries).

Syntax

RndUniN( l..u ): number;

Return value

number

Parameter | Description
l | Lower boundary (number)
u | Upper boundary (number) Condition: l <= u

Example

dclrand
  rCube  : RndUniN(1..6);
  rArtNo : RndUniN(1..10000);
  rPrice : RndUniN(10..2000);

dcltrans
  transaction t1
  var
    i: number;
  begin
    for i := 1 to rCube do
      c1: UpdArticle();
    end;
  end t1;

dclsql
  UpdArticle:
    UPDATE article SET price = :rPrice
    WHERE articlenumber = :rArtNo;

rCube is a random variable that generates integer random values between 1 and 6. Each value has the same probability. rCube is used in a for loop of a transaction to express a random factor of repetition. The random variable rArtNo generating integer numbers between 1 and 10000 is used in a SQL command to access an article randomly. The random variable rPrice is used to update the price of the accessed article; the price is set randomly to a value between 10 and 2000.

Sample scripts

OraArrayFetch.bdf, OraSample.bdf, Trans.bdf

Parent topic: Random Types
Related reference
RndUniF Random Type (for wait statements)
RndUniI Random Type (uniform distribution with intervals)


Normal Distribution

Since Silk Performer provides no random type for generating random values that follow a normal distribution, you have to implement your own function for this purpose. The BDL code shown below illustrates how your function should look like.

To use this function, enter exactly the same BDL code in your test script.

Implementation

dclrand
  rUniform01: RndUniF(0.0 .. 1.0);

dclfunc
  function NormalDistribution(fMean, fStd: float): float
  var
    i : number;
    f : float;
  begin
    f := -6.0;
    for i := 1 to 12do
      f := f + rUniform01;
    end;
    NormalDistribution := fMean + fStd*f;
  end NormalDistribution;

Return value

a random value following a normal distribution with the specified mean value and standard deviation

Parameter | Description
fMean | Mean value of the normal distribution the generated random value has to follow
fStd | Standard deviation of the normal distribution the generated random value has to follow

Example

dcltrans
  transaction TMain
  var
    i: number;
  begin
    for i := 1 to 20 do
      writeln(NormalDistribution(20.0, 2.0));
    end;
  end TMain;

Output

19.756000
16.140000
20.464000
20.844000
19.546000
...
Parent topic: Random Types


Runtime Functions

Silk Performer provides the following runtime functions:

  • Wait Time Options for Virtual Users
    Explains the options that Silk Performer offers for simulating idle times of virtual users and what the differences are.
  • Halt Statement
    Terminates the simulation of the current user.
  • ThinkTime Function
    Simulates thinking periods during user transactions (for example, the time required to enter input data).
  • Throw Statement
    Terminates the execution of an event handler function by passing execution control to the runtime system.
  • Wait Statement
    Simulates waiting periods produced by the user of a transaction (for example, the time for entering input data).
Parent topic: General Functions


Wait Time Options for Virtual Users

In order to realistically simulate real user behaviour, virtual users sometimes need to be idle before proceeding with the next action defined in a BDL script. Silk Performer offers three options to do this:
  • Wait statement
  • ThinkTime function
  • fWait parameter in Low-Level Web Functions

Wait and ThinkTime do not affect the transaction busy time, whereas the fWait parameter in low-level web function calls adds to the transaction busy time. The behavior of the fWait parameter in low-level web functions is described in detail in Low-Level Web Function Replay Timing.

The difference between Wait and ThinkTime

How long a virtual user remains idle during a ThinkTime function call depends on the think time options, such as stresstest, random think time, think time limit, or think time adjustment parameters set via SetThinkTimeAdjustment.

The Wait statement forces a virtual user to remain idle for exactly the amount of time specified by the parameter.

Wait option | Dependent on ThinkTime options | Affects transaction busy time
ThinkTime function | yes | no
Wait statement | no | no
fWait parameter in low-level web function | yes | yes
Parent topic: Runtime Functions


ThinkTime Function

Action

Simulates thinking periods during user transactions (for example, the time required to enter input data). This function only affects simulation in case of a real load test. Note that during Try Script runs, think times are ignored completely.

Include file

Kernel.bdh

Syntax

ThinkTime( in fTime      : float,
           in nOption    : number optional,
           in nDeviation : number optional ): float;

Return value

Actual thinking time (in seconds).

Parameter | Description
fTime | Time interval that the simulated user must wait (in seconds).
nOption

Specifies whether or not random values should be generated for think time periods (optional). The following options are available:

  • OPT_THINKTIME_STRESSTEST. Think time is ignored so that the tested system can be stressed using maximum load.

  • OPT_THINKTIME_EXPONENTIAL. Random think time values are generated following an exponential distribution. The fTime parameter specifies the mean value of the distribution.

  • OPT_THINKTIME_UNIFORM. Generates random think time values following a uniform distribution. The deviation factor (3rd parameter) specifies the deviation range above and below the think time value.

  • OPT_THINKTIME_FORCEEXACT. The specified think time is maintained regardless of profile settings.

When this parameter is omitted, the user waits as long as specified.
nDeviation | The deviation factor used when OPT_THINKTIME_UNIFORM is set (in %).

Example

dcltrans
  transaction TMain
  begin
    SetStressTest(false);
    ThinkTime(3.0);
    WebUrl("http://www.MyCompany.com");
    ThinkTime(5.0, OPT_THINKTIME_EXPONENTIAL);
    WebUrl("http://support.MyCompany.com/index.jspa");
    ...
  end TMain;

Sample scripts

RandomLogin.bdf, Measure01.bdf, Measure02.bdf, Measure03.bdf, OraSample.bdf, DBApi01.bdf

Parent topic: Runtime Functions
Related reference
SetStressTest Function
GetStressTest Function
GetThinkTimeLimit Function
SetThinkTimeLimit Function


Simulation Setting Functions

Silk Performer provides the following simulation setting functions:

  • GetCallEndTransaction Function
    Gets the value of the setting that specifies whether the final transaction (end transaction) is to be processed when the load test is stopped.
  • GetCancelAfterSimTime Function
    Retrieves the current setting for whether to abort the simulation when the simulation time exceeds.
  • GetCompleteTransaction Function
    Gets the value of the setting that specifies whether the active transaction and the final transaction are to be processed when the load-test is stopped.
  • GetPacingTime Function
    Gets the pacing time.
  • GetRandomThinkTime Function
    Reads state of randomization using an exponential distribution for the thinking periods specified in several functions.
  • GetRandomTransactions Function
    Retrieves the current setting that determines whether to perform all transactions in random or sequential order.
  • GetSmoothArrivalRate Function
    Retrieves the current settings that determines whether to force each virtual user to perform all transactions within the specified simulation interval.
  • GetStressTest Function
    Gets the current value of the stress test switch.
  • GetThinkTimeLimit Function
    Gets the value of the setting which specifies whether think times should be limited to a certain maximum value.
  • SetCallEndTransaction Function
    Specifies whether the final transaction (end transaction) is to be processed when the load test is stopped.
  • SetCancelAfterSimTime Function
    Specifies whether to abort the simulation when the simulation time exceeds.
  • SetCompleteTransaction Function
    Specifies whether the active transaction is to be processed when the load test is stopped.
  • SetPacingTime Function
    Sets the pacing time.
  • SetRandomThinkTime Function
    Enables randomization for the thinktime periods specified in several functions.
  • SetRandomTransactions Function
    Specifies whether to perform all transactions in random or sequential order.
  • SetSmoothArrivalRate Function
    Determines whether to force each virtual user to perform all transactions within the specified simulation interval.
  • SetStressTest Function
    Specifies whether or not Silk Performer should ignore the thinking periods specified with the ThinkTime function and several low-level web functions.
  • SetThinkTimeLimit Function
    Specifies whether think times should be limited to a certain maximum value.
  • SetCancelOnErrorInBeginTransaction Function
    Specifies whether the runtime should be halted in case of an error in the begin transaction.
  • GetCancelOnErrorInBeginTransaction Function
    Gets the value of the setting that specifies whether the runtime should be halted in case of an error in the begin transaction.
  • SetThinkTimeAdjustment Function
    Adjusts think times for each user type, which enables you to adjust the throughput requirements of the load test you are planning.
  • GetThinkTimeAdjustment Function
    Returns the state of the current think time adjustment.
  • GetThinkTimeRandomization Function
    Returns the state of randomization for the think time periods specified in functions.
  • SetThinkTimeRandomization Function
    Allows for the changing of think time randomization for various functions.
Parent topic: General Functions


GetCallEndTransaction Function

Action

Gets the value of the setting that specifies whether the final transaction (end transaction) is to be processed when the load test is stopped.

Include file

Kernel.bdh

Syntax

GetCallEndTransaction( ): boolean;

Return value

  • true if the final transaction is to be processed when the load test is stopped

  • false otherwise

Example

dcltrans
  transaction TMain
begin
  if GetCallEndTransaction() then
    writeln("This virtual user will execute the final "
            "transaction when the simulation is aborted.")
  else
    writeln("This virtual user does not execute the "
    "final transaction when the simulation is stopped.")
  end
end TMain;
Parent topic: Simulation Setting Functions
Related reference
SetCallEndTransaction Function
SetCompleteTransaction Function
GetCompleteTransaction Function


GetCancelAfterSimTime Function

Action

Retrieves the current setting for whether to abort the simulation when the simulation time exceeds. This setting only affects load tests with a steady-state workload.

Include file

Kernel.bdh

Syntax

GetCancelAfterSimTime(): boolean;

Return value

  • true if the simulation will be aborted when the simulation time exceeds

  • false otherwise

Example

dcltrans
transaction TMain
begin
if GetCancelAfterSimTime() then
write("simulation will be canceled "
"when simulation time exceeds")
else
write("simulation will be running until all "
"transaction have been executed");
end;
end TMain;
Parent topic: Simulation Setting Functions
Related reference
SetCancelAfterSimTime Function


GetCompleteTransaction Function

Action

Gets the value of the setting that specifies whether the active transaction and the final transaction are to be processed when the load-test is stopped.

Include file

Kernel.bdh

Syntax

GetCompleteTransaction(): boolean;

Return value

  • true if the active transaction and the final transaction are to be processed when the load-test is stopped

  • false otherwise

Example

dcltrans
transaction TMain
begin
if GetCompleteTransaction() then
writeln("This virtual user completes the current "
"transaction when the simulation is aborted.")
else
writeln("This virtual user does not complete the "
"current transaction when the simulation is aborted.")
end
end TMain;
Parent topic: Simulation Setting Functions
Related reference
GetCallEndTransaction Function
SetCallEndTransaction Function
SetCompleteTransaction Function


GetPacingTime Function

Action

Gets the pacing time.

Include file

Kernel.bdh

Syntax

GetPacingTime( out ePacingMode  : number,
               out ePacingScope : number optional,
               out fTimeMinSecs : double optional,
               out fTimeMaxSecs : double optional ): boolean;
Parameter | Description
ePacingMode
  • OPT_PACING_MODE_OFF (0)
  • OPT_PACING_MODE_PACINGTIME (1)
  • OPT_PACING_MODE_TOTALTIME (2)
ePacingScope
  • OPT_PACING_SCOPE_TRANSACTION (1)
  • OPT_PACING_SCOPE_SESSION (2)
fTimeMinSecs | The minimum value of the pacing time in seconds
fTimeMaxSecs | The maximum value of the pacing time in seconds

Return value

  • true if successful

  • false otherwise

Example

benchmark BenchmarkName

use "kernel.bdh"

dcluser
  user
    VUGroup
  transactions
    TmyTrans1       : 1;

dcltrans
  transaction TmyTrans1
  var
    nPacingMode : number;
    nPacingScope : number;
    fTimeMin : float;
    fTimeMax : float;
  begin
    // wait a random time between 5 to 10 seconds after each transaction
    SetPacingTime(OPT_PACING_MODE_PACINGTIME, OPT_PACING_SCOPE_TRANSACTION, 5.0, 10.0);

    // receive Pacing information
    GetPacingTime(nPacingMode, nPacingScope, fTimeMin, fTimeMax);
    Print("Pacing Mode: " + string(nPacingMode) + ", " +
          "Pacing Scope: " + string(nPacingScope) + ", " +
          "Time Min: " + string(fTimeMin) + ", " +
          "Time Max: " + string(fTimeMax));

  end TmyTrans1;
Parent topic: Simulation Setting Functions
Related concepts
Pacing
Related reference
SetPacingTime Function


GetStressTest Function

Action

Gets the current value of the stress test switch.

Include file

Kernel.bdh

Syntax

GetStressTest(): boolean;

Return value

  • true if stress test is set

  • false otherwise

Example

dcltrans
  transaction TInit
  begin
    write("StressTest: ");

    if GetStressTest() then
      write("true")
    else
      write("false")
    end;

    writeln;
  end TInit;
Parent topic: Simulation Setting Functions
Related reference
SetStressTest Function
ThinkTime Function


GetThinkTimeLimit Function

Action

Gets the value of the setting which specifies whether think times should be limited to a certain maximum value. If a think time is specified, which is longer than the specified think time limit, the limit duration is taken instead.

Include file

Kernel.bdh

Syntax

GetThinkTimeLimit( out fLimit : float optional ): boolean;

Return value

  • true if a think time limit is set for the virtual user

  • false otherwise

Parameter | Description
fLimit | Think time limit in seconds, which is never exceeded, if the function returns true (optional).

Example

dcltrans
  transaction TMain
  var
    fLimit : float;
  begin
    SetThinkTimeLimit(true, 2.0);

    if GetThinkTimeLimit(fLimit) then
      writeln("Think times are limited to " + string(fLimit) +
                 "seconds.")
    else
      writeln("No think time limit is set for the current"
                "virtual user.");
    end
  end TMain;
Parent topic: Simulation Setting Functions
Related reference
SetThinkTimeLimit Function
ThinkTime Function


SetCallEndTransaction Function

Action

Specifies whether the final transaction (end transaction) is to be processed when the load test is stopped.

If you enable this option, the stopped virtual user checks whether an end transaction exists, and if so, executes it. If you disable this option, the stopped virtual user does not execute the end transaction.

Include file

Kernel.bdh

Syntax

SetCallEndTransaction( in bEnable : boolean );
Parameter | Description
bEnable | If this parameter is set to true, the final transaction is processed after a virtual user has been stopped. Otherwise, if this parameter is set to false, the final transaction is omitted.

Example

dcltrans
  transaction TInit
  begin
    SetCallEndTransaction(true);
  end TInit;
Parent topic: Simulation Setting Functions
Related reference
GetCallEndTransaction Function
SetCompleteTransaction Function
GetCompleteTransaction Function


SetCancelAfterSimTime Function

Action

Specifies whether to abort the simulation when the simulation time exceeds. This setting only affects load tests with a steady-state workload. The ending transaction will be processed in any case.

Include file

Kernel.bdh

Syntax

SetCancelAfterSimTime( in bCancel : boolean );
Parameter | Description
bCancel | Specifies whether to abort the simulation when the simulation time exceeds.

Example

dcltrans
  transaction TInit
  begin
    SetCancelAfterSimTime(true);
  end TInit;
Parent topic: Simulation Setting Functions
Related reference
GetCancelAfterSimTime Function


SetCompleteTransaction Function

Action

Specifies whether the active transaction is to be processed when the load test is stopped.

If you enable this option, the virtual user checks whether to stop only at the beginning of a new transaction. Thus the active transactions is completed before the user is stopped. If you disable this option, the virtual user checks whether to stop during thinking and waiting times, times in the waiting queue, and at the beginning of each transaction.

Include file

Kernel.bdh

Syntax

SetCompleteTransaction( in bComplete : boolean );
Parameter | Description
bComplete | If this parameter is set to true, the active and the final transaction are processed. Otherwise, if this parameter is set to false, the active transaction is aborted and the final transaction is omitted.

Example

dcltrans
  transaction TInit
  begin
    SetCompleteTransaction(true);
  end TInit;
Parent topic: Simulation Setting Functions
Related reference
GetCallEndTransaction Function
SetCallEndTransaction Function
GetCompleteTransaction Function


SetPacingTime Function

Action

Sets the pacing time.

Include file

Kernel.bdh

Syntax

SetPacingTime( in ePacingMode  : number,
               in ePacingScope : number optional,
               in fTimeMinSecs : double optional,
               in fTimeMaxSecs : double optional ): boolean;
Parameter | Description
ePacingMode
  • OPT_PACING_MODE_OFF (0)
  • OPT_PACING_MODE_PACINGTIME (1)
  • OPT_PACING_MODE_TOTALTIME (2)
ePacingScope
  • OPT_PACING_SCOPE_TRANSACTION (1)
  • OPT_PACING_SCOPE_SESSION (2)
fTimeMinSecs | The minimum value of the pacing time in seconds
fTimeMaxSecs | The maximum value of the pacing time in seconds

Return value

  • true if successful

  • false otherwise

Example

benchmark BenchmarkName

use "kernel.bdh"

dcluser
  user
    VUGroup
  transactions
    TmyTrans1       : 1;

dcltrans
  transaction TmyTrans1
  var
    nPacingMode : number;
    nPacingScope : number;
    fTimeMin : float;
    fTimeMax : float;
  begin
    // wait a random time between 5 to 10 seconds after each transaction
    SetPacingTime(OPT_PACING_MODE_PACINGTIME, OPT_PACING_SCOPE_TRANSACTION, 5.0, 10.0);

    // receive Pacing information
    GetPacingTime(nPacingMode, nPacingScope, fTimeMin, fTimeMax);
    Print("Pacing Mode: " + string(nPacingMode) + ", " +
          "Pacing Scope: " + string(nPacingScope) + ", " +
          "Time Min: " + string(fTimeMin) + ", " +
          "Time Max: " + string(fTimeMax));

  end TmyTrans1;
Parent topic: Simulation Setting Functions
Related concepts
Pacing
Related reference
GetPacingTime Function


SetStressTest Function

Action

Specifies whether or not Silk Performer should ignore the thinking periods specified with the ThinkTime function and several low-level web functions.

Note: This function overrides the setting specified in the Simulation tab of the Profile Settings - Simulation dialog.

Include file

Kernel.bdh

Syntax

SetStressTest(in bST: boolean): boolean;

Return value

  • true if successful

  • false otherwise

Parameter | Description
bST | If this parameter is set to true, Silk Performer ignores the thinking period

Example

dcltrans
  transaction TInit
  begin
    SetStressTest(true); // In this case, Silk Performer
    ThinkTime(5.0); // ignores the thinking period
  end TInit;

Sample scripts

Measure01.bdf, Measure02.bdf, Measure03.bdf

Parent topic: Simulation Setting Functions
Related reference
GetStressTest Function
ThinkTime Function
SetRandomThinkTime Function


SetThinkTimeLimit Function

Action

Specifies whether think times should be limited to a certain maximum value. If a think time is specified, which is longer than the specified think time limit, the limit duration is taken instead.

Include file

Kernel.bdh

Syntax

SetThinkTimeLimit( in bEnable: boolean,
                   in fLimit : float optional);
Parameter | Description
bEnable | Specifies whether a think time limit should be activated.
fLimit | Think time limit in seconds, which is never exceeded, if bEnable is true (optional).

Example

dcltrans
  transaction TMain
  var
    fLimit : float;
  begin
    SetThinkTimeLimit(true, 2.0);

    if GetThinkTimeLimit(fLimit) then
      writeln("Think times are limited to " + string(fLimit) +
              "seconds.");
    else
      writeln("No think time limit is set for the current"
              "virtual user.");
    end
  end TMain;
Parent topic: Simulation Setting Functions
Related reference
GetThinkTimeLimit Function
ThinkTime Function


SetCancelOnErrorInBeginTransaction Function

Action

Specifies whether the runtime should be halted in case of an error in the begin transaction.

If you enable this option, the runtime will be halted in case of an error. Otherwise it will continue running the script.

Include file

Kernel.bdh

Syntax

SetCancelOnErrorInBeginTransaction( in bCancel : boolean );
Parameter | Description
bCancel | If this parameter is set to true, the runtime will be halted in case of an error in the begin transaction. Otherwise, the runtime will continue running the script.

Example

dcltrans
  transaction TInit
  begin
    SetCancelOnErrorInBeginTransaction(true);
    RepMessage("Custom Error", SEVERITY_ERROR);
  end TInit;
Parent topic: Simulation Setting Functions
Related reference
GetCancelOnErrorInBeginTransaction Function
GetCallEndTransaction Function
SetCompleteTransaction Function
GetCompleteTransaction Function


GetCancelOnErrorInBeginTransaction Function

Action

Gets the value of the setting that specifies whether the runtime should be halted in case of an error in the begin transaction.

Include file

Kernel.bdh

Syntax

GetCancelOnErrorInBeginTransaction( ): boolean;

Return value

  • true if the runtime should be halted in case of an error in the begin transaction

  • false otherwise

Example

dcltrans
  transaction TInit
  begin
    if GetCancelOnErrorInBeginTransaction()then
      writeln("This virtual user will be halted once the error has"
              "risen.")
    end;
    RepMessage("Custom Error", SEVERITY_ERROR);
  end TInit;
Parent topic: Simulation Setting Functions
Related reference
SetCancelOnErrorInBeginTransaction Function
SetCallEndTransaction Function
GetCompleteTransaction Function


SetThinkTimeAdjustment Function

Action

Silk Performer allows you to adjust think times for each user type. With think time adjustment, a user type’s session time can easily be adjusted to the throughput requirements of the test you are planning.

With this function it is possible to change and disable think time adjustment during a test.

Note: This function only has an effect if the virtual user script contains ThinkTime() function calls.

Include file

Kernel.bdh

Syntax

SetThinkTimeAdjustment( in eOption          : number ,
                        in fThinkTimeFactor : float optional,
                        in fSessionTime     : float optional );
Parameter | Description
eOption

Can be either:

  • OPT_TTA_NONE : Disables think time adjustment.

  • OPT_TTA_STRESSTEST : Think times are ignored.

  • OPT_TTA_STATIC : Think times are multiplied by a static factor to adjust session time. The parameter fThinkTimeFactor must be specified.

  • OPT_TTA_DYNAMIC : Dynamic think time adaptation is used to keep throughput rates constant at varying load levels. Both the fThinktimeFactor and fSessionTime parameters must be specified.

fThinkTimeFactor | Think times are multiplied by this static factor to adjust session time.
fSessionTime | The session time to reach when using dynamic think-time adjustment.

Example

use "kernel.bdh"
var
  nTrans : number init 0;

dcluser
  user
    WebUser
  transactions
    TWeb        : 1;

dcltrans
  transaction TWeb
  var
    nTTA : number;
  begin
    nTrans := nTrans + 1;
    ThinkTime(3.0);

    if nTrans = 5 then
      SetThinktimeAdjustment(OPT_TTA_DYNAMIC, 3.0, 9.0);
    end;

    if nTrans = 9 then
      SetThinktimeAdjustment(OPT_TTA_NONE);
    end;

    nTTA := GetThinkTimeAdjustment();
    write("thinktime adjustment: ");
    if nTTA = OPT_TTA_NONE then
      write("disabled");
    elseif nTTA = OPT_TTA_STRESSTEST then
      write("stresstest");
    elseif nTTA = OPT_TTA_STATIC then
      write("static");
    elseif nTTA = OPT_TTA_DYNAMIC then
      write("dynamic");
    end;
end TWeb;
Parent topic: Simulation Setting Functions
Related reference
GetThinkTimeAdjustment Function


GetThinkTimeAdjustment Function

Action

Silk Performer allows you to adjust think times for each user type. With think time adjustment, a user type’s session time can easily be adjusted to your throughput requirements.

Returns the state of the current think time adjustment.

Include file

Kernel.bdh

Syntax

GetThinkTimeAdjustment( out fThinkTimeFactor : float optional,
                        out fSessionTime     : float optional ) number;

Return value

Can be either:

  • OPT_TTA_NONE : Adjustment of think times is disabled.

  • OPT_TTA_STRESSTEST : Think times are ignored.

  • OPT_TTA_STATIC : Think times are multiplied by a static factor to adjust session time. The parameter fThinkTimeFactor is set.

  • OPT_TTA_DYNAMIC : Dynamic think time adaptation is used to keep throughput rates constant.

Parameter | Description
fThinkTimeFactor | Think times are multiplied by this static factor to adjust session time.
fSessionTime | The session time to reach when dynamic think time adjustment is used.

Example

use "kernel.bdh"
var
  nTrans : number init 0;

dcluser
  user
    WebUser
  transactions
    TWeb        : 1;

dcltrans
  transaction TWeb
  var
    nTTA : number;
  begin
    nTrans := nTrans + 1;
    ThinkTime(3.0);

    if nTrans = 5 then
      SetThinktimeAdjustment(OPT_TTA_DYNAMIC, 3.0, 9.0);
    end;

    if nTrans = 9 then
      SetThinktimeAdjustment(OPT_TTA_NONE);
    end;

    nTTA := GetThinkTimeAdjustment();
    write("thinktime adjustment: ");
    if nTTA = OPT_TTA_NONE then
      write("disabled");
    elseif nTTA = OPT_TTA_STRESSTEST then
      write("stresstest");
    elseif nTTA = OPT_TTA_STATIC then
      write("static");
    elseif nTTA = OPT_TTA_DYNAMIC then
      write("dynamic");
    end;
  end TWeb;
Parent topic: Simulation Setting Functions
Related reference
SetThinkTimeAdjustment Function
ThinkTime Function


GetThinkTimeRandomization Function

Action

Returns the state of randomization for the think time periods specified in functions.

Include file

Kernel.bdh

Syntax

GetThinkTimeRandomization( out nDeviation : number optional ) : number;

Return value

Can be either:

  • OPT_TTR_EXACT: Specified think time periods are used as-is. However if think time adjustment is enabled, think time values can be adjusted as required.

  • OPT_TTR_FORCEEXACT: Specified think time periods are used without further adjustment.

  • OPT_TTR_EXPONENTIAL: Specified think time periods are randomized following an exponential distribution.

  • OPT_TTR_UNIFORM: Specified think time periods are randomized following a uniform distribution. The deviation factor nDeviation is also set.

Parameter | Description
nDeviation | The deviation factor used if OPT_TTR_UNIFORM is set. Must be a value between 1 and 100 (%).

Example

dcltrans
  transaction TMain
  var
    nTTR, nDev : number;
  begin
    nTTR := GetThinkTimeRandomization(nDev);
    if nTTR = OPT_TTR_EXACT then
      write("exact");
    elseif nTTR = OPT_TTR_FORCEEXACT then
      write("forceexact");
    elseif nTTR = OPT_THINKTIME_EXPONENTIAL then
      write("exponential");
    elseif nTTR = OPT_TTR_UNIFORM  then
      write("uniform: ");
      write(string(nDev));
      write("%");
    else
      write("not possible");
    end;
  end TMain;
Parent topic: Simulation Setting Functions
Related reference
SetThinkTimeRandomization Function
SetThinkTimeAdjustment Function
ThinkTime Function
RndSeed Function


SetThinkTimeRandomization Function

Action

Allows for the changing of think time randomization for various functions.

Note: This function overrides the setting on the Simulation tab of the Profile Settings - Simulation dialog.

Include file

Kernel.bdh

Syntax

SetThinkTimeRandomization( in eOption    : number,
                           in nDeviation : number optional );
Parameter | Description
eOption

Can be either:

  • OPT_TTR_EXACT: Specified think time periods are used as-is. However if think time adjustment is enabled, think time values can be adjusted as required.

  • OPT_TTR_FORCEEXACT: Specified think time periods are used without further adjustment.

  • OPT_TTR_EXPONENTIAL: Specified think time periods are randomized following an exponential distribution.

  • OPT_TTR_UNIFORM: Specified think time periods are randomized following a uniform distribution. A deviation factor must be specified with this option (parameter nDeviation).
nDeviation | The deviation factor used when OPT_TTR_UNIFORM is set. Must be a value between 1 and 100 (%).

Example

dcltrans
  transaction TMain
  begin
    SetThinkTimeRandomization (OPT_TTR_UNIFORM, 20 /* % */);
    WebUrl("http://standardhost/index.html", 2.1);
    // 2.1 is the mean value of the
    // uniform distributed thinking period
  end TMain;
Parent topic: Simulation Setting Functions
Related reference
GetThinkTimeRandomization Function
ThinkTime Function
RndSeed Function


String Functions

In BDL, strings represent a sequence of characters, and are chiefly of fixed length. The length of a string is controlled by using a null character to mark the end of the string. Strings are passed to functions by using a pointer to the first character.

Note: The index of the first character belonging to a string is one (1), not (0).
  • BinSearch Function
    Searches binary data for either a string or a specified amount of binary data.
  • Bin2Hex Function
    Converts an ASCII representation of binary data into the hexadecimal representation.
  • BinAdd Function
    Appends a string or binary data to other binary data.
  • Binlen Function
    Returns a string's data length.
  • BinSetlen Function
    Sets the actual data length of a string.
  • CallConversionFunction Function
    Converts a value by using the conversion function in a custom DLL.
  • Decrypt Function
    Decrypts a string that has been encrypted using the Encrypt function.
  • Decrypt3DES Function
    Decrypts a string that has been encrypted using the Encrypt3DES function.
  • Encrypt Function
    Encrypts string or binary data into a printable format using RSA’s RC4 cipher.
  • Encrypt3DES Function
    Encrypts string or binary data into a printable format using the Triple Data Encryption Algorithm (Triple DES) block cipher.
  • FromEncoding Function
    Converts a string, from the codepage that has been set by SetEncoding, to the ANSI string that is printable within the Silk Performer GUI.
  • FromUnicode Function
    Converts all unicode escape sequences of type \uxxxx from string into corresponding characters.
  • FromUTF8 Function
    Converts a UTF8-encoded byte sequence into an ANSI string representation.
  • FStrReplace Function
    Replaces all occurrences of a search string by a replace string in a source string.
  • GetEncoding Function
    Gets the name of the codepage that has been set.
  • HashSHA2 Function
    Converts the input string into SHA2 encryption.
  • StrAnsi2Unicode Function
    Converts a string from single-byte representation to unicode representation.
  • StrUnicode2Ansi Function
    Converts a string from unicode representation to single-byte representation.
  • StrUnicodeLen Function
    Determines the number of characters a string in unicode format consists of.
  • StrAdd Function
    Appends a string or binary data to another string.
  • Strcat Function
    Appends a string to another string.
  • Strchr Function
    Searches for the first occurrence of a character in a string.
  • Strcpy Function
    Copies a string into another string.
  • Strcspn Function
    Searches a string for a character belonging to a defined set of characters.
  • Stricmp Function
    Performs a lowercase comparison of strings.
  • Strlen Function
    Retrieves the length of a string.
  • StrSize Function
    Returns the size of a string's currently allocated memory buffer.
  • StrResize Function
    Resizes a string's memory buffer.
  • Strlwr Function
    Converts a string to lowercase
  • StrlwrEx Function
    Converts a string to lowercase format (and umlautes, if required).
  • Strncmp Function
    Compares lexicographically and case-sensitively the first count characters in two strings.
  • Strncpy Function
    Copies the initial characters of a string to another string.
  • Strnicmp Function
    Compares lexicographically the first characters of two strings.
  • Strnset Function
    Overwrites the beginning of a string with a number of characters.
  • Strpbrk Function
    Searches a string for the first occurrence of any one character out of a defined set.
  • Strrchr Function
    Searches a string for the last occurrence of a character.
  • Strrev Function
    Reverses the order of characters of a string.
  • StrSearch Function
    Searches a string for a substring.
  • StrSearchDelimited Function
    Searches for a string delimited on both sides by a specified character sequence.
  • Strset Function
    Replaces all characters of a string with a specified character.
  • Strspn Function
    Searches a string for the first character that does not belong to the set of characters.
  • Strstr Function
    Searches a string for a substring.
  • Strtok Function
    Finds the next token in a string.
  • Strupr Function
    Converts a string to uppercase.
  • StruprEx Function
    Converts a string to uppercase format (and umlautes if required).
  • Substr Function
    Extracts a substring out of a string.
  • StrIsNull Function
    Checks whether a string is null.
  • StrSetNull Function
    Sets a string to null explicitly.
  • StrIsEmpty Function
    Checks whether a string is empty or null.
  • StrFromHostCP Function
    Converts a targeted host-character-set string that uses a specified code page into an ANSI string.
  • StrGetHostCP Function
    Returns the default host code page used for string conversions.
  • StrSetHostCP Function
    Sets the default host code page used for string conversions.
  • StrToHostCP Function
    Converts an ANSI string representation into a targeted host-character-set string using the specified code page.
  • SetEncoding Function
    Sets a codepage, which is used by the functions FromEncoding and ToEncoding, to convert the given strings.
  • ToEncoding Function
    Converts the given ANSI string into the string of the codepage that has been selected by the SetEncoding function.
  • ToUnicode Function
    Converts ANSI string representation into a unicode escape sequence of type \uxxxx.
  • ToUTF8 Function
    Converts an ANSI string representation into a UTF8-encoded byte sequence.
Parent topic: General Functions


BinSearch Function

Action

Searches binary data for either a string or a specified amount of binary data.

Include file

Kernel.bdh

Syntax

BinSearch( in sSource     : string,
           in nSourceSize : number,
           in sSearch     : string,
           in nSearchSize : number optional,
           in nOptions    : number optional,
           in nAlign      : number optional ): number;

Return value

Position index where the data to search for was found, or zero if the substring was not found or an error occurred. Note that the index of the first byte is one (1), not zero (0).

Parameter | Description
sSource | Binary data to search
nSourceSize | Size of binary data to search
sSearch | String or binary data to look for
nSearchSize | Size of the binary data to look for (optional). When searching binary data for a string, this parameter can be omitted
nOptions

Specifies how to search the specified binary data (optional). By passing one of the following parameters to the function, it is possible to determine whether to start a new search or to continue searching

  • STR_SEARCH_FIRST. Search for the first occurrence (default)

  • STR_SEARCH_NEXT. Continue a search started before

In addition, you can determine to search binary data for a string case-sensitively by passing the STR_SEARCH_MATCH_CASE flag to the function:

Passing the STR_SEARCH_REVERSE flag to the function specifies to search the binary data in reverse order.
nAlign | Search alignment (default). If an alignment is specified, the function checks both if the data is found, and, if so, whether it is aligned to a multiple of the specified value

Example

dcltrans
  transaction TBinSearch
  var
    nPos, nDir: number;
  begin
    nPos := BinSearch("DECDEFG", 0, "DE");
    write(nPos); writeln;

    nPos := BinSearch("\h00010203040506", 7,"\h030405", 3);
    write(nPos); writeln;

    nDir := STR_SEARCH_FIRST;
    loop
      nPos := BinSearch("\h01000001000001", 7, "\h01", 1, nDir);
      if nPos = 0 then exit end;
      write(nPos); writeln;
      nDir := STR_SEARCH_NEXT;
    end;
  end TBinSearch;
Parent topic: String Functions


Bin2Hex Function

Action

Converts an ASCII representation of binary data into the hexadecimal representation.

Include file

Kernel.bdh

Syntax

Bin2Hex( in  sBinData : string,
         in  nBinLen  : number,
         out sHexData : string,
         in  nHexLen  : number optional ): boolean;

Return value

  • true if successful

  • false otherwise

Parameter | Description
sBinData | String buffer containing the binary data to convert to hexadecimal notation
nBinLen | Number of bytes to be converted
sHexData | String receiving the hexadecimal representation of the binary data
nHexLen | Maximum length of the string receiving the hexadecimal representation of the binary data. You have to specify at least 2*nBinLen+1 bytes to be able to convert all binary data to the hexadecimal representation. (optional) If the specified buffer is too small, the result will be truncated. In any case, the result will be NULL-terminated.

Example

transaction TMain
  var
    sString1, sString2: string;
  begin
    sString1 := "Test String";
    Bin2Hex(sString1, STRING_COMPLETE, sString2);
    writeln("Bin2Hex of <" + sString1 + "> is <" + sString2 + ">");
  end TMain;

Output

Bin2Hex of <Test String> is <5465737420537472696E67>
Parent topic: String Functions


BinAdd Function

Action

Appends a string or binary data to other binary data.

Include file

Kernel.bdh

Syntax

BinAdd( inout sString : string,
        in    sAppend : string,
        in    nCount  : number optional );
Parameter | Description
sString | Source string. This parameter will contain the concatenated data after the BinAdd operation. The provided data (sAppend) will be appended at the end of the specified data sequence (sSstring).
sAppend | String or binary data to append.
nCount | Number of bytes to append (optional). Omit this parameter to append all available data.

Example

dcltrans
transaction TWeb
  var
    sData : string;
  begin

    sData := "Hugo";
    BinAdd(sData, "\h00");
    BinAdd(sData, "John");
    BinAdd(sData, "\h00");
    writedata(bin(sData));
    writedata(sData);
    StrAdd(sData, "_Smith");
    writedata(bin(sData));

  end TWeb;

Output

00000000  Hugo·John·        48 75 67 6F 00 4A 6F 68 6E 00
Hugo
Hugo_Smith
Parent topic: String Functions
Related reference
StrAdd Function


Binlen Function

Action

Returns a string's data length. In contrast to the Strlen function Binlen does not return the string length, which is the number of characters until the first '\0' character, but returns the real data length stored in the string.

Include file

Kernel.bdh

Syntax

Binlen( in sString : string allownull ) : number;

Return value

  • the actual data length the string is currently holding

Parameter | Description
sString | String whose data length is returned.

Example

dcltrans
  transaction TMain
  var
    sString : string;
  begin
    sString := "String";

        Print("Strlen = " + string(Strlen(sString)));
    Print("Binlen = " + string(Binlen(sString)));
    sString := sString + "\h001122334455";

        Print("Strlen = " + string(Strlen(sString)));
    Print("Binlen = " + string(Binlen(sString)));
  end TMain;

Output

Strlen = 6
Binlen = 6
Strlen = 6
Binlen = 12
Parent topic: String Functions
Related reference
BinSetlen Function
Strlen Function
StrResize Function
StrSize Function


BinSetlen Function

Action

Sets the actual data length of a string. The specified length must be within the range of 0 and StrSize().

Note: Under normal circumstances the data length of a string variable is always set correctly by the runtime. However, some external functions might require manual interference in order to have the data length set correctly. This function can also be used for stripping a string to the specified length.

Include file

Kernel.bdh

Syntax

BinSetlen( in sString : string,
           in nNewLen : number ) : boolean;

Return value

  • true if the new data length could be set successfully

  • false otherwise

Parameter | Description
sString | String whose data length is set.
nNewLen | Data length the string should be set to.

Example

dcltrans
  transaction TMain
  var
    sString : string;
  begin
    sString := "Hello world";
    BinSetlen(sString, 5);

Print(sString);
    Print("Strlen = " + string(Strlen(sString)));
    Print("Binlen = " + string(Binlen(sString)));
  end TMain;

Output

HelloStrlen = 5Binlen = 5
Parent topic: String Functions
Related reference
Binlen Function
Strlen Function
StrResize Function
StrSize Function


CallConversionFunction Function

Action

Converts the value sValueToConvert by using the conversion function sConversionFunction in the DLL sConversionDll. Usually this function is used by recording rules.

Include file

Kernel.bdh

Syntax

function CallConversionFunction(
  sConversionDll : in string,
  sConversionFunction : in string,
  sValueToConvert : inout dstring explicit) : string;

Return value

The converted value. If conversion failed, then the original value is returned.

Parameter | Description
sConversionDll | The name of the conversion DLL. This is the filename without the full path. The DLL is searched for in the recording rules directory and the current project directory.
sConversionFunction | The function is called to convert the value and is exported by the conversion DLL.
sValueToConvert | A variable which contains the value is converted. The conversion is done in place so the value of the variable passed is changed.

Example

dclfunc
 function ConvertToUpperCase(sValueToConvert : string) : string <API_FUNCTION>
 var
 begin
  ConvertToUpperCase := CallConversionFunction("SampleConversion.dll", "ConvertToUpperCase", sValueToConvert);
 end ConvertToUpperCase;

dcltrans
 transaction TMain
 begin
  WebSetBrowser(WEB_BROWSER_MSIE8);
  WebSetUserBehavior(WEB_USERBEHAVIOR_FIRST_TIME);
 end TMain:

Sample script

CConversionRecRule.bdf

SilkEssential sample

CConversionRecRule.sep

Parent topic: String Functions


Decrypt Function

Action

Decrypts a string that has been encrypted using the Encrypt function.

Note: The Decrypt3DES function uses a higher security algorithm than this function and should be used in newly generated scripts to be FIPS compliant.

Include file

kernel.bdh

Syntax

Decrypt( in sEncyptedData : string,
         in sKey          : string optional ): string;

Return value

  • decrypted string

Parameter | Description
sEncyptedData | Data to be decrypted
sKey | String or binary data used as encryption key (optional).

Example

dcltrans
  transaction TMain
  var
    sUserPass  : string;
    sEncrypted : string;
  begin    // Build your own authentication header
    AttributeGetString("Password", sUserPass);
    sEncrypted := Encrypt(sUserPass);
    Print(sEncrypted);
    sUserPass := Decrypt(sEncrypted);
    Print("decrypted password: " + sUserPass);
  end TMain;
Parent topic: String Functions
Related reference
Encrypt Function
Decrypt3DES Function


Decrypt3DES Function

Action

Decrypts a string that has been encrypted using the Encrypt3DES function.

Include file

kernel.bdh

Syntax

Decrypt3DES( in sEncryptedData : string,
             in sKey1 : string optional,
             in sKey2 : string optional,
             in sKey3 : string optional ): string;

Return value

  • decrypted string

Parameter | Description
sEncryptedData | Data to be decrypted.
sKey1 | String or binary data used as first encryption key (optional).
sKey2 | String or binary data used as second encryption key (optional).
sKey3 | String or binary data used as third encryption key (optional).

Example

dcltrans
  transaction TMain
  var
    sUserPass  : string;
    sEncrypted : string;
  begin
    // Build your own authentication header
    AttributeGetString("Password", sUserPass);
    sEncrypted := Encrypt3DES(sUserPass);
    Print(sEncrypted);
    sUserPass := Decrypt3DES(sEncrypted);
    Print("decrypted password: " + sUserPass);
  end TMain;
Parent topic: String Functions
Related reference
Encrypt3DES Function
Decrypt Function


Encrypt Function

Action

Encrypts string or binary data into a printable format using RSA’s RC4 cipher. This function is useful for encrypting passwords and other sensitive data.

Note: The Encrypt3DES function uses a higher security algorithm than this function and should be used in newly generated scripts to be FIPS compliant.

Include file

kernel.bdh

Syntax

Encrypt( in sData : string,
         in sKey  : string optional ): string;

Return value

  • encrypted string

Parameter | Description
sData | String or binary data to be encrypted
sKey | String or binary data used as encryption key (optional).
Note: The returned string is about 30% larger in size than the original data

Example

dcltrans
  transaction TMain
  var
    sUserPass  : string;
    sEncrypted : string;
  begin
    // Build your own authentication header
    AttributeGetString("Password", sUserPass);
    sEncrypted := Encrypt(sUserPass);
    Print(sEncrypted);
    sUserPass := Decrypt(sEncrypted);
    Print("decrypted password: " + sUserPass);
  end TMain;
Parent topic: String Functions
Related reference
Decrypt Function
Encrypt3DES Function


Encrypt3DES Function

Action

Encrypts string or binary data into a printable format using the Triple Data Encryption Algorithm (Triple DES) block cipher. This function is useful for encrypting passwords and other sensitive data.

Include file

kernel.bdh

Syntax

Encrypt3DES( in sData : string,
             in sKey1 : string optional,
             in sKey2 : string optional,
             in sKey3 : string optional ): string;

Return value

  • encrypted string

Parameter | Description
sData | String or binary data to be encrypted
sKey1 | String or binary data used as first encryption key (optional).
sKey2 | String or binary data used as second encryption key (optional).
sKey3 | String or binary data used as third encryption key (optional).
Note: The returned string is about 30% larger in size than the original data.

Example

dcltrans
  transaction TMain
  var
    sUserPass  : string;
    sEncrypted : string;
  begin
    // Build your own authentication header
    AttributeGetString("Password", sUserPass);
    sEncrypted := Encrypt3DES(sUserPass);
    Print(sEncrypted);
    sUserPass := Decrypt3DES(sEncrypted);
    Print("decrypted password: " + sUserPass);
  end TMain;
Parent topic: String Functions
Related reference
Decrypt3DES Function
Encrypt Function


FromEncoding Function

Action

Converts a string, from the codepage that has been set by SetEncoding, to the ANSI string that is printable within the Silk Performer GUI.

Include file

Kernel.bdh

Syntax

FromEncoding( in sSource : string ) : string;

Return value

  • Converted string

Parameter | Description
sSource | Source string to be converted.

Example

dcltrans
  transaction TMain
  var
    sResult : string;
  begin
    SetEncoding("UTF-8");
    WebPageUrl("http://testsite.company.com.cn");
    WebParseHtmlBound(sResult, STRING_COMPLETE, "Home", "Street");
    WebPageLink(ToEncoding("??"), "?? - Company  ??");
    writeln(FromEncoding(sResult));
  end TMain;
Parent topic: String Functions
Related reference
ToEncoding Function
SetEncoding Function
GetEncoding Function


FromUnicode Function

Action

Converts all unicode escape sequences of type \uxxxx from string into corresponding characters.

Include file

Kernel.bdh

Syntax

FromUnicode( in sSource : string ): string;

Return value

  • converted string
Parameter | Description
sSource | Source string to be converted.

Example

dcltrans
  transaction TMain
  var
    sConverted : string;
  begin

    sConverted := FromUnicode("\u0061\0041\0062\u0042\u0063\u0043");
    Print(sConverted); // "AaBbCc"

  end TMain;
Parent topic: String Functions


FromUTF8 Function

Action

Converts a UTF8-encoded byte sequence into an ANSI string representation.

Include file

Kernel.bdh

Syntax

FromUTF8( in sSource : string ) : string;

Return value

  • Converted string

Parameter | Description
sSource | Source string to be converted.

Example

dcltrans
  transaction TMain

  var
    sResult : string;
  begin
    WebPageUrl("http://testsite.company.com.cn");
    WebParseHtmlBound(sResult, STRING_COMPLETE, "Home", "Street");
    WebPageLink(ToUTF8("ÄÄ/ÜÖÖÜ"), "eBay");
    writeln(FromUTF8(sResult));
  end TMain;

Parent topic: String Functions


FStrReplace Function

Action

Replaces all occurrences of a search string by a replace string, within a source string. This action also modifies the source string.
Note: Do not use this function in a load test, as it can impact the results.

Include file

Kernel.bdh

Syntax

FStrReplace(
   inout sSource        : string,
   in    sSearch        : string,
   in    sReplace       : string,
   in    bMatchCase     : boolean optional,
   in    bWholeWordOnly : boolean optional ) : string;
Parameter | Description
sSource | The source string within which you want to search.
sSearch | The string within sSource that you are searching for.
sReplace | The string that will replace sSearch. Note that sSource also changes, as soon as sSearch is changed.
bMatchCase | 1 to perform a case-sensitive search. If you set this parameter to 0 or omit it, the search will not be case sensitive.
bWholeWordOnly | This option allows the search to be restricted to whole words only. This is useful for searching for ' a ', or 'A' without finding all words including 'a'. Set this parameter to 1 to search for whole words only. If you set this parameter to 0 or omit it, the search will not be restricted to matching whole words only.

Example

dcltrans
  transaction TWeb
  var
    sSource : string;
    sSearch : string;
    sReplace : string;
    sOut : string;
  begin
    sSource := "An ideal pack for long trail trips, its strong heli-arc
welded 6061-T6 aircraft-quality aluminum frame with V-truss design
resists diagonal distortion.";
    sSearch := "ideal pack";
    sReplace := "optimal pack";
    sOut := FStrReplace(sSource, sSearch, sReplace);
    writeln(sOut);
  end TWeb;

Output

An optimal pack for long trail trips, its strong heli-arc
welded 6061-T6 aircraft-quality aluminum frame with V-truss design
resists diagonal distortion.
Parent topic: String Functions


GetEncoding Function

Action

Gets the name of the codepage that has been set.

Include file

Kernel.bdh

Syntax

GetEncoding( ): string;

Return value

  • Name of the codepage that is currently set.

Example

dcltrans
  transaction TMain
  var
    sResult : string;
  begin
    SetEncoding("UTF-8");
    WebPageUrl("http://testsite.company.com.cn");
    WebParseHtmlBound(sResult, STRING_COMPLETE, "Home", "Street");
    WebPageLink(ToEncoding("??"), "?? - Company  ??");
    writeln(FromEncoding(sResult));
    writeln("http://testsite.company.com.cn has the codepage "  + GetEncoding() + " set");
  end TMain;
Parent topic: String Functions
Related reference
FromEncoding Function
ToEncoding Function
SetEncoding Function


HashSHA2 Function

Action

Calculates an SHA2 hash value of an input string. The required SHA2 hash length can be passed as a function argument.

Include file

Kernel.bdh

Syntax

HashSha2( in sBuffer    : string
          in nBufferLen : number optional,
          in eHashType  : number optional ): string;

Return value

Encryption of the input string.

Parameter | Description
sBuffer | The input string to be encrypted.
nBufferLen | The length of the input string. This parameter is optional, but if hashType is specified, then bufferLen must be 0 or the length of the input string.
eHashType
  • HASH_TYPE_SHA_224
  • HASH_TYPE_SHA_256 (default)
  • HASH_TYPE_SHA_384
  • HASH_TYPE_SHA_512
  • HASH_TYPE_SHA_512_224
  • HASH_TYPE_SHA_512_256

Example

dcltrans
  transaction TMain
  const
    input := "Random String";
  var
    sConverted : string;
  begin

    sConverted := HashSHA2(input, Strlen(input), HASH_TYPE_SHA_256);
    Print("sConverted = " + sConverted);

    sConverted := HashSHA2(input, Strlen(input));
    Print("sConverted = " + sConverted);

    sConverted := HashSHA2(input);
    Print("sConverted = " + sConverted);

    sConverted := HashSHA2(input, 0, HASH_TYPE_SHA_224);
    Print("sConverted = " + sConverted);

  end TMain;

Output
    sConverted = d3ffa2bcb37fb6c6a467512c2fa5b67e1a3106896e1592a858841bef06a40b81
    sConverted = d3ffa2bcb37fb6c6a467512c2fa5b67e1a3106896e1592a858841bef06a40b81
    sConverted = d3ffa2bcb37fb6c6a467512c2fa5b67e1a3106896e1592a858841bef06a40b81
    sConverted = 5871b7141b5b9e3c2d9f5b3f87f078d951969d52e8109126a6cc0701
Parent topic: String Functions


StrAnsi2Unicode Function

Action

Converts a string from single-byte representation to unicode representation.

Include file

Kernel.bdh

Syntax

StrAnsi2Unicode( out sUnicode     : string,
                 in  nUnicodeByte : number,
                 in  sAnsi        : string ): boolean;

Return value

  • true if successful

  • false otherwise

Parameter | Description
sUnicode | String receiving the unicode representation.
nUnicodeByte | Number of bytes to be used from sUnicode buffer.
sAnsi | String in single-byte representation that is to be converted.

Example

dcltrans
  transaction TMain
  var
    sAnsi, sUnicode: string;
  begin
    sAnsi := "hello world!";
    StrAnsi2Unicode(sUnicode, STRING_COMPLETE, sAnsi);
    writeln(StrUnicodeLen(sUnicode));
    StrUnicode2Ansi(sAnsi, STRING_COMPLETE, sUnicode);
  end TMain;
Parent topic: String Functions
Related reference
StrUnicode2Ansi Function
StrUnicodeLen Function


StrUnicode2Ansi Function

Action

Converts a string from unicode representation to single byte representation.

Include file

Kernel.bdh

Syntax

StrUnicode2Ansi( out sAnsi      : string,
                 in  nAnsiBytes : number,
                 in  sUnicode   : string,
                 in  nByteOrder : number optional ): boolean;

Return value

  • true if successful

  • false otherwise

Parameter | Description
sAnsi | String receiving the single-byte representation.
nAnsiBytes | Number of bytes to be used in sAnsi.
sUnicode | String in unicode representation that is to be converted.
nByteOrder

Number (optional) which declares if the Unicode is in little endian or in big endian. Possible values are:

  • OPT_LITTLE_ENDIAN. Specifies little endian byte order. (default)

  • OPT_BIG_ENDIAN. Specifies big endian byte order.

Example

dcltrans
  transaction TMain
  var
    sAnsi, sUnicode: string;
  begin
    sAnsi := "hello world!";
    StrAnsi2Unicode(sUnicode, STRING_COMPLETE, sAnsi);
    writeln(StrUnicodeLen(sUnicode));
    StrUnicode2Ansi(sAnsi, STRING_COMPLETE, sUnicode);
  end TMain;
Parent topic: String Functions
Related reference
StrAnsi2Unicode Function
StrUnicodeLen Function


StrUnicodeLen Function

Action

Determines the number of characters a string in unicode format consists of. The terminating NULL is not regarded as a character.

Include file

Kernel.bdh

Syntax

StrUnicodeLen( in sUnicode: string ): number;

Return value

The number of characters the string consists of.

Parameter | Description
sUnicode | String whose length is to be retrieved.

Example

dcltrans
  transaction TMain
  var
    sAnsi, sUnicode: string;
  begin
    sAnsi := "hello world!";

    StrAnsi2Unicode(sUnicode, sizeof(sUnicode), sAnsi);
    writeln(StrUnicodeLen(sUnicode));
    StrUnicode2Ansi(sAnsi, sizeof(sAnsi), sUnicode);
  end TMain;
Parent topic: String Functions
Related reference
StrAnsi2Unicode Function
StrUnicode2Ansi Function


StrAdd Function

Action

Appends a string or binary data to another string.

Include file

Kernel.bdh

Syntax

StrAdd( inout sString : string,
        in    sAppend : string,
        in    nCount  : number optional );
Parameter | Description
sString | Source string. This parameter will contain the concatenated string after the StrAdd operation. The specified data (sAppend) will be appended at the first occurrence of a 0 byte in sString (regardless of possible binary data). If you want to add the data at the end of a binary body use BinAdd instead.
sAppend | String or binary data to append.
nCount | Number of bytes to append (optional). Omit this parameter to append all available data.

Example

dcltrans
transaction TWeb
  var
    sData : string;
  begin

    sData := "Hugo";
    BinAdd(sData, "\h00");
    BinAdd(sData, "John");
    BinAdd(sData, "\h00");
    writedata(bin(sData));
    writedata(sData);
    StrAdd(sData, "_Smith");
    writedata(bin(sData));

end TWeb;

Output

00000000  Hugo·John·        48 75 67 6F 00 4A 6F 68 6E 00
Hugo
Hugo_Smith
Parent topic: String Functions
Related reference
BinAdd Function


Strcat Function

Action

Appends a string sAppend to another string.

Include file

Kernel.bdh

Syntax

Strcat( inout sString : string,
        in    sAppend : string ): string;

Return value

concatenated string

Parameter | Description
sString | Source string. This parameter will contain the concatenated string after the Strcat operation
sAppend | String to append
Note: The use of this function has been expanded. It is possible to pass to the function either a string or a pointer to a buffer (in the latter case the keyword in has to be used).

Example

dcltrans
  transaction TStrcat
  var
    sString1, sString2 : string(100);
    sOutput1, sOutput2 : string(100);
    nBuffer1, nBuffer2 : number;
  begin
    nBuffer1 := Malloc(100); nBuffer2 := Malloc(100);
    sString1 := "Hello "; sString2 := "world!";

    // copy sString1 to output string and append sString2
    Strcpy(sOutput1, sString1); Strcat(sOutput1, sString2);

    // copy strings to buffers and concatenate them
    Strcpy(in nBuffer1, sString1); Strcpy(in nBuffer2, sString2);
    Strcat(in nBuffer1, in nBuffer2);
    Strcpy(sOutput2, in nBuffer1);

    write(sOutput1); writeln;
    write(sOutput2); writeln;
    Free(nBuffer1); Free(nBuffer2);
  end TStrcat;

Output

Hello world!
Hello world!
Parent topic: String Functions


Strchr Function

Action

Searches for the first occurrence of a character in a string.

Include file

Kernel.bdh

Syntax

Strchr( in sString    : string,
        in nCharacter : number ): string;

Return value

String beginning with the first occurrence of the defined character. If the character is not found, the returned string is empty.

Parameter | Description
sString | Defines the string to search in
nCharacter | Defines the character to search

Example

dcltrans
  transaction TStrchr
  var
    sString, sPart : string;
    nChar          : number;
  begin
    sString := "Hello world!";
    nChar := ord('w');
    write("string = "); write(sString); writeln;
    write("char = "); write(chr(nChar)); writeln;

    sPart := Strchr(sString, nChar);
    write("part = "); write(sPart); writeln;
  end TStrchr;

Output

string = Hello world!
char = w
part = world!
Parent topic: String Functions
Related reference
Strrchr Function


Strcpy Function

Action

Copies a string into another string.

Include file

Kernel.bdh

Syntax

Strcpy( inout sDest   : string,
        in    sSource : string ): string;

Return value

The string actually copied.

Parameter | Description
sDest | Destination string
sSource | Source string
Note: The use of this function has been expanded. It is possible to pass to the function either a string or a pointer to a buffer (in the latter case the keyword in has to be used).

Example

dcltrans
  transaction TStrcpy
  var
    sString1, sString2 : string;
    sOutput : string;
    nBuffer1, nBuffer2 : number;
  begin
    nBuffer1 := Malloc(100); nBuffer2 := Malloc(100);
    // copy "Hello world!" message to all strings and buffers
    Strcpy(sString1, "Hello world!");
    Strcpy(sString2, sString1);
    Strcpy(in nBuffer1, sString1);
    Strcpy(in nBuffer2, in nBuffer1);
    Strcpy(sOutput, in nBuffer2);
    write(sString2); writeln;
    write(sOutput); writeln;
    Free(nBuffer1); Free(nBuffer2);
  end TStrcpy;

Output

Hello world!
Hello world!
Parent topic: String Functions


Strcspn Function

Action

Searches in sString for the first occurrence of one character belonging to a defined set of characters in a string.

Include file

Kernel.bdh

Syntax

Strcspn( in sString       : string,
         in sCharacterSet : string ): number;

Return value

Index of the first character in sString that belongs to the set of characters in sCharacterSet. If sString begins with a character in sCharacterSet, the function returns 1. If none of the characters in sString is in sCharacterSet, the function returns 0.

Parameter | Description
sString | Specifies the string to search in
sCharacterSet | Specifies the set of characters in a string

Example

dcltrans
  transaction TStrcspn
  var
    sString, sSet : string;
    nPos          : number;
  begin
    sString := "Hello world!";
    sSet := "awx_?";
    write("string = "); write(sString); writeln;
    write("set = "); write(sSet); writeln;

    // search for the first occurrence of one of the characters
    nPos := Strcspn(sString, sSet);
    write("pos = "); write(nPos); writeln;
  end TStrcspn;

Output

string = Hello world!
set = awx_?
pos = 7
Parent topic: String Functions
Related reference
Strpbrk Function
Strspn Function


Stricmp Function

Action

Performs a lowercase comparison of strings.

Include file

Kernel.bdh

Syntax

Stricmp( in sString1 : string,
         in sString2 : string ): number;

Return value

  • value < 0. sString1 is less than sString2

  • value = 0. sString1 is identical to sString2

  • value > 0. sString1 is greater than sString2

Parameter | Description
sString1 | Defines the first string to compare
sString2 | Defines the second string to compare

Example

dcltrans
  transaction TStricmp
  var
    sString1, sString2: string;
  begin
    sString1 := "Hello world!";
    sString2 := "HELLO WORLD!";
    write("string1 = "); write(sString1); writeln;
    write("string2 = "); write(sString2); writeln;

    // perform lowercase comparison
    if Stricmp(sString1, sString2) = 0 then
      write("strings are equal when converted to lowercase"); writeln;
    else
      write("strings are different"); writeln;
    end;
  end TStricmp;

Output

string1 = Hello world!
string2 = HELLO WORLD!
strings are equal when converted to lowercase
Parent topic: String Functions


Strlen Function

Action

Retrieves the length of a string.

In contrast to the Binlen function Strlen does not return the data length, but returns the number of characters before the first '\0' (null) character.

Include file

Kernel.bdh

Syntax

Strlen( in sString : string ): number;

Return value

string length

Parameter | Description
sString | Input string

Example

dcltrans
  transaction TStrlen
  var
    sString : string;
    nLength : number;
  begin
    sString := "Hello world!";
    write("string = "); write(sString); writeln;
    nLength := Strlen(sString);
    write("length = "); write(nLength); writeln;
    write("length of long string = ");
    write(Strlen("This is quite a long string")); writeln;
  end TStrlen;

Output

string = Hello world!
length = 12
length of long string = 27

Sample scripts

WebFileUpload01.bdf

Parent topic: String Functions
Related reference
Binlen Function
BinSetlen Function
StrResize Function
StrSize Function


StrSize Function

Action

Returns the size of a string's currently allocated memory buffer.

Include file

Kernel.bdh

Syntax

StrSize( in sString : string ): number;

Return value

  • the amount of memory the string has currently allocated

Parameter | Description
sString | String whose memory size is to be retrieved.

Example

dcltrans
  transaction TMain
  var
    sString : string;
  begin
    Print("Allocated memory: " + string(StrSize(sString)) + " Bytes");

 StrResize(sString, 1024);
    Print("Allocated memory: " + string(StrSize(sString)) + " Bytes");
    StrResize(sString, 10, 100);
    Print("Allocated memory: " + string(StrSize(sString)) + " Bytes");
  end TMain;

Output

Allocated memory: 254 Bytes
Allocated memory: 1024 Bytes
Allocated memory: 100 Bytes
Parent topic: String Functions
Related reference
Binlen Function
BinSetlen Function
Strlen Function
StrResize Function


StrResize Function

Action

Resizes a string's memory buffer. The new size of the memory buffer is specified with a minimum and maximum value in order for the string to decide whether it must really resize its memory buffer.

Include file

Kernel.bdh

Syntax

StrResize ( in sString  : string,
            in nMinSize : number,
            in nMaxSize : number optional );
Parameter | Description
sString | String whose memory size is to be resized.
nMinSize | Minimum value which the string's memory buffer is resized to.
nMaxSize | Maximum value which the string's memory buffer is resized to (optional and default is unlimited).

Example

dcltrans
  transaction TMain
  var
    sString : string;
  begin
    Print("Allocated memory: " + string(StrSize(sString)) + " Bytes");

    StrResize(sString, 1024);
    Print("Allocated memory: " + string(StrSize(sString)) + " Bytes");
    StrResize(sString, 10, 100);
    Print("Allocated memory: " + string(StrSize(sString)) + " Bytes");
  end
TMain;

Output

Allocated memory: 254 Bytes
Allocated memory: 1024 Bytes
Allocated memory: 100 Bytes
Parent topic: String Functions
Related reference
Binlen Function
BinSetlen Function
Strlen Function
StrSize Function


Strlwr Function

Action

Converts a string to lowercase.

Include file

Kernel.bdh

Syntax

Strlwr(inout sString: string): string;

Return value

The string converted to lowercase.

Parameter | Description
sString | String to be converted. This parameter will contain the result string after the Strlwr operation

Example

dcltrans
  transaction TStrlwr
  var
    sString, sLower: string;
  begin
    sString := "HeLlO wOrLd!";
    write("string = "); write(sString); writeln;
    // convert string to lowercase
    sLower := Strlwr(sString);
    write("string = "); write(sString); writeln;
    write("lower = "); write(sLower); writeln;
  end TStrlwr;

Output

string = HeLlO wOrLd!
string = hello world!
lower = hello world!
Parent topic: String Functions
Related reference
Strupr Function


StrlwrEx Function

Action

Converts a string to lowercase format (and umlautes, if required).

Include file

kernel.bdh

Syntax

StrlwrEx(
      inout sString : string ): string ;

Return value

the modified string

Parameter | Description
sString | String to be converted. This parameter will contain the result string after the StrlwrEx operation

Example

dcltrans
  transaction TStrlwrEx
  var
    sString, sLower: string;
  begin
    sString := "HeLlÖ wOrLd!";
    write("string = "); write(sString); writeln;

    // convert string to lowercase
    sLower := StrlwrEx(sString);
    write("string = "); write(sString); writeln;
    write("lower  = "); write(sLower); writeln;
  end TStrlwrEx;

Output

string = HeLlÖ wOrLd!
string = hellö world!
lower  = hellö world!
Parent topic: String Functions
Related reference
Strings
Strlwr Function
StruprEx Function


Strncmp Function

Action

Compares lexicographically and case-sensitively the first count characters in two strings. For case-insensitive string comparison refer to the Strnicmp function.

Include file

Kernel.bdh

Syntax

Strncmp(in sString1 : string,in sString2 : string,in nCount : number): number;

Return value

  • value < 0. sString1 is less than sString2

  • value = 0. sString1 is identical to sString2

  • value > 0. sString1 is greater than sString2

Parameter | Description
sString1 | Defines the first string to compare
sString2 | Defines the second string to compare
nCount | Defines the number of characters to compare

Example

dcltrans
  transaction TStrncmp
  var
    sString1, sString2: string;
  begin
    sString1 := "Hello world!";
    sString2 := "Hello WORLD!";
    write("string1 = "); write(sString1); writeln;
    write("string2 = "); write(sString2); writeln;
    // compare strings
    if Strncmp(sString1, sString2, Strlen(sString1)) = 0 then
      write("strings are equal"); writeln;
    else
      write("strings are not equal"); writeln;
    end;
    // compare first 5 characters of strings
    if Strncmp(sString1, sString2, 5) = 0 then
      write("first 5 characters of the strings are equal"); writeln;
    else
      write("first 5 characters are not equal"); writeln;
    end;
  end TStrncmp;

Output

string1 = Hello world!
string2 = Hello WORLD!
strings are not equal
first 5 characters of the strings are equal
Parent topic: String Functions
Related reference
Strnicmp Function


Strncpy Function

Action

Copies the initial nCount characters of sSource to sDest and returns sDest. If nCount is less than or equal to the length of sSource, no null character is appended to the copied string. If nCount is greater than the length of sSource, the destination string is padded with null characters up to length count. The behavior of Strncpy is undefined if the source string and the destination string overlap.

Include file

Kernel.bdh

Syntax

Strncpy( out sDest   : string,
         in  sSource : string,
         in  nCount  : number): string;

Return value

The string actually copied. No special value indicates an error.

Parameter | Description
sDest | String to be overwritten. This parameter will contain the result of the copy operation
sSource | Is copied into sDest
nCount | Defines the number of characters to copy

Example

dcltrans
  transaction TStrncpy
  var
    sSource, sDest, sResult: string;
  begin
    sDest := "That is beautiful!";
    sSource := "This is just a test!";
    write("dest = "); write(sDest); writeln;
    write("source = "); write(sSource); writeln;
    sResult := Strncpy(sDest, sSource, 20);
    write("dest = "); write(sDest); writeln;
    write("result = "); write(sResult); writeln;
  end TStrncpy;

Output

dest   = That is beautiful!
source = This is just a test!
dest   = This is just a test!
result = This is just a test!
Parent topic: String Functions


Strnicmp Function

Action

Compares lexicographically the first nCount characters in two strings without regard to case-sensitivity. For case-sensitive string comparison use the Strncmp function.

Include file

Kernel.bdh

Syntax

Strnicmp(in sString1 : string,
         in sString2 : string,
         in nCount : number): number;

Return value

  • value < 0. sString1 is less than sString2

  • value = 0. sString1 is identical to sString2

  • value > 0. sString1 is greater than sString2

Parameter | Description
sString1 | Defines the first string to compare
sString2 | Defines the second string to compare
nCount | Defines the number of characters to compare

Example

dcltrans
  transaction TStrnicmp
  var
    sString1, sString2 : string;
    nResult1, nResult2 : number;
  begin
    sString1 := "HELLO beautiful world!";
    sString2 := "Hello beautiful lady!";
    write("string1 = "); write(sString1); writeln;
    write("string2 = "); write(sString2); writeln;
    nResult1 := Strnicmp(sString1, sString2,15);
    nResult2 := Strnicmp(sString1, sString2, 20);
    if nResult1 = 0 then
      write("first 15 characters are equal"); writeln;
    else
      write("first 15 characters are not equal"); writeln;
    end;
    if nResult2 = 0 then
      write("first 20 characters are equal"); writeln;
    else
      write("first 20 characters are not equal"); writeln;
    end;
  end TStrnicmp;

Output

string1 = HELLO beautiful world!
string2 = Hello beautiful lady!
first 15 characters are equal
first 20 characters are not equal
Parent topic: String Functions
Related reference
Strncmp Function


Strnset Function

Action

Overwrites the beginning of a string with nCount characters.

Include file

Kernel.bdh

Syntax

Strnset( inout sString    : string,
         in    nCharacter : number,
         in    nCount     : number ): string;

Return value

the altered string

Parameter | Description
sString | String to be overwritten. This parameter will contain the altered string after the Strnset operation
nCharacter | Defines a character that the function uses to overwrite a section of sString
nCount | Defines the number of characters to overwrite in sString

Example

dcltrans
  transaction TStrnset
  var
    sString, sResult : string;
    nChar : number;
  begin
    sString := "Hello world!";
    nChar := ord('*');
    write("string = "); write(sString); writeln;
    write("char   = "); write(chr(nChar)); writeln;

    sResult := Strnset(sString, nChar, 5);
    write("result = "); write(sResult); writeln;
  end TStrnset;

Output

string = Hello world!
char   = *
result = ***** world!
Parent topic: String Functions


Strpbrk Function

Action

Searches for the first occurrence of any one character out of a defined set of characters in a string.

Include file

Kernel.bdh

Syntax

Strpbrk( in sString       : string,
         in sCharacterSet : string ): string;

Return value

the shortened string, beginning with a character defined in sCharacterSet

Parameter | Description
sString | Identifies the string to search in
sCharacterSet | Defines a set of characters and the search criteria

Example

dcltrans
  transaction TStrpbrk
  var
    sString, sSet, sResult1, sResult2: string;
  begin
    sString := "Hello world!";
    sSet := "lwx";
    write("string  = "); write(sString); writeln;
    write("set     = "); write(sSet); writeln;

    sResult1 := Strpbrk(sString, sSet);
    sResult2 := Strpbrk(sString[5], sSet);
    write("result1 = "); write(sResult1); writeln;
    write("result2 = "); write(sResult2); writeln;
  end TStrpbrk;

Output

string  = Hello world!
set     = lwx
result1 = llo world!
result2 = world!
Parent topic: String Functions
Related reference
Strcspn Function
Strspn Function


Strrchr Function

Action

Searches for the last occurrence of a character in a string.

Include file

Kernel.bdh

Syntax

Strrchr( in sString    : string,
         in nCharacter : number ): string;

Return value

String beginning with the last occurrence of the defined character. If the character is not found, the returned string is empty.

Parameter | Description
sString | Defines the string to search in
nCharacter | Defines the character to search

Example

dcltrans
  transaction TStrrchr
  var
    sString, sResult : string;
    nChar : number;
  begin
    sString := "Hello world!";
    nChar := ord('l');
    write("string = "); write(sString); writeln;
    write("char   = "); write(chr(nChar)); writeln;

    sResult := Strrchr(sString, nChar);
    write("result = "); write(sResult); writeln;
  end TStrrchr;

Output

string = Hello world!
char   = l
result = ld!
Parent topic: String Functions
Related reference
Strchr Function


Strrev Function

Action

Reverses the order of characters of a string.

Include file

Kernel.bdh

Syntax

Strrev(inout sString: string): string;

Return value

The reversed string.

Parameter | Description
sString | String to reverse. This parameter also contains the result after the Strrev operation.

Example

dcltrans
  transaction TStrrev
  var
    sString: string;
  begin
    sString := "Hello world!";
    write("String = "); write(sString); writeln;
    // reverse characters of string
    Strrev(sString);
    write("String = "); write(sString); writeln;
  end TStrrev;

Output

String = Hello world!
String = !dlrow olleH
Parent topic: String Functions


StrSearch Function

Action

Searches for a substring in a string.

Include file

Kernel.bdh

Syntax

StrSearch(in sSource : string,
          in sSearch : string,
          in nFlags  : number) : number;

Return value

Index of the position of the found substring, or zero if the substring was not found or an error occurred.

Parameter | Description
sSource | Source string to be searched
sSearch | String to search for
nFlags

Option flags. Several combinations of the following options are possible:

  • STR_SEARCH_FIRST: Start a new search.

  • STR_SEARCH_NEXT: Continue a previous search.

  • STR_SEARCH_MATCH_CASE: Search case-sensitive.

  • STR_SEARCH_REVERSE: Search from right to left.
Note: The STR_SEARCH_NEXT option is allowed only if the function is called with the same source string as in the previous call.

Example

dcltrans
  transaction TStrSearch
  var
    sString, sWord : string;
    nPos : number;
  begin
    sString := "The dog, the cat and the mouse are very tired today";
    sWord := "the";
    write("string = "); write(sString); writeln;
    write("word = "); write(sWord); writeln;
    nPos := StrSearch(sString, sWord, STR_SEARCH_FIRST);
    write("pos = "); write(nPos); writeln;
    nPos := StrSearch(sString, sWord, STR_SEARCH_NEXT);
    write("pos = "); write(nPos); writeln;
    nPos := StrSearch(sString, sWord,STR_SEARCH_FIRST | STR_SEARCH_MATCH_CASE);
    write("pos = "); write(nPos); writeln;
    nPos := StrSearch(sString, sWord,STR_SEARCH_FIRST | STR_SEARCH_REVERSE);
    write("pos = "); write(nPos); writeln;
  end TStrSearch;

Output

string = The dog, the cat and the mouse are very tired
today
word = the
pos = 1
pos = 10
pos = 10
pos = 22

Sample scripts

WebFileUpload01.bdf

Parent topic: String Functions
Related reference
StrSearchDelimited Function


StrSearchDelimited Function

Action

Searches for a string delimited on the left by sLeftVal and on the right by sRightVal. The search direction for delimiters can be from left to right and vice versa. It is also possible to search for the n-th occurrence of delimiters. It is further possible to continue a search at the positions found at a previous search.

Include file

Kernel.bdh

Syntax

StrSearchDelimited( out sTarget      : string,
                    in  nMaxTarget   : number,
                    in  sSource      : string,
                    in  sLeftVal     : string allownull,
                    in  nLVOccurrence : number,
                    in  sRightVal    : string allownull,
                    in  nRVOccurrence : number,
                    in  nFlags       : number ): boolean;

Return value

  • true if a substring could be found which is delimited on the left by sLeftVal and on the right by sRightVal and no error occurred

  • false otherwise

Parameter | Description
sTarget | String variable to receive the found substring
nMaxTarget | Maximum number of characters to write into sTarget. This value must be <= the size of sTarget.
sSource | Source string to be searched
sLeftVal | Left delimiter string to search for
nLVOccurrence | Search until sLeftVal is found nLVOccurrence times
sRightVal | Right delimiter string to search for
nRVOccurrence | Search until sRightVal is found nRVOccurrence times
nFlags

Option flags. Several combinations of the following options are possible:

  • STR_SEARCH_FIRST: Start a new search.

  • STR_SEARCH_NEXT: Continue a previous search.

  • STR_SEARCH_MATCH_CASE: Search case-sensitive.

  • STR_SEARCH_IGNORE_WHITESPACES: Ignore white spaces during search.
Note: The STR_SEARCH_NEXT option is allowed only if the function is called with the same source string as in the previous call.

  • A value of zero for nLVOccurrence and nRVOccurrence means that the corresponding position is kept from the previous search.

  • A negative value for nLVOccurrence and nRVOccurrence means to search from right to left.

  • If sLeftVal/sRightVal is null, the beginning/end of the source string is used as a delimiter.

  • Except for the case when nLVOccurrence and nRVOccurrence are negative or the case when nLVOccurrence is positive and nRVOccurrence is negative, the sRightVal is searched starting from the position where sLeftVal is found. If nLVOccurrence and nRVOccurrence are negative, sRightVal is searched first and then the search for sLeftVal starts from the position where sRightVal has been found. If nLVOccurrence is positive and nRVOccurrence is negative, sRightVal is searched starting from the end of the source string.

Example

dcltrans
  transaction TStrSearchDelimited
  var
    sText, sWord1, sWord2, sResult : string;
    nPos                           : number;
    bOk                            : boolean;
  begin
    sText := "The quick brown dog jumps over "
             "the lazy fox and the lazy cat";
    sWord1 := "the";
    sWord2 := "the";
    bOk := StrSearchDelimited(sResult, STRING_COMPLETE, sText,
                              sWord1, 1, sWord2, 1, 0);
    writeln(sResult);

    bOk := StrSearchDelimited(sResult, STRING_COMPLETE, sText,
                              sWord1, 1, sWord2, 2, STR_SEARCH_NEXT);
    writeln(sResult);

    bOk := StrSearchDelimited(sResult, STRING_COMPLETE, sText,
                              sWord1, 0, sWord2, 1, STR_SEARCH_NEXT);
    writeln(sResult);

    bOk := StrSearchDelimited(sResult, STRING_COMPLETE, sText, sWord1,
                              -1, sWord2, 0, STR_SEARCH_NEXT);
    writeln(sResult);

    bOk := StrSearchDelimited(sResult, STRING_COMPLETE, sText,
                              NULL, 1, sWord2, -1, 0);
    writeln(sResult);

    bOk := StrSearchDelimited(sResult, STRING_COMPLETE, sText,
                              sWord1, 3, NULL, 1, 0);
    writeln(sResult);
  end TStrSearchDelimited;

Output

 quick brown dog jumps over

 quick brown dog jumps over the lazy fox and

The quick brown dog jumps over the lazy fox and
 lazy cat
Parent topic: String Functions
Related reference
StrSearch Function


Strset Function

Action

Replaces all characters of a string with the character nCharacter.

Include file

Kernel.bdh

Syntax

Strset( inout sString    : string,
        in    nCharacter : number ): string;

Return value

the altered string

Parameter | Description
sString | String to be overwritten. This parameter will contain the altered string after the Setset operation
nCharacter | Defines the character for the operation

Example

dcltrans
  transaction TStrset
  var
    sString, sResult : string;
    nChar            : number;
  begin
    sString := "Hello world!";
    nChar   := ord('*');
    write("string = "); write(sString); writeln;
    write("char   = "); write(chr(nChar)); writeln;

    sResult := Strset(sString, nChar);
    write("string = "); write(sString); writeln;
    write("result = "); write(sResult); writeln;
  end TStrset;

Output

string = Hello world!
char   = *
string = ************
result = ************
Parent topic: String Functions


Strspn Function

Action

Searches in sString for the first character that does not belong to the set of characters in sCharacterSet.

Include file

Kernel.bdh

Syntax

Strspn( in sString       : string,
        in sCharacterSet : string ): number;

Return value

Index of the first character in sString that does not belong to the set of characters in sCharacterSet. If sString begins with a character not in sCharacterSet, the function returns 1.

Parameter | Description
sString | Defines the string to search in
sCharacterSet | Defines a set of character as a search criteria

Example

dcltrans
  transaction TStrspn
  var
    sString, sSet : string;
    nIndex        : number;
  begin
    sString := "Hello world!";
    sSet    := "ABCDEFGHabcdefgh";
    write("string = "); write(sString); writeln;
    write("set    = "); write(sSet); writeln;

    nIndex := Strspn(sString, sSet);
    write("index  = "); write(nIndex); writeln;
  end TStrspn;

Output

string = Hello world!
set    = ABCDEFGHabcdefgh
index  = 3
Parent topic: String Functions
Related reference
Strcspn Function
Strpbrk Function


Strstr Function

Action

Searches a string for a substring.

Include file

Kernel.bdh

Syntax

Strstr( in sString    : string,
        in sSubString : string ): string;

Return value

sString starting at the first occurrence of sSubString

Parameter | Description
sString | Defines the string to search in
sSubString | Defines the string to search in sString

Example

dcltrans
  transaction TStrstr
  var
    sString, sSubString, sResult: string;
  begin
    sString    := "Hope the weather will be fine tomorrow!";
    sSubString := "the";
    write("string    = "); write(sString); writeln;
    write("substring = "); write(sSubString); writeln;

    sResult := Strstr(sString, sSubString);
    write("result    = "); write(sResult); writeln;
  end TStrstr;

Output

string    = Hope the weather will be fine tomorrow!
substring = the
result    = the weather will be fine tomorrow!
Parent topic: String Functions


Strtok Function

Action

Finds the next token in a string.

Include file

Kernel.bdh

Syntax

Strtok( in sTokenString  : string allownull,
        in sDelimiterSet : string ): string;

Return value

Next token found in sTokenString. This function returns an empty string when no more tokens are found. Each call modifies sTokenString by substituting a null character for each delimiter that is encountered.

Parameter | Description
sTokenString | Defines the string to search in. Each call modifies this parameter by substituting a null character for each delimiter that is encountered.
sDelimiterSet | Defines a set of characters that subdivide the tokens.

Example

dcltrans
  transaction TStrtok
  var
    sTokenString, sDelimiterSet, sToken: string;
  begin
    sTokenString := "apples+peaches*bananas/physical training="
                    "very healthy";
    sDelimiterSet := "+*/=";
    write("Tokens found: "); writeln;
    sToken := Strtok(sTokenString, sDelimiterSet);

    while sToken <> "" do
      write(sToken); write(", ");
      sToken := Strtok(NULL, sDelimiterSet);
    end;
  end TStrtok;

Output

Tokens found:
apples, peaches, bananas, physical training, very healthy,
Parent topic: String Functions


Strupr Function

Action

Converts a string to uppercase.

Include file

Kernel.bdh

Syntax

Strupr(inout sString: string): string;

Return value

The string converted to uppercase.

Parameter | Description
sString | String to be converted. This parameter will contain the result string after the Strupr operation

Example

dcltrans
  transaction TStrupr
  var
    sString, sUpper: string;
  begin
    sString := "HeLlO wOrLd!";
    write("string = "); write(sString); writeln;
    // convert string to uppercase
    sUpper := Strupr(sString);
    write("string = "); write(sString); writeln;
    write("upper = "); write(sUpper); writeln;
  end TStrupr;

Output

string = HeLlO wOrLd!
string = HELLO WORLD!
upper = HELLO WORLD!
Parent topic: String Functions
Related reference
Strlwr Function


StruprEx Function

Action

Converts a string to uppercase format (and umlautes if required).

Include file

kernel.bdh

Syntax

StruprEx( inout sString : string): string;

Return value

The string converted to uppercase.

Parameter | Description
sString | String to be converted. This parameter will contain the result string after the StrUprEx operation.

Example

dcltrans
  transaction TStruprEx
  var
    sString, sUpper: string;
  begin
    sString := "HeLlÖ wOrLd!";
    write("string = "); write(sString); writeln;

    // convert string to uppercase
    sUpper := StruprEx(sString);
    write("string = "); write(sString); writeln;
    write("upper  = "); write(sUpper); writeln;
  end TStruprEx;

Output

string = HeLlÖ wOrLd!
string = HELLÖ WORLD!
upper  = HELLÖ WORLD!
Parent topic: String Functions


Substr Function

Action

Extracts a substring (nLen characters in length, beginning at position nStart) from a string.

If the start position is not within the string an error is raised. If the length specification exceeds the string’s length, the substring ends with the last character of the string.

Include file

Kernel.bdh

Syntax

Substr( in  sSource : string,
        out sDest   : string,
        in  nStart  : number,
        in  nLen    : number): string;

Return value

copied substring

Parameter | Description
sSource | Source string
sDest | Destination string
nStart | Position of first character
nLen | Length of substring

Example

dcltrans
  transaction TSubstr
  var
    sString, sPart: string;
  begin
    sString := "Hello world!";
    write("string = "); write(sString); writeln;
    // extract substring "world"
    Substr(sString, sPart, 7, 5);
    write("part = "); write(sPart); writeln;
  end TSubstr;

Output

string = Hello world!
part = world
Parent topic: String Functions


StrIsNull Function

Action

Checks whether a string is null.

Note: BDL strings implement null pointer semantics, i.e. BDL differentiates between a null string and an empty string.

Include file

Kernel.bdh

Syntax

StrIsNull( in sString : string ) : boolean;

Return value

  • true if successful

  • false otherwise

Parameter | Description
sString | String to be checked for null.

Example

dcltrans
  transaction TMain
  var
    sString : string;
  begin
    if StrIsNull(sString)then
      Print("sString is null");
    else
      Print("sString is not null");
    end;

    if StrIsEmpty(sString) then
      Print("sString is empty");
    else
      Print("sString is not empty");
    end;

    StrSetNull(sString);

    if StrIsNull(sString)then
      Print("sString is null");
    else
      Print("sString is not null");
    end;

    if StrIsEmpty(sString) then
      Print("sString is empty");
    else
      Print("sString is not empty");
    end;
  end TMain;

Output

sString is not null
sString is empty
sString is null
sString is empty
Parent topic: String Functions
Related reference
StrIsEmpty Function
StrSetNull Function


StrSetNull Function

Action

Sets a string to null explicitly.

Note: BDL strings implement null pointer semantics, i.e. BDL differentiates between a null string and an empty string.

Include file

Kernel.bdh

Syntax

StrSetNull( inout sString : string ) : boolean;

Return value

  • true if string was set to null

  • false otherwise

Parameter | Description
sString | String to be set to null.

Example

dcltrans
  transaction TMain
  var
    sString : string;
  begin
    if StrIsNull(sString) then
      Print("sString is null");
    else
      Print("sString is not null");
    end;

    if StrIsEmpty(sString) then
      Print("sString is empty");
    else
      Print("sString is not empty");
    end;

    StrSetNull(sString);

    if StrIsNull(sString) then
      Print("sString is null");
    else
      Print("sString is not null");
    end;

    if StrIsEmpty(sString) then
      Print("sString is empty");
    else
      Print("sString is not empty");
    end;
 end TMain;

Output

sString is not null
sString is empty
sString is null
sString is empty
Parent topic: String Functions
Related reference
StrIsEmpty Function
StrIsNull Function


StrIsEmpty Function

Action

Checks whether a string is empty.

Note: BDL strings implement null pointer semantics, i.e. BDL differentiates between a null string and an empty string.

Include file

Kernel.bdh

Syntax

StrIsEmpty( in sString : string allownull ): boolean;

Return value

  • true if string is empty or null

  • false otherwise

Parameter | Description
sString | String to be checked.

Example

dcltrans
  transaction TMain
  var
    sString : string;
  begin
    if StrIsNull(sString) then
      Print("sString is null");
    else
      Print("sString is not null");
    end;

    if StrIsEmpty(sString)then
      Print("sString is empty");
    else
      Print("sString is not empty");
    end;

    StrSetNull(sString);

    if StrIsNull(sString) then
      Print("sString is null");
    else
      Print("sString is not null");
    end;

    if StrIsEmpty(sString) then
      Print("sString is empty");
    else
      Print("sString is not empty");
    end;
  end TMain;

Output

sString is not null
sString is empty
sString is null
sString is empty
Parent topic: String Functions
Related reference
StrIsNull Function
StrSetNull Function


StrFromHostCP Function

Action

Converts a targeted host-character-set string that uses a specified code page into an ANSI string.

Include file

Kernel.bdh

Syntax

StrFromHostCP(
    in sSource   : string,
    in uCodePage : number optional ) : string;

Return value

  • Converted string

Parameter | Description
sSource | Source string to be converted.
nCodePage | Code page number to be used for conversion (optional). If omitted, the default host-character-set code page is used (See StrSetHostCP for details).

Example

dcltrans
  transaction TInit
  begin
    StrSetHostCP(28591);// 28591 (ISO 8859-1 Latin I)

    if StrGetHostCP()<>28591 then
      RaiseError(ERROR_CUSTOM, "(ISO 8859-1 Latin I) not supported", SEVERITY_PROCESS_EXIT);
    end;
  end TInit;

  transaction   TMain
  var
    hWeb0     : number;
    sBuffer   : string;
    sBoundary : string;
    nOption   : number;
  begin
    WebTcpipConnect(hWeb0, "My.TelnetHost.IP", WEB_PORT_TELNET);
    WebTcpipSetTelnetMode(hWeb0, TERMINAL_TYPE_ANSI, 80, 24, true,
      TELNET_MODEOPT_RFC_1576 | TELNET_MODEOPT_AUTO_RECV);

    WebTelnetRecvCommand(hWeb0, TELNET_CMD_DO, TELNET_OPT_TerminalType);
    WebTelnetRecvCommand(hWeb0, TELNET_CMD_DO, TELNET_OPT_TerminalSpeed);
    WebTelnetRecvCommand(hWeb0, TELNET_CMD_DO, TELNET_OPT_XDisplayLocation);
    WebTelnetRecvCommand(hWeb0, TELNET_CMD_DO, TELNET_OPT_NewEnvironment);
    WebTelnetSendCommand(hWeb0, TELNET_CMD_WILL, TELNET_OPT_TerminalType);
    WebTelnetSendCommand(hWeb0, TELNET_CMD_WONT, TELNET_OPT_TerminalSpeed);
    WebTelnetSendCommand(hWeb0, TELNET_CMD_WONT, TELNET_OPT_XDisplayLocation);
    WebTelnetSendCommand(hWeb0, TELNET_CMD_WONT, TELNET_OPT_NewEnvironment);
    WebTelnetRecvSubNegotiation(hWeb0, TELNET_OPT_TerminalType);
    WebTelnetSendTerminalType(hWeb0, "vt100");
    WebTelnetRecvCommand(hWeb0, TELNET_CMD_WILL, TELNET_OPT_SuppressGoAhead);
    WebTelnetRecvCommand(hWeb0, TELNET_CMD_DO, TELNET_OPT_Echo);
    WebTelnetRecvCommand(hWeb0, TELNET_CMD_DO, TELNET_OPT_NegotiateWindowSize);
    WebTelnetRecvCommand(hWeb0, TELNET_CMD_WILL, TELNET_OPT_Status);
    WebTelnetRecvCommand(hWeb0, TELNET_CMD_DO, TELNET_OPT_RemoteFlowControl);
    WebTelnetSendCommand(hWeb0, TELNET_CMD_DO, TELNET_OPT_SuppressGoAhead);
    WebTelnetSendCommand(hWeb0, TELNET_CMD_WONT, TELNET_OPT_Echo);
    WebTelnetSendCommand(hWeb0, TELNET_CMD_WILL, TELNET_OPT_NegotiateWindowSize);
    WebTelnetSendSubNegotiation(hWeb0, TELNET_OPT_NegotiateWindowSize, "\h00500018");
    WebTelnetSendCommand(hWeb0, TELNET_CMD_DONT, TELNET_OPT_Status);
    WebTelnetSendCommand(hWeb0, TELNET_CMD_WONT, TELNET_OPT_RemoteFlowControl);
    WebTelnetRecvCommand(hWeb0, TELNET_CMD_WILL, TELNET_OPT_Echo);
    WebTcpipGetPacketBoundary(hWeb0, sBoundary);
    WebTcpipRecvPacketsUntilData(hWeb0, "login: ");
    WebTelnetTypeKeys(hWeb0, StrToHostCP("leo"), 359.3, TELNET_FLAG_CASE_SENSITIVE);

    if StriCmp(StrFromHostCP(sBuffer), "leo") <> 0 then
      RaiseError(ERROR_CUSTOM);
    end;

    WebTcpipSendBin(hWeb0, "\h0D00");
    WebTcpipRecvExact(hWeb0, NULL, 390);
    WebTcpipSetPacketBoundary(hWeb0, sBoundary);
    WebTcpipRecvUntilIdle(hWeb0, NULL, 5000);
    WebTcpipSendBin(hWeb0, "\h0D000D0A");
    WebTcpipRecvPackets(hWeb0, NULL, 3);
    WebTcpipSendBin(hWeb0, "\h0D00");
    WebTcpipSendPacket(hWeb0, StrToHostCP("8") + "\h0D00");
    WebTcpipRecvClose(hWeb0, NULL);
    WebTcpipShutdown(hWeb0);
  end TMain;
Parent topic: String Functions


StrGetHostCP Function

Action

Returns the default host code page used for string conversions when using StrToHostCP and StrFromHostCP functions.

Include file

Kernel.bdh

Syntax

StrGetHostCP( ): number;

Return value

  • Currently set host code page used for string conversions.

Example

dcltrans
  transaction TInit
  begin
    StrSetHostCP(28591); // 28591 (ISO 8859-1 Latin I)

    if StrGetHostCP()<>28591 then
      RaiseError(ERROR_CUSTOM, "(ISO 8859-1 Latin I) not supported", SEVERITY_PROCESS_EXIT;
    end;
  end TInit;

  transaction   TMain
  var
    hWeb0     : number;
    sBuffer   : string;
    sBoundary : string;
    nOption   : number;
  begin
    WebTcpipConnect(hWeb0, "My.TelnetHost.IP",WEB_PORT_TELNET);
    WebTcpipSetTelnetMode(hWeb0, TERMINAL_TYPE_ANSI, 80, 24, true,
      TELNET_MODEOPT_RFC_1576 | TELNET_MODEOPT_AUTO_RECV);

    WebTelnetRecvCommand(hWeb0, TELNET_CMD_DO, TELNET_OPT_TerminalType);
    WebTelnetRecvCommand(hWeb0, TELNET_CMD_DO, TELNET_OPT_TerminalSpeed);
    WebTelnetRecvCommand(hWeb0, TELNET_CMD_DO, TELNET_OPT_XDisplayLocation);
    WebTelnetRecvCommand(hWeb0, TELNET_CMD_DO, TELNET_OPT_NewEnvironment);
    WebTelnetSendCommand(hWeb0, TELNET_CMD_WILL, TELNET_OPT_TerminalType);
    WebTelnetSendCommand(hWeb0, TELNET_CMD_WONT, TELNET_OPT_TerminalSpeed);
    WebTelnetSendCommand(hWeb0, TELNET_CMD_WONT, TELNET_OPT_XDisplayLocation);
    WebTelnetSendCommand(hWeb0, TELNET_CMD_WONT, TELNET_OPT_NewEnvironment);
    WebTelnetRecvSubNegotiation(hWeb0, TELNET_OPT_TerminalType);
    WebTelnetSendTerminalType(hWeb0, "vt100");
    WebTelnetRecvCommand(hWeb0, TELNET_CMD_WILL, TELNET_OPT_SuppressGoAhead);
    WebTelnetRecvCommand(hWeb0, TELNET_CMD_DO, TELNET_OPT_Echo);
    WebTelnetRecvCommand(hWeb0, TELNET_CMD_DO, TELNET_OPT_NegotiateWindowSize);
    WebTelnetRecvCommand(hWeb0, TELNET_CMD_WILL, TELNET_OPT_Status);
    WebTelnetRecvCommand(hWeb0, TELNET_CMD_DO, TELNET_OPT_RemoteFlowControl);
    WebTelnetSendCommand(hWeb0, TELNET_CMD_DO, TELNET_OPT_SuppressGoAhead);
    WebTelnetSendCommand(hWeb0, TELNET_CMD_WONT, TELNET_OPT_Echo);
    WebTelnetSendCommand(hWeb0, TELNET_CMD_WILL, TELNET_OPT_NegotiateWindowSize);
    WebTelnetSendSubNegotiation(hWeb0, TELNET_OPT_NegotiateWindowSize, "\h00500018");
    WebTelnetSendCommand(hWeb0, TELNET_CMD_DONT, TELNET_OPT_Status);
    WebTelnetSendCommand(hWeb0, TELNET_CMD_WONT, TELNET_OPT_RemoteFlowControl);
    WebTelnetRecvCommand(hWeb0, TELNET_CMD_WILL, TELNET_OPT_Echo);
    WebTcpipGetPacketBoundary(hWeb0, sBoundary);
    WebTcpipRecvPacketsUntilData(hWeb0, "login: ");
    WebTelnetTypeKeys(hWeb0, StrToHostCP("leo"), 359.3, TELNET_FLAG_CASE_SENSITIVE);

    if StriCmp(StrFromHostCP(sBuffer), "leo") <> 0 then
      RaiseError(ERROR_CUSTOM);
    end;

    WebTcpipSendBin(hWeb0, "\h0D00");
    WebTcpipRecvExact(hWeb0, NULL, 390);
    WebTcpipSetPacketBoundary(hWeb0, sBoundary);
    WebTcpipRecvUntilIdle(hWeb0, NULL, 5000);
    WebTcpipSendBin(hWeb0, "\h0D000D0A");
    WebTcpipRecvPackets(hWeb0, NULL, 3);
    WebTcpipSendBin(hWeb0, "\h0D00");
    WebTcpipSendPacket(hWeb0, StrToHostCP("8") + "\h0D00");
    WebTcpipRecvClose(hWeb0, NULL);
    WebTcpipShutdown(hWeb0);
  end TMain;
Parent topic: String Functions


StrSetHostCP Function

Action

Sets the default host code page used for string conversions when using StrToHostCP and StrFromHostCP functions.

Include file

Kernel.bdh

Syntax

StrSetHostCP( in nCodePage : number );
Parameter | Description
nCodePage | Code page number to use for conversion.

Example

dcltrans
  transaction TInit
  begin
    StrSetHostCP(28591);// 28591 (ISO 8859-1 Latin I)

    if StrGetHostCP()<>28591 then
      RaiseError(ERROR_CUSTOM, "(ISO 8859-1 Latin I) not supported", SEVERITY_PROCESS_EXIT);
    end;
  end TInit;

  transaction   TMain
  var
    hWeb0     : number;
    sBuffer   : string;
    sBoundary : string;
    nOption   : number;
  begin
    WebTcpipConnect(hWeb0, "My.TelnetHost.IP", WEB_PORT_TELNET);
    WebTcpipSetTelnetMode(hWeb0, TERMINAL_TYPE_ANSI, 80, 24, true,
      TELNET_MODEOPT_RFC_1576 | TELNET_MODEOPT_AUTO_RECV);

    WebTelnetRecvCommand(hWeb0, TELNET_CMD_DO, TELNET_OPT_TerminalType);
    WebTelnetRecvCommand(hWeb0, TELNET_CMD_DO, TELNET_OPT_TerminalSpeed);
    WebTelnetRecvCommand(hWeb0, TELNET_CMD_DO, TELNET_OPT_XDisplayLocation);
    WebTelnetRecvCommand(hWeb0, TELNET_CMD_DO, TELNET_OPT_NewEnvironment);
    WebTelnetSendCommand(hWeb0, TELNET_CMD_WILL, TELNET_OPT_TerminalType);
    WebTelnetSendCommand(hWeb0, TELNET_CMD_WONT, TELNET_OPT_TerminalSpeed);
    WebTelnetSendCommand(hWeb0, TELNET_CMD_WONT, TELNET_OPT_XDisplayLocation);
    WebTelnetSendCommand(hWeb0, TELNET_CMD_WONT, TELNET_OPT_NewEnvironment);
    WebTelnetRecvSubNegotiation(hWeb0, TELNET_OPT_TerminalType);
    WebTelnetSendTerminalType(hWeb0, "vt100");
    WebTelnetRecvCommand(hWeb0, TELNET_CMD_WILL, TELNET_OPT_SuppressGoAhead);
    WebTelnetRecvCommand(hWeb0, TELNET_CMD_DO, TELNET_OPT_Echo);
    WebTelnetRecvCommand(hWeb0, TELNET_CMD_DO, TELNET_OPT_NegotiateWindowSize);
    WebTelnetRecvCommand(hWeb0, TELNET_CMD_WILL, TELNET_OPT_Status);
    WebTelnetRecvCommand(hWeb0, TELNET_CMD_DO, TELNET_OPT_RemoteFlowControl);
    WebTelnetSendCommand(hWeb0, TELNET_CMD_DO, TELNET_OPT_SuppressGoAhead);
    WebTelnetSendCommand(hWeb0, TELNET_CMD_WONT, TELNET_OPT_Echo);
    WebTelnetSendCommand(hWeb0, TELNET_CMD_WILL, TELNET_OPT_NegotiateWindowSize);
    WebTelnetSendSubNegotiation(hWeb0, TELNET_OPT_NegotiateWindowSize, "\h00500018");
    WebTelnetSendCommand(hWeb0, TELNET_CMD_DONT, TELNET_OPT_Status);
    WebTelnetSendCommand(hWeb0, TELNET_CMD_WONT, TELNET_OPT_RemoteFlowControl);
    WebTelnetRecvCommand(hWeb0, TELNET_CMD_WILL, TELNET_OPT_Echo);
    WebTcpipGetPacketBoundary(hWeb0, sBoundary);
    WebTcpipRecvPacketsUntilData(hWeb0, "login: ");
    WebTelnetTypeKeys(hWeb0, StrToHostCP("leo"), 359.3, TELNET_FLAG_CASE_SENSITIVE);

    if StriCmp(StrFromHostCP(sBuffer), "leo") <> 0 then
      RaiseError(ERROR_CUSTOM);
    end;

    WebTcpipSendBin(hWeb0, "\h0D00");
    WebTcpipRecvExact(hWeb0, NULL, 390);
    WebTcpipSetPacketBoundary(hWeb0, sBoundary);
    WebTcpipRecvUntilIdle(hWeb0, NULL, 5000);
    WebTcpipSendBin(hWeb0, "\h0D000D0A");
    WebTcpipRecvPackets(hWeb0, NULL, 3);
    WebTcpipSendBin(hWeb0, "\h0D00");
    WebTcpipSendPacket(hWeb0, StrToHostCP("8") + "\h0D00");
    WebTcpipRecvClose(hWeb0, NULL);
    WebTcpipShutdown(hWeb0);
  end TMain;

Parent topic: String Functions


StrToHostCP Function

Action

Converts an ANSI string representation into a targeted host-character-set string using the specified code page.

Include file

Kernel.bdh

Syntax

StrToHostCP(
    in sSource   : string,
    in uCodePage : number optional ) : string;

Return value

  • Converted string

Parameter | Description
sSource | Source string to be converted
nCodePage | Code page number to use for conversion (optional). If omitted, the default host-character-set code page is used (See StrSetHostCP for details).

Example

dcltrans
  transaction TInit
  begin
    StrSetHostCP(28591);// 28591 (ISO 8859-1 Latin I)

    if StrGetHostCP()<>28591 then
      RaiseError(ERROR_CUSTOM, "(ISO 8859-1 Latin I) not supported", SEVERITY_PROCESS_EXIT);
    end;
  end TInit;

  transaction   TMain
  var
    hWeb0     : number;
    sBuffer   : string;
    sBoundary : string;
    nOption   : number;
  begin
    WebTcpipConnect(hWeb0, "My.TelnetHost.IP", WEB_PORT_TELNET);
    WebTcpipSetTelnetMode(hWeb0, TERMINAL_TYPE_ANSI, 80, 24, true,
      TELNET_MODEOPT_RFC_1576 | TELNET_MODEOPT_AUTO_RECV);

    WebTelnetRecvCommand(hWeb0, TELNET_CMD_DO, TELNET_OPT_TerminalType);
    WebTelnetRecvCommand(hWeb0, TELNET_CMD_DO, TELNET_OPT_TerminalSpeed);
    WebTelnetRecvCommand(hWeb0, TELNET_CMD_DO, TELNET_OPT_XDisplayLocation);
    WebTelnetRecvCommand(hWeb0, TELNET_CMD_DO, TELNET_OPT_NewEnvironment);
    WebTelnetSendCommand(hWeb0, TELNET_CMD_WILL, TELNET_OPT_TerminalType);
    WebTelnetSendCommand(hWeb0, TELNET_CMD_WONT, TELNET_OPT_TerminalSpeed);
    WebTelnetSendCommand(hWeb0, TELNET_CMD_WONT, TELNET_OPT_XDisplayLocation);
    WebTelnetSendCommand(hWeb0, TELNET_CMD_WONT, TELNET_OPT_NewEnvironment);
    WebTelnetRecvSubNegotiation(hWeb0, TELNET_OPT_TerminalType);
    WebTelnetSendTerminalType(hWeb0, "vt100");
    WebTelnetRecvCommand(hWeb0, TELNET_CMD_WILL, TELNET_OPT_SuppressGoAhead);
    WebTelnetRecvCommand(hWeb0, TELNET_CMD_DO, TELNET_OPT_Echo);
    WebTelnetRecvCommand(hWeb0, TELNET_CMD_DO, TELNET_OPT_NegotiateWindowSize);
    WebTelnetRecvCommand(hWeb0, TELNET_CMD_WILL, TELNET_OPT_Status);
    WebTelnetRecvCommand(hWeb0, TELNET_CMD_DO, TELNET_OPT_RemoteFlowControl);
    WebTelnetSendCommand(hWeb0, TELNET_CMD_DO, TELNET_OPT_SuppressGoAhead);
    WebTelnetSendCommand(hWeb0, TELNET_CMD_WONT, TELNET_OPT_Echo);
    WebTelnetSendCommand(hWeb0, TELNET_CMD_WILL, TELNET_OPT_NegotiateWindowSize);
    WebTelnetSendSubNegotiation(hWeb0, TELNET_OPT_NegotiateWindowSize, "\h00500018");
    WebTelnetSendCommand(hWeb0, TELNET_CMD_DONT, TELNET_OPT_Status);
    WebTelnetSendCommand(hWeb0, TELNET_CMD_WONT, TELNET_OPT_RemoteFlowControl);
    WebTelnetRecvCommand(hWeb0, TELNET_CMD_WILL, TELNET_OPT_Echo);
    WebTcpipGetPacketBoundary(hWeb0, sBoundary);
    WebTcpipRecvPacketsUntilData(hWeb0, "login: ");
    WebTelnetTypeKeys(hWeb0, StrToHostCP("leo"), 359.3, TELNET_FLAG_CASE_SENSITIVE);

    if StriCmp(StrFromHostCP(sBuffer), "leo") <> 0 then
      RaiseError(ERROR_CUSTOM);
    end;

    WebTcpipSendBin(hWeb0, "\h0D00");
    WebTcpipRecvExact(hWeb0, NULL, 390);
    WebTcpipSetPacketBoundary(hWeb0, sBoundary);
    WebTcpipRecvUntilIdle(hWeb0, NULL, 5000);
    WebTcpipSendBin(hWeb0, "\h0D000D0A");
    WebTcpipRecvPackets(hWeb0, NULL, 3);
    WebTcpipSendBin(hWeb0, "\h0D00");
    WebTcpipSendPacket(hWeb0, StrToHostCP("8") + "\h0D00");
    WebTcpipRecvClose(hWeb0, NULL);
    WebTcpipShutdown(hWeb0);
  end TMain;

Parent topic: String Functions


SetEncoding Function

Action

Sets a codepage, which is used by the functions FromEncoding and ToEncoding, to convert the given strings.

Include file

Kernel.bdh

Syntax

SetEncoding( in sCodepage: string ): boolean;

Return value

  • true if the codepage could be set.

  • false otherwise

Parameter | Description
sCodepage | The name of the used codepage. E.g.: "UTF-8", "WINDOWS-1255", "EUC-JP"

Example

dcltrans
  transaction TMain
  var
    sResult : string;
  begin
    SetEncoding("UTF-8");
    WebPageUrl("http://testsite.company.com.cn");
    WebParseHtmlBound(sResult, STRING_COMPLETE, "Home", "Street");
    WebPageLink(ToEncoding("??"), "?? - Company  ??");
    writeln(FromEncoding(sResult));
    writeln("http://testsite.company.com.cn has the codepage "  + GetEncoding() + " set");
  end TMain;
Parent topic: String Functions
Related reference
FromEncoding Function
ToEncoding Function
GetEncoding Function


ToEncoding Function

Action

Converts the given ANSI string into the string of the codepage that has been selected by the SetEncoding function.

Include file

Kernel.bdh

Syntax

ToEncoding( in ParamName : string ): string;

Return value

  • Converted string

Parameter | Description
sSource | Source string to be converted.

Example

dcltrans
  transaction TMain
  var
    sResult : string;
  begin
    SetEncoding("UTF-8");
    WebPageUrl("http://testsite.company.com.cn");
    WebParseHtmlBound(sResult, STRING_COMPLETE, "Home", "Street");
    WebPageLink(ToEncoding("??"), "?? - Company ??");
    writeln(FromEncoding(sResult));
    writeln("http://testsite.company.com.cn has the codepage"  + GetEncoding() + " set");
  end TMain;
Parent topic: String Functions
Related reference
FromEncoding Function
SetEncoding Function
GetEncoding Function


ToUnicode Function

Action

Converts ANSI string representation into a unicode escape sequence of type \uxxxx.

Include file

Kernel.bdh

Syntax

ToUnicode( in sSource : string ): string;

Return value

  • converted string
Parameter | Description
sSource | Source string to be converted.

Example

dcltrans
  transaction TMain
  var
    sConverted : string;
  begin

    sConverted := ToUnicode("AaBbCc");
    Print(sConverted); // "\u0061\0041\0062\u0042\u0063\u0043"

  end TMain;
Parent topic: String Functions


ToUTF8 Function

Action

Converts an ANSI string representation into a UTF8-encoded byte sequence.

Include file

Kernel.bdh

Syntax

ToUTF8( in sSource : string ) : string;

Return value

  • Converted string

Parameter | Description
sSource | Source string to be converted.

Example

dcltrans
  transaction TMain
  var
    sResult : string;
  begin
    WebPageUrl("http://testsite.company.com.cn");
    WebParseHtmlBound(sResult, STRING_COMPLETE, "Home", "Street");
    WebPageLink(ToUTF8("ÄÄ/ÜÖÖÜ"), "eBay");
    writeln(FromUTF8(sResult));
  end TMain;

Parent topic: String Functions


Regular Expressions

Regular expressions represent an advanced technique for checking syntax of strings or for parsing values out of strings. They are very powerful but significantly slower and more difficult to use than the StrSearch and StrSearchDelimited functions.

For parsing responses of Web pages, WebParseResponseData is the fastest implementation, since it operates on the incoming data stream instead of storing the entire Web page. When using regular expressions, it is necessary to store the entire page or a part of the page in a string variable. This can be done with WebParseResponseData or WebTcpipRecvClose.

Silk Performer provides the following functions to handle regular expressions:

  • Structure of Regular Expressions
    Describes the structure of regular expressions and shows which characters may be used
  • StrRegexClose Function
    Closes a handle opened with the StrRegexCompile function.
  • StrRegexCompile Function
    Compiles a regular expression and applies the resulting automaton to a handle for later use.
  • StrRegexExecute Function
    Executes a compiled regular expression on the string argument.
  • StrRegexFindFirst Function
    Creates an iterator over matched portions and stores the first matching substring into sTarget.
  • StrRegexFindNext Function
    Advances to the next matched substring and stores the result into sTarget.
  • StrRegexImmediate Function
    Compiles a regular expression and executes it to match a source string.
  • StrRegexSubst Function
    Substitutes matched portions into a template string.
Parent topic: General Functions


Structure of Regular Expressions

Silk Performer uses an equivalent regular expression implementation as found in 4.x BSD Unix system.

The table below describes the structure of regular expressions and shows which characters may be used:

Character | Description
[1] | char | Matches itself, unless it is a special character (metachar): . \ [ ] * + ^ $
[2] . Matches any character
[3] \

Matches the subsequent character unless it is a left or right round bracket, a digit 1 to 9 or a left or right angle bracket (see [7], [8] and [9]).

It is used as an escape character for all other meta-characters, and itself. When used in a set (see [4]), it is treated as an ordinary character.

[4] [set]

Matches one of the characters in the set. If the first character in the set is "^", it matches a character NOT in the set. The shorthand “S-E” is used to specify a set of characters from S to E, inclusively. The special characters "]" and "-" have no special meaning if they appear as the first chars in the set.

Examples:

[a-z] any lowercase letter

[^]-] any character except ] and -

[^A-Z] any character except uppercase letters

[a-zA-Z] any letter

[5] * Any regular expression of [1] to [4] followed by the closure character (*) matches a string of zero or more characters that have that form.
[6] + Same as [5], except it matches one or more.
[7] \ A regular expression of form [1] to [10] enclosed as \(form\) matches whatever the specified form matches. The enclosure creates a set of tags, used for [8] and for pattern substitution. The tagged forms are numbered starting from 1.
[8] \ A \ character followed by a digit 1 to 9 matches whatever a previously tagged regular expression ([7]) matched. For example, “\5” represents the fifth pattern specified in the “\(form\)” format.
[9]

\<

\>

A regular expression starting with a \< construct and/or ending with a \> construct, restricts the pattern matching to the beginning of a word, and/or the end of a word. A word is defined to be a character string beginning and/or ending with the characters A-Z a-z 0-9 and _. It must also be preceded and/or followed by any character other than those mentioned.
[10] | A composite regular expression xy, where x and y are of form [1] to [10] matches the longest match of x followed by a match for y.
[11] ^ $ A regular expression starting with a ^ character and/or ending with a $ character restricts the pattern matching to the beginning of the line or to the end of line. Elsewhere in the expression, ^ and $ are treated as ordinary characters.

Example

Pattern | Matches | Comment
\\\.\* | \.* | backslash dot asterisk
\[\]\+\^\$ | []+^$ | other special characters
foo*.* | fo foo fooo foobar fobar foxx ... |
fo[ob]a[rz] | fobar fooar fobaz fooaz |
foo\\+ | foo\ foo\\ foo\\\ ... |
\(foo\)[1-3]\1 | foo1foo foo2foo foo3foo | the same as: foo[1-3]foo
\(fo.*\)-\1 | foo-foo fo-fo fob-fob foobar-foobar ... |
Parent topic: Regular Expressions


StrRegexClose Function

Action

Closes the handle opened by StrRegexCompile. Call this function when the compiled regular expression is no longer needed.

Include file

Kernel.bdh

Syntax

StrRegexClose( inout hRegex: number ): boolean;

Return value

  • true if successful

  • false otherwise

Parameter | Description
hRegex | Valid handle to a compiled regular expression. This handle must have been generated with a previous call to StrRegexCompile.

Example

dcltrans
  transaction TMain
  var
    hRegex                   : number;
    sRegex, sSource, sTarget : string;
    match                    : boolean;
  begin
    sSource := "SessionIDTest.asp?SessionID=SID8:44:43&amp;"
               "Param2=Value2";
    sRegex := "SessionID=\(SID[0-9:]+\)";
    write("source = "+sSource); writeln;
    write("regex = "+sRegex); writeln;
    StrRegexCompile(hRegex, sRegex);
    match := StrRegexExecute(hRegex, sSource);

    if match then
      StrRegexSubst(hRegex, "\1", sTarget, STRING_COMPLETE);
      write("match: "+sTarget); writeln;
    else
      write("no match"); writeln;
    end;

    StrRegexClose(hRegex);
  end TMain;

Output

source = SessionIDTest.asp?SessionID=SID8:44:43&amp;Param2=Value2
regex = SessionID=\(SID[0-9:]+\)
match: SID8:44:43

Sample scripts

WebRegularExpressions01.bdf

Parent topic: Regular Expressions
Related reference
StrRegexCompile Function
StrRegexExecute Function
StrRegexSubst Function


StrRegexCompile Function

Action

Compiles a regular expression and applies the resulting automaton (compiled byte code) to a handle for later use by StrRegexExecute, StrRegexSubst and StrRegexClose.

This function is very advantageous when you need to reuse the same regular expression over and over again because it speeds up the execution of the BDL-Script.

Include file

Kernel.bdh

Syntax

StrRegexCompile( inout hRegex   : number,
                 in    sRegex   : string,
                 in    nBufSize : number optional): boolean;

Return value

  • true if successful

  • false otherwise

Parameter | Description
hRegex | Variable receiving the handle to the compiled regular expression
sRegex | Regular expression
nBufSize | Size of the buffer used to store the compiled regular expression (optional). Default value is 2048.

Example

dcltrans
  transaction TMain
  var
    hRegex                   : number;
    sRegex, sSource, sTarget : string;
    match                    : boolean;
  begin
    sSource := "SessionIDTest.asp?SessionID=SID8:44:43&amp;"
               "Param2=Value2";
    sRegex := "SessionID=\(SID[0-9:]+\)";
    write("source = "+sSource); writeln;
    write("regex = "+sRegex); writeln;
    StrRegexCompile(hRegex, sRegex);
    match := StrRegexExecute(hRegex, sSource);

    if match then
      StrRegexSubst(hRegex, "\1", sTarget, STRING_COMPLETE);
      write("match: "+sTarget); writeln;
    else
      write("no match"); writeln;
    end;

    StrRegexClose(hRegex);
  end TMain;

Output

source = SessionIDTest.asp?SessionID=SID8:44:43&amp;Param2=Value2
regex = SessionID=\(SID[0-9:]+\)
match: SID8:44:43

Sample scripts

WebRegularExpressions01.bdf

Parent topic: Regular Expressions
Related reference
StrRegexClose Function
StrRegexExecute Function
StrRegexSubst Function


StrRegexExecute Function

Action

Executes the compiled regular expression on the string argument.

Include file

Kernel.bdh

Syntax

StrRegexExecute( in    hRegex  : number,
                 inout sSource : string ): boolean;

Return value

  • true if a match of the regular expression in the string sSource could be found.

  • false on errors or if no match could be found. Use GetLastError and GetErrorMsg to query for more information.

Parameter | Description
hRegex | Valid handle to a compiled regular expression. This handle must have been generated with a previous call to StrRegexCompile.
sSource | String to be matched by the regular expression

Example

dcltrans
  transaction TMain
  var
    hRegex                   : number;
    sRegex, sSource, sTarget : string;
    match                    : boolean;
  begin
    sSource := "SessionIDTest.asp?SessionID=SID8:44:43&amp;"
               "Param2=Value2";
    sRegex := "SessionID=\(SID[0-9:]+\)";
    write("source = "+sSource); writeln;
    write("regex = "+sRegex); writeln;
    StrRegexCompile(hRegex, sRegex);
    match := StrRegexExecute(hRegex, sSource);

    if match then
      StrRegexSubst(hRegex, "\1", sTarget, STRING_COMPLETE);
      write("match: "+sTarget); writeln;
    else
      write("no match"); writeln;
    end;

    StrRegexClose(hRegex);
  end TMain;

Output

source = SessionIDTest.asp?
SessionID=SID8:44:43&amp;Param2=Value2
regex = SessionID=\(SID[0-9:]+\)
match: SID8:44:43

Sample scripts

WebRegularExpressions01.bdf

Parent topic: Regular Expressions
Related reference
StrRegexClose Function
StrRegexCompile Function
StrRegexSubst Function


StrRegexFindFirst Function

Action

Creates an iterator over matched portions and stores the first matching substring into sTarget.

Include file

Kernel.bdh

Syntax

StrRegexFindFirst( in  hRegex  : number,
                   in  sSource : string,
                   out sTarget : string,
                   in  iLen    : number ): boolean;

Return value

  • true if successful

  • false otherwise

Parameter | Description
hRegex | Valid handle to a compiled regular expression. This handle must have been generated with a previous call to StrRegexCompile.
sSource | String to be matched by the regular expression.
sTarget | String which receives the result of the substitution string.
iLen | Size of sTarget.

Example

transaction TMain
var
  s       : string;
  sResult : string;
  hRegex  : number;
begin
  s := "page1 alpha beta omega page4 page2 gamma page3";
  StrRegexCompile(hRegex, "page[0-9]");

  if (StrRegexExecute(hRegex, s)) then
    StrRegexFindFirst(hRegex, s, sResult, STRING_COMPLETE);
    Print(sResult);

    while StrRegexFindNext(hRegex, sResult, STRING_COMPLETE) do
      Print(sResult);
    end;
  end;
  StrRegexClose(hRegex);
end TMain;
Parent topic: Regular Expressions
Related reference
StrRegexFindNext Function
StrRegexCompile Function
StrRegexExecute Function
StrRegexClose Function


StrRegexFindNext Function

Action

Advances to the next matched substring and stores the result into sTarget.

Include file

Kernel.bdh

Syntax

StrRegexFindFirst( in  hRegex  : number,
                   out sTarget : string,
                   in  iLen    : number ): boolean;

Return value

  • true if successful

  • false otherwise

Parameter | Description
hRegex | Valid handle to a compiled regular expression. This handle must have been generated with a previous call to StrRegexCompile.
sTarget | String which receives the result of the substitution string.
iLen | Size of sTarget.

Example

transaction TMain
var
  s       : string;
  sResult : string;
  hRegex  : number;
begin
  s := "page1 alpha beta omega page4 page2 gamma page3";
  StrRegexCompile(hRegex, "page[0-9]");

  if (StrRegexExecute(hRegex, s)) then
    StrRegexFindFirst(hRegex, s, sResult, STRING_COMPLETE);
    Print(sResult);

    while StrRegexFindNext(hRegex, sResult, STRING_COMPLETE) do
      Print(sResult);
    end;
  end;
  StrRegexClose(hRegex);
end TMain;
Parent topic: Regular Expressions
Related reference
StrRegexFindFirst Function
StrRegexCompile Function
StrRegexExecute Function
StrRegexClose Function


StrRegexImmediate Function

Action

Compiles a regular expression and executes it to match a source string. An optional substitution string may be specified to parse out information from the source string.

Include file

Kernel.bdh

Syntax

StrRegexImmediate( in  sSource    : string,
                   in  sRegex     : string,
                   in  sSubst     : string optional,
                   out sTarget    : string optional,
                   in  nMaxTarget : number optional ): boolean;

Return value

  • true if a match of the regular expression in the string sSource could be found.

  • false on errors or if no match could be found. Use GetLastError and GetErrorMsg to query for more information.

Parameter | Description
sSource | String to be matched by the regular expression
sRegex | Regular expression
sSubst | String into which matched portions are substituted (optional)
sTarget | String which receives the result of the substitution string (optional)
nMaxTarget | Size of sTarget (optional)

Example

dcltrans
  transaction TMain
  var
    sRegex, sSource, sTarget : string;
    match                    : boolean;
  begin
    sSource := "SessionIDTest.asp?SessionID=SID8:44:43&amp;"
               "Param2=Value2";
    sRegex := "SID[0-9]+:[0-9]+:[0-9]+";
    write("source = "+sSource); writeln;
    write("regex = "+sRegex); writeln;
    match := StrRegexImmediate(sSource, sRegex, "&", sTarget);

    if match then
      write("match: "+sTarget); writeln;
    else
      write("no match"); writeln;
    end;
  end TMain;

Output

source = SessionIDTest.asp?SessionID=SID8:44:43&amp;Param2=Value2
regex = SID[0-9]+:[0-9]+:[0-9]+
match: SID8:44:43

Sample scripts

WebRegularExpressions01.bdf

Parent topic: Regular Expressions
Related reference
StrRegexCompile Function
StrRegexExecute Function
StrRegexSubst Function
StrRegexClose Function


StrRegexSubst Function

Action

Substitutes matched portions into a template string sSubst. The result is then stored in sTarget. Call this function if you want to easily extract multiple parts from the source string.

Include file

Kernel.bdh

Syntax

StrRegexSubst( in  hRegex     : number,
               in  sSubst     : string,
               out sTarget    : string,
               in  nMaxTarget : number ): boolean;

Return value

  • true if successful

  • false otherwise

Parameter | Description
hRegex | Valid handle to a compiled regular expression. This handle must have been generated with a previous call to StrRegexCompile.
sSubst | String into which matched portions are substituted
sTarget | String which receives the result of the substitution string
nMaxTarget | Size of sTarget

Example

dcltrans
  transaction TMain
  var
    hRegex                   : number;
    sRegex, sSource, sTarget : string;
    match                    : boolean;
  begin
    sSource := "SessionIDTest.asp?SessionID=SID8:44:43&amp;"
               "Param2=Value2";
    sRegex := "SessionID=\(SID[0-9:]+\)";
    write("source = "+sSource); writeln;
    write("regex = "+sRegex); writeln;
    StrRegexCompile(hRegex, sRegex);
    match := StrRegexExecute(hRegex, sSource);

    if match then
      StrRegexSubst(hRegex, "\1", sTarget, STRING_COMPLETE);
      write("match: "+sTarget); writeln;
    else
      write("no match"); writeln;
    end;

    StrRegexClose(hRegex);
  end TMain;

Output

source = SessionIDTest.asp?SessionID=SID8:44:43&amp;Param2=Value2
regex = SessionID=\(SID[0-9:]+\)
match: SID8:44:43

Sample scripts

WebRegularExpressions01.bdf

Parent topic: Regular Expressions
Related reference
StrRegexClose Function
StrRegexCompile Function
StrRegexExecute Function


System Information Functions

The following functions are available for retrieving system information:

  • GetInternetExplorerInfo Function
    Returns the major and minor version and the build number of the installed Internet Explorer.
  • GetOperatingSystemDisplayString Function
    Returns the long name of the operating system.
  • GetOperatingSystemInfo Function
    Returns the major and minor version and the build number of the operating system.
Parent topic: General Functions


GetInternetExplorerInfo Function

Action

Returns the major and minor version and the build number of the installed Internet Explorer.

Include File

Kernel.bdh

Syntax

GetInternetExplorerInfo( majorVersion : out long,
                         minorVersion : out long,
                         buildNumber  : out long optional ): boolean;

Return value

  • true if successful

  • false otherwise

Parameter | Description
majorVersion | The major version of the installed Internet Explorer
minorVersion | The minor version of the installed Internet Explorer
buildNumber | Optional: The build number of the installed Internet Explorer

Example

benchmark SilkPerformerRecorder

use "Kernel.bdh"

dcluser
  user
    VUser
  transactions
    TInit           : begin;
    TMain           : 1;

var

dclrand

dcltrans
  transaction TInit
  begin
  end TInit;

  transaction TMain
  var
    majorVersion, minorVersion, buildNumber : number;
  begin
   if GetInternetExplorerInfo (majorVersion, minorVersion,  buildNumber) then
      Print(string(majorVersion)+" "+string(minorVersion)+" "+string(buildNumber));
    end;
  end TMain;
Parent topic: System Information Functions
Parent topic: Browser-Driven Web Load Testing Functions


GetOperatingSystemDisplayString Function

Action

Returns the long name of the operating system.

Include File

Kernel.bdh

Syntax

GetOperatingSystemDisplayString(displayString : out dstring) : boolean;

Return value

  • true if successful

  • false otherwise

Parameter | Description
displayString | The long name of the operating system

Example

dcltrans
  transaction TMain
  var
    display : string;
  begin
   if GetOperatingSystemDisplayString(display) then
      Print(display);
    end;
  end TMain;

Output

Microsoft Windows 7 Enterprise Edition (build 7600), 64-bit
Parent topic: System Information Functions


GetOperatingSystemInfo Function

Action

Returns the major and minor version and the build number of the operating system.

Include File

Kernel.bdh

Syntax

GetOperatingSystemInfo(
  majorVersion : out long,
  minorVersion : out long,
  buildNumber : out long optional) : boolean;

Return value

  • true if successful

  • false otherwise

Parameter | Description
majorVersion | The major version of the operating system
minorVersion | The minor version of the operating system
buildNumber | The build number of the operating system

Example

dcltrans
  transaction TMain
  var
    majorVersion, minorVersion, buildNumber : number;
  begin
   if GetOperatingSystemInfo(majorVersion, minorVersion,  buildNumber) then
      Print(string(majorVersion)+" "+string(minorVersion)+" "+string(buildNumber));
    end;
end TMain;

Output

6 1 7600
Parent topic: System Information Functions


Attributes Manipulation Functions

Silk Performer enables you to associate any number of attributes with a virtual user.

Project attributes can be used to automatically initialize user attributes. By specifying a project attribute, a corresponding user attribute is defined and initialized for each virtual user. User attributes are also useful when working with Silk Performer frameworks, for example when the user behavior is defined in two separate scripts like BDL and Java. In this case, user attributes enable the exchange of data between the two scripts. The types of attributes associated with a user may vary.

The following functions serve to set and retrieve the values of user attributes:

  • Project Attributes
    Provides an overview for project attributes, which are name-value pairs that can be defined for a project.
  • AttributeGetBinary Function
    Retrieves binary data from a specified attribute of the user.
  • AttributeGetBoolean Function
    Retrieves a boolean value from a specified attribute of the user.
  • AttributeGetDouble Function
    Retrieves a floating-point value from a specified attribute of the user.
  • AttributeGetInt Function
    Retrieves an integer value from a specified attribute of the user.
  • AttributeGetString Function
    Retrieves a string from a specified attribute of the user.
  • AttributeSetBinary Function
    Assigns binary data to a specified attribute of the user.
  • AttributeSetBoolean Function
    Assigns a boolean value to a specified attribute of the user.
  • AttributeSetDouble Function
    Assigns a floating-point value to a specified attribute of the user.
  • AttributeSetInt Function
    Assigns an integer value to a specified attribute of the user.
  • AttributeSetString Function
    Assigns a string to a specified attribute of the user.
  • AttributeDelete Function
    Deletes a specified attribute associated with a virtual user.
Parent topic: General Functions


Project Attributes

Project attributes are name-value pairs with some additional information, which can be defined for a project. Each virtual user is initialized at runtime with these attributes. A useful scenario is to parameterize the BDL scripts on the project level.

Project attributes can be defined in Silk Performer's Project > Project Attributes menu. An attribute consists of a name, a type, a value, and a default value. The type specifies the way how the value and the default value of an attribute should be interpreted.

Possible attribute types are:

  • string

  • numeric

  • float

  • boolean

Depending on the type of the attribute, the project attributes can be accessed in the script via the following BDL functions:
Note: The name of an attribute is case sensitive.

  • AttributeGetString: for type "string"

  • AttributeGetInt: for type "numeric"

  • AttributeGetDouble: for type "float"

  • AttributeGetBoolean: for type "boolean"

Parent topic: Attributes Manipulation Functions
Related reference
AttributeGetBoolean Function
AttributeGetDouble Function
AttributeGetInt Function
AttributeGetString Function


AttributeGetBinary Function

Action

Retrieves binary data from a specified attribute of the user.

User attributes are useful when working with Silk Performer frameworks, in fact, when the user behavior is defined in two separate script. In that case, user attributes enable the exchange of data between scripts, for example, between a Silk Performer and a Java script.

Include file

Kernel.bdh

Syntax

AttributeGetBinary( in  sName       : string,
                    out sBuffer     : string,
                    in  sBufferSize : number optional,
                    out nDataLen    : number optional ): boolean;

Return value

  • true if successful

  • false otherwise

Parameter | Description
sName | Name of the attribute of which the value is retrieved.
sBuffer | Buffer receiving the binary data.
sBufferSize | Size of the buffer that receives the data (optional).
nDataLen | Variable receiving the actual amount of retrieved data (in bytes; optional).

Example

dcltrans
  transaction TMain
  var
    sString, sBuffer : string;
  begin
    AttributeSetString("name", "Jim");
    AttributeSetInt("age", 23);
    AttributeSetDouble("cash", 4503.60);
    AttributeSetBinary("code", "\h9EF30533");

    // do anything, for example, call an external function

    AttributeGetString("name", sString);
    writeln(sString);
    writeln(AttributeGetInt("age"));
    writeln(AttributeGetDouble("cash"));
    AttributeGetBinary("code", sBuffer);
    WriteData(sBuffer, STRING_COMPLETE);
  end TMain;
Parent topic: Attributes Manipulation Functions


AttributeGetBoolean Function

Action

Retrieves a boolean value from a specified attribute of the user.

User attributes are useful when working with Silk Performer frameworks, in fact, when the user behavior is defined in two separate script. In that case, user attributes enable the exchange of data between scripts, for example, between a Silk Performer and a Java script.

Another useful scenario is to define project attributes in Silk Performer. Using AttributeGet(Bool, Double, Int, String), these values can be retrieved by the BDL script in order to parameterize the script via project attributes.

Include file

Kernel.bdh

Syntax

AttributeGetBoolean( in sName : string ): boolean;

Return value

Boolean value that is retrieved.

Parameter | Description
sName | Name of the attribute of which the value is retrieved. The name of the attribute is case sensitive.

Example

dcltrans
  transaction TMain
  var
    sUrl,sString, sBuffer : string;
  begin
    AttributeSetString("name", "Jim");
    AttributeSetInt("age", 23);
    AttributeSetBoolean("member", true);
    AttributeSetDouble("cash", 4503.60);
    AttributeSetBinary("code", "\h9EF30533", 4);

    AttributeGetString("name", sString);
    writeln(sString);
    writeln(AttributeGetInt("age"));

    if AttributeGetBoolean("member") then
      writeln("true");
    else
      writeln("false");
    end;

    writeln(AttributeGetDouble("cash"));
    AttributeGetBinary("code", sBuffer);
    WriteData(sBuffer, STRING_COMPLETE);
  end TMain;
Parent topic: Attributes Manipulation Functions
Related reference
AttributeSetBoolean Function


AttributeGetDouble Function

Action

Retrieves a floating-point value from a specified attribute of the user.

User attributes are useful when working with Silk Performer frameworks, in fact, when the user behavior is defined in two separate script. In that case, user attributes enable the exchange of data between scripts, for example, between a Silk Performer and a Java script.

Another useful scenario is to define project attributes in Silk Performer. Using AttributeGet(Bool, Double, Int, String), these values can be retrieved by the BDL script in order to parameterize the script via project attributes.

Include file

Kernel.bdh

Syntax

AttributeGetDouble( in sName : string ): float;

Return value

Floating-point value that is retrieved.

Parameter | Description
sName | Name of the attribute of which the value is retrieved. The name of the attribute is case sensitive.

Example

dcltrans
  transaction TMain
  var
    i                      : number;
    sUrl, sString, sBuffer : string;
  begin
    AttributeSetString("name", "Jim");
    AttributeSetInt("age", 23);
    AttributeSetDouble("cash", 4503.60);
    AttributeSetBinary("code", "\h9EF30533", 4);

    // do anything, for example, call an external function
    for i := 1 to AttributeGetInt("TIMES") do
      AttributeGetString("URL", sUrl);
      WebPageUrl(sUrl);
    end;

    AttributeGetString("name", sString);
    writeln(sString);
    writeln(AttributeGetInt("age"));
    writeln(AttributeGetDouble("cash"));
    AttributeGetBinary("code", sBuffer);
    WriteData(sBuffer, STRING_COMPLETE);
  end TMain;
Parent topic: Attributes Manipulation Functions
Related reference
AttributeSetDouble Function


AttributeGetInt Function

Action

Retrieves an integer value from a specified attribute of the user.

User attributes are useful when working with Silk Performer frameworks, in fact, when the user behavior is defined in two separate script. In that case, user attributes enable the exchange of data between scripts, for example, between a Silk Performer and a Java script.

Another useful scenario is to define project attributes in Silk Performer. Using AttributeGet(Bool, Double, Int, String), these values can be retrieved by the BDL script in order to parameterize the script via project attributes.

Include file

Kernel.bdh

Syntax

AttributeGetInt( in sName: string ): number;

Return value

Integer value that is retrieved.

Parameter | Description
sName | Name of the attribute of which the value is retrieved. The name of the attribute is case sensitive.

Example

dcltrans
  transaction TMain
  var
    i                      : number;
    sUrl, sString, sBuffer : string;
  begin
    AttributeSetString("name", "Jim");
    AttributeSetInt("age", 23);
    AttributeSetDouble("cash", 4503.60);
    AttributeSetBinary("code", "\h9EF30533", 4);

    // do anything, for example, call an external function
    for i := 1 to AttributeGetInt("TIMES") do
      AttributeGetString("URL", sUrl );
      WebPageUrl(sUrl);
    end;

    AttributeGetString("name", sString);
    writeln(sString);
    writeln(AttributeGetInt("age"));
    writeln(AttributeGetDouble("cash"));
    AttributeGetBinary("code", sBuffer);
    WriteData(sBuffer, STRING_COMPLETE);
  end TMain;
Parent topic: Attributes Manipulation Functions


AttributeGetString Function

Action

Retrieves a string from a specified attribute of the user.

User attributes are useful when working with Silk Performer frameworks, in fact, when the user behavior is defined in two separate scripts. In that case, user attributes enable the exchange of data between scripts, for example, between a Silk Performer and a Java script.

Another useful scenario is to define project attributes in Silk Performer. Using AttributeGet(Bool, Double, Int, String), these values can be retrieved by the BDL script in order to parameterize the script via project attributes.

Include file

Kernel.bdh

Syntax

AttributeGetString( in  sName           : string,
                    out sString         : string,
                    in  nSize           : number optional,
                    in  useDefaultValue : boolean optional ): boolean;

Return value

  • true if successful

  • false otherwise

Parameter | Description
sName | Name of the attribute of which the value is retrieved. The name of the attribute is case sensitive.
sString | Buffer receiving the string.
nSize | Size of the buffer that receives the string (optional). If not specified, this parameter is set to 0 (zero), indicating that the size of the string is unlimited.
useDefaultValue | If set to true, the default value of a project attribute is read if no value has been defined. If not specified, this parameter is set to false.

Example

dcltrans
  transaction TMain
  var
    i                      : number;
    sUrl, sString, sBuffer : string;
  begin
    AttributeSetString("name", "Jim");
    AttributeSetInt("age", 23);
    AttributeSetDouble("cash", 4503.60);
    AttributeSetBinary("code", "\h9EF30533");

    // do anything, for example, call an external function

    for i := 1 to AttributeGetInt("TIMES") do
      AttributeGetString("URL", sUrl);
      WebPageUrl(sUrl);
    end;

    AttributeGetString("name", sString);
    writeln(sString);
    writeln(AttributeGetInt("age"));
    writeln(AttributeGetDouble("cash"));
    AttributeGetBinary("code", sBuffer);
    WriteData(sBuffer, STRING_COMPLETE);
  end TMain;
Parent topic: Attributes Manipulation Functions
Related reference
AttributeSetString Function


AttributeSetBinary Function

Action

Assigns binary data to a specified attribute of the user. The function automatically creates the attribute if it does not exist.

User attributes are useful when working with Silk Performer frameworks, in fact, when the user behavior is defined in two separate script. In that case, user attributes enable the exchange of data between scripts, for example, between a Silk Performer and a Java script.

Include file

Kernel.bdh

Syntax

AttributeSetBinary( in sName   : string,
                    in sBuffer : string,
                    in nSize   : number optional ): boolean;

Return value

  • true if successful

  • false otherwise

Parameter | Description
sName | Name of the attribute whose value is set. The function automatically creates the attribute if it does not exist.
sBuffer | Binary data that is assigned to the specified attribute.
nSize | Amount of binary data that is assigned to the attribute (in bytes; optional).

Example

dcltrans
  transaction TMain
  var
    sString, sBuffer : string;
  begin
    AttributeSetString("name", "Jim");
    AttributeSetInt("age", 23);
    AttributeSetDouble("cash", 4503.60);
    AttributeSetBinary("code", "\h9EF30533");

    // do anything, for example, call an external function

    AttributeGetString("name", sString);
    writeln(sString);
    writeln(AttributeGetInt("age"));
    writeln(AttributeGetDouble("cash"));
    AttributeGetBinary("code", sBuffer);
    WriteData(sBuffer, STRING_COMPLETE);
  end TMain;
Parent topic: Attributes Manipulation Functions
Related reference
AttributeSetBinary Function


AttributeSetBoolean Function

Action

Assigns a boolean value to a specified attribute of the user. The function automatically creates the attribute if it does not exist.

User attributes are useful when working with Silk Performer frameworks, in fact, when the user behavior is defined in two separate script. In that case, user attributes enable the exchange of data between scripts, for example, between a Silk Performer and a Java script.

Include file

Kernel.bdh

Syntax

AttributeSetBoolean( in sName  : string,
                     in bValue : boolean ): boolean;

Return value

  • true if successful

  • false otherwise

Parameter | Description
sName | Name of the attribute whose value is set. The function automatically creates the attribute if it does not exist.
bValue | Boolean value that is assigned to the specified attribute.

Example

dcltrans
  transaction TMain
  var
    sString, sBuffer : string;
  begin
    AttributeSetString("name", "Jim");
    AttributeSetInt("age", 23);
    AttributeSetBoolean("member", true);
    AttributeSetDouble("cash", 4503.60);
    AttributeSetBinary("code", "\h9EF30533", 4);

    // do anything, for example, call an external function
    AttributeGetString("name", sString);
    writeln(sString);
    writeln(AttributeGetInt("age"));
    if AttributeGetBoolean("member") then
      writeln("true");
    else
      writeln("false");
    end;
    writeln(AttributeGetDouble("cash"));
    AttributeGetBinary("code", sBuffer);
    WriteData(sBuffer, STRING_COMPLETE);
  end TMain;
Parent topic: Attributes Manipulation Functions
Related reference
AttributeGetBoolean Function


AttributeSetDouble Function

Action

Assigns a floating-point value to a specified attribute of the user. The function automatically creates the attribute if it does not exist.

User attributes are useful when working with Silk Performer frameworks, in fact, when the user behavior is defined in two separate script. In that case, user attributes enable the exchange of data between scripts, for example, between a Silk Performer and a Java script.

Include file

Kernel.bdh

Syntax

AttributeSetDouble( in sName  : string,
                    in fValue : float ): boolean;

Return value

  • true if successful

  • false otherwise

Parameter | Description
sName | Name of the attribute whose value is set. The function automatically creates the attribute if it does not exist.
fValue | Floating-point value that is assigned to the specified attribute.

Example

dcltrans
  transaction TMain
  var
    sString, sBuffer : string;
  begin
    AttributeSetString("name", "Jim");
    AttributeSetInt("age", 23);
    AttributeSetDouble("cash", 4503.60);
    AttributeSetBinary("code", "\h9EF30533", 4);

    // do anything, for example, call an external function
    AttributeGetString("name", sString);
    writeln(sString);
    writeln(AttributeGetInt("age"));
    writeln(AttributeGetDouble("cash"));
    AttributeGetBinary("code", sBuffer);
    WriteData(sBuffer, STRING_COMPLETE);
  end TMain;
Parent topic: Attributes Manipulation Functions
Related reference
AttributeGetDouble Function


AttributeSetInt Function

Action

Assigns an integer value to a specified attribute of the user. The function automatically creates the attribute if it does not exist.

User attributes are useful when working with Silk Performer frameworks, in fact, when the user behavior is defined in two separate script. In that case, user attributes enable the exchange of data between scripts, for example, between a Silk Performer and a Java script.

Include file

Kernel.bdh

Syntax

AttributeSetInt( in sName  : string,
                 in nValue : number ): boolean;

Return value

  • true if successful

  • false otherwise

Parameter | Description
sName | Name of the attribute whose value is set. The function automatically creates the attribute if it does not exist.
nValue | Integer value that is assigned to the specified attribute.

Example

dcltrans
  transaction TMain
  var
    sString, sBuffer : string;
  begin
    AttributeSetString("name", "Jim");
    AttributeSetInt("age", 23);
    AttributeSetDouble("cash", 4503.60);
    AttributeSetBinary("code", "\h9EF30533", 4);

    // do anything, for example, call an external function
    AttributeGetString("name", sString);
    writeln(sString);
    writeln(AttributeGetInt("age"));
    writeln(AttributeGetDouble("cash"));
    AttributeGetBinary("code", sBuffer);
    WriteData(sBuffer, STRING_COMPLETE);
  end TMain;
Parent topic: Attributes Manipulation Functions


AttributeSetString Function

Action

Assigns a string to a specified attribute of the user. The function automatically creates the attribute if it does not exist.

User attributes are useful when working with Silk Performer frameworks, in fact, when the user behavior is defined in two separate script. In that case, user attributes enable the exchange of data between scripts, for example, between a Silk Performer and a Java script.

Include file

Kernel.bdh

Syntax

AttributeSetString( in sName   : string,
                    in sString : string ): boolean;

Return value

  • true if successful

  • false otherwise

Parameter | Description
sName | Name of the attribute whose value is set. The function automatically creates the attribute if it does not exist.
sString | String that is assigned to the specified attribute.

Example

dcltrans
  transaction TMain
  var
    sString, sBuffer : string;
  begin
    AttributeSetString("name", "Jim");
    AttributeSetInt("age", 23);
    AttributeSetDouble("cash", 4503.60);
    AttributeSetBinary("code", "\h9EF30533");

    // do anything, for example, call an external function

    AttributeGetString("name", sString);
    writeln(sString);
    riteln(AttributeGetInt("age"));
    writeln(AttributeGetDouble("cash"));
    AttributeGetBinary("code", sBuffer);
    WriteData(sBuffer, STRING_COMPLETE);
  end TMain;
Parent topic: Attributes Manipulation Functions
Related reference
AttributeGetString Function


AttributeDelete Function

Action

Deletes a specified attribute associated with a virtual user.

Include file

Kernel.bdh

Syntax

AttributeDelete( in sName : string ): boolean;

Return value

  • true if successful

  • false otherwise

Parameter | Description
sName | Name of the attribute that is to be deleted.

Example

dcltrans
  transaction TMain
  var
    sUrl, sString, sBuffer : string;
  begin
    AttributeSetString("name", "Jim");
    AttributeSetInt("age", 23);
    AttributeSetDouble("cash", 4503.60);
    AttributeSetBinary("code", "\h9EF30533", 4);

    // do anything, for example, call an external function
    AttributeGetString("name", sString);
    writeln(sString);
    writeln(AttributeGetInt("age"));
    writeln(AttributeGetDouble("cash"));
    AttributeGetBinary("code", sBuffer);
    WriteData(sBuffer, STRING_COMPLETE);

    AttributeDelete("name");
    AttributeDelete("age");
    AttributeDelete("cash");
    AttributeDelete("code");
  end TMain;
Parent topic: Attributes Manipulation Functions


XML Functions

Silk Performer provides several API functions that allow you to work with XML documents and parse and verify XML values of web response documents. All these functions are based on an XML dom parser that ships with Silk Performer.

Note: Most of the BDL functions of the XML API work with handles. Handles are numeric values that are internally mapped to XML documents/nodes/node lists, ... . When you no longer need the handles, be sure to free them. This will keep the used memory as small as possible.
  • XmlAppendChild Function
    Appends the node to a parent node as additional child node.
  • XmlFreeHandle Function
    XmlFreeHandle should be called on node, nodelist and document handles as soon as they are no longer needed in the script to keep memory usage low.
  • XmlCreateDocument Function
    Creates an empty XML document that can be populated with the other XML API functions like XmlCreateNode, XmlAppendChild,
  • XmlCreateDocumentFromFile Function
    Loads an XML document from a file.
  • XmlCreateDocumentFromXml Function
    Loads an XML document from a string that contains a valid XML content.
  • XmlCreateNode Function
    Creates a new XML element node.
  • XmlCreateNodeFromXml Function
    Creates an XML node from a string that contains a valid XML representation of an XML node.
  • XmlGetChildNodes Function
    Returns a handle to a list of nodes (nodelist) that contains all child handles of the passed node/document handle.
  • XmlGetChildByIndex Function
    Returns a handle to a child node of the passed node/document handle.
  • XmlSelectSingleNode Function
    Executes an X-Path query on the passed handle (either document or node) and returns the first resulting node handle.
  • XmlSelectNodes Function
    Executes an X-Path query on the passed handle (either document or node) and returns the resulting handles in a node list.
  • XmlRemoveChild Function
    Removes the node from its current parent node (can be either a node or the document).
  • XmlReplaceNode Function
    Replaces the node passed in parameter hDestNode with the node in parameter hSourceNode.
  • XmlGetCount Function
    Takes a nodelist handle and returns the number of nodes that are stored in this list.
  • XmlGetItem Function
    Returns a node from the nodelist.
  • XmlGetInnerXml Function
    Returns the inner XML representation of the passed node/document handle.
  • XmlGetXml Function
    Returns the XML representation of the passed node/document handle.
  • XmlSetNodeAttribute Function
    Sets the value of an attribute of the passed node.
  • XmlGetAttributeByIndex Function
    Returns the value of a nodes attribute.
  • XmlGetAttributeByName Function
    Returns the value of a nodes attribute.
  • XmlGetAttributeCount Function
    Returns the number of attributes that are defined for the passed node.
  • XmlGetNodeName Function
    Returns the name of the passed node.
  • XmlGetNodeType Function
    Returns the type of the node passed as paramter.
  • XmlSetNodeValue Function
    Sets the text value of the passed node.
  • XmlGetNodeValue Function
    Returns the text value of the node.
  • XmlGetNodeTypedValue Function
    Returns the typed value of a node.
  • XmlSetNamespaces Function
    Sets the namespaces and the prefix for the namespaces that will be recognized by the XML parser.
  • XmlSetOption Function
    Allows enabling/disabling different XML parsing options.
  • XML Basics
    Describes some basic concepts that should be known when working with XML documents.
Parent topic: General Functions
Related concepts
XML First Steps
Related reference
WebXmlParseNodeAttribute Function
WebXmlParseNodeValue Function
WebXmlVerifyNodeAttribute Function
WebXmlVerifyNodeValue Function
XML Sample


XmlAppendChild Function

Action

Appends the node to a parent node as additional child node. If the child node has already had a parent node (is a node of an existing XML document), the node will be cloned and the cloned node will be appended to the passed parent node. After the call, hChildNode is the handle to the cloned node.

Include file

XmlAPI.bdh

Syntax

XmlAppendChild( in hParentNode : number,
                in hChildNode  : number ): boolean;

Return value

  • true if successful

  • false otherwise

Parameter | Description
hParentNode | Handle to an XML node that will be the parent
hChildNode | Handle to an XML node that will be appended to the parent node

Example

dcltrans
  transaction TMain
  var
  hDocument, hResult, hNewNode : number;
  begin
    hDocument := XmlCreateDocumentFromXml( "<root><child1 attr1='avalue1'>childvalue1</child1>"
                 "<child2 attr1= 'avalue2'>childvalue2</child2></root>");
    hNewNode := XmlCreateNode("child3");
    hResult  := XmlSelectSingleNode(hDocument, "/root");
    XmlAppendChild(hResult, hNewNode);
  end TMain;
Parent topic: XML Functions
Related concepts
Working with Nodes
Related reference
XmlReplaceNode Function
XmlRemoveChild Function


XmlFreeHandle Function

Action

XmlFreeHandle should be called on node, nodelist and document handles as soon as they are no longer needed in the script to keep memory usage low. If no parameters are passed, all currently used handles are freed and are then no longer valid.

You can pass a handle to a document, node or nodelist handle. If you pass true for parameter bAndDepending and the passed handle is a document handle, all handles to nodes of this document will also be freed and are then no longer valid.

Include file

XmlAPI.bdh

Syntax

XmlFreeHandle( in hHandle          : number optional,
               in bAndDepending    : boolean optional ): boolean;

Return value

  • true if succeeded

  • false if failed

Parameter | Description
hHandle | A valid document/node/nodelist handle If omitted, all handles that are still in use will be freed.
bAndDepending | If the handle is a document handle and bAndDepending is true, all handles for this document will be freed.

Example

dcltrans
  transaction TMain
  var
  hDocument, hResult, hOrderItems, hItem, hCount : number;
  itemIx                                         : number;
  sAttrValue                                     : string;
  begin
    hDocument := XmlCreateDocumentFromFile ("C:\\MyXMLDocuments\\Order.xml");
    hOrderItems := XmlSelectNodes(hDocument, "//OrderItem");
    hCount := XmlGetCount(hOrderItems);

    for itemIx := 0 to hCount - 1 do
      hItem := XmlGetItem(hOrderItems, itemIx);
      XmlGetAttributeByName(hItem, "price", sAttrValue);
    end;

    XmlFreeHandle();
  end TMain;
Parent topic: XML Functions
Related reference
XmlCreateDocument Function
XmlCreateNode Function


XmlCreateDocument Function

Action

Creates an empty XML document that can be populated with the other XML API functions like XmlCreateNode, XmlAppendChild, ... .

Include file

XmlAPI.bdh

Syntax

XmlCreateDocument( ): number;

Return value

  • document handle if successful

  • 0 otherwise

Example

dcltrans
  transaction TMain
  var
  hDocument, hRootNode, hChildNode, hResult : number;
  sAttrValue, sXmlString                    : string;
  begin
    hDocument  := XmlCreateDocument();
    hRootNode  := XmlCreateNode("root", XMLNODE_ELEMENT);
    hChildNode := XmlCreateNodeFromXml("<child1 attr1='avalue1'>childvalue1</child1>"
                                  "<child2 attr1='avalue2'>childvalue2</child2>");
    XmlAppendChild(hDocument, hRootNode);
    XmlAppendChild(hRootNode, hChildNode);
    hResult := XmlSelectSingleNode(hDocument, "/root/child2");
    XmlGetAttributeByName(hResult, "attr1", sAttrValue);
    XmlSetNodeAttribute(hResult, "attr1", "new avalue");
    XmlGetXml(hDocument, sXmlString);
  end TMain;
Parent topic: XML Functions
Related concepts
Creating an Empty XML Document
Related reference
XmlCreateDocumentFromFile Function
XmlCreateDocumentFromXml Function
XML Sample


XmlCreateDocumentFromFile Function

Action

Loads an XML document from a file. You have to pass the absolute filename. If you want to load XML documents from files in the data section, use GetDataFilePath to get the absolute filename.

Include file

XmlAPI.bdh

Syntax

XmlCreateDocumentFromFile( in sFilename : string ): number;

Return value

  • document handle if successful

  • 0 otherwise

Parameter | Description
sFilename | Filename of the XML file that should be loaded!

Example

dcltrans
  transaction TMain
  var
hDocument, hOrderItem : number;
sAttrValue            : string;
  begin
    hDocument := XmlCreateDocumentFromFile("C:\\MyXMLDocuments\\Order.xml");
    hOrderItem := XmlSelectSingleNode(hDocument, "//OrderItem[1]");
    XmlGetAttributeByName(hOrderItem, "price", sAttrValue);
  end TMain;
Parent topic: XML Functions
Related concepts
Loading an XML Document
Related reference
XmlCreateDocument Function
XmlCreateDocumentFromXml Function
GetDataFilePath Function
XML Sample


XmlCreateDocumentFromXml Function

Action

Loads an XML document from a string that contains a valid XML content.

Include file

XmlAPI.bdh

Syntax

XmlCreateDocumentFromXml( in sXmlString : string ): number;

Return value

  • document handle if successful

  • 0 otherwise

Parameter | Description
sXmlString | String containing a valid XML document

Example

dcltrans
  transaction TMain
  var
 hDocument, hResult     : number;
 sAttrValue, sXmlString : string;
  begin
    hDocument := XmlCreateDocumentFromXml( "<root><child1 attr1='avalue1'>childvalue1</child1>"
                 "<child2 attr1='avalue2'>childvalue2</child2></root>");
    hResult := XmlSelectSingleNode(hDocument, "/root/child2");
    XmlGetAttributeByName(hResult, "attr1", sAttrValue);
    XmlSetNodeAttribute(hResult, "attr1",  "new avalue");
    XmlGetXml(hDocument, sXmlString);
  end TMain;
Parent topic: XML Functions
Related concepts
Loading an XML Document
Related reference
XmlCreateDocumentFromFile Function
XmlCreateDocument Function
XML Sample


XmlCreateNode Function

Action

If you do not specify a special node type, XmlCreateNode creates a new XML element node of specified name. The node can then be added as root node to a document or as child node to another XML element node. To set the value/attributes of the node use XmlSetNodeValue, XmlSetNodeAttribute.

To create a different type (e.g.: COMMENT, CDATA, ...) of XML node, pass the desired type as 2nd parameter. The name parameter will be ignored for other types than the element or attribute type.

Include file

XmlAPI.bdh

Syntax

XmlCreateNode( in sNodeName  : string,
               in nNodeType  : number optional,
               in sNamespace : string optional ): number;

Return value

  • node handle if successful

  • 0 otherwise

Parameter | Description
sNodeName | Name of the node that will be created
nNodeType

(optional) Type of the node that should be created. If omitted an XML element will be created: Possible types:

  • XMLNODE_ELEMENT

  • XMLNODE_ATTRIBUTE

  • XMLNODE_TEXT

  • XMLNODE_CDATA_SECTION

  • XMLNODE_ENTITY_REFERENCE

  • XMLNODE_ENTITY

  • XMLNODE_PROCESSING_INSTRUCTION

  • XMLNODE_COMMENT

  • XMLNODE_DOCUMENT_FRAGMENT
sNamespace

(optional)

String defining the namespace Uniform Resource Identifier (URI).

If specified, the node is created in the context of the namespaceURI with the prefix specified on the node name. If the sNodeName parameter does not have a prefix, this is treated as the default namespace.

Example

dcltrans
  transaction TMain
  var
    hDocument, hResult, hNewNode : number;
  begin
    hDocument := XmlCreateDocumentFromXml( "<root><child1 attr1='avalue1'>childvalue1</child1>"
                 "<child2 attr1= 'avalue2'>childvalue2</child2></root>");
    hNewNode := XmlCreateNode("child3");
    hResult := XmlSelectSingleNode(hDocument, "/root"):
    XmlAppendChild(hResult, hNewNode);
  end TMain;
Parent topic: XML Functions
Related concepts
Creating Nodes
Related reference
XmlCreateNodeFromXml Function
XmlSetNodeValue Function
XmlSetNodeAttribute Function
XML Sample


XmlCreateNodeFromXml Function

Action

Creates an XML node from a string that contains a valid XML representation of an XML node.

The string can also contain complex nodes with child nodes, e.g.: <cars><car>BMW</car><car>Volvo</car></cars>

Include file

XmlAPI.bdh

Syntax

XmlCreateNodeFromXml( in sXmlString : string ): boolean;

Return value

  • true if successful

  • false otherwise

Parameter | Description
sXmlString | Valid XML string

Example

dcltrans
  transaction TMain
  var
  hDocument, hResult, hNewNode : number;
  begin
    hDocument := XmlCreateDocumentFromXml( "<root><child1 attr1='avalue1'>childvalue1</child1>"
                 "<child2 attr1= 'avalue2'>childvalue2</child2></root>");
    hNewNode := XmlCreateNodeFromXml("<child3 attr1='avalue3'>childvalue3</child3>");
    hResult := XmlSelectSingleNode(hDocument, "/root");
    XmlAppendChild (hResult, hNewNode);
  end TMain;
Parent topic: XML Functions
Related reference
XmlCreateNode Function


XmlGetChildNodes Function

Action

XmlGetChildNodes returns a handle to a list of nodes (nodelist) that contains all child handles of the passed node/document handle. To access a node in the nodelist you have to use XmlGetItem. To determine the number of nodes in the nodelist, use XmlGetCount. If you call this method on an element node with a text value the function will return 1 because the text value itself is a child node of type text.

If you want to access a specific child node, you can also call XmlGetChildByIndex to get a direct reference to a child node.

Include file

XmlAPI.bdh

Syntax

XmlGetChildNodes( in hDocNode : number ): number;

Return value

  • nodelist handle if successful

  • 0 if failed

Parameter | Description
hDocNode | Handle to an XML node/document If the handle is a document handle, the root elements will be returned. Normally there is only one root element - except if there are processing instructions.

Example

dcltrans
  transaction TMain
  var
    hDocument, hRoot, hRootChildren: number;
  begin
    hDocument := XmlCreateDocumentFromXml( "<root><child1 attr1='avalue1'>childvalue1</child1>"
                  "<child2 attr1= 'avalue2'>childvalue2</child2></root>");
    hRoot := XmlSelectSingleNode(hDocument, "/root");
    hRootChildren := XmlGetChildNodes(hRoot);
  end TMain;
Parent topic: XML Functions
Related concepts
Browsing the XML Document
Related reference
XmlGetChildByIndex Function
XmlGetCount Function
XmlSelectNodes Function
XmlGetItem Function
XML Sample


XmlGetChildByIndex Function

Action

Returns a handle to a child node of the passed node/document handle. The child node is identified by its index where the first child has index 0.

A document node can also have multiple child nodes because XML documents can have multiple processing instructions on the first level. But there can only be one element node at the root level of a document.

Include file

XmlAPI.bdh

Syntax

XmlGetChildByIndex( in hDocNode : number,
                    in nIndex   : number ): number;

Return value

  • node handle if successful

  • 0 if failed

Parameter | Description
hDocNode | Handle to an XML node/document If the handle is a document handle, a root element will be returned. Normally there is only one root element - except if there are processing instructions.
nIndex | Child index that should be returned. Index of first child is 0.

Example

dcltrans
  transaction TMain
  var
   hDocument, hRoot, hRootChild: number;
  begin
    hDocument := XmlCreateDocumentFromXml( "<root><child1 attr1='avalue1'>childvalue1</child1>"
                 "<child2 attr1= 'avalue2'>childvalue2</child2></root>");
    Root     := XmlSelectSingleNode(hDocument, "/root");
    hRootChild:= XmlGetChildByIndex(hRoot, 0 );
  end TMain;
Parent topic: XML Functions
Related reference
XmlGetChildNodes Function


XmlSelectSingleNode Function

Action

Executes an X-Path query on the passed handle (either document or node) and returns the first resulting node handle. If the query returns no handles, XmlSelectSingleNode returns 0. For a detailed description of X-Path, check the specification at http://www.w3c.org. The root node for the query is the passed node/document handle.

Include file

XmlAPI.bdh

Syntax

XmlSelectSingleNode( in hDocNode : number,
                     in sQuery   : string ): number;

Return value

  • node handle if successful

  • 0 otherwise

Parameter | Description
hDocNode | A valid document or node handle
sQuery | X-Path query that will be executed on the handle that is passed.

Example

dcltrans
  transaction TMain
  var
   hDocument, hResult, hItem : number;
   sAttrValue                : string;
  begin
    hDocument := XmlCreateDocumentFromFile("C:\\MyXMLDocuments\\Order.xml");
    hItem := XmlSelectSingleNode(hDocument, "//OrderItem[1]");
    XmlGetAttributeByName(hItem, "price", sAttrValue);
  end TMain;
Parent topic: XML Functions
Related concepts
Executing X-Path Queries
Related reference
XmlSelectNodes Function


XmlSelectNodes Function

Action

Executes an X-Path query on the passed handle (either document or node) and returns the resulting handles in a node list. If the query returns no handles, XmlSelectNodes returns a valid nodelist handle with no containing nodes (so XmlGetCount would return 0). For a detailed description of X-Path, check the specification at http://www.w3c.org. The root node for the query is the passed node/document handle.

Include file

XmlAPI.bdh

Syntax

XmlSelectNodes( in hDocNode : number,
                in sQuery   : string ): number;

Return value

  • node list handle if successful

  • 0 otherwise

Parameter | Description
hDocNode | A valid document or node handle
sQuery | X-Path query that will be executed on the handle that is passed.

Example

dcltrans
  transaction TMain
  var
   hDocument, hResult : number;
    hOrderItems, hItem : number;
    hCount, itemIx     : number;
    sAttrValue         : string;
  begin
    hDocument : XmlCreateDocumentFromFile("C:\\MyXMLDocume nts\\Order.xml");
    hOrderItems := XmlSelectNodes(hDocument, "//OrderItem");
    hCount := XmlGetCount(hOrderItems);

    for itemIx := 0 to hCount - 1 do
      hItem := XmlGetItem(hOrderItems, itemIx);
      XmlGetAttributeByName(hItem, "price", sAttrValue);
    end;
  end TMain;
Parent topic: XML Functions
Related concepts
Executing X-Path Queries
Related reference
XmlGetCount Function
XmlGetItem Function
XmlGetChildNodes Function
XML Sample
XmlSelectSingleNode Function


XmlRemoveChild Function

Action

Removes the node from its current parent node (can be either a node or the document). The whole node will be removed from its parent- with all the child nodes. After calling this function the node handle can be appended to another node or document.

Include file

XmlAPI.bdh

Syntax

XmlRemoveChild( in hNode : number ): boolean;

Return value

  • true if successful

  • false otherwise

Parameter | Description
hNode | XML node that will be deleted

Example

dcltrans
  transaction TMain
  var
    hDocument, hResult: number;
  begin
    hDocument := XmlCreateDocumentFromXml("<root><child1 attr1='avalue1'>childvalue1</child1>"
                  "<child2 attr1= 'avalue2'>childvalue2</child2></root>");
    hResult := XmlSelectSingleNode(hDocument, "/root/child2");
    XmlRemoveChild(hResult);
  end TMain;
Parent topic: XML Functions
Related concepts
Deleting Nodes
Related reference
XmlAppendChild Function
XmlReplaceNode Function


XmlReplaceNode Function

Action

XmlReplaceNode replaces the node passed in parameter hDestNode with the node in parameter hSourceNode. The source node must not be a child of another node - you would have to remove the node first from its current parent. The replaced node can afterwards be used to append to another node.

XmlReplaceNode simply does the following things: Removes hDestNode from the parent and appends hSourceNode to the former parent of hDestNode.

Include file

XmlAPI.bdh

Syntax

XmlReplaceNode( in hDestNode   : number,
                in hSourceNode : number ): boolean;

Return value

  • true if successful

  • false otherwise

Parameter | Description
hDestNode | XML node handle that will be replaced by hSourceNode
hSourceNode | XML node handle that will replace hDestNode

Example

dcltrans
  transaction TMain
  var
    hDocument, hResult, hNewNode : number;
  begin
    hDocument := XmlCreateDocumentFromXml("<root><child1 attr1='avalue1'>childvalue1</child1>"
                  "<child2 attr1= 'avalue2'>childvalue2</child2></root>");
    hNewNode := XmlCreateNodeFromXml("<child3 attr1='avalue3'>childvalue3</child3>");
    hResult := XmlSelectSingleNode(hDocument,"/root");
    XmlReplaceNode(hResult, hNewNode);
  end TMain;
Parent topic: XML Functions
Related concepts
Working with Nodes
Related reference
XmlAppendChild Function
XmlRemoveChild Function


XmlGetCount Function

Action

XmlGetCount takes a nodelist handle and returns the number of nodes that are stored in this list. A nodelist will be returned by XmlGetChildNodes and XmlSelectNodes. To access a node in the nodelist call XmlGetItem.

Include file

XmlAPI.bdh

Syntax

XmlGetCount( in hNodeList : number ): number;

Return value

  • number of nodes

Parameter | Description
hNodeList | A valid node list handle

Example

dcltrans
  transaction TMain
  var
    hDocument, hResult : number;
    hOrderItems, hItem : number;
    hCount, itemIx     : number;
    sAttrValue         : string;
  begin
    hDocument := XmlCreateDocumentFromFile("C:\\MyXMLDocuments\\Order.xml");
    hOrderItems := XmlSelectNodes(hDocument, "//OrderItem");
    hCount := XmlGetCount(hOrderItems);

    for itemIx := 0 to hCount - 1 do
      hItem := XmlGetItem(hOrderItems, itemIx);
      XmlGetAttributeByName(hItem, "price", sAttrValue);
    end;
  end TMain;
Parent topic: XML Functions
Related concepts
Browsing the XML Document
Related reference
XmlSelectNodes Function
XmlGetItem Function
XmlGetChildNodes Function
XML Sample


XmlGetItem Function

Action

XmlGetItem returns a node from the nodelist. The nodes are identified by their index in the list beginning with 0 for the first. Use XmlGetCount to determine the number of nodes in the nodelist. You can iterate through the nodes in the nodelist by accessing the nodes from index 0 to XmlGetCount - 1.

If you want to access a specific child node, you can also call XmlGetChildByIndex to get a direct reference to a child node.

Include file

XmlAPI.bdh

Syntax

XmlGetItem( in hNodeList  : number,
            in nIndex     : number ): number;

Return value

  • handle to the node
  • 0 if failed/wrong index
Parameter | Description
hNodeList | A valid node list
nIndex | Index of the node that should be returned. Index for first element is 0.

Example

dcltrans
  transaction TMain
  var
   hDocument, hResult : number;
    hOrderItems, hItem : number;
    hCount, itemIx     : number;
    sAttrValue         : string;
  begin
    hDocument   := XmlCreateDocumentFromFile("C:\\MyXMLDocuments\\Order.xml");
    hOrderItems := XmlSelectNodes(hDocument, "//OrderItem");
    hCount      := XmlGetCount(hOrderItems);

    for itemIx := 0 to hCount - 1 do
      hItem := XmlGetItem(hOrderItems, itemIx);
      XmlGetAttributeByName(hItem, "price", sAttrValue);
    end;
  end TMain;
Parent topic: XML Functions
Related reference
XmlGetCount Function
XmlSelectNodes Function
XmlGetChildNodes Function
XML Sample


XmlGetInnerXml Function

Action

Returns the inner XML representation of the passed node/document handle. Ensure that the string buffer is large enough to hold the XML. If you pass a document handle you get the inner XML representation of the whole document. If you pass a node handle, you will get the inner representation of the whole node (with all child nodes). Inner represenation means that the node tag itself will not be contained in the buffer.

Include file

XmlAPI.bdh

Syntax

XmlGetInnerXml( in    hDocNode   : number,
                inout sXmlString : string,
                in    nMaxXmlLen : number optional ): boolean;

Return value

  • true if successful

  • false otherwise

Parameter | Description
hDocNode | A valid node/document handle
sXmlString | String variable that receives the XML representation
nMaxXmlLen | Maximum length of the string to return (optional). If this parameter is omitted or set to STRING_COMPLETE all available data is stored in sXmlString.

Example

dcltrans
  transaction TMain
  var
    hDocument, hResult : number;
    sXmlString         : string;
  begin
    hDocument := XmlCreateDocumentFromXml(
                  "<root><child1  attr1='avalue1'>childvalue1</child1>"
                  "<child2 attr1= 'avalue2'>childvalue2</child2></root>");
    hResult := XmlSelectSingleNode(hDocument, "/root/child2"):
    XmlRemoveChild(hResult );
    XmlGetInnerXml(hDocument, sXmlString);
  end TMain;
Parent topic: XML Functions


XmlGetXml Function

Action

Returns the XML representation of the passed node/document handle. Ensure that the string buffer is large enough to hold the XML. If you pass a document handle you get the XML representation of the whole document. If you pass a node handle, you will get the representation of the whole node (with all child nodes).

Include file

XmlAPI.bdh

Syntax

XmlGetXml( in    hDocNode   : number,
           inout sXmlString : string,
           in    nMaxXmlLen : number optional ): boolean;

Return value

  • true if successful

  • false otherwise

Parameter | Description
hDocNode | A valid node/document handle.
sXmlString | String variable that receives the XML representation.
nMaxXmlLen | Maximum length of the string to return (optional). If this parameter is omitted or set to STRING_COMPLETE all available data is stored in sXmlString.

Example

dcltrans
  transaction TMain
  var
    hDocument, hResult : number;
    sXmlString         : string;
  begin
    hDocument := XmlCreateDocumentFromXml("<root><child1 attr1='avalue1'>childvalue1</child1>"
               "<child2 attr1= 'avalue2'>childvalue2</child2></root>");
    hResult := XmlSelectSingleNode(hDocument, "/root/child2");
    XmlRemoveChild(hResult );
    XmlGetXml(hDocument, sXmlString);
  end TMain;
Parent topic: XML Functions


XmlSetNodeAttribute Function

Action

Sets the value of an attribute of the passed node. The method either overwrites the value of an existing attribute or creates a new attribute with the specified name.

Include file

XmlAPI.bdh

Syntax

XmlSetNodeAttribute( in  hNode      : number,
                     in  sAttrName  : string,
                     in  sAttrValue : string ): boolean;

Return value

  • true if successful

  • false otherwise

Parameter | Description
hNode | Handle to an XML node
sAttrName | Attribute name thats value should be set.
sAttrValue | New value for the attribute

Example

dcltrans
  transaction TMain
  var
    hDocument, hResult : number;
  begin
    hDocument := XmlCreateDocumentFromXml( "<root><child1 attr1='avalue1'>childvalue1</child1>"
                 "<child2 attr1= 'avalue2'>childvalue2</child2></root>");
    hResult := XmlSelectSingleNode(hDocument, "/root/child2");
    XmlSetNodeAttribute(hResult, "attr1", newavalue1");
  end TMain;
Parent topic: XML Functions
Related concepts
Working with Nodes
Related reference
XmlGetAttributeByName Function


XmlGetAttributeByIndex Function

Action

Returns the value of a nodes attribute. The attribute is identified by the attribute's index - beginning with 0 for the first attribute.

Include file

XmlAPI.bdh

Syntax

XmlGetAttributeByIndex( in  hNode : number,
                        in  hIndex       : number,
                        out sValue       : string,
                        in  nMaxValueLen : number optional ): boolean;

Return value

  • true if successful

  • false if failed

Parameter | Description
hNode | Handle to an XML node
hIndex | Index of the attribute that should be returned. Index for first element is 0.
sValue | String variable that receives the value of the attribute
nMaxValueLen | Maximum length of the string to return (optional). If this parameter is omitted or set to STRING_COMPLETE all available data is stored in sValue.

Example

dcltrans
  transaction TMain
  var
    hDocument, hResult : number;
    sValue: string;
  begin
    hDocument := XmlCreateDocumentFromXml("<root><child1 attr1='avalue1'>childvalue1</child1>"
                "<child2 attr1= 'avalue2'>childvalue2</child2></root>");
    hResult := XmlSelectSingleNode(hDocument, "/root/child2");
    XmlGetAttributeByIndex(hResult, 0, sValue);
  end TMain;
Parent topic: XML Functions
Related reference
XmlGetAttributeByName Function


XmlGetAttributeByName Function

Action

Returns the value of a nodes attribute. The attribute is identified by the attributes name.

Include file

XmlAPI.bdh

Syntax

XmlGetAttributeByName( in    hNode      : number,
                       in    sAttrName  : string,
                       inout sValue     : string,
                       in  nMaxValueLen : number optional ): boolean;

Return value

  • true if successful

  • false if failed

Parameter | Description
hNode | Handle to an XML node
sAttrName | Name of the attribute that should be returned.
sValue | String variable that receives the value of the attribute
nMaxValueLen | Maximum length of the string to return (optional). If this parameter is omitted or set to STRING_COMPLETE all available data is stored in sValue.

Example

dcltrans
  transaction TMain
  var
    hDocument, hResult : number;
    sValue             : string;
  begin
    hDocument := XmlCreateDocumentFromXml( "<root><child1 attr1='avalue1'>childvalue1</child1>"
               "<child2 attr1='avalue2'>childvalue2</child2>");
    hResult := XmlSelectSingleNode(hDocument, "/root/child2");
    XmlGetAttributeByName(hResult, "attr1", sValue);
  end TMain;
Parent topic: XML Functions
Related reference
XmlGetAttributeByIndex Function


XmlGetAttributeCount Function

Action

Returns the number of attributes that are defined for the passed node. You can afterwards access the attribute values with XmlGetAttributeByIndex.

Include file

XmlAPI.bdh

Syntax

XmlGetAttributeCount( in hNode : number ): number;

Return value

  • number of attributes

Parameter | Description
hNode | Handle to an XML node

Example

dcltrans
  transaction TMain
  var
    hDocument, hResult, nAttrCount : number;
  begin
    hDocument := XmlCreateDocumentFromXml( "<root><child1 attr1='avalue1'>childvalue1</child1>"
                  "<child2 attr1= 'avalue2'>childvalue2</child2></root>");
    hResult := XmlSelectSingleNode(hDocument, "/root/child2");
    nAttrCount := XmlGetAttributeCount(hResult );
  end TMain;
Parent topic: XML Functions
Related concepts
Getting Node and Attribute Values
Related reference
XmlGetAttributeByIndex Function


XmlGetNodeName Function

Action

Returns the name of the passed node.

Include file

XmlAPI.bdh

Syntax

XmlGetNodeName( in     hNode        : number,
                inout  sName        : string,
                in     nMaxNameLen  : number optional ): boolean;

Return value

  • true if successful

  • false otherwise

Parameter | Description
hNode | Handle to an XML node.
sName | String variable that receives the name of the node.
nMaxNameLen | Maximum length of the string to return (optional). If this parameter is omitted or set to STRING_COMPLETE all available data is stored in sName.

Example

dcltrans
  transaction TMain
  var
   hDocument, hResult : number;
   sName              : string;
  begin
    hDocument := XmlCreateDocumentFromXml( "<root><child1 attr1='avalue1'>childvalue1</child1>"
                "<child2 attr1= 'avalue2'>childvalue2</child2></root>");
    hResult := XmlSelectSingleNode(hDocument, "/root/child2");
    XmlGetNodeName(hResult, sName);
  end TMain;
Parent topic: XML Functions


XmlGetNodeType Function

Action

Returns the type of the node passed as paramter. For a description of all possible node types please see the constant definitions in the XmlAPI.bdh file.

Include file

XmlAPI.bdh

Syntax

XmlGetNodeType( in hNode: number ): number;

Return value

  • type of node

Parameter | Description
hNode | Handle to an XML node

Example

dcltrans
  transaction TMain
  var
    hDocument, hResult, nType: number;
  begin
    hDocument := XmlCreateDocumentFromXml("<root><child1 attr1='avalue1'>childvalue1</child1>"
                                        "<child2 attr1=  'avalue2'>childvalue2</child2></root>");
    hResult := XmlSelectSingleNode(hDocument, "/root");
    nType := XmlGetNodeType(hResult);

    if(nType = XMLNODE_ELEMENT) then
      writeln("Root node is of type ELEMENT");
    end;

    if(nType = XMLNODE_TEXT) then
      writeln("Root node is of type TEXT");
    end;
  end TMain;
Parent topic: XML Functions


XmlSetNodeValue Function

Action

Sets the text value of the passed node. Use XmlGetNodeValue to retrieve the current text value of a node.

Include file

XmlAPI.bdh

Syntax

XmlSetNodeValue (in hNode     : number,
                 in sNewValue : string ): boolean;

Return value

  • true if successful

  • false otherwise

Parameter | Description
hNode | Handle to an XML node
sNewValue | New node value

Example

dcltrans
  transaction TMain
  var
    hDocument, hResult : number;
  begin
    hDocument := XmlCreateDocumentFromXml( "<root><child1 attr1='avalue1'>childvalue1</child1>"
                "<child2 attr1= 'avalue2'>childvalue2</child2></root>");
    hResult := XmlSelectSingleNode(hDocument, "/root/child2");
    XmlSetNodeValue(hResult, "newchildvalue2");
  end TMain;
Parent topic: XML Functions
Related concepts
Working with Nodes


XmlGetNodeValue Function

Action

Returns the text value of the node. If the node is of type text the value of this node will be returned. If the node is an element node - the values of the direct child text nodes will be returned. If the node has no value or just other child nodes, the method returns an empty string.

Include file

XmlAPI.bdh

Syntax

XmlGetNodeValue( in     hNode        : number,
                 inout  sValue       : string,
                 in     nMaxValueLen : number optional ): boolean;

Return value

  • true if successful

  • false otherwise

Parameter | Description
hNode | Handle to an XML node.
sValue | String variable that receives the value of the node.
nMaxValueLen | Maximum length of the string to return (optional). If this parameter is omitted or set to STRING_COMPLETE all available data is stored in sValue.

Example

dcltrans
  transaction TMain
  var
    hDocument, hResult : number;
  sValue             : string;
  begin
    hDocument := XmlCreateDocumentFromXml( "<root><child1 attr1='avalue1'>childvalue1</child1>"
               "<child2 attr1= 'avalue2'>childvalue2</child2></root>");
    hResult := XmlSelectSingleNode(hDocument, "/root/child2");
    XmlGetNodeValue(hResult, sValue);
  end TMain;
Parent topic: XML Functions
Related concepts
Getting Node and Attribute Values
Related reference
XmlGetNodeTypedValue Function


XmlGetNodeTypedValue Function

Action

Returns the typed value of a node. A Typed value is the text representation of all sub text node values of the passed node. If the node has only a text value - this will be the returned string. If the node has several child nodes, the returned string will be the concatenated string of the text value of the child nodes.

Include file

XmlAPI.bdh

Syntax

XmlGetNodeTypedValue( in    hNode        : number,
                      inout sValue       : string,
                      in    nMaxValueLen : number optional ): boolean;

Return value

  • true if successful

  • false otherwise

Parameter | Description
hNode | Handle to an XML node
sValue | String variable that receives the typed value of the node
nMaxValueLen | Maximum length of the string to return (optional). If this parameter is omitted or set to STRING_COMPLETE all available data is stored in sValue.

Example

dcltrans
  transaction TMain
  var
    hDocument, hResult : number;
    sValue             : string;
  begin
    hDocument := XmlCreateDocumentFromXml( "<root><child1 attr1='avalue1'>childvalue1</child1>"
               "<child2 attr1= 'avalue2'>childvalue2</child2></root>");
    hResult := XmlSelectSingleNode(hDocument, "/root");
    XmlGetNodeTypedValue(hResult, sValue);
  end TMain;
Parent topic: XML Functions
Related concepts
Getting Node and Attribute Values
Related reference
XmlGetNodeValue Function


XmlSetNamespaces Function

Action

Sets the namespaces and the prefix for the namespaces that will be recognized by the XML parser.

If no namespace is defined, the parser will recognize all namespaces that are defined in the root node with the prefixes that are defined in the document.

The namespace definition string has to be defined with xmlns:PREFIX= 'URI'. Multiple namespaces can be defined in the string - seperated by blank.

Example: xmlns:NS1='http://testns1.org' xmlns:NS2='http://testns2.org'

Include file

XmlAPI.bdh

Syntax

XmlSetNamespaces( in hDoc        : number,
                  in sNamespaces : string ): boolean;

Return value

  • true if successful

  • false otherwise

Parameter | Description
hDoc | Handle to an XML document
sNamespaces | Namespaces definition string Default the parser will recognize all namespaces that are defined in the root node with the prefixes that are defined in the document.

Example

dcltrans
  transaction TMain
  var
    hDocument, hResult : number;
  begin
    hDocument := XmlCreateDocumentFromXml( "<ns1:root xmlns:ns1='http://test.org' ><child1 attr1='avalue1'>childvalue1</child1>"
                 "<child2 attr1= 'avalue2'>childvalue2</child2></ns1:root>");
    XmlSetNamespaces(hDocument, "xmlns:ns1='http://test.org'nxmlns:ns2='http://test2.org'");
    hResult := XmlSelectSingleNode(hDocument, "/ns1:root/child2");
    XmlSetNodeAttribute(hResult, "attr1", "newavalue1");
  end TMain;
Parent topic: XML Functions
Related concepts
Default Namespaces in XML


XmlSetOption Function

Action

Allows enabling/disabling different XML parsing options.

Include file

XmlAPI.bdh

Syntax

XmlSetOption( in nOption : number,
              in bValue  : boolean ): boolean;

Return value

  • true if successful

  • false otherwise

Parameter | Description
nOption

Option that should be either enabled (true) or disabled (false). Current option values are:

  • XML_OPT_RESOLVE_HREF (default: disabled) If enabled, XML items that are referenced with an href tag will be replaced with the referenced XML node.

  • XML_OPT_RESOLVE_EXTERNALS (default: disabled) If enabled, external referenced documents will be resolved.

  • XML_OPT_PRESERVE_WHITESPACE (default: disabled) If enabled, white spaces will be preserved when parsing XML content.
bValue | True to enable the option, false to disable it.

Example

dcltrans
  transaction TMain
  var
    hDocument  : number;
    sXmlString : string;
  begin
    XmlSetOption(XML_OPT_PRESERVE_WHITESPACE, true);
    hDocument := XmlCreateDocumentFromXml("<root>          <child1 attr1='avalue1'>childvalue1</child1>"
                                           "<child2 attr1= 'avalue2'>childvalue2</child2></root>");
    XmlGetXml(hDocument, sXmlString);
    writeln(sXmlString);
  end TMain;

Parent topic: XML Functions


XML Basics

This section describes some basic concepts that should be known when working with XML documents.

  • XML Document Structure
    Provides an overview of the XML document structure.
  • X-Path Queries
    Describes how to execute queries against an XML document and retrieve the queried node/nodes.
  • XML Documents
    Provides an overview of XML documents and describes how to get a document handle.
  • Namespaces in XML
    Provides an overview of the attributes of a node, namespaces.
  • XML First Steps
    Lists the first steps and basic concepts for the XML functions.
Parent topic: XML Functions


XML Document Structure

The following figure gives you an overview of an XML document. An XML document contains XML nodes of different types. Nodes of type "Element" can have child nodes and therefore complex structures can be defined in an XML document.

Raw XML Content | Type of Node | Value | Number of Children
<?xml version="1.0" ?> | Processing Instruction |  |
<Order> | Element |  | 3
<!-- This is an order > | Comment | This is an order |
<Name> | Element |  | 1
Scott Bradley | Text | Scott Bradley |
</Name> |  |  |
<OrderItems> | Element |  | 1
<Item id="1"> | Element with Attribute |  | 1
Lord of the Rings | Text | Lord of the Rings |
</Item> |  |  |
</OrderItems> |  |  |
</Order> |  |  |

The left column shows you the raw XML content. The second column shows you the type of a node. As you can see, there are different types of nodes in an XML document. The third column shows you the value of a node and the fourth column displays the number of children a specific node has.

Each element in an XML document is called a node - where there are different types of nodes. Element nodes are those nodes that are defined as follows: "<{Name of node}>". Element nodes need a closing node tag ("</ {Name of node}>") if the node has child nodes - otherwise it would be possible to define an element node that has no child nodes as the following: "<{Name of node} />", e.g.: "<Order />"

Element nodes can have multiple attributes which are defined in the starting tag of a node - you can see in the example above that the node named "Item" has an attribute called "id" with the value "1".

Element nodes can have a text value - you can see in the example above that the node named "Name" has the text value "Scott Bradley". Although it seems that the value belongs to the node name, the text value itself is a separate node of type text and is a child of "Name".

The example above shows us two more node types of common use: <?: marks a process instruction: these are nodes telling the XML parser specific things about the XML document. <!--:marks a comment node: this type of node allows you to define comments.

Parent topic: XML Basics
Related concepts
XML Documents
Creating an Empty XML Document
Browsing the XML Document
Loading an XML Document


X-Path Queries

X-Path allows you to execute queries against an XML document and retrieves the queried node/nodes. X-Path can be very complex. For a detailed description, see the X-Path specification at http://www.w3c.org.

<Order>
  <Name>Scott Bradley</Name>
  <OrderItems>
    <Item id="1">Lord of the Rings</Item>
    <Item id="2">Star Wars - Episode II</Item>
  </OrderItems>
  <Price>45.90</Price>
</Order>

To query a specific node in the document you can specify the exact path to an element. Each element will be addressed by its name. So to query the name element we use the following query: "/Order/Name" You see that we have to use a slash prior to the element name. The query engine will start at the document root and searches for a node named "Order". If the node is found, it searches for a subnode named "Name".

The second possibility is to tell the query engine to search for all nodes with a specific name. So, to query all nodes with name "Item" we would use the following statement: "//Item" You see that we use a double slash in this case telling the query engine that it should look for all nodes in the document to match the name.

If we want to query an element that is defined multiple times - like the "Item" node in the example above - we can either query for all nodes with name "Item" or we can tell the engine to just return one of the two identified by its index. So, to query the 2nd "Item" node we would use one of the following statements: "/Order/OrderItems/Item[2]" or "//Item[2]"

If we want to query an "Item" node with a special attribute value - for example the one with id = "2" we would use the following query: "/Order/OrderItems/Item[@id='2']" or "//Item[@id='2']" As you can see we can tell the engine to only return the Item node(s) where the attribute named "id" has the value '2'.

Parent topic: XML Basics
Related concepts
Executing X-Path Queries


XML Documents

The API functions provided by Silk Performer work on handles that represent either a whole XML document, a single node or a list of nodes. Depending on the type of handle, there are different functions that can be used to operate on those type of nodes.

There are different ways to get a document handle. You can either load an existing document from a file, load an existing document from a valid XML string or create a new document from scratch. The methods responsible for this are XmlCreateDocument, XmlCreateDocumentFromFile and XmlCreateDocumentFromXml. All these functions return a handle to a document.

  • Types of Handles
    Lists the types of handles that can be returned by the API functions and have to be used as input parameters for those functions.
Parent topic: XML Basics
Related concepts
XML Document Structure
Creating an Empty XML Document
Browsing the XML Document


Types of Handles

The following table lists the types of handles that can be returned by the API functions and have to be used as input parameters for those functions to work with them. When a function returns a handle, you have to verify that the value is not 0. All methods return a 0 (NULL-Handle) in case of an error:

Type of Handles | Returned by Functions | Description
Document | XmlCreateDocument XmlCreateDocumentFromFile XmlCreateDocumentFromXml | A document handle represents the virtual root node of an XML document. The children of this virtual document node are the top level nodes of the document. You can either iterate through those children or execute X-Path queries to query the whole document.
Node | XmlSelectSingleNode XmlGetItem XmlGetChildByIndex XmlCreateNode XmlCreateNodeFromXml | There are different types of XML nodes - to get an overview of those types, see the XML Basics section. XML Nodes can be queried with X-Path or can be accessed by iterating through a document. Nodes can be modified, deleted and added. An element node itself has child nodes - like the document node has it child nodes representing the top level nodes in the document.
NodeList | XmlGetChildNodes XmlSelectNodes | Nodelist handles store none, one or multiple node handles which can be accessed with the XmlGetItem function. So if you want to operate on a node in a nodelist you first have to get the node handle out of the list and operate on that handle.
Parent topic: XML Documents


Namespaces in XML

Namespaces in XML can be defined as attributes of a node. You define the namespace and the prefix to use for it. If your document contains namespaces and you want to execute X-Path Queries where you want to find nodes that are in specific namespaces, you have to tell the parser which namespaces you want to use and which prefixes to use for this namespaces. XmlSetNamespaces allows to set the namespaces that should be recognized by the parser. The definition is like the definition in the XML document. xmlns:prefix=namespace. Multiple definitions can be separated by blank. See the following document:

<root xmlns:ns1='MyName1' xmlns:ns2='MyName2'>
<ns1:child1>value1</ns1:child1>
<ns2:child2>value2</ns2:child2>
</root>

If you want to execute a query like /root/child1 you have to define child1 in a namespace with a namespace prefix of your choice (doesn't have to be the same prefix like in the source document), and you have to tell the compiler which namespace should be assigned to that prefix. The table below describes the different possibilities to execute the same query:

X-Path | SetNamespaces
/root/ns1:child1 | xmlns:ns1='MyName1'
/root/myprefix:child1 | xmlns:myprefix='MyName1'
dcltrans
transaction TMain
var
  hDoc, hChild : number;
  sValue, sXML : string;
begin
  hDoc   := XmlCreateDocumentFromXml("<root xmlns:ns1='MyName1'><ns1:child>value1</ns1:child></root>");
  XmlSetNamespaces(hDoc, "xmlns:ns1='MyName1'");
  hChild := XmlSelectSingleNode("/root/ns1:child");
  ...
  XmlFreeHandle(hChild);
  XmlFreeHandle(hDoc);
end TMain;
  • Default Namespaces in XML
    Describes how to define default namespaces for elements using the xmlns attribute.
Parent topic: XML Basics


Default Namespaces in XML

XML namespaces can be used for more than defining namespace prefixes and using those prefixes with element names. You can also define default namespaces for elements using the xmlns attribute. To query elements with default namespaces you must call XmlSetNamespaces using a prefix name. The prefix name can later be used in an X-Path query.

See the following document:

<root>
  <child1 xmlns=’MyName1’>value1</child1>
</root>

To execute a query like /root/child1 you must define the namespace of child1 with XmlSetNamespaces using a self-defined prefix.

dcltrans
  transaction TMain
  var
    hDoc, hChild : number;
    sValue, sXML : string;
  begin
    hDoc   := XmlCreateDocumentFromXml("<root><child1 xmlns=’MyName1’>value1<child></root>");
    XmlSetNamespaces(hDoc, "xmlns:myprefix='MyName1'");
    hChild := XmlSelectSingleNode("/root/myprefix:child");
    ...
    XmlFreeHandle(hChild);
    XmlFreeHandle(hDoc);
  end TMain;
Parent topic: Namespaces in XML
Related reference
XmlSetNamespaces Function


XML First Steps

Silk Performer provides several API functions that allow you to work with XML documents, parse and verify XML values of web response documents. All these functions are based on an XML dom parser that ships with Silk Performer. This topic lists the first steps and basic concepts to use these functions.

  1. Creating an Empty XML Document
    Describes how to create an empty XML document.
  2. Loading an XML Document
    Describes how an XML file can be loaded from a file or from a string buffer.
  3. Determining the Handle for a Node
    Describes the two methods for determining the handle for a node.
  4. Getting Node and Attribute Values
    Provides an overview of the functions to get node and attribute values of a document.
  5. Creating Nodes
    Describes how newly created nodes can be appended at any place in the document.
  6. Deleting Nodes
    Describes how existing nodes can be removed from a document.
  7. Working with Nodes
    Describes the functions that you can use with nodes.
  8. XML Sample
    Demonstrates how to load an existing XML document from a file and modify it.
Parent topic: XML Basics
Related reference
XML Sample


Creating an Empty XML Document

The BDL API provides the function XMLCreateDocument to create an empty XML document. The function returns a handle to the created document. Use functions for creating and appending nodes to the document to build a valid XML document.

dcltrans
transaction TMain
var
  hDoc : number;
begin
  hDoc := XmlCreateDocument();
  ...
  XmlFreeHandle(hDoc);
end TMain;
Parent topic: XML First Steps
Next topic: Loading an XML Document
Related concepts
XML Documents
XML Document Structure
Browsing the XML Document
Related reference
XmlCreateDocument Function


Loading an XML Document

The BDL API provides two ways to load an XML file - it can be loaded from a file or from a string buffer.

XmlCreateDocumentFromFile

This function loads a document from a file and returns a handle to the document. Use functions for browsing the document to get values of nodes and attributes.

dcltrans
  transaction TMain
  var
    hDoc : number;
    sXmlFile : string;
  begin
    GetDataFilePath("order.xml", sXmlFile);
    hDoc := XmlCreateDocumentFromFile(sXmlFile);
    ...
    XmlFreeHandle(hDoc);
  end TMain;

XmlCreateDocumentFromXml

This functions loads a document from a string buffer and returns a handle to the document. Use functions for browsing the document to get values of nodes and attributes.

dcltrans
  transaction TMain
  var
    hDoc : number;
  begin
    hDoc := XmlCreateDocumentFromXml("<root><child>value1</child><child>value2</child></root>");
    ...
    XmlFreeHandle(hDoc);
  end TMain;
Parent topic: XML First Steps
Previous topic: Creating an Empty XML Document
Next topic: Determining the Handle for a Node
Related concepts
XML Document Structure
Related reference
XmlCreateDocumentFromFile Function
XmlCreateDocumentFromXml Function


Determining the Handle for a Node

You can determine the handle for a node by browsing through a document (start at the document root and explore all child nodes), or you can get specific nodes by executing an X-Path query.

  • Browsing the XML Document
    Describes how to iterate through all nodes in a document starting at the "virtual" document root node.
  • Executing X-Path Queries
    Describes how to execute X-Path queries on a document or on nodes of a document
Parent topic: XML First Steps
Previous topic: Loading an XML Document
Next topic: Getting Node and Attribute Values


Browsing the XML Document

The handle to a document is the handle to a "virtual" root node. The root node of an XML document would be the first child of the document handle. Typically, an XML document only has one root element - so you would always get the root node by getting the first child of the document. But if the root contains processing instructions (<?xml ... >), these instructions are also children of the document.

Starting at the "virtual" document root node, you can iterate through all nodes in a document. You can get the child nodes of a node with XmlGetChildNodes. This function returns a handle to a node list. A node list contains 0 or more node handles. These handles can be received with XmlGetItem with a 0 based index to the element in the list. The number of elements can be received with XmlGetCount on the node list. You can access a child node directly with XmlGetChildByIndex.

dcltrans
transaction TMain
var
  hDoc, hChildren, hRoot, hChild : number;
begin
  hDoc      := XmlCreateDocumentFromXml("<root><child>value1</child><child>value2</child></root>");
  hRoot     := XmlGetChildByIndex(hDoc, 0);
  hChildren := XmlGetChildNodes(hRoot);
  hChild    := XmlGetItem(hChildren, 1);
  ...
  XmlFreeHandle(hChild);
  XmlFreeHandle(hChildren);
  XmlFreeHandle(hRoot);
  XmlFreeHandle(hDoc);
end TMain;
Parent topic: Determining the Handle for a Node
Related concepts
XML Documents
XML Document Structure
Creating an Empty XML Document
Related reference
XmlGetCount Function
XmlGetChildNodes Function


Executing X-Path Queries

You can execute X-Path queries on a document or on nodes of a document. If you execute the query on the document, the root element is the initial point for the query - otherwise it is the node. There are two functions to execute an X-Path Query. XmlSelectNodes returns node list with all nodes that match the query. XmlSelectSingleNode returns the first node that matches the query. For a detailed description of X-Path, see the online documentation at http://www.w3c.org.

dcltrans
transaction TMain
var
  hDoc, hChildren, hRoot, hChild : number;
begin
  hDoc      := XmlCreateDocumentFromXml("<root><child>value1</child><child>value2</child></root>");
  hRoot     := XmlSelectSingleNode(hDoc, "/root");
  hChildren := XmlSelectNodes("/root/child");
  hChild    := XmlGetItem(hChildren, 1);
  ...
  XmlFreeHandle(hChild);
  XmlFreeHandle(hChildren);
  XmlFreeHandle(hRoot);
  XmlFreeHandle(hDoc);
  XmlFreeHandle(hDoc);
end TMain;
Parent topic: Determining the Handle for a Node
Related concepts
X-Path Queries
Related reference
XmlSelectNodes Function
XmlSelectSingleNode Function


Getting Node and Attribute Values

There are several functions to get node and attribute values of a document. All of these functions require a handle to a node. XmlGetNodeValue returns the text value associated with the node. XmlGetNodeTypedValue returns the node value expressed in its defined data type. If you have a look at the sample above, there are child elements with a text value (value1 and value2). XmlGetNodeValue on one of the nodes will return null because value1 and value2 are child nodes of the child elements. To get the test values (value1 and value2) you can either get the first child of one of the child nodes and use XmlGetNodeValue, or you use XmlGetNodeTypedValue on the child nodes directly.

dcltrans
transaction TMain
var
  hDoc, hChild, hTextNode : number;
  sValue : string;
begin
  hDoc      := XmlCreateDocumentFromXml("<root><child>value1</child><child>value2</child></root>");
  hChild    := XmlSelectSingleNode(hDoc, "/root/child[1]");
  hTextNode := XmlGetChildByIndex(hChild, 0);

  // following two functions will return the same value - sValue will contain value1
  XmlGetNodeValue(hTextNode, sValue);
  XmlGetNodeTypedValue(hChild, sValue);
  ...
  XmlFreeHandle(hChild);
  XmlFreeHandle(hTextNode);
  XmlFreeHandle(hDoc);
end TMain;

Attributes can be accessed by name or index. XmlGetAttributeCount returns the number of attributes defined in the passed node. XmlGetAttributeByName returns the value of the attribute identified by name. XmlGetAttributeByIndex returns the value of the attribute identified by the 0 based index.

dcltrans
transaction TMain
var
  hDoc, hChild : number;
  sValue : string;
begin
  hDoc   := XmlCreateDocumentFromXml("<root><child attr1='attrvalue1'>value1</child></root>");
  hChild := XmlSelectSingleNode(hDoc, "/root/child");

  // following two functions will both access attribute attr1 - sValue will contain attrvalue1
  XmlGetAttributeByName(hChild, "attr1", sValue);
  XmlGetAttributeByIndex(hChild, 0, sValue);
  ...
  XmlFreeHandle(hChild);
  XmlFreeHandle(hDoc);
end TMain;
Parent topic: XML First Steps
Previous topic: Determining the Handle for a Node
Next topic: Creating Nodes
Related reference
XmlGetAttributeByIndex Function
XmlGetNodeTypedValue Function
XmlGetNodeValue Function


Creating Nodes

Newly created nodes can be appended at any place in the document. Nodes can be created in two ways - either with XmlCreateNode, which is creating an empty node, or with XmlCreateNodeFromXml, which creates a node from a valid XML node representation. Those two functions return a new node handle which can then be used to append to an existing node in the document. XmlAppendChild is the function that allows you to append the created node to an existing node. The appended node will become a child node of the parent node.
dcltrans
transaction TMain
var
  hNode1, hNode2 : number;
begin
  hNode1 := XmlCreateNode("child");
  hNode2 := XmlCreateNodeFromXml("<child attr1='attrvalue1'>value1</child>");
    ...
  XmlFreeHandle(hNode1);
  XmlFreeHandle(hNode2);
end TMain;
Parent topic: XML First Steps
Previous topic: Getting Node and Attribute Values
Next topic: Deleting Nodes
Related reference
XmlCreateNode Function


Deleting Nodes

Existing nodes can be removed from a document. To delete a node you have to get the handle to that node by either iterating through the document till you have found the node or by querying for a specific node. XmlRemoveChild takes the node handle and removes the node (and all the child nodes) from the document. The node handle will still be valid - so you can remove it from one position and append the node to another. You can even append the node to another XML document.

Parent topic: XML First Steps
Previous topic: Creating Nodes
Next topic: Working with Nodes
Related reference
XmlRemoveChild Function


Working with Nodes

If you have a valid node handle, you can call different functions to work with the node:

  • XmlAppendChild appends a node to a parent node. You can append a new node (XmlCreateNode, XmlCreateNodeFromXml) or a node that has been removed from its parent (XmlRemoveChild) to another node. If you call XmlAppendChild on a node that is already appended to a parent node, the node will be cloned and added to the new parent. The handle to the child node will hold the cloned node after the call.
  • XmlReplaceNode replaces one node with another.
  • XmlSetNodeValue sets the value of a node.
  • XmlSetNodeAttribute sets the value of a node's attribute.
Parent topic: XML First Steps
Previous topic: Deleting Nodes
Next topic: XML Sample
Related reference
XmlAppendChild Function
XmlReplaceNode Function
XmlSetNodeValue Function


XML Sample

This topic walks you through a sample that covers the basic XML API functions.

Sample Overview

The sample is loading an existing XML document from a file. It modifies this XML document and iterates through the document with the possible techniques. The file the sample is using has the following structure:

<Order>
  <Name>Scott Bradley</Name>
  <OrderItems>
    <Item id="1">Lord of the Rings</Item>
  </OrderItems>
  <Price>25.90</Price>
</Order>

Starting

First, we create a new project (the project type does not matter). Then, we take the XML snapshot from the Sample Overview section, store it in a text file and add it to the data file section of our project. Store the file as ORDER.XML.

Create a new plain script and include the XmlAPI.BDH file with the following statement:
use "XMLAPI.BDH"

Loading the XML Document

The first step is to load the document and get the document handle. We need a variable that is storing the handle (number) and one string variable to get the absolute path of our XML document. We have to get the absolute path because XmlCreateDocumentFromFile requires the absolute path to the file that should be loaded - GetDataFilePath is the function that returns the absolute path to a file in the data file section.

As you can see in the sample code below we have to check if the returned handle value is not null. In case of an error - every XML function that returns a handle will return a 0. As you can further see - we have to free the handles when they are no longer needed - so we free the document handle at the end of our script.

dcltrans
  transaction TmyTrans1
  var
    hDoc     : number;
    sXmlFile : string;
  begin
    GetDataFilePath("order.xml", sXmlFile);
    hDoc := XmlCreateDocumentFromFile (sXmlFile);
    if (hDoc <> 0) then
      ...
      XmlFreeHandle(hDoc);
    end;
  end TmyTrans1;

Iterating through an XML Document

We now have a document handle in hDoc which is in fact the "virtual" document root node - a node that is the parent node of all top level nodes in the document - in our case it would be the parent of the node "Order".

If we want to iterate through all nodes in the XML document we have to get all child nodes of the document and iterate through them. And we also go through the child nodes of the returned child nodes - so to iterate through the whole document we have to write a function that will be called recursively - to make things easier in this sample we only iterate 2 node levels.

XmlGetChildNodes returns a nodelist handle. XmlGetCount returns the number of items in the nodelist and with XmlGetItem we can access one node in the list identified by the index (0 for the first item; XmlGetCount - 1 for the last).

We are going to write the node names and values to the output file:

dcltrans
  transaction TmyTrans1
  var
    hDoc, hChildren, hChildNode, nChildIx, nChildCount : number;
    hChildren2, hChildNode2, nChildIx2, nChildCount2   : number;
    sXmlFile, sName, sValue                            : string;
  begin
    GetDataFilePath("order.xml", sXmlFile);
    hDoc := XmlCreateDocumentFromFile(sXmlFile);
    if (hDoc <> 0) then
      hChildren := XmlGetChildNodes(hDoc); // get the nodelist to the children
      nChildCount := XmlGetCount(hChildren); // get the number of items in the nodelist
      for nChildIx := 0 to nChildCount -1 do// iterate through the children
        hChildNode := XmlGetItem(hChildren, nChildIx); // get a child out of the list
        XmlGetNodeName(hChildNode, sName);
        XmlGetNodeValue(hChildNode, sValue);
        writeln(sName + ":" + sValue);
        // now we do the same for the children of this child node
        hChildren2 := XmlGetChildNodes(hChildNode);
        nChildCount2 := XmlGetCount(hChildren2);
        for nChildIx2 := 0 to nChildCount2 -1 do
          hChildNode2 := XmlGetItem(hChildren2, nChildIx2);
          XmlGetNodeName(hChildNode2 , sName);
          XmlGetNodeValue(hChildNode2 , sValue);
          writeln(" " + sName + ":" + sValue);
          XmlFreeHandle(hChildNode2);
        end;
        XmlFreeHandle(hChildren2);
        XmlFreeHandle(hChildNode);
      end;
      XmlFreeHandle(hChildren);
      XmlFreeHandle(hDoc);
    end;
  end TmyTrans1;

Output File:

Order:
  Name:Scott Bradley
  OrderItems:
  Price:

Execute Queries

If you know exactly which node in the document you want to get - you can execute an X-Path query. There are two functions that allow you to execute queries - XmlSelectNodes and XmlSelectSingleNode. XmlSelectNodes returns a nodelist of all resulting nodes whereas XmlSelectSingleNode returns the first resulting node or 0 if there were no nodes matching the query. In our sample we want to query all nodes with name "Item" and write the values to the output file.

dcltrans
  transaction TmyTrans1
  var
    hDoc, hResultNodes, hNode, nResultIx, nResultCount : number;
    sXmlFile, sName, sValue                            : string;
  begin
    GetDataFilePath("order.xml", sXmlFile);
    hDoc := XmlCreateDocumentFromFile(sXmlFile);
    if (hDoc <> 0) then
      hResultNodes := XmlSelectNodes(hDoc, "//Item"); // get all nodes of name Item
      nResultCount := XmlGetCount(hResultNodes); // get the number of items in the nodelist
      for nResultIx := 0 to nResultCount -1 do // iterate through the children
        hNode := XmlGetItem(hResultNodes, nResultIx); // get a child out of the list
        XmlGetNodeName(hNode, sName);
        XmlGetNodeValue(hNode, sValue);
        writeln(sName + ":" + sValue);
        XmlFreeHandle(hNode);
      end;
      XmlFreeHandle(hResultNodes);
      XmlFreeHandle(hDoc);
    end;
  end TmyTrans1;

Output File:

Item: Lord of the Rings

Creating Nodes

Now lets create a new Item node in our XML document. We can either create the whole XML node (including value and attributes) with XmlCreateNodeFromXml or we can create the node with XmlCreateNode and set the value and attributes with other API functions. After creating the node and setting the values - we are appending the node to the OrderItems node. So we have to do the following steps: Create the node, Set the value and attributes, Get the OrderItems node and append the created node to the order items node.

dcltrans
transaction TmyTrans1
var
  hDoc, hOrderItems, hNewItem : number;
  sXmlFile, sXml              : string;
begin
  GetDataFilePath("order.xml", sXmlFile);
  hDoc := XmlCreateDocumentFromFile(sXmlFile);
  if (hDoc <> 0) then
    hOrderItems := XmlSelectSingleNode(hDoc, "/Order/OrderItems"); // get the OrderItems node
    hNewItem := XmlCreateNode("Item"); // Create a new Item Node
    XmlSetNodeAttribute(hNewItem, "id", "2"); // set the node attribute
    XmlSetNodeValue(hNewItem, "Star Wars - Episode II"); // set the node value
    XmlAppendChild(hOrderItems, hNewItem); // append the node
    // now lets get the XML representation
    XmlGetXml(hDoc, sXml);
    writeln(sXml);
    XmlFreeHandle(hNewItem);
    XmlFreeHandle(hOrderItems);
    XmlFreeHandle(hDoc);
  end;
end TmyTrans1;

Output File:

<Order>
  <Name>Scott Bradley</Name>
  <OrderItems>
    <Item id="1">Lord of the Rings</Item>
    <Item id="2">Star Wars - Episode II</Item>
  </OrderItems>
  <Price>25.90</Price>
</Order>

Working with Nodes / Removing

As you have already seen in the previous examples - there are several functions to get the name and value of a node XmlGetNodeValue, XmlGetNodeName) and there are functions to set the value and attributes of a node (XmlSetNodeValue, XmlSetNodeAttribute).

Iterating through nodes is also already described above - but there is also another way to get a child node of a node. XmlGetChildNodeByIndex directly returns the node handle to a child of a node. This function is useful if you know exactly which child node you want to access. Otherwise, you need to iterate through the nodelist returned by XmlGetChildNodes.

Attributes can also be accessed either by name or by index. XmlGetAttributeByIndex returns the value of an attribute identified by its index whereas XmlGetAttributeByName returns the value of an attribute identified by its name.

XmlRemoveChild allows you to remove a node from the document.

The following sample code will make use of some of the above mentioned functions to remove the Item node with the attribute value "2" for attribute "id":

dcltrans
  transaction TmyTrans1
  var
    hDoc, hOrderItems, hItems, hItem, nItemCount, nItemIx : number;
    sXmlFile, sXml                                        : string;
  begin
    GetDataFilePath("order.xml", sXmlFile);
    hDoc := XmlCreateDocumentFromFile(sXmlFile);
    if (hDoc <> 0) then
      hOrderItems := XmlSelectSingleNode(hDoc, "/Order/OrderItems/*"); // get all Item nodes
      nItemCount := XmlGetCount(hOrderItems);
      for nItemIx := 0 to nItemCount -1 do
        hItem := XmlGetItem(hOrderItems, nItemIx);
        XmlGetAttributeByName(hItem, "id", sAttrValue);
        if(StrICmp(sAttrValue, "2") = 0) then
          XmlRemoveChild(hItem);
        end;
        XmlFreeHandle(hItem);
      end;
      // now lets get the XML representation
      XmlGetXml(hDoc, sXml);
      writeln(sXml);
      XmlFreeHandle(hOrderItems);
      XmlFreeHandle(hDoc);
    end;
  end TmyTrans1;

Output File:

<Order>
  <Name>Scott Bradley</Name>
  <OrderItems>
    <Item id="1">Lord of the Rings</Item>
  </OrderItems>
  <Price>25.90</Price>
</Order>
Parent topic: XML First Steps
Previous topic: Working with Nodes
Related concepts
XML First Steps
Related reference
XmlCreateDocument Function
XmlCreateNode Function
XmlCreateDocumentFromFile Function
XmlCreateDocumentFromXml Function


Application Server Functions

  • CORBA Functions Reference
    Lists BDL functions to simplify the creation and use of CORBA test scripts.
  • Jolt Functions Reference
    Lists BDL functions to simulate Jolt-based client/server interaction.
  • Oracle Forms Functions Reference
    Lists BDL functions for testing Oracle Forms applications.
  • TUXEDO Functions Reference
    Lists BDL functions for handling TUXEDO function calls from within Silk Performer.
  • Jacada Functions Reference
    Lists BDL functions to handle Jacada function calls from within Silk Performer.
Parent topic: Benchmark Description Language (BDL) Reference


CORBA Functions Reference

Silk Performer provides functions to simplify the creation and use of CORBA test scripts.

Required include files

To use any of the CORBA functions provided with Silk Performer, you must use the proper include file in your test scripts. These files are part of the Silk Performer installation. Add the following lines to your test scripts:

use "WebAPI.bdh"
use "IIOP.bdh"
  • General Setting Functions Overview
    Lists BDL functions for presetting parameters for IiopRequest function calls.
  • Bootstrapping Functions
    Lists BDL functions for bootstrapping and locating CORBA objects.
  • Basic CORBA Functions
    Lists BDL functions for referencing and handling CORBA objects.
  • Status Retrieving Functions
    Lists BDL functions to retrieve the status and size of the reply associated with a CORBA object.
  • Parameter Setting and Getting Functions Overview
    Lists BDL functions for setting the parameters and retrieving the return parameters of an operation in advance of calling the IiopRequest function.
  • Measurement Functions
    Lists BDL functions for measuring operation calls related to CORBA objects.
  • Wonderwall Functions Overview
    Lists BDL functions for testing CORBA applications that make use of the Orbix Wonderwall.
Parent topic: Application Server Functions


General Setting Functions Overview

These setting functions are used to preset parameters for IiopRequest function calls. This is useful to make IIOP request functions more readable by using fewer parameters for values that do not change often.

  • IiopSetByteOrder Function
    Specifies the byte order used to pass messages.
  • IiopSetMaxGiopVersion Function
    Sets the maximum General Inter-ORB Protocol version and is also used as the default value for any IIOP message.
  • IiopSetOrbMode Function
  • IiopSetPrincipal Function
    Specifies the principal setting sent along with request messages to the server.
  • IiopSetProxy Function
    Sets a traffic forwarder host where all IIOP traffic is sent to, no matter what the target address in an IOR specifies.
  • IiopSetServiceContext Function
    Specifies the service context list that is sent along with messages that are exchanged between server and client objects.
  • IiopBeginServiceContext Function
    Prepares a CORBA object handle for construction of a service context.
  • IiopDeleteServiceContextList Function
    Deletes the entire service context list for an object.
  • IiopEndServiceContext Function
    Finalizes the construction of a service context.
  • IiopGetServiceContext Function
    Gets the service context list for an object that has been sent along with a message from a server object.
  • IiopGetServiceContextList Function
    Reads off a list of service contexts that may have been added to the reply of an IIOP request.
  • IiopGetEncapsulation Function
    Reveals the content of an encapsulation as defined in the CORBA specification.
  • IiopSetAddressingMode Function
    Sets the default addressing mode or specifies an addressing mode for a particular object.
  • IiopSetFragmentSize Function
    Sets the default fragmentation limit for any object, or specifies a fragmentation limit for a particular object.
  • IiopSetWCharType Function
    Determines how Silk Performer interprets wide characters.
  • IiopSetMaxChunkSize Function
    Sets the maximum size of value type chunks. Chunked encoding may be used with value types only.
  • IiopSetFirewall Function
    Sets the default or an object's firewall handling mode.
  • IiopRegisterValueType Function
    Registers a value typecode in order to be able to parse IIOP reply messages that contain non-chunked derived value types.
  • IiopSetShutdownMode Function
    Specifies the shutdown behaviour of connections for the IIOP load engine.
Parent topic: CORBA Functions Reference


IiopSetByteOrder Function

Action

Specifies the byte order used to pass messages. Depending on this setting, either the byte with the highest or the lowest order is sent first, followed by the remaining bytes in the corresponding order.

Include file

IIOP.bdh

Syntax

IiopSetByteOrder( in nByteOrder : number ): boolean;

Return value

  • true if successful

  • false otherwise

Parameter Description
nByteOrder

Byte order used to pass messages. Possible options are:

  • IIOP_BIG_ENDIAN. Most significant byte is sent first

  • IIOP_LITTLE_ENDIAN. Least significant byte is sent first

Example

dcltrans
  transaction TWebInit
  begin
    // set byte order
    if IiopSetByteOrder(IIOP_BIG_ENDIAN)then
      writeln("byte order set to IIOP_BIG_ENDIAN");
    end;
  end TWebInit;

Output

byte order set to IIOP_BIG_ENDIAN
Parent topic: General Setting Functions Overview


IiopSetMaxGiopVersion Function

Action

Sets the maximum General Inter-ORB Protocol version and is also used as the default value for any IIOP message.

Include File

IIOP.bdh

Syntax

IiopSetMaxGiopVersion( in sVersion : string ): boolean;

Return value

  • true if successful

  • false otherwise

Parameter | Description
sVersion | General Inter-ORB Protocol version

Example

dcltrans
  transaction TWebInit
  begin
    // set GIOP version
    if IiopSetMaxGiopVersion("1.2") then
      writeln("GIOP version set to 1.2");
    end;
  end TWebInit;

Output

GIOP version set to 1.0
Parent topic: General Setting Functions Overview


IiopSetOrbMode Function

Action

Specifies the overall behavior of the IIOP load engine. The user can choose between the Sybase/Jaguar mode and the standard mode. In the standard mode the IIOP engine behaves according to the CORBA specification.

The Sybase/Jaguar orb behaves slightly different in that it does not regard message ids as significant information to pair up requests with responses. Therefore it does not allow for multi-threaded communication over a particular connection.

Include file

IIOP.bdh

Syntax

IiopSetOrbMode( in eOrbMode : number): boolean;

Return value

  • true if successful

  • false otherwise

Parameter Description
eOrbMode Specifies the general IIOP engine mode. Valid options are:
  • IIOP_ORB_MODE_STANDARD (default)
  • IIOP_ORB_MODE_JAGUAR

Example

dcltrans
  transaction TMain
  const
    HOST   := "192.168.20.21";   // server
    PORT   := 1052;              // port
    KEY    := "...\h00";         // key
    KEYLEN := 4;                 // key length
  var
    hIiop : number;   // handle to a CORBA object

  begin
    IiopSetMaxGiopVersion("1.0");
    IiopSetByteOrder(IIOP_BIG_ENDIAN);

    // set IIOP engine mode to Jaguar orb behavior:
    // single-threaded communication per connection
    IiopSetOrbMode(IIOP_ORB_MODE_JAGUAR);

    IiopObjectCreate(hIiop, "IDL:DemoObject:1.0", "1.2", HOST, PORT, KEY, KEYLEN);

    IiopRequest(hIiop, "Print");
    IiopObjectRelease(hIiop);
  end TMain;
Parent topic: General Setting Functions Overview


IiopSetPrincipal Function

Action

Specifies the principal setting sent along with request messages to the server. This setting may be used as client identification by the ORB.

Include file

IIOP.bdh

Syntax

IiopSetPrincipal( in sPrincipal    : string,
                  in nPrincipalLen : number optional ): boolean;

Return value

  • true if successful

  • false otherwise

Parameter | Description
sPrincipal | Buffer containing the principal setting.
nPrincipalLen | Length of the principal setting (optional).

Example

dcltrans
  transaction TInit
  const
    PRINCIPAL := "username" "\h00";
  begin
    // general settings
    IiopSetMaxGiopVersion("1.2");
    IiopSetByteOrder(IIOP_BIG_ENDIAN);

    if IiopSetPrincipal(PRINCIPAL)then
      writeln("principal successful set");
    end;
  end TInit;

Output

principal successful set

Sample scripts

UnivB.bdf, AnyDemo.bdf, AsyncBank.bdf, Bank.bdf, Callback.bdf, SimpleAsyncBank.bdf, TypeTest.bdf

You can find the sample script(s) here: <Public documents>\Silk Performer <version>\Samples\Corba

Parent topic: General Setting Functions Overview


IiopSetProxy Function

Action

Sets a traffic forwarder host where all IIOP traffic is sent to, no matter what the target address in an IOR specifies.

Include file

IIOP.bdh

Syntax

IiopSetProxy(
  in sProxyHost : string,
  in nProxyPort : number ): boolean;

Return value

  • true if successful

  • false otherwise

Parameter | Description
sProxyHost | Host name where the IIOP traffic forwarder is running. In an empty string is passed, the proxy will be disabled.
nProxyPort | Port where the IIOP traffic forwarder is listening. If 0 is specified the proxy will be disabled

Example

dcltrans
  transaction TInit
  begin
    // general settings
    IiopSetMaxGiopVersion("1.2");
    IiopSetByteOrder(IIOP_BIG_ENDIAN);

    if IiopSetProxy("proxy", 5000) then
      writeln("IIOP proxy successfully set");
    end;
  end TInit;

Output

IIOP proxy successfully set
Parent topic: General Setting Functions Overview


IiopSetServiceContext Function

Action

For an object, specifies the service context list that is sent along with messages that are exchanged between server and client objects. Usually the service context list contains information that is not visible to a developer using an ORB.

A service context list is held globally for a CORBA object. This means that the service context list is sent unchanged with every IiopRequest function call, unless a new service context list is created, using the functions IiopBeginServiceContext, IiopEndServiceContext, IiopSetServiceContext or IiopDeleteServiceContextList.

However, if a service context list is defined for a callback object using the same functions, it is bound to a special operation defined by IiopObjectListen. Any time this operation is invoked by the server, Silk Performer returns the service context list along with the IIOP reply message.

Include file

IIOP.bdh

Syntax

IiopSetServiceContext( in hIiop           : number,
                       in sServContext    : string,
                       in nServContextLen : number optional ): boolean;

Return value

  • true if successful

  • false otherwise

Parameter | Description
hIiop | Handle to a CORBA object.
sServContext | Buffer containing the service context.
nServContextLen | Length of the service context (optional).

Example

dcltrans
  transaction TServiceContext
  const
    HOST           := "192.168.20.21"; // server
    PORT           := 1052;            // port
    KEY            := "...\h00";       // key
    KEYLEN         := 4;               // key length
    SERVICECONTEXT := "\h00000001000000010000000C00000000"
"\h0001010001000001";
  var
    hIiop : number;
  begin
    // general settings
    IiopSetMaxGiopVersion("1.2");
    IiopSetByteOrder(IIOP_BIG_ENDIAN);

    // retrieve handle to server
    IiopObjectCreate(hIiop, "IDL:DemoObject:1.0", "1.2", HOST, PORT, KEY);

    // set service context
    if IiopSetServiceContext(hIiop, SERVICECONTEXT) then
      writeln("service context successfully set");
    end;

    IiopRequest(hIiop, "Request");
    IiopObjectRelease(hIiop);
  end TServiceContext;

Output

service context successfuly set
Parent topic: General Setting Functions Overview
Related reference
IiopGetServiceContext Function


IiopBeginServiceContext Function

Action

Prepares a CORBA object handle for construction of a service context. The content of the service context is supplied using an IIOPGetFunctions function and is completed by calling an IiopEndServiceContext function.

Service context lists are held globally for CORBA objects. This means that service context lists are sent unchanged with each IiopRequest function call, unless a new service context list is created using the functions IiopBeginServiceContext, IiopEndServiceContext, IiopSetServiceContext, or IiopDeleteServiceContextList.

However, when a service context list is defined for a callback object using the same functions, the list is bound to a special operation defined by IiopObjectListen. When this operation is invoked by the server, Silk Performer returns the service context list along with the IIOP reply message.

Include file

IIOP.bdh

Syntax

IiopBeginServiceContext( in hIiop      : number,
                         in nServiceId : number,
                         in nByteOrder : number optional
                         in bIgnoreBO  : boolean optional ): boolean;

Return value

  • true if successful

  • false otherwise

Parameter | Description
hIiop | Handle of a CORBA object.
nServiceId | Unsigned long value that represents the service ID number.
nByteOrder

A service context can be marshaled in a byte order that is different than the rest of an IIOP message. When omitted, the current byte order is assumed.

Valid parameters include either of the following:

  • IIOP_BIG_ENDIAN. The most significant byte is sent first

  • IIOP_LITTLE_ENDIAN. The least significant byte is sent first
bIgnoreBO | When true, the byte order flag is not sent. This flag is only used with VisiBroker security tickets (optional, default value = false).

Example

dcltrans
  transaction TServiceContext
  const
    HOST   := "192.168.20.21"; // server
    PORT   := 1052; // port
    KEY    := "...\h00"; // key
    KEYLEN := 4; // key length
  var
    hIiop: number; // handle to CORBA object
  begin
    IiopSetMaxGiopVersion("1.2");
    IiopSetByteOrder(IIOP_BIG_ENDIAN);

     // retrieve handle to server
    IiopObjectCreate(hIiop, "IDL:DemoObject:1.0","1.2",
                     HOST, PORT, KEY, KEYLEN);

     // create service context
    IiopBeginServiceContext(hIiop, 1, IIOP_LITTLE_ENDIAN);
    IiopSetUlong(hIiop, 0x1010);
    IiopSetUlong(hIiop, 0x0110);
    IiopEndServiceContext(hIiop);

     // pass long value parameter to request
    IiopSetLong(hIiop, 593814064);
     // call request "DecToHex" with long parameter
    IiopRequest(hIiop, "DecToHex");
    ...
    IiopObjectRelease(hIiop);
  end TServiceContext;
Parent topic: General Setting Functions Overview
Related reference
IiopGetServiceContextList Function
IiopEndServiceContext Function


IiopDeleteServiceContextList Function

Action

Deletes the entire service context list for an object.

A service context list is held globally for a CORBA object. This means that the service context list is sent unchanged with every IiopRequest function call, unless a new service context list is created, using the functions IiopBeginServiceContext, IiopEndServiceContext, IiopSetServiceContext or IiopDeleteServiceContextList.

However, if a service context list is defined for a callback object using the same functions, it is bound to a special operation defined by IiopObjectListen. Any time this operation is invoked by the server, Silk Performer returns the service context list along with the IIOP reply message.

Include file

IIOP.bdh

Syntax

IiopDeleteServiceContextList( in hIiop: number ): boolean;

Return value

  • true if successful

  • false otherwise

Parameter | Description
hIiop | Handle to a CORBA object.

Example

dcltrans
  transaction TServiceContext
  const
    HOST   := "192.168.20.21"; // server
    PORT   := 1052; // port
    KEY    := "...\h00"; // key
    KEYLEN := 4; // key length
  var
    hIiop: number; // handle to CORBA object
  begin
    IiopSetMaxGiopVersion("1.2");
    IiopSetByteOrder(IIOP_BIG_ENDIAN);

    // retrieve handle to server
    IiopObjectCreate(hIiop, "IDL:DemoObject:1.0", "1.2",
                     HOST, PORT, KEY, KEYLEN);

    // create service context
    IiopBeginServiceContext(hIiop, 1, IIOP_LITTLE_ENDIAN);
    IiopSetUlong(hIiop, 0x1010);
    IiopSetUlong(hIiop, 0x0110);
    IiopEndServiceContext(hIiop);

    // create another service context
    IiopBeginServiceContext(hIiop, 17, IIOP_BIG_ENDIAN);
    IiopSetShort(hIiop, 2);
    ...
    IiopEndServiceContext(hIiop);

    // pass long value parameter to request
    IiopSetLong(hIiop, 593814064);

    // call request "DecToHex" with long parameter
    IiopRequest(hIiop, "DecToHex");
    // do not send a service context list along with the next request
    IiopDeleteServiceContextList(hIiop);
    IiopSetLong(hIiop, 593814065);
    IiopRequest(hIiop, "DecToHex");
    ...
    IiopObjectRelease(hIiop);
  end TServiceContext;
Parent topic: General Setting Functions Overview


IiopEndServiceContext Function

Action

Finalizes the construction of a service context. This process is started by calling the IiopBeginServiceContext; the content of a service context is supplied with the help of the IIOP SetFunctions.

A service context list is held globally for a CORBA object. This means that the service context list is sent unchanged with every IiopRequest function call, unless a new service context list is created, using the functions IiopBeginServiceContext, IiopEndServiceContext, IiopSetServiceContext or IiopDeleteServiceContextList.

However, if a service context list is defined for a callback object using the same functions, it is bound to a special operation defined by IiopObjectListen. Any time this operation is invoked by the server, Silk Performer returns the service context list along with the IIOP reply message.

Include file

IIOP.bdh

Syntax

IiopEndServiceContext( in hIiop: number ): boolean;

Return value

  • true if successful

  • false otherwise

Parameter | Description
hIiop | Handle to a CORBA object.

Example

dcltrans
  transaction TServiceContext
  const
    HOST   := "192.168.20.21"; // server
    PORT   := 1052; // port
    KEY    := "...\h00"; // key
    KEYLEN := 4; // key length
  var
    hIiop: number; // handle to CORBA object
  begin
    IiopSetMaxGiopVersion("1.2");
    IiopSetByteOrder(IIOP_BIG_ENDIAN);

    // retrieve handle to server
    IiopObjectCreate(hIiop, "IDL:DemoObject:1.0", "1.2",
                     HOST, PORT, KEY, KEYLEN);

    // create service context
    IiopBeginServiceContext(hIiop, 1, IIOP_LITTLE_ENDIAN);
    IiopSetUlong(hIiop, 0x1010);
    IiopSetUlong(hIiop, 0x0110);
    IiopEndServiceContext(hIiop);

    // pass long value parameter to request
    IiopSetLong(hIiop, 593814064);

    // call request "DecToHex" with long parameter
    IiopRequest(hIiop, "DecToHex");
    ...
    IiopObjectRelease(hIiop);
  end TServiceContext;
Parent topic: General Setting Functions Overview
Related reference
IiopGetServiceContextList Function
IiopBeginServiceContext Function


IiopGetServiceContext Function

Action

Gets the service context list for an object that has been sent along with a message from a server object. Usually the service context list contains information that is not visible to a developer using an ORB.

A service context list is held globally for a CORBA object. This means that the service context list is sent unchanged with every IiopRequest function call, unless a new service context list is created, using the functions IiopBeginServiceContext, IiopEndServiceContext, IiopSetServiceContext or IiopDeleteServiceContextList.

However, if a service context list is defined for a callback object using the same functions, it is bound to a special operation defined by IiopObjectListen. Any time this operation is invoked by the server, Silk Performer returns the service context list along with the IIOP reply message.

Include file

Iiop.bdh

Syntax

IiopGetServiceContext( in  hIiop        : number,
                       out sContext     : string,
                       in  nContextSize : number optional,
                       out nUsed        : number optional): boolean;

Return value

  • true if successful

  • false otherwise

Parameter | Description
hIiop | Handle to a CORBA object.
sContext | String variable that receives the service context.
nContextSize | Size of the string variable that receives the service context (optional).
nUsed | Variable that receives the number of bytes that are copied to the buffer (optional).

Example

dcltrans
  transaction TServiceContext
  var
    sBuf : string();
  begin
    // general settings
    IiopSetMaxGiopVersion("1.2");
    IiopSetByteOrder(IIOP_BIG_ENDIAN);

    // retrieve handle to server
    IiopObjectCreate(hIiop, "IDL:DemoObject:1.0", "1.2", HOST, PORT, KEY);
    IiopRequest(hIiop, "ARequest");

    // get service context
    IiopGetServiceContext(hIiop, sBuf)
    WriteData(sBuf, STRING_COMPLETE, OPT_WRITEDATA_HEX);
    IiopObjectRelease(hIiop);
  end TServiceContext;
Parent topic: General Setting Functions Overview
Related reference
IiopSetServiceContext Function


IiopGetServiceContextList Function

Action

Reads off a list of service contexts that may have been added to the reply of an IIOP request. The contents of the list can be retrieved by using the IiopGet functions on the handle that has been returned.

A service context list is held globally for a CORBA object. This means that the service context list is sent unchanged with every IiopRequest function call, unless a new service context list is created, using the functions IiopBeginServiceContext, IiopEndServiceContext, IiopSetServiceContext or IiopDeleteServiceContextList.

However, if a service context list is defined for a callback object using the same functions, it is bound to a special operation defined by IiopObjectListen. Any time this operation is invoked by the server, Silk Performer returns the service context list along with the IIOP reply message.

Include file

IIOP.bdh

Syntax

IiopGetServiceContextList( in    hIiop   : number,
                           inout hSrvCtx : number): boolean;

Return value

  • true if successful

  • false otherwise

Parameter | Description
hIiop | Handle to a CORBA object.
hSrvCtx | Handle to a parser object containing the service context.

Example

dcltrans
  transaction TServiceContext
  const
    HOST   := "192.168.20.21"; // server
    PORT   := 1052; // port
    KEY    := "...\h00"; // key
    KEYLEN := 4; // key length
  var
    hIiop   : number; // handle to CORBA object
    hSrvCtx : number; // handle to service context
    hEnc    : number; // handle to a parser object that contains an
    // encapsulation (IIOP data block)
    i          : number;
    nServCtxId : number;
  begin
    IiopSetMaxGiopVersion("1.2");
    IiopSetByteOrder(IIOP_BIG_ENDIAN);

    // retrieve handle to server
    IiopObjectCreate(hIiop, "IDL:DemoObject:1.0", "1.2",
                     HOST, PORT, KEY, KEYLEN);

    // create service context
    IiopBeginServiceContext(hIiop, 1, IIOP_LITTLE_ENDIAN);
    IiopSetUlong(hIiop, 0x1010);
    IiopSetUlong(hIiop, 0x0110);
    IiopEndServiceContext(hIiop);

    // pass long value parameter to request
    IiopSetLong(hIiop, 593814064);
    // call request "DecToHex" with long parameter
    IiopRequest(hIiop, "DecToHex");
    IiopGetServiceContextList(hIiop, hSrvCtx);

    for i := 1 to IiopGetLong(hSrvCtx);
      IiopGetLong(hSrvCtx, nServCtxId);
      IiopGetEncapsulation(hSrvCtx, hEnc);
      if nServCtxId = 0 then
        IiopGetLong(hEnc);
        ...
      end;
    end;

    ...
    IiopParserRelease(hSrvCtx);
    IiopParserRelease(hEnc);
    IiopObjectRelease(hIiop);
  end TServiceContext;
Parent topic: General Setting Functions Overview
Related reference
IiopBeginServiceContext Function
IiopEndServiceContext Function


IiopGetEncapsulation Function

Action

Reveals the content of an encapsulation as defined in the CORBA specification. Encapsulations are, for example, used within service contexts and the function is a handy way to work inside an encapsulation.

Include file

IIOP.bdh

Syntax

IiopGetEncapsulation( in    hParserIn  : number,
                      inout hParserOut : number ): boolean;

Return value

  • true if successful

  • false otherwise

Parameter | Description
hParserIn | A handle to a parser, which may also be a CORBA object, from which the encapsulation is read.
hParserOut | A handle that can subsequently be used to inspect the contents of the encapsulation by using the IiopGet functions.

Example

dcltrans
  transaction TServiceContext
  const
    HOST   := "192.168.20.21"; // server
    PORT   := 1052; // port
    KEY    := "...\h00"; // key
    KEYLEN := 4; // key length
  var
    hIiop   : number; // handle to CORBA object
    hSrvCtx : number; // handle to service context
    hEnc    : number; // handle to a parser object containing an
    // encapsulation (IIOP data block);
    i          : number;
    nServCtxId : number;
  begin
    IiopSetMaxGiopVersion("1.2");
    IiopSetByteOrder(IIOP_BIG_ENDIAN);

     // retrieve handle to server
    IiopObjectCreate(hIiop, "IDL:DemoObject:1.0", "1.2",
                     HOST, PORT, KEY, KEYLEN);

    // create service context
    IiopBeginServiceContext(hIiop, 1, IIOP_LITTLE_ENDIAN);
    IiopSetUlong(hIiop, 0x1010);
    IiopSetUlong(hIiop, 0x0110);
    IiopEndServiceContext(hIiop);

    // pass long value parameter to request
    IiopSetLong(hIiop, 593814064);
    // call request "DecToHex" with long parameter
    IiopRequest(hIiop, "DecToHex");
    IiopGetServiceContextList(hIiop, hSrvCtx);

    for i := 1 to IiopGetLong(hSrvCtx);
      IiopGetLong(hSrvCtx, nServCtxId);
      IiopGetEncapsulation(hSrvCtx, hEnc);
      if nServCtxId = 0 then
        IiopGetLong(hEnc);
        ...
      end;
    end;

    ...
    IiopParserRelease(hSrvCtx);
    IiopParserRelease(hEnc);
    IiopObjectRelease(hIiop);
  end TServiceContext;
Parent topic: General Setting Functions Overview


IiopSetAddressingMode Function

Action

Sets the default addressing mode or specifies an addressing mode for a particular object.

Include file

Iiop.bdh

Syntax

IiopSetAddressingMode( in hIiop : number,
                       in nMode : number ): boolean;

Return value

  • true if successful

  • false otherwise

Parameter | Description
hIiop | Handle to a CORBA object.
nMode

Addressing mode. Must be one of:

  • IIOP_ADDR_KEY. The target address is specified by the key. This is the default addressing mode.

  • IIOP_ADDR_PROFILE. The target address is specified by a profile (part of an IOR). This addressing mode is needed, for example, for traversing firewalls.

  • IIOP_ADDR_REFERENCE. The target address is specified by an IOR.

Example

dcltrans
  transaction TAddressingMode
  begin
    // general settings
    IiopSetMaxGiopVersion("1.2");
    IiopSetByteOrder(IIOP_BIG_ENDIAN);
    IiopSetAddressingMode(0, IIOP_ADDR_KEY); // set default addressing mode

    // retrieve handle to server
    IiopObjectCreate(hIiop, "IDL:DemoObject:1.0", "1.2", HOST, PORT, KEY, KEYLEN);
    IiopSetAddressingMode(hIiop, IIOP_ADDR_PROFILE); // set addressing mode for hIiop
     // the IIOP request message resulting from the following IiopRequest call
    // will contain a profile as target address information.
    IiopRequest(hIiop, "ARequest");
    IiopObjectRelease(hIiop);
  end TAddressingMode;
Parent topic: General Setting Functions Overview


IiopSetFragmentSize Function

Action

Sets the default fragmentation limit for any object, or specifies a fragmentation limit for a particular object. If the length of an IIOP request/reply message exceeds this limit it is fragmented (broken into parts).

Include file

Iiop.bdh

Syntax

IiopSetFragmentSize( in hIiop : number,
                     in nSize : number ): boolean;

Return value

  • true if successful

  • false otherwise

Parameter | Description
hIiop | Handle to a CORBA object.
nSize | Fragmentation size; if zero, IIOP messages will not be fragmented.

Example

dcltrans
  transaction TFragmentSize
  var
    sBuf  : string(1024);
    nUsed : number;
  begin
    // general settings
    IiopSetMaxGiopVersion("1.2");
    IiopSetByteOrder(IIOP_BIG_ENDIAN);
    IiopSetFragmentSize(0, 0); // set default: no fragmentation

    // retrieve handle to server
    IiopObjectCreate(hIiop, "IDL:DemoObject:1.0", "1.2", HOST, PORT, KEY, KEYLEN);
    IiopSetFragmentSize(hIiop, 2048); // set fragment size of hIiop message
    IiopSetBinaryFromFile(hIiop, "very_large_file.dat");

    // the IIOP request message resulting from the following IiopRequest call
    // will be split into several messages, each 2048 bytes long.
    IiopRequest(hIiop, "AFragmentedRequest");
    IiopObjectRelease(hIiop);
  end TFragmentSize;
Parent topic: General Setting Functions Overview


IiopSetWCharType Function

Action

Determines how Silk Performer interprets wide characters. By default, wide characters as regarded to be Unicode.

Include file

IIOP.bdh

Syntax

IiopSetWCharType( in nCharType : number,
                  in nCharSize : number optional ): boolean;

Return value

  • true if successful

  • false otherwise

Parameter | Description
nCharType

Determines the type of wide characters. This parameter can be one or more of the following:

  • IIOP_BYTE_ORIENTED. Wide characters are of different size and bytes are not swapped for transmission.

  • IIOP_WIDE_LITTLE_ENDIAN. Wide characters are of fixed size and are represented in little-endian byte order. Bytes are swapped depending on the byte order used for transmission.

  • IIOP_WIDE_BIG_ENDIAN. Wide characters are of fixed size and are represented in big-endian byte order. Bytes are swapped depending on the byte order used for transmission.

  • IIOP_WIDE_NO_LENGTH_ENCODED. With IIOP 1.2 the wchar encoding contains a length indication. When this flag is used, wchars are encoded without the length encoding.

  • IOP_WIDE_NULL_TERMINATED. With IIOP 1.2 wstrings are not null-terminated. When this setting is used, wstrings are null-terminated as in prior IIOP versions.

  • IIOP_WIDE_LENGTH_IN_WCHAR. With IIOP 1.2 the length of a wstring is measured in bytes (chars). When this setting is used, the length of a wstring is counted in wchars as in prior IIOP versions.

  • IIOP_WIDE_BYTE_ORIENTED. The same as IIOP_BYTE_ORIENTED.
nCharSize | Specifies the size of a wide character for the character types IIOP_WIDE_LITTLE_ENDIAN and IIOP_WIDE_BIG_ENDIAN (optional). The size must be 1, 2, or 4.

Example

var
  hIiop: number;

dcltrans
  transaction TMain
  begin
    // use the big endian representation
    IiopSetWCharType(IIOP_WIDE_BIG_ENDIAN, 2);
    IiopSetWString(hIiop, "\x004d00610072006b00750073", 12);
    // use the little endian representation
    IiopSetWCharType(IIOP_WIDE_LITTLE_ENDIAN, 2);
    IiopSetWString(hIiop, "\x4d00610072006b0075007300", 12);
    // alternatively, use the IiopSetString function
    IiopSetString(hIiop, "Markus", IIOP_USE_WCHAR);
  end TMain;
Parent topic: General Setting Functions Overview


IiopSetMaxChunkSize Function

Action

Sets the maximum size of value type chunks. Chunked encoding may be used with value types only.

Include file

Iiop.bdh

Syntax

IiopSetMaxChunkSize( in nSize : number ): boolean;

Return value

  • true if successful

  • false otherwise

Parameter | Description
nSize | Maximum size of a chunk used for chunked value state encoding.

Example

dcltrans
  transaction TMaxChunkSize
  const
   HOST           := "192.168.20.21"; // server
    PORT           := 1052;           // port
    KEY            := "...\h00";      // key
    KEYLEN         := 4;              // key length
  var
    sBuf   : string(1024);
    nUsed  : number;
  begin
    // general settings
    IiopSetMaxGiopVersion("1.2");
    IiopSetByteOrder(IIOP_BIG_ENDIAN);
    IiopSetMaxChunkSize(2096); // set maximum chunk size

     // retrieve handle to server
    IiopObjectCreate(hIiop, "IDL:DemoObject:1.0", "1.2", HOST, PORT, KEY, KEYLEN);

     // set value
    IiopSetValue(hIiop, REP_ID);
    IiopSetLong(hIiop, 5);
    IiopEndValue(hIiop);

     // set another value
    IiopSetValue(hIiop, REP_ID_LIST, CODE_BASE, TRUE);  // value is being chunked encoded

    for i := 1 to 10000
      IiopSetLong(hIiop, i);
      IiopSetBoolean(hIiop, TRUE);
      IiopSetString(hIiop, "This is a string");
    end;

     IiopEndValue(hIiop);

     // call request "SetValue"
    // the IIOP request message resulting from the following IiopRequest call
    // contains a value whose state members are chunked into several 2096 byte chunks.
    IiopRequest(hIiop, "SetValue");
    IiopObjectRelease(hIiop);
  end TMaxChunkSize;
Parent topic: General Setting Functions Overview


IiopSetFirewall Function

Action

Sets the default or an object's firewall handling mode.

Include file

Iiop.bdh

Syntax

IiopSetFirewall( in hIiop : number,                 in nMode : number ): boolean;

Return value

  • true if successful

  • false otherwise

Parameter | Description
hIiop | Handle to a CORBA object
nMode

Addressing mode. Must be one of:

  • IIOP_FIREWALL_IGNORE. Firewall information of IORs (if present) is ignored.

  • IIOP_FIREWALL_USE_ALWAYS. Firewall information of IORs (if present) is used to connect to a remote object.

Example

dcltrans
  transaction TFirewallMode
  begin
    // general settings
    IiopSetMaxGiopVersion("1.2");
    IiopSetByteOrder(IIOP_BIG_ENDIAN);
    IiopSetFirewall(0, IIOP_FIREWALL_USE_ALWAYS); // set default

     // retrieve handle to server
    IiopObjectCreate(hIiop, "IDL:DemoObject:1.0", "1.2", HOST, PORT, KEY, KEYLEN);
    IiopSetFirewall(hIiop, IIOP_FIREWALL_IGNORE);
    IiopRequest(hIiop, "ARequest");
    IiopObjectRelease(hIiop);
  end TFirewallMode;
Parent topic: General Setting Functions Overview


IiopRegisterValueType Function

Action

Registers a value typecode in order to be able to parse IIOP reply messages that contain non-chunked derived value types.

Include file

Iiop.bdh

Syntax

IiopRegisterValueType( in sValueTc : string,
                       in nTcLen   : number optional ): boolean;

Return value

  • true if successful

  • false otherwise

Parameter | Description
sValueTc | Value typecode that is to be registered.
nTcLen | Length of the value typecode (optional).

Example

dcltrans
  transaction TInit
  const
    csTypecode := "\h0000001D000000C20000000000000038524D49"
      "\h3A6A6176612E6C616E672E496E74656765723A363444343743"
      "\h314430313938304235453A3132453241304134463738313837"
      "\h380000000008496E746567657200000000000000001D000000"
      "\h33580000000000000036524D493A6A6176612E6C616E672E4E"
      "\h756D6265723A3731444138424537463937313132383A383641"
      "\h43393531443042393445303842000000000000074E756D6265"
      "\h72000000020000000000000000000000h00000100000001000"
      "\h000000000003000000";
  begin
    IiopRegisterValueType(csTypecode);
  end TInit;
Parent topic: General Setting Functions Overview


IiopSetShutdownMode Function

Action

Specifies the shutdown behaviour of connections for the IIOP load engine. The user can choose between the graceful method and the hard reset.

Include file

IIOP.bdh

Syntax

IiopSetShutdownMode( in eShutdownMode : number): boolean;

Return value

  • true if successful

  • false otherwise

Parameter Description
eShutdownMode

Specifies the shutdown behaviour of connections. Valid options are:

  • IIOP_SHUTDOWN_RESET

  • IIOP_SHUTDOWN_GRACEFUL (Default)

Example

dcltrans
  transaction TMain
  const
    HOST   := "192.168.20.21";   // server
    PORT   := 1052;              // port
    KEY    := "...\h00";         // key
    KEYLEN := 4;                 // key length
  var
    hIiop : number;   // handle to a CORBA object
    nSum  : number;
  begin
    IiopSetMaxGiopVersion("1.0");
    IiopSetByteOrder(IIOP_BIG_ENDIAN);
    IiopSetShutdownMode(IIOP_SHUTDOWN_RESET);

    IiopObjectCreate(hIiop, "IDL:DemoObject:1.0", "1.2", HOST, PORT, KEY, KEYLEN);

    IiopRequest(hIiop, "Print", IIOP_ONEWAY | IIOP_ADDR_PROFILE);
    IiopObjectRelease(hIiop); // connection is reset
  end TMain;

Parent topic: General Setting Functions Overview


Bootstrapping Functions

Usually, different proceeding depending on the ORB are necessary to locate the initial CORBA object. So several function calls at the begin of a script are required to receive a handle to the desired object.

To simplify this procedure, Silk Performer provides a number of functions for bootstrapping and locating CORBA objects.

Bea WLE/M3-specific bootstrapping functions

  • IiopBeaFactoryBind

  • IiopBeaServiceBind

OrbixWeb-specific bootstrapping functions

  • IiopOrbixDaemonBind

  • IiopOrbixPing

  • IiopOrbixServerBind

VisiBroker-specific bootstrapping functions

  • IiopVbServerBind

  • IiopVbrokerServerBind

General Bootstrapping Functions

  • IiopObjectByIor

  • IiopBeaFactoryBind Function
    Retrieves a handle to a factory object, for example, to the FactoryFinder object in Weblogic Enterprise (WLE).
  • IiopBeaServiceBind Function
    Retrieves a handle to a service object, for example, the FactoryFinder object in Weblogic Enterprise (WLE).
  • IiopOrbixDaemonBind Function
    Retrieves a handle to the Orbix daemon.
  • IiopOrbixPing Function
    Sends the _IT_PING request to an object.
  • IiopOrbixServerBind Function
    Uses the Orbix daemon to retrieve a handle to a specified CORBA object.
  • IiopVbServerBind Function
    Performs a UDP broadcast to locate a VisiBroker SmartAgent.
  • IiopVbrokerServerBind Function
Parent topic: CORBA Functions Reference


IiopBeaFactoryBind Function

Action

Retrieves a handle to a factory object, for example, to the FactoryFinder object in Weblogic Enterprise (WLE).

Include file

IIOP.bdh

Syntax

IiopBeaFactoryBind( in hFF     : number;
                    in sIFName : string ): number;

Return value

  • Handle to factory object if successful

  • 0 if an error occurred

Parameter | Description
hFF | Handle to FactoryFinder object
sIFName | Name of the factory to be located. This is supposed to be the interface repository string "IDL:<factoryname>:1.0"

Example

dcltrans
  transaction TBeaServiceBind
  const
    HOST := "192.168.20.21"; // server
    PORT := 1052; // port
  var
    hFactFinder : number; // handle to FactoryFinder
    hFact       : number; // handle to a factory object
  begin
    IiopSetMaxGiopVersion("1.2");
    IiopSetByteOrder(IIOP_BIG_ENDIAN);

    // retrieve handle to service object
    hFactFinder := IiopBeaServiceBind(HOST, PORT, "FactoryFinder");
    hFact := IiopBeaFactoryBind(hFactFinder, "IDL:SomeFactory:1.0");

    // release objects
    IiopObjectRelease(hFactFinder);
    IiopObjectRelease(hFact);
  end TBeaServiceBind;

Sample scripts

UnivB.bdf

You can find the sample script(s) here: <Public documents>\Silk Performer <version>\Samples\Corba

Parent topic: Bootstrapping Functions
Related reference
IiopBeaServiceBind Function


IiopBeaServiceBind Function

Action

Retrieves a handle to a service object, for example, the FactoryFinder object in Weblogic Enterprise (WLE).

Include file

IIOP.bdh

Syntax

IiopBeaServiceBind( in sHost    : string;
                    in nPort    : number;
                    in sService : string ): number;

Return value

  • Handle to service object if successful

  • 0 if an error occurred

Parameter | Description
sHost | Host name where WLE/M3 is running
nPort | Port where WLE/M3 is listening
sService | Service name

Example

dcltrans
  transaction TBeaServiceBind
  const
    HOST := "192.168.20.21"; // server
    PORT := 1052; // port
  var
    hFactFinder : number; // handle to FactoryFinder object
    hFact       : number; // handle to a factory object
  begin
    IiopSetMaxGiopVersion("1.2");
    IiopSetByteOrder(IIOP_BIG_ENDIAN);

    // retrieve handle to service object
    hFactFinder := IiopBeaServiceBind(HOST, PORT, "FactoryFinder");
    hFact := IiopBeaFactoryBind(hFactFinder, "IDL:SomeFactory:1.0");

    // release objects
    IiopObjectRelease(hFactFinder);
    IiopObjectRelease(hFact);
  end TBeaServiceBind;

Sample scripts

UnivB.bdf

You can find the sample script(s) here: <Public documents>\Silk Performer <version>\Samples\Corba

Parent topic: Bootstrapping Functions
Related reference
IiopBeaFactoryBind Function


IiopOrbixDaemonBind Function

Action

Retrieves a handle to the Orbix daemon. This function can be used to get the initial CORBA object, consequently it simplifies Orbix/OrbixWeb-specific bootstrapping.

Include file

IIOP.bdh

Syntax

IiopOrbixDaemonBind( in sHost : string,                     in nPort : number ): number;

Return value

  • Handle to the OrbixWeb daemon if successful

  • 0 if an error occurred

Parameter | Description
sHost | Orbix host
nPort | Orbix port number, OrbixWeb default port number is 1571

Example

dcltrans
  transaction TMain
  const
    ORBIX_HOST := "192.168.20.55"; // Orbix host
    ORBIX_PORT := 1571; // default Orbix port
  var
    hDaemon, hBank: number;
  begin
    // global settings
    IiopSetMaxGiopVersion("1.2");
    IiopSetByteOrder(IIOP_LITTLE_ENDIAN);
    IiopSetPrincipal("principal", Strlen("principal")+1);

    // OrbixWeb bootstrapping
    hDaemon := IiopOrbixDaemonBind(ORBIX_HOST, ORBIX_PORT);

    // get object reference handle to bank object
    hBank := IiopOrbixServerBind(hDaemon, ORBIX_HOST,
                                 "bank", "","bank");

    // release objects
    IiopObjectRelease(hDaemon);
    IiopObjectRelease(hBank);
  end TMain;

Sample scripts

AnyDemo.bdf, AsyncBank.bdf, Bank.bdf, Callback.bdf, SimpleAsyncBank.bdf, TypeTest.bdf

You can find the sample script(s) here: <Public documents>\Silk Performer <version>\Samples\Corba

Parent topic: Bootstrapping Functions
Related reference
IiopOrbixPing Function
IiopOrbixServerBind Function


IiopOrbixPing Function

Action

Sends the _IT_PING request to an object.

Include file

IIOP.bdh

Syntax

IiopOrbixPing( in hIiop : number ): number;

Return value

  • Handle to the OrbixWeb object if successful

  • 0 if an error occurred

Parameter | Description
hIiop | Handle to a CORBA object. The corresponding object structure has to contain a dummy key that enables the Orbix daemon locating the object

Example

dcltrans
  transaction TMain
  const
    ORBIX_HOST := "192.168.20.55"; // Orbix host
    ORBIX_PORT := 1571;            // default Orbix port
  var
    hDaemon, hObject: number;
  begin
    // global settings
    IiopSetMaxGiopVersion("1.2");
    IiopSetByteOrder(IIOP_LITTLE_ENDIAN);
    IiopSetPrincipal("principal", Strlen("principal")+1);

    // OrbixWeb bootstrapping
    hDaemon := IiopOrbixDaemonBind(ORBIX_HOST, ORBIX_PORT);

    // send _IT_PINg request to Orbix daemon
    hObject := IiopOrbixPing(hDaemon);

    // release objects
    IiopObjectRelease(hDaemon);
    IiopObjectRelease(hObject);
end TMain;
Parent topic: Bootstrapping Functions
Related reference
IiopOrbixDaemonBind Function
IiopOrbixServerBind Function


IiopOrbixServerBind Function

Action

Uses the Orbix daemon to retrieve a handle to a specified CORBA object. This function requests the getIIOPDetails operation provided by the Orbix daemon to get the IOR, and establishes an object handle used to reference to the object.

Include file

IIOP.bdh

Syntax

IiopOrbixServerBind( in hDaemon  : number,
                     in sHost    : string,
                     in sServer  : string,
                     in sMarker  : string,
                     in sIfrName : string ) : number;

Return value

  • Handle to the OrbixWeb object if successful

  • 0 if an error occurred

Parameter | Description
hDaemon | Handle to the Orbix daemon
sHost | Orbix host
sServer | Server name
sMarker | Marker name of the object. If NULL, any OrbixWeb object will match
sIfrName | Interface Repository name of the object. Pass only the object name to the function, neither the "IDL:" prefix, nor the "1.2" suffix

Example

dcltrans
  transaction TMain
  const
    ORBIX_HOST := "192.168.20.55"; // Orbix host
    ORBIX_PORT := 1571; // default Orbix port
  var
    hDaemon, hBank: number;
  begin
    // global settings
    IiopSetMaxGiopVersion("1.2");
    IiopSetByteOrder(IIOP_LITTLE_ENDIAN);
    IiopSetPrincipal("principal", Strlen("principal")+1);
    // OrbixWeb bootstrapping
    hDaemon := IiopOrbixDaemonBind(ORBIX_HOST, ORBIX_PORT);
    // get object reference handle to bank object
    hBank := IiopOrbixServerBind(hDaemon, ORBIX_HOST,
                                 "bank", "", "bank");

    // release objects
    IiopObjectRelease(hDaemon);
    IiopObjectRelease(hBank);
  end TMain;

Sample scripts

AnyDemo.bdf, AsyncBank.bdf, Bank.bdf, Callback.bdf, SimpleAsyncBank.bdf, TypeTest.bdf

You can find the sample script(s) here: <Public documents>\Silk Performer <version>\Samples\Corba

Parent topic: Bootstrapping Functions
Related reference
IiopOrbixDaemonBind Function
IiopOrbixPing Function


IiopVbServerBind Function

Action

Performs a UDP broadcast to locate a VisiBroker SmartAgent. When a SmartAgent is located, the function queries it for an object reference. Since a non-standard protocol is used to locate SmartAgents, the way that Silk Performer retrieves object references differs from the way that real VisiBroker clients behave.

Include file

IIOP.bdh

Syntax

IiopVbServerBind( inout hIiop       : number,
                  in    sInterface  : string,
                  in    sObjectName : string optional,
                  in    nPort       : number optional,
                  in    sHost       : string optional ): boolean;

Return value

  • true if successful

  • false otherwise

Parameter | Description
hIiop | Variable that receives the handle of the CORBA object.
sInterface | Repository ID of the object to be located.
sObjectName | Name of the object to be located (optional). When this parameter is omitted, the function returns any object that has a matching interface.
nPort | The port number where SmartAgent listens (optional). The default value is 14000.
sHost | The host name where SmartAgent (osagent.exe) runs. When this parameter is specified, no broadcast is made, however the host is contacted directly (optional).

Example

dcltrans
  transaction TMain
  var
    hBankManager : number;
    hAccount     : number;
    fBalance     : float;
  begin
    IiopSetMaxGiopVersion("1.2");
    IiopSetByteOrder(IIOP_BIG_ENDIAN);
    IiopVbServerBind(hBankManager, "IDL:Bank/AccountManager:1.0", "Bank Manager");

    // open account
    IiopSetString(hBankManager, "Jack B. Quick");
    IiopRequest(hBankManager, "open", IIOP_RESPONSE_EXPECTED);

    // release IIOP object
    IiopObjectRelease(hBankManager);
  end TMain;

Sample scripts

AsyncFact.bdf, AsyncOdb.bdf, Conf.bdf, DynAny.bdf, Factory.bdf, Odb.bdf, Vbrokerbank01.bdf, Vbrokerbank02.bdf

You can find the sample script(s) here: <Public documents>\Silk Performer <version>\Samples\Corba

Parent topic: Bootstrapping Functions
Related reference
IiopVbrokerServerBind Function


IiopVbrokerServerBind Function

Action

Uses the VisiBroker Gatekeeper to retrieve a handle to a specified VisiBroker object.

Include file

IIOP.bdh

Syntax

IiopVbrokerServerBind(in hGatekeeper : number,
in sName : string,
in sServer : string): number;

Return value

  • Handle to the object if successful

  • 0 if an error occurred

Parameter | Description
hGatekeeper | Handle to the VisiBroker Gatekeeper
sName | Interface Repository name of the object
sServer | Server name

Sample scripts

VBrokerBankGate.bdf

You can find the sample script(s) here: <Public documents>\Silk Performer <version>\Samples\Corba

Parent topic: Bootstrapping Functions
Related reference
IiopVbServerBind Function


Basic CORBA Functions

  • IiopObjectByIor Function
    Establishes an object handle that is used in all CORBA functions in a Silk Performer script to reference to CORBA objects.
  • IiopObjectCreate Function
    Creates a handle to an CORBA object.
  • IiopObjectConnect Function
    Establishes a connection to a specified CORBA object.
  • IiopObjectListen Function
    Sets up a callback to listen for incoming requests.
  • IiopObjectGetHost Function
    Retrieves the IP address of the host where a specified CORBA object is located.
  • IiopObjectGetPort Function
    Retrieves the port number used to access a specified CORBA object.
  • IiopObjectGetKey Function
    Retrieves the key used to identify a specified CORBA object.
  • IiopObjectGetInterface Function
    Retrieves the repository id of an object's interface.
  • IiopObjectGetProfile Function
    Retrieves an IIOP profile from an IOR. IIOP profiles are used to identify individual objects accessible through IIOP.
  • IiopObjectGetComponent Function
    Retrieves a component from an Internet profile of an IOR.
  • IiopObjectSetPort Function
    Sets the port number used to access a specified CORBA object.
  • IiopObjectSetInterface Function
    Defines the interface of an object. The interface will be part of the IOR whenever the object is passed to a function as a parameter.
  • IiopObjectSetProfile Function
    Appends or replaces a profile in an IOR. If the specified profile exists, the component is replaced.
  • IiopObjectSetComponent Function
    Appends or replaces an component of an IOR.
  • IiopObjectSetIiopProfile Function
    Appends or replaces an Internet profile in an IOR.
  • IiopObjectDuplicate Function
    Duplicates a CORBA object handle.
  • IiopLocateRequest Function
  • IiopEndValue Function
    Marks the end of a value type parameter that is associated with a CORBA object.
  • IiopRequest Function
    Sends an IIOP Request Message.
  • IiopWaitForReply Function
    Waits for a reply of a specific request.
  • IiopParserRelease Function
    Releases a CORBA parser object and frees all resources.
  • IiopObjectRelease Function
    Releases a CORBA object and frees all resources.
  • IiopObjectShutdown Function
    Closes a connection to a specified CORBA object.
  • IiopObjectSetSsl Function
    Specifies to access a given CORBA object using the Secure Socket Layer protocol.
  • IiopObjectSetBidirectional Function
    Prepares a connection to a remote object in order to receive callbacks for a local object.
Parent topic: CORBA Functions Reference


IiopObjectByIor Function

Action

Establishes an object handle that is used in all CORBA functions in a Silk Performer script to reference to CORBA objects.

Include file

IIOP.bdh

Syntax

IiopObjectByIor( inout hIiop   : number,
                 in  sIor      : string,
                 in  nIorLen   : number optional ):boolean;

Return value

  • true if successful

  • false otherwise

Parameter | Description
hIiop | Variable receiving a handle to the CORBA object
sIor

IOR identifying the CORBA object. The following formats are valid:

binary: "\h1100000049444c3a5479706554657374" "\h3a312e30000000000100000000000000" "\h5e000000010102000f0000003139322e" "\h3136382e32302e3132390000270f0000" "\h1b0000003a3e0231310c000000004a02" "\h00002900000008000000000000000000" "\h02000000000000000800000001000000" "\h415f5449060000000600000001000000" "\h1100"

stringified: "IOR:010000001100000049444c3a5479706554657374" "3a312e300000000001000000000000005e0000000101" "02000f0000003139322e3136382e32302e3132390000" "270f00001b0000003a3e0231310c000000004a020000" "29000000080000000000000000000200000000000000" "0800000001000000415f544906000000060000000100" "00001100"

URL: stored in a file: "FILE://c:/init.ior"
nIorLen | Length of sIor.

Example

dcltrans
  transaction TMain
  var
    hIiop: number;
  begin
    IiopObjectByIor(hIiop, "HTTP://www.inprise.com:15000/gatekeeper.ior");
    ...
    IiopObjectRelease(hIiop);
  end TMain;
Parent topic: Basic CORBA Functions
Related reference
IiopObjectRelease Function
IiopObjectCreate Function


IiopObjectCreate Function

Action

Creates a handle to an CORBA object. In addition to the host, port and key of the object the function enables you to specify the CORBA interface and the IIOP version that is used to communicate with the object.

Include file

IIOP.bdh

Syntax

IiopObjectCreate( inout hIiop      : number,
                  in    sInterface : string,
                  in    sVersion   : string,
                  in    sHost      : string allownull,
                  in    nPort      : number,
                  in    sKey       : string,
                  in    nKeyLen    : number optional ): boolean;

Return value

  • true if successful

  • false otherwise

Parameter | Description
hIiop | Variable receiving the handle to the CORBA object.
sInterface | Repository identification of the CORBA object interface.
sVersion | IIOP version the application uses, currently “1.0”, “1.1” or “1.2”.
sHost | Host name or IP address of the host where the CORBA object has been deployed.
nPort | Port on which the CORBA object is listening for incoming connections.
sKey | Key identifying the CORBA object.
nKeyLen | Length of the key that identifies the CORBA object (optional).

Example

var
  hIiop: number;

dcltrans
  transaction TMain
  begin
    IiopObjectCreate(hIiop, "IDL:Bank/AccountManager:1.0", "1.2",
      "MyComputer", 1234,
      "\h01504D43000000001C00000049444C3A" // ·PMC········IDL: 00000000
      "\h42616E6B2F4163636F756E744D616E61" // Bank/AccountMana 00000010
      "\h6765723A312E30000D00000042616E6B" // ger:1.0·····Bank 00000020
      "\h204D616E6167657200");             // Manager· 00000030
    IiopLocateRequest(hIiop);
    IiopSetString(hIiop, "Johnny"); // name
    IiopRequest(hIiop, "open");
  end TMain;
Parent topic: Basic CORBA Functions
Related reference
IiopObjectRelease Function
IiopObjectByIor Function


IiopObjectConnect Function

Action

Establishes a connection to a specified CORBA object. Since the IiopRequest function automatically opens a connection to the corresponding object, calling this function is necessary only in individual cases, for example, to perform some specific bootstrapping procedures.

Include file

IIOP.bdh

Syntax

IiopObjectConnect(in hIiop: number): boolean;

Return value

  • true if successful

  • false otherwise

Parameter | Description
hIiop | Handle to a CORBA object

Example

dcltrans
transaction TMain
const
HOST := "192.168.20.21"; // server
PORT := 1052; // port
KEY := "...\h00"; // key
KEYLEN := 4; // key length
var
hIiop: number; // handle to CORBA object
begin
IiopSetMaxGiopVersion("1.2");
IiopSetByteOrder(IIOP_BIG_ENDIAN);IiopObjectCreate(hIiop, "IDL:DemoObject:1.0", "1.2", HOST, PORT, KEY, KEYLEN);
IiopObjectConnect(hIiop);
...
IiopObjectShutdown(hIiop);
IiopObjectRelease(hIiop);
end TMain;
Parent topic: Basic CORBA Functions
Related reference
IiopObjectShutdown Function


IiopObjectListen Function

Action

Sets up a callback to listen for incoming requests. Such requests are answered with a reply containing the parameters set on the object handle before calling the IiopObjectListen function. This function must be called for each operation that is supposed to be answered.

Optionally the callback can be re-routed to a native function exported by a so-called IIOP extension dll.

Include file

IIOP.bdh

Syntax

IiopObjectListen( in hIiop      : number,
                  in sOperation : string,
                  in sDllName   : string optional,
                  in sDllFunc   : string optional ): boolean;

Return value

  • true if successful

  • false otherwise

Parameter | Description
hIiop | Handle to a CORBA object.
sOperation | Name of operation to be answered.
sDllName | Name of the callback extension dll (optional).
sDllFunc | Name of the native function that is called whenever a callback occurs (optional).

Example

const
  LOCALHOST := "192.55.21.188";
  DAEMONPORT := 1570;
  REMOTEHOST := "192.55.21.192";
var
  ghDaemon, ghRemoteServer, ghCallback: number;

dcltrans
  transaction TMain
  begin
    IiopSetMaxGiopVersion("1.2");
    IiopSetByteOrder(IIOP_BIG_ENDIAN);
    ghDaemon       := IiopOrbixDaemonBind(LOCALHOST, DAEMONPORT);
    ghRemoteServer := IiopOrbixServerBind(ghDaemon, REMOTEHOST, "remote", "", "remote");

   // set up callback object
    IiopObjectCreate(ghCallback, "IDL:DemoObject:1.0", "1.2", LOCALHOST, 0,
      "\h3A5C6D69746368656C6C2E7365677565"
      "\h6175743A2D3838393233363930343A30"
      "\h3A3A4946523A6C6F63616C00");
    IiopObjectSetInterface(ghCallback, "IDL:local:1.0");
    IiopObjectListen(ghCallback, "callback_func");
    IiopSetObject(ghRemoteServer, ghCallback);
    IiopRequest(ghRemoteServer, "func", IIOP_ONEWAY);
    // enable the user to answer callbacks.
    wait(20.0);
    IiopObjectRelease(ghRemoteServer);
    IiopObjectRelease(ghCallback);
  end TMain;

Sample scripts

Callback.bdf

You can find the sample script(s) here: <Public documents>\Silk Performer <version>\Samples\Corba

Parent topic: Basic CORBA Functions


IiopObjectGetHost Function

Action

Retrieves the IP address of the host where a specified CORBA object is located.

Include file

IIOP.bdh

Syntax

IiopObjectGetHost( in  hIiop     : number,
                   out sHost     : string,
                   in  nHostSize : number optional ): boolean;

Return value

  • true if successful

  • false otherwise

Parameter | Description
hIiop | Handle to a CORBA object.
sHost | String receiving the IP address of the host where the CORBA object is located.
nHostSize | Size of the string receiving the IP address (optional).

Example

dcltrans
  transaction TMain
  const
    HOST   := "192.168.20.21"; // server
    PORT   := 1052;            // port
    KEY    := "...\h00";       // key
    KEYLEN := 4;               // key length
  var
    hIiop, nPort            : number;
    sHost, sKey, sInterface : string;
  begin
    IiopSetMaxGiopVersion("1.2");
    IiopSetByteOrder(IIOP_BIG_ENDIAN);
    IiopObjectCreate(hIiop, "IDL:DemoObject:1.0", "1.2", HOST, PORT, KEY, KEYLEN);

    // retrieve information about object
    IiopObjectGetHost(hIiop, sHost);
    nPort := IiopObjectGetPort(hIiop);
    IiopObjectGetKey(hIiop, sKey);
    IiopObjectGetInterface(hIiop, sInterface);
    IiopObjectRelease(hIiop);
  end TMain;

Sample scripts

AnyDemo.bdf

You can find the sample script(s) here: <Public documents>\Silk Performer <version>\Samples\Corba

Parent topic: Basic CORBA Functions
Related reference
IiopObjectSetPort Function
IiopObjectGetPort Function
IiopObjectGetKey Function
IiopObjectGetInterface Function


IiopObjectGetPort Function

Action

Retrieves the port number used to access a specified CORBA object.

Include file

IIOP.bdh

Syntax

IiopObjectGetPort( in hIiop: number ): number;

Return value

Port number used to access the specified CORBA object

Parameter | Description
hIiop | Handle to a CORBA object.

Example

dcltrans
  transaction TMain
  const
    HOST   := "192.168.20.21"; // server
    PORT   := 1052;            // port
    KEY    := "...\h00";       // key
    KEYLEN := 4;               // key length
  var
    hIiop, nPort            : number;
    sHost, sKey, sInterface : string;
  begin
    IiopSetMaxGiopVersion("1.2");
    IiopSetByteOrder(IIOP_BIG_ENDIAN);
    IiopObjectCreate(hIiop, "IDL:DemoObject:1.0", "1.2", HOST, PORT, KEY, KEYLEN);

    // retrieve information about object
    IiopObjectGetHost(hIiop, sHost);
    nPort := IiopObjectGetPort(hIiop);
    IiopObjectGetKey(hIiop, sKey);
    IiopObjectGetInterface(hIiop, sInterface);
     IiopObjectRelease(hIiop);
  end TMain;

Sample scripts

AnyDemo.bdf

You can find the sample script(s) here: <Public documents>\Silk Performer <version>\Samples\Corba

Parent topic: Basic CORBA Functions
Related reference
IiopObjectSetPort Function
IiopObjectGetHost Function
IiopObjectGetKey Function
IiopObjectGetInterface Function


IiopObjectGetKey Function

Action

Retrieves the key used to identify a specified CORBA object.

Include file

IIOP.bdh

Return value

  • true if successful

  • false otherwise

Parameter | Description
hIiop | Handle to a CORBA object.
sKey | Buffer receiving the key used to identify the specified CORBA object.
nKeySize | Size of the buffer receiving the key (optional).
nKeyLen | Variable receiving the actual size of the key (optional).

Example

dcltrans
  transaction TMain
  const
    HOST   := "192.168.20.21"; // server
    PORT   := 1052;            // port
    KEY    := "...\h00";       // key
    KEYLEN := 4;               // key length
  var
    hIiop, nPort            : number;
    sHost, sKey, sInterface : string;
  begin
    IiopSetMaxGiopVersion("1.2");
    IiopSetByteOrder(IIOP_BIG_ENDIAN);
    IiopObjectCreate(hIiop, "IDL:DemoObject:1.0", "1.2", HOST, PORT, KEY, KEYLEN);

    // retrieve information about object
    IiopObjectGetHost(hIiop, sHost);
    nPort := IiopObjectGetPort(hIiop);
    IiopObjectGetKey(hIiop, sKey);
    IiopObjectGetInterface(hIiop, sInterface);

    IiopObjectRelease(hIiop);
  end TMain;

Sample scripts

AnyDemo.bdf

You can find the sample script(s) here: <Public documents>\Silk Performer <version>\Samples\Corba

Parent topic: Basic CORBA Functions
Related reference
IiopObjectSetPort Function
IiopObjectGetHost Function
IiopObjectGetPort Function
IiopObjectGetInterface Function


IiopObjectGetInterface Function

Action

Retrieves the repository id of an object's interface.

Include file

IIOP.bdh

Syntax

IiopObjectGetInterface( in  hIiop      : number,
                        out sInterface : string,
                        in  nSize      : number optional ): boolean;

Return value

  • true if successful

  • false otherwise

Parameter | Description
hIiop | Handle to a CORBA object.
sInterface | String receiving the repository id of the specified object interface.
nSize | Size of the string receiving the object interface (optional).

Example

dcltrans
  transaction TMain
  const
    HOST   := "192.168.20.21"; // server
    PORT   := 1052;            // port
    KEY    := "...\h00";       // key
    KEYLEN := 4;               // key length
  var
    hIiop, nPort            : number;
    sHost, sKey, sInterface : string;
  begin
    IiopSetMaxGiopVersion("1.2");
    IiopSetByteOrder(IIOP_BIG_ENDIAN);
    IiopObjectCreate(hIiop, "IDL:DemoObject:1.0", "1.2", HOST, PORT, KEY, KEYLEN);

    // retrieve information about object
    IiopObjectGetHost(hIiop, sHost));
    nPort := IiopObjectGetPort(hIiop);
    IiopObjectGetKey(hIiop, sKey);
    IiopObjectGetInterface(hIiop, sInterface);
     IiopObjectRelease(hIiop);
  end TMain;
Parent topic: Basic CORBA Functions
Related reference
IiopObjectSetPort Function
IiopObjectGetHost Function
IiopObjectGetPort Function
IiopObjectGetKey Function


IiopObjectGetProfile Function

Action

Retrieves an IIOP profile from an IOR. IIOP profiles are used to identify individual objects accessible through IIOP.

Include file

IIOP.bdh

Syntax

IiopObjectGetProfile( in  hIiop       : number,
                      in  nProfile    : number,
                      out nTag        : number,
                      out sData       : string,
                      in  nBufferSize : number optional,
                      out nLen        : number optional ): boolean;

Return value

  • true if successful

  • false otherwise

Parameter | Description
hIiop | Handle to a CORBA object.
nProfile | Index of the profile. Set this parameter to IIOP_FIRST or IIOP_LAST for the first or the last profile, respectively. The index of the first profile is zero (0).
nTag | Number variable receiving the profile tag. Profile tags are described in the CORBA specification.
sData | Buffer receiving the profile data.
nBufferSize | Size of the buffer that receives the profile data in bytes (optional).
nLen | Variable receiving the amount of profile data (in bytes) that was copied into the buffer (optional).

Example

var
  hSSLBank, hCombined: number;

dcltrans
  transaction TMain
  var
    sData : string;
    nType : number;
  begin
    // create an empty object
    IiopObjectCreate(hCombined, "", "", "", 0, "", 0);

    // copy profile of bank object using SSL
    IiopObjectGetProfile(hSSLBank, IIOP_FIRST, nType, sData);
    IiopObjectSetProfile(hCombined, IIOP_NO_REPLACE, nType, sData);
    IiopSetString(hCombined, "James Smith");
    IiopRequest(hCombined, "open");
  end TMain;
Parent topic: Basic CORBA Functions


IiopObjectGetComponent Function

Action

Retrieves a component from an Internet profile of an IOR.

Include file

IIOP.bdh

Syntax

IiopObjectGetComponent( in  hIiop       : number,
                        in  nProfile    : number,
                        in  nComponent  : number,
                        out nTag        : number,
                        out sData       : string,
                        in  nBufferSize : number optional,
                        out nLen        : number optional ): boolean;

Return value

  • true if successful

  • false otherwise

Parameter | Description
hIiop | Handle to a CORBA Object.
nProfile | Index of the Internet profile. Set this parameter to IIOP_FIRST or IIOP_LAST for the first or the last profile, respectively. The index of the first profile is zero (0).
nComponent | Index of the component within the selected profile. Set this parameter to IIOP_FIRST or IIOP_LAST for the first or the last component, respectively. The index of the first component is zero (0).
nTag | Variable receiving the component tag. Component tags are described in the CORBA specification.
sData | Buffer receiving the component data.
nBufferSize | Size of the buffer that receives the component data in bytes (optional).
nLen | Variable receiving the amount of component data (in bytes) that is copied into the buffer (optional).

Example

var
  hSSLBank: number;

dcltrans
  transaction TMain
  var
    sData, sDataHex : string;
    nType, nLen : number;
  begin
    if IiopObjectGetComponent(hSSLBank, IIOP_FIRST, IIOP_FIRST, nType,
        sData, STRING_COMPLETE, nLen) and (nType = 20) then
      Bin2Hex(sData, nLen, sDataHex);
      writeln("hSSLBank contains an SSL tag: " + sDataHex);
    end;
  end TMain;
Parent topic: Basic CORBA Functions


IiopObjectSetPort Function

Action

Sets the port number used to access a specified CORBA object.

Include file

IIOP.bdh

Syntax

IiopObjectSetPort( in hIiop : number,
                   in nPort : number ): boolean;

Return value

  • true if successful

  • false otherwise

Parameter | Description
hIiop | Handle to a CORBA object
nPort | New port number used to access the specified CORBA object

Example

dcltrans
  transaction TMain
  const
    HOST   := "192.168.20.21"; // server
    PORT   := 1052; // port
    KEY    := "...\h00"; // key
    KEYLEN := 4; // key length
  var
    hIiop: number;
  begin
    IiopSetMaxGiopVersion("1.2");
    IiopSetByteOrder(IIOP_BIG_ENDIAN);
    IiopObjectCreate(hIiop, "IDL:DemoObject:1.0", "1.2", HOST, PORT, KEY, KEYLEN);

    // set new port number used to access object
    IiopObjectSetPort(hIiop, 1500);
    IiopObjectRelease(hIiop);
  end TMain;
Parent topic: Basic CORBA Functions
Related reference
IiopObjectGetHost Function
IiopObjectGetPort Function
IiopObjectGetKey Function
IiopObjectGetInterface Function


IiopObjectSetInterface Function

Action

Defines the interface of an object. The interface will be part of the IOR whenever the object is passed to a function as a parameter.

Include file

IIOP.bdh

Syntax

IiopObjectSetInterface( in hIiop      : number,
                        in sInterface : string ): boolean;

Return value

  • true if successful

  • false otherwise

Parameter | Description
hIiop | Handle to a CORBA object
sInterface | Repository ID of the object's interface

Example

const
  LOCALHOST := "192.55.21.188";
  DAEMONPORT := 1570;
  REMOTEHOST := "192.55.21.192";
var
  ghDaemon, ghRemoteServer, ghCallback: number;
 dcltrans
  transaction TMain
  begin
    IiopSetMaxGiopVersion("1.2");
    IiopSetByteOrder(IIOP_BIG_ENDIAN);
    ghDaemon       := IiopOrbixDaemonBind(LOCALHOST, DAEMONPORT);
    ghRemoteServer := IiopOrbixServerBind(ghDaemon,
                        REMOTEHOST, "remote", "","remote");

     // set up callback object
    IiopObjectCreate(hIiop, "IDL:DemoObject:1.0", "1.2", LOCALHOST,0,
                     "\h3A5C6D69746368656C6C2E7365677565"
                     "\h6175743A2D3838393233363930343A30"
                     "\h3A3A4946523A6C6F63616C00", 44);
    IiopObjectSetInterface(ghCallback, "IDL:local:1.0");
    IiopObjectListen(ghCallback, "callback_func");
    IiopSetObject(ghRemoteServer, ghCallback);
    IiopRequest(ghRemoteServer, "func",IIOP_ONEWAY);

    // enable the user to answer callbacks.
    wait(20.0);
    IiopObjectRelease(ghRemoteServer);
    IiopObjectRelease(ghCallback);
  end TMain;

Sample scripts

Callback.bdf

You can find the sample script(s) here: <Public documents>\Silk Performer <version>\Samples\Corba

Parent topic: Basic CORBA Functions
Related reference
IiopObjectSetSsl Function


IiopObjectSetProfile Function

Action

Appends or replaces a profile in an IOR. If the specified profile exists, the component is replaced. This can be suppressed by using the flag IIOP_NO_REPLACE. If a replacement is impossible because of an invalid profile index, the function appends the component to the list. This again can be suppressed with the flag IIOP_NO_APPEND.

Include file

IIOP.bdh

Syntax

IiopObjectSetProfile( in hIiop        : number,
                      in nProfile     : number,
                      in nProfileTag  : number,
                      in sProfileData : string,
                      in sProfileLen  : number optional ): boolean;

Return value

  • true if successful

  • false otherwise

Parameter | Description
hIiop | Handle to a CORBA object.
nProfile | Index of the profile. Set this parameter to IIOP_FIRST or IIOP_LAST for the first or the last profile, respectively. In addition, you can supply either the IIOP_NO_REPLACE or the IIOP_NO_APPEND flag. The index of the first profile is zero (0).
nProfileTag | Profile tag as described in the CORBA specification.
sProfileData | Profile data containing the byte order flag as described in the CORBA specification.
sProfileLen | Amount of profile data in bytes (optional).

Example

var
  hBank, hSSLBank, hCombined: number;
 dcltrans
  transaction TMain
  var
    sData : string;
    nType : number;
  begin
    // create an empty object
    IiopObjectCreate(hCombined, "", "", "", 0, "",0);
     // copy profile of bank object using SSL
    IiopObjectGetProfile(hSSLBank, IIOP_FIRST, nType, sData);
    IiopObjectSetProfile(hCombined, IIOP_NO_REPLACE, nType, sData);
     // copy profile of bank object
    IiopObjectGetProfile(hBank, IIOP_FIRST, nType, sData);
    IiopObjectSetProfile(hCombined, IIOP_NO_REPLACE, nType, sData);
    IiopSetString(hCombined, "James Smith");
    IiopRequest(hCombined, "open");
  end TMain;
Parent topic: Basic CORBA Functions


IiopObjectSetComponent Function

Action

Appends or replaces an component of an IOR. If the specified component exists in the selected profile and the tag of the component matches, the component is replaced. This can be suppressed by using the flag IIOP_NO_REPLACE. If a replacement is impossible because the component does not exist, the function appends the component to the list within the profile. This again can be suppressed by the flag IIOP_NO_APPEND.

Include file

IIOP.bdh

Syntax

IiopObjectSetComponent( in hIiop      : number,
                        in nProfile   : number,
                        in nComponent : number,
                        in nTag       : number,
                        in sData      : string,
                        in nDataLen   : number optional): boolean;

Return value

  • true if successful

  • false otherwise

Parameter | Description
hIiop | Handle to a CORBA Object.
nProfile | Index of the Internet profile to change. Set this parameter to IIOP_FIRST or IIOP_LAST to change the first or the last profile, respectively. The index of the first profile is zero (0).
nComponent | Index of the component. Set this parameter to IIOP_FIRST or IIOP_LAST for the first or the last component, respectively. In addition, you can supply one either the IIOP_NO_REPLACE or the IIOP_NO_APPEND flag. The index of the first component is zero (0).
nTag | Component tag to set.
sData | Component data including the byte order flag.
nDataLen | Amount of component data in bytes (optional).

Example

const
  sAltHost := "192.168.20.20";
  nAltPort := 1033;

dcltrans
  transaction TMain
  var
    sData : string;
    nLen  : number;
  begin
    // set an alternate IIOP address in an Internet profile
    // compute the size of the component data
    nLen := (4 + 4 + (strlen(sAltHost)+1) + 1) & 0xfffffffe + 2;
    SetChar(sData, 1, 1); // choose little endian
    SetLong(sData, 5, strlen(sAltHost)+1);
 // size of hostname    SetString(sData, 9, sAltHost);
 // hostname    SetUShort(sData, nLen-1, nAltPort);

     // 0x3 is the tag for an alternate IIOP address.
    IiopObjectSetComponent(hIiop, IIOP_FIRST, IIOP_FIRST, 0x3, sData, nLen);
  end TMain;
Parent topic: Basic CORBA Functions


IiopObjectSetIiopProfile Function

Action

Appends or replaces an Internet profile in an IOR. If the specified profile exists, the component is replaced. This can be suppressed by using the flag IIOP_NO_REPLACE. If a replacement is impossible because of an invalid profile index or because the selected profile is no Internet profile, the function appends the component to the list. This again can be suppressed by the flag IIOP_NO_APPEND.

Include file

IIOP.bdh

Syntax

IiopObjectSetIiopProfile( in hIiop    : number,
                          in nProfile : number,
                          in sVersion : string,
                          in sHost    : string,
                          in nPort    : number,
                          in sKey     : string,
                          in nKeyLen  : number optional ): boolean;

Return value

  • true if successful

  • false otherwise

Parameter | Description
hIiop | Handle to a CORBA object.
nProfile | Index of the profile. Set this parameter to IIOP_FIRST or IIOP_LAST for the first or the last profile, respectively. In addition, you can supply either the IIOP_NO_REPLACE or the IIOP_NO_APPEND flag. The index of the first profile is zero (0).
sVersion | IIOP version used to communicate with the CORBA object. Currently this parameter can be set to “1.0”, “1.1” or “1.2”.
sHost | Host name or IP address of the machine where the CORBA object is located.
nPort | Port on that the CORBA object is listening for incoming connections.
sKey | Unique key that identifies the CORBA object.
nKeyLen | Length of the key identifying the object in bytes (optional).

Example

var
  hSSLBank, hCombined: number;
 dcltrans
  transaction TMain
  var
    sData, sKey : string;
    nType       : number;
  begin
    // create an empty object
    IiopObjectCreate(hCombined, "", "", "", 0, "", 0);

    // copy profile of bank using SSL
    IiopObjectGetProfile(hSSLBank, IIOP_FIRST, nType, sData);
    IiopObjectSetProfile(hCombined, IIOP_NO_REPLACE, nType, sData);

    // append an internet profile for a bank object
    IiopObjectSetIiopProfile(hCombined, IIOP_NO_REPLACE, "1.2",
                               sHost, nPort, sKey);
    IiopSetString(hCombined, "James Smith");
    IiopRequest(hCombined, "open");
  end TMain;
Parent topic: Basic CORBA Functions


IiopObjectDuplicate Function

Action

Duplicates a CORBA object handle. Since each handle is associated with a data structure, you need to call this function to copy an object handle.

Include file

IIOP.bdh

Syntax

IiopObjectDuplicate( in  hIiop : number,
                     out hCopy : number ): boolean;

Return value

  • true if successful

  • false otherwise

Parameter | Description
hIiop | Handle to a CORBA object
hCopy | Variable receiving the copy of the CORBA object handle

Example

dcltrans
  transaction TMain
  const
    HOST   := "192.168.20.21"; // server
    PORT   := 1052; // port
    KEY    := "...\h00"; // key
    KEYLEN := 4; // key length
  var
    hIiop, hCopy: number;
  begin
    IiopSetMaxGiopVersion("1.2");
    IiopSetByteOrder(IIOP_BIG_ENDIAN);
    IiopObjectCreate(hIiop, "IDL:DemoObject:1.0", "1.2", HOST, PORT, KEY, KEYLEN);
    // copy object handle
    IiopObjectDuplicate(hIiop, hCopy);
    IiopObjectRelease(hIiop);
    IiopObjectRelease(hCopy);
  end TMain;
Parent topic: Basic CORBA Functions


IiopLocateRequest Function

Action

Sends an IIOP LocateRequest message, waits until the server sends a LocateReply message, and binds the BDL object handle to the new object key and host address of the received IOR.

Sends an IIOP LocateRequest message, waits until the server sends a LocateReply message, and binds the BDL object handle to the new object key and host address of the received IOR.

Include file

IIOP.bdh

Syntax

IiopLocateRequest( in hIiop  : number,
                   in nFlags : number optional ): boolean;

Return value

  • true if successful

  • false otherwise

Parameter | Description
hIiop | Handle to a CORBA object
nFlags

Specifies the location request message variant sent to the server (optional). Possible values are:

  • IIOP_IGNORE_EXCEPTION. Prevents the generation of error messages. This parameter may be combined with the following flag:

  • IIOP_IGNORE_FORWARDS. The request is not re-sent if a "location forward" or "needs addressing mode" response is received.

This parameter may be combined with one of the following flags:

  • IIOP_ADDR_KEY. The target address is specified by the key. This is the default addressing mode.

  • IIOP_ADDR_PROFILE. The target address is specified by a profile (part of an IOR). This addressing mode is needed, for example, for traversing firewalls.

  • IIOP_ADDR_REFERENCE. The target address is specified by an IOR.

This parameter may be combined with one of the following flags:

  • IIOP_USE_V10. The request is sent using IIOP 1.0 encoding (if possible).

  • IIOP_USE_V11. The request is sent using IIOP 1.1 encoding (if possible).

  • IIOP_USE_V12. The request is sent using IIOP 1.2 encoding (if possible).

Example

dcltrans
  transaction TLocateRequest
  const
    HOST   := "192.168.20.21"; // server
    PORT   := 1052; // port
    KEY    := "...\h00"; // key
    KEYLEN := 4; // key length
  var
    hIiop : number;
    // handle to CORBA object
    nSum : number;
  begin
    IiopSetMaxGiopVersion("1.2");
    IiopSetByteOrder(IIOP_BIG_ENDIAN);
    // retrieve handle to server
    IiopObjectCreate(hIiop, "IDL:DemoObject:1.0", "1.2", HOST, PORT, KEY, KEYLEN);
    IiopLocateRequest(hIiop);
    // call request "Print"
    IiopRequest(hIiop, "Print", IIOP_ADDR_REFERENCE | IIOP_USE_V12);
    IiopObjectRelease(hIiop);
  end TLocateRequest;
Parent topic: Basic CORBA Functions
Related reference
IiopWaitForReply Function
IiopRequest Function


IiopEndValue Function

Action

Marks the end of a value type parameter that is associated with a CORBA object. This function can be used to set the parameters of a request in advance of calling the IiopRequest function.

Include file

Iiop.bdh

Syntax

IiopEndValue( in hIiop: number ): boolean;

Return value

  • true if successful

  • false otherwise

Parameter | Description
hIiop | Handle to a CORBA object.

Example

dcltrans
  transaction TEndValue
  const
    HOST        := "192.168.20.21"; // server
    PORT        := 1052; // port
    KEY         := "...\h00"; // key
    KEYLEN      := 4; // key length
    REP_ID      := "IDL:SetValueType:1.0";
    REP_ID_LIST := " IDL:DerivedValue:1.0 IDL:BaseValue:1.0 IDL:AbstractValue:1.0";
    CODE_BASE   := "www.codebase.com";
 var
    hIiop : number;
    // Handle to CORBA object
  begin
    IiopSetMaxGiopVersion("1.2");
    IiopSetByteOrder(IIOP_BIG_ENDIAN);
     // retrieve handle to server
    IiopObjectCreate(hIiop, "IDL:DemoObject:1.0", "1.2", HOST, PORT, KEY, KEYLEN);
     // set value    IiopSetValue(hIiop, REP_ID);
    IiopSetLong(hIiop, 5);
    IiopEndValue(hIiop );
    // set another value
    IiopSetValue(hIiop, REP_ID_LIST, CODE_BASE, TRUE);
    IiopSetBoolean(hIiop, TRUE);
    IiopSetLong(hIiop, 3);
    IiopSetValue(hIiop, REP_Id, "", TRUE);
    IiopSetLong(hIiop, 12);
    IiopEndValue(hIiop );
    IiopSetString(hIiop, "This is a string");
    IiopEndValue(hIiop );
    // call request "SetValue"
    IiopRequest(hIiop, "SetValue");
    IiopObjectRelease(hIiop);
  end TEndValue;
Parent topic: Basic CORBA Functions
Related reference
IiopRequest Function


IiopRequest Function

Action

Sends an IIOP Request Message. Depending on the specified message type, it is possible to wait until this function receives an IIOP Reply Message from the server.

Include file

IIOP.bdh

Syntax

IiopRequest( in hIiop    : number,
             in sRequest : string,
             in nFlag    : number optional,
             in nId      : number optional): boolean;

Return value

  • true if successful

  • false otherwise

Parameter | Description
hIiop | Handle to a CORBA object
sRequest | Name of the requested operation
nFlag

Specifies the request message variant sent to the server (optional). Possible values are:

  • IIOP_RESPONSE_EXPECTED. Waits for a response (default)

  • IIOP_SYSTEM_RESPONSE. A response from the server is expected, but the response does not necessarily contain application level data (ORB dependent).

  • IIOP_ONEWAY. No response from the server expected

  • IIOP_NON_BLOCKING. Indicates that the caller will not wait for an immediate reply. This flag can be used to generate asynchronous IIOP traffic

This parameter may be combined with the following flag:

  • IIOP_IGNORE_EXCEPTION. Prevents the generation of error messages.

This parameter may be combined with the following flag:

  • IIOP_IGNORE_FORWARDS. The request is not re-sent if a "location forward" or "needs addressing mode" response is received.

This parameter may be combined with one of the following flags:

  • IIOP_ADDR_KEY. The target address is specified by the key. This is the default addressing mode.

  • IIOP_ADDR_PROFILE. The target address is specified by a profile (part of an IOR). This addressing mode is needed, for example, for traversing firewalls.

  • IIOP_ADDR_REFERENCE. The target address is specified by an IOR.

This parameter may be combined with one of the following flags:

  • IIOP_USE_V10. The request is sent using IIOP 1.0 encoding (if possible).

  • IIOP_USE_V11. The request is sent using IIOP 1.1 encoding (if possible).

  • IIOP_USE_V12. The request is sent using IIOP 1.2 encoding (if possible).
nId

Identification number for this request (optional).

Note: This parameter affects the function's behavior only if nFlag is set to IIOP_NON_BLOCKING.

If an identification number is associated with a request, the IiopWaitForReply function can be used to wait for a reply from the request. Exceptional cases:

  • 0. Return parameters will not be stored, consequently no reply data can be retrieved (default)

  • -1 is not allowed

Example

dcltrans
  transaction TRequest
  const
    HOST := "192.168.20.21"; // server
    PORT := 1052; // port
    KEY := "...\h00"; // key
    KEYLEN := 4; // key length
  var
    hIiop : number; // handle to a CORBA object
    nSum : number;
  begin
    IiopSetMaxGiopVersion("1.0");
    IiopSetByteOrder(IIOP_BIG_ENDIAN);
    // retrieve handle to server
    IiopObjectCreate(hIiop, "IDL:DemoObject:1.0", "1.2",
                        HOST, PORT, KEY,KEYLEN);
    // call request "Print"
    IiopRequest(hIiop, "Print", IIOP_ONEWAY | IIOP_ADDR_PROFILE);
    IiopObjectRelease(hIiop);
  end TRequest;
Parent topic: Basic CORBA Functions
Related reference
IiopWaitForReply Function
IiopLocateRequest Function


IiopWaitForReply Function

Action

Waits for a reply of a specific request. To enable waiting, an identification number has to be associated with the request. The identification number can be specified via an optional parameter of the IiopRequest function.

Include file

IIOP.bdh

Syntax

IiopWaitForReply( in hIiop : number,
                  in nId   : number ): boolean;

Return value

  • true if successful

  • false otherwise

Parameter | Description
hIiop | Handle to a CORBA object
nId

Identification number of the request to wait for. A reply from the specified request has to be received before the simulation continues

  • 0 Not allowed

  • IIOP_ALL_REPLIES Waits for all replies of the object

Example

dcltrans
  transaction TMain
  const
    ID_JIM := 1;
    // identification numbers
    ID_BOB := 2;
  var
    hBank, hJim, hBob: number;
  begin
    // retrieve handle to Bank/AccountManager
    ...
    // open an account for Jim
    IiopSetString(hBank, "Jim");
    IiopRequest(hBank, "open", IIOP_NON_BLOCKING, ID_JIM);
    // open an account for Bob
    IiopSetString(hBank, "Bob");
    IiopRequest(hBank, "open", IIOP_NON_BLOCKING, ID_BOB);
    // do anything else
    ...
    // wait until Jim's account has been opened
    IiopWaitForReply(hBank, ID_JIM);
    IiopGetObject(hBank, hJim);
    // wait until Bob's account has been opened
    IiopWaitForReply(hBank, ID_BOB);
    IiopGetObject(hBank, hBob);
    // release object
    IiopObjectRelease(hBank);
    IiopObjectRelease(hJim);
    IiopObjectRelease(hBob);
  end TMain;

Sample scripts

AsyncBank.bdf, SimpleAsyncBank.bdf, AsyncFact.bdf, AsyncOdb.bdf

You can find the sample script(s) here: <Public documents>\Silk Performer <version>\Samples\Corba

Parent topic: Basic CORBA Functions
Related reference
IiopLocateRequest Function
IiopRequest Function


IiopParserRelease Function

Action

Releases a CORBA parser object and frees all resources.

Include file

IIOP.bdh

Syntax

IiopParserRelease(inout hParser: number): boolean;

Return value

  • true if successful

  • false otherwise

Parameter | Description
hParser | A handle to an IIOP parser object.

Example

dcltrans
  transaction TServiceContext
  const
    HOST := "192.168.20.21"; // server
    PORT := 1052; // port
    KEY := "...\h00"; // key
    KEYLEN := 4; // key length
  var
    hIiop : number;
    // handle to CORBA objecthSrvCtx : number;
    // handle to service contexti : number;nServCtxId : number;
  begin
    IiopSetMaxGiopVersion("1.2");
    IiopSetByteOrder(IIOP_BIG_ENDIAN);

    // retrieve handle to server
    IiopObjectCreate(hIiop, "IDL:DemoObject:1.0", "1.2",HOST, PORT, KEY, KEYLEN);
    // create service context
    IiopBeginServiceContext(hIiop, 1, IIOP_LITTLE_ENDIAN);
    IiopSetUlong(hIiop, 0x1010);
    IiopSetUlong(hIiop, 0x0110);
    IiopEndServiceContext(hIiop);

    // pass long value parameter to request
    IiopSetLong(hIiop, 593814064);

    // call request "DecToHex" with long parameter
    IiopRequest(hIiop, "DecToHex");
    IiopGetServiceContextList(hIiop, hSrvCtx);
    ...
    IiopParserRelease(hSrvCtx);
    IiopObjectRelease(hIiop);
  end TServiceContext;
Parent topic: Basic CORBA Functions


IiopObjectRelease Function

Action

Releases a CORBA object and frees all resources.

Note: CORBA objects are automatically released if the IiopObjectCreate function is called to bind a handle to another object.

Include file

IIOP.bdh

Syntax

IiopObjectRelease(inout hIiop: number): boolean;

Return value

  • true if successful

  • false otherwise

Parameter | Description
hIiop | Handle to a CORBA object

Example

dcltrans
transaction TObjectRelease
const
HOST := "192.168.20.21"; // server
PORT := 1052; // port
KEY := "...\h00"; // key
KEYLEN := 4; // key length
var
hIiop : number;
// handle to a CORBA objectnSum : number;
begin
IiopSetMaxGiopVersion("1.2");IiopSetByteOrder(IIOP_BIG_ENDIAN);
// retrieve handle to server
IiopObjectCreate(hIiop, "IDL:DemoObject:1.0", "1.2",HOST, PORT, KEY, KEYLEN);
// call request "Print"
IiopRequest(hIiop, "Print", IIOP_ONEWAY);
IiopObjectRelease(hIiop);
end TObjectRelease;
Parent topic: Basic CORBA Functions
Related reference
IiopObjectCreate Function
IiopObjectByIor Function


IiopObjectShutdown Function

Action

Closes a connection to a specified CORBA object. Since connections to the corresponding object are opened and close automatically, calling this function is necessary only in individual cases, for example, to perform some specific bootstrapping procedures.

Include file

IIOP.bdh

Syntax

IiopObjectShutdown(in hIiop: number): boolean;

Return value

  • true if successful

  • false otherwise

Parameter | Description
hIiop | Handle to a CORBA object

Example

dcltrans
  transaction TMain
  const
    HOST := "192.168.20.21"; // server
    PORT := 1052; // port
    KEY := "...\h00"; // key
    KEYLEN := 4; // key length
  var
    hIiop: number; // handle to CORBA object
  begin
    IiopSetMaxGiopVersion("1.2");
    IiopSetByteOrder(IIOP_BIG_ENDIAN);IiopObjectCreate(hIiop, "IDL:DemoObject:1.0", "1.2",
                                                       HOST, PORT, KEY, KEYLEN);
    IiopObjectConnect(hIiop);
    ...
    IiopObjectShutdown(hIiop);IiopObjectRelease(hIiop);
  end TMain;
Parent topic: Basic CORBA Functions
Related reference
IiopObjectConnect Function


IiopObjectSetSsl Function

Action

Specifies to access a given CORBA object using the Secure Socket Layer protocol.

Include file

IIOP.bdh

Syntax

IiopObjectSetSsl(in hIiop      : number,
                 in nTargetSup : number,
                 in nTargetReq : number,
                 in nPort      : number): boolean;

Return value

  • true if successful

  • false otherwise

Parameter | Description
hIiop | Handle to a CORBA object
nTargetSup | "AssociationOptions TargetSupports" as defined in Secure Socket Layer/CORBA Security. Although the value of this parameter is written to the IOR of the specified object, it does not affect the way the object is accessed. Use the SslSetEncryption and SslSetClientCert functions to specify security options
nTargetReq | "AssociationOptions TargetSupports" as defined in Secure Socket Layer/CORBA Security. Although the value of this parameter is written to the IOR of the specified object, it does not affect the way the object is accessed.
nPort | Number of the port the specified CORBA object listens to in order to be accessed over a secure connection

Example

var
ghIiop0: number;
dcltrans
transaction TMain
const
HOST := "192.168.20.21"; // server
PORT := 1052; // port
KEY := "...\h00"; // key
KEYLEN := 4; // key length
var
nSize : number;
bReturn : boolean;
begin
SslSetEncryption(3);
IiopSetMaxGiopVersion("1.2");
IiopSetByteOrder(IIOP_LITTLE_ENDIAN);
IiopObjectCreate(ghIiop0, "IDL:DemoObject:1.0", "1.2", HOST, PORT, KEY, KEYLEN);
IiopObjectSetSsl(ghIiop0, 0, 0, 2059);
IiopRequest(ghIiop0, "_non_existent");
IiopGetBoolean(ghIiop0);
...
end TMain;
Parent topic: Basic CORBA Functions
Related reference
IiopObjectSetInterface Function


IiopObjectSetBidirectional Function

Action

Prepares a connection to a remote object in order to receive callbacks for a local object.

Include file

IIOP.bdh

Syntax

IiopObjectSetBidirectional( in hRemote : number,
                            in hLocal  : number,
                            in nFlags  : number optional ): boolean;

Return value

  • true if successful

  • false otherwise

Parameter | Description
hRemote | Remote CORBA object. The connection between the local and the remote object is prepared to receive bidirectional IIOP traffic.
hLocal | Local CORBA object. The connection between the local and the remote object is prepared to receive bidirectional IIOP traffic.
nFlags

Bidirectional connection flag (optional).

Pass the IIOP_NO_LISTEN flag to the function to prevent Silk Performer from preparing resources for incoming connects during a subsequent IiopObjectListen function call. Unless you specify this flag, Silk Performer accepts both incoming connects and bidirectional IIOP. When you pass this flag to the function, only bidirectional IIOP is accepted.

Pass the IIOP_USE_ORBIX_BIDIR_TAG flag to the function to modify the IOR of the callback object, in fact, for the Orbix ORB to use bidirectional IIOP when it tries to invoke the callback.

Example

var
  hRemote, hCallback: number;
 dcltrans
  transaction TMain
  begin
    // set up a callback object
    IiopObjectCreate(hCallback, "IDL:local:1.0" , "1.2",
                    "MyComputer", 0, "key");
    IiopObjectSetBidirectional(hRemote, hCallback,
                               IIOP_USE_ORBIX_BIDIR_TAG);
    IiopObjectListen(hCallback, "callback_func");
    // export the callback
    IiopSetObject(hRemote, hCallback);
    IiopRequest(hRemote, "func", IIOP_ONEWAY);
  end TMain;
Parent topic: Basic CORBA Functions


Status Retrieving Functions

  • IiopGetReplyDataLen Function
    Retrieves the size of the reply associated with a CORBA object after an IiopRequest function call.
  • IiopGetReplyStatus Function
Parent topic: CORBA Functions Reference


IiopGetReplyDataLen Function

Action

Retrieves the size of the reply associated with a CORBA object after an IiopRequest function call.

Include file

IIOP.bdh

Syntax

IiopGetReplyDataLen( in  hIiop    : number,
                     out nDataLen : number,
                     in  nAlign   : number optional ): boolean;

Return value

  • true if successful

  • false otherwise

Parameter | Description
hIiop | Handle to a CORBA object
nDataLen | Variable receiving the size of the reply associated with a CORBA object
nAlign

Reply data alignment (optional). Possible options are:

  • IIOP_ALIGN_2. Alignment to 2-byte boundaries

  • IIOP_ALIGN_4. Alignment to 4-byte boundaries

  • IIOP_ALIGN_8. Alignment to 8-byte boundaries

  • IIOP_ALIGN_16. Alignment to 16-byte boundaries

Default setting is alignment to 1-byte boundaries.

Example

dcltrans
  transaction TGetReplyDataLen
  const
    HOST := "192.168.20.21"; // server
    PORT := 1052;            // port
    KEY := "...\h00";        // key
    KEYLEN := 4;             // key length
  var
    hIiop : number; // handle to CORBA object
    nLen : number;
    sLower : string;
  begin
    IiopSetMaxGiopVersion("1.0");
    IiopSetByteOrder(IIOP_BIG_ENDIAN);

    // retrieve handle to server
    IiopObjectCreate(hIiop, "IDL:DemoObject:1.0", "1.2",
    HOST, PORT, KEY, KEYLEN);

   // call request "ToLower" with string parameter
    IiopSetString(hIiop, "CONVERT TO LOWERCASE");
    IiopRequest(hIiop, "ToLower");

    // retrieve length of return parameters
    IiopGetReplyDataLen(hIiop, nLen);
    write("length = "); write(nLen); writeln;

    // retrieve string return parameter
    IiopGetString(hIiop, sLower);
    write("converted string = "); write(sLower); writeln;
    IiopObjectRelease(hIiop);
  end TGetReplyDataLen;

Output

length = 21converted string = convert to lowercase
Parent topic: Status Retrieving Functions
Related reference
IiopGetStatistics Function
IiopGetReplyStatus Function
IiopRequest Function


IiopGetReplyStatus Function

Action

Retrieves the reply status of the service previously requested, either IiopRequest or IiopLocateRequest.

Include file

IIOP.bdh

Syntax

IiopGetReplyStatus( in  hIiop   : number,
                    out nStatus : number ): boolean;

Return value

  • true if successful

  • false otherwise

Parameter | Description
hIiop | Handle to a CORBA object
nStatus

Variable receiving the reply status. Possible return values for IiopRequest are:

  • IIOP_NO_EXCEPTION: Request completed successfully

  • IIOP_USER_EXCEPTION: User exception occurred

  • IIOP_SYSTEM_EXCEPTION: System exception occurred

  • IIOP_ABORTED: Request aborted, for example, when a timeout occurs

  • IIOP_LOCATION_FWD_PERM: Object is located elsewhere

  • IIOP_NEEDS_ADDR_MODE: Further addressing information needed to locate object

Possible return values for IiopLocateRequest are:

  • IIOP_UNKNOWN_OBJECT: The object is not recognized

  • IIOP_OBJECT_HERE: Object is present

  • IIOP_OBJECT_FORWARD: Object is located elsewhere

  • IIOP_OBJECT_FWD_PERM: Object is permanently located elsewhere

  • IIOP_LOC_SYS_EXCEPTION: System exception occurred

  • IIOP_LOC_NEEDS_ADDR_MODE: Further addressing information needed to locate object

Example

dcltrans
  transaction TGetReplyStatus
  const
    HOST   := "192.168.20.21"; // server
    PORT   := 1052; // port
    KEY    := "...\h00"; // key
    KEYLEN := 4; // key length
  var
    hIiop   : number; // handle to CORBA object
    nStatus : number;
  begin
    IiopSetMaxGiopVersion("1.0");
    IiopSetByteOrder(IIOP_BIG_ENDIAN);

    // retrieve handle to server
    IiopObjectCreate(hIiop, "IDL:DemoObject:1.0", "1.2",
                     HOST, PORT, KEY, KEYLEN);

    // call request "Init"
    IiopRequest(hIiop, "Init");

     // retrieve status
    IiopGetReplyStatus(hIiop, nStatus);

    if nStatus = IIOP_NO_EXCEPTION then
      write("initialization completed successfully");
    else
      write("error during initialization");
    end;

    writeln;
    IiopObjectRelease(hIiop);
  end TGetReplyStatus;

Output

initialization completed successfully
Parent topic: Status Retrieving Functions
Related reference
IiopGetStatistics Function
IiopGetReplyDataLen Function
IiopRequest Function


Parameter Setting and Getting Functions Overview

The following functions can be used to set the parameters and retrieve the return parameters of an operation in advance of calling the IiopRequest function. Each function call associates a specified parameter with a CORBA object or retrieves a return parameter after a request.

Some additional functions are provided to retrieve information about the status and the reply of a request.

  • IiopTypecodeCmp Function
    Checks whether two typecodes are equal.
  • Parameter Setting Functions
    Lists BDL functions for setting the parameters of an operation in advance of calling the IiopRequest function.
  • Parameter Getting Functions
    Lists BDL functions for retrieving the return parameters of an operation in advance of calling the IiopRequest function.
Parent topic: CORBA Functions Reference


IiopTypecodeCmp Function

Action

Checks whether two typecodes are equal. Since typecodes defined in CORBA contain padding bytes that can be set to arbitrary values, you cannot determine the equality of two typecodes by using binary comparison.

Include file

IIOP.bdh

Syntax

IiopTypecodeCmp( in sTypecode1 : string,
                 in nTc1Len    : number,
                 in sTypecode2 : string,
                 in nTc2Len    : number optional ): boolean;

Return value

  • true if the typecodes are equal

  • false otherwise

Parameter | Description
sTypecode1 | Buffer containing the first typecode.
nTc1Len | Length of the first typecode.
sTypecode2 | Buffer containing the second typecode.
nTc2Len | Length of the second typecode (optional).
Parent topic: Parameter Setting and Getting Functions Overview


Parameter Setting Functions

  • IiopSetAnyAsBoolean Function
    Assigns a boolean value to an instance of the Any type and associates the instance with a CORBA object.
  • IiopSetAnyAsChar Function
    Assigns a character to an instance of the Any type and associates the instance with a CORBA object.
  • IiopSetAnyAsDouble Function
    Assigns a double value to an instance of the Any type and associates the instance with a CORBA object.
  • IiopSetAnyAsFloat Function
    Assigns a floating-point value to an instance of the Any type and associates the instance with a CORBA object.
  • IiopSetAnyAsLLong Function
    Assigns an 8-byte long value to an instance of the Any type and associates the instance with a CORBA object.
  • IiopSetAnyAsLong Function
    Assigns a long value to an instance of the Any type and associates the instance with a CORBA object.
  • IiopSetAnyAsObject Function
    Assigns an object to an instance of the Any type and associates the instance with a CORBA object.
  • IiopSetAnyAsOctet Function
    Assigns an octet to an instance of the Any type and associates the instance with a CORBA object.
  • IiopSetAnyAsShort Function
    Assigns a short value to an instance of the Any type and associates the instance with a CORBA object.
  • IiopSetAnyAsString Function
    Assigns a string to an instance of the Any type and associates the instance with a CORBA object.
  • IiopSetAnyAsULLong Function
    Assigns an unsigned 8-byte long value to an instance of the Any type and associates the instance with a CORBA object.
  • IiopSetAnyAsULong Function
    Assigns an unsigned long value to an instance of the Any type and associates the instance with a CORBA object.
  • IiopSetAnyAsUShort Function
    Assigns an unsigned short value to an instance of the Any type and associates the instance with a CORBA object.
  • IiopSetAnyAsWChar Function
    Assigns a wide character to an instance of the Any type and associates the instance with a CORBA object.
  • IiopSetAnyAsWString Function
    Assigns a wide character string to an instance of the Any type and associates the instance with a CORBA object.
  • IiopSetBinary Function
    Associates a parameter containing binary data with a CORBA object.
  • IiopSetBinaryFromFile Function
    Reads binary data from a file and associates the data with a CORBA object.
  • IiopSetBoolean Function
    Associates a boolean parameter with a CORBA object.
  • IiopSetChar Function
    Associates a character parameter with a CORBA object.
  • IiopSetDouble Function
    Associates a double value parameter with a CORBA object.
  • IiopSetFloat Function
    Associates a float value parameter with a CORBA object. This function can be used to set parameters of a request in advance of calling the IiopRequest function.
  • IiopSetFragment Function
    Indicates the begin of a new fragment. This function causes data (subsequentially set via IiopSet functions) to be sent by means of a new fragment.
  • IiopSetLLong Function
    Associates an 8-byte long parameter with a CORBA object or with an Any data type.
  • IiopSetLong Function
    Associates a long value parameter with a CORBA object.
  • IiopSetObject Function
    Associates an object parameter with a CORBA object.
  • IiopSetOctet Function
    Associates an octet parameter with a CORBA object.
  • IiopSetOctetSequence Function
    Associates a octet sequence parameter with a CORBA object.
  • IiopSetShort Function
    Associates a short value parameter with a CORBA object.
  • IiopSetString Function
    Associates a string parameter with a CORBA object.
  • IiopSetULLong Function
    Associates an 8-byte long parameter with a CORBA object or with an Any data type.
  • IiopSetULong Function
    Associates an unsigned long value parameter with a CORBA object.
  • IiopSetUShort Function
  • IiopSetValueIndirect Function
    Associates a value type indirection parameter with a CORBA object.
  • IiopSetValue Function
    Sets the header of a value type parameter that is associated with a CORBA object.
  • IiopSetWChar Function
    Associates a wide character parameter with a CORBA object.
  • IiopSetWString Function
    Associates a wide character string parameter with a CORBA object.
Parent topic: Parameter Setting and Getting Functions Overview


IiopSetAnyAsBoolean Function

Action

Assigns a boolean value to an instance of the Any type and associates the instance with a CORBA object. The instance of the Any type is created and released automatically. This function can be used to set parameters of a request in advance of calling the IiopRequest function.

Include file

IIOP.bdh

Syntax

IiopSetAnyAsBoolean( in hIiop  : number,
                     in bValue : boolean ): boolean;

Return value

  • true if successful

  • false otherwise

Parameter | Description
hIiop | Handle to a CORBA object.
bValue | Boolean value that is assigned to the instance of the Any type and then associated with the CORBA object.

Example

dcltrans
  transaction TMain
  const
    HOST   := "192.168.20.21"; // server
    PORT   := 1052; // port
    KEY    := "...\h00"; // key
    KEYLEN := 4; // key length
  var
    hIiop: number; // handle to CORBA object
  begin
    IiopSetMaxGiopVersion("1.2");
    IiopSetByteOrder(IIOP_BIG_ENDIAN);

    // retrieve handle to server
    IiopObjectCreate(hIiop, "IDL:DemoObject:1.0", "1.2",
                     HOST, PORT, KEY, KEYLEN);
    // pass boolean value parameter to request
    IiopSetAnyAsBoolean(hIiop, true);

    // call operation "Print" with boolean parameter
    IiopRequest(hIiop, "Print");
    IiopObjectRelease(hIiop);
  end TMain;
Parent topic: Parameter Setting Functions
Related reference
IiopRequest Function


IiopSetAnyAsChar Function

Action

Assigns a character to an instance of the Any type and associates the instance with a CORBA object. The instance of the Any type is created and released automatically. This function can be used to set parameters of a request in advance of calling the IiopRequest function.

Include file

IIOP.bdh

Syntax

IiopSetAnyAsChar( in hIiop : number,
                  in nChar : number ): boolean;

Return value

  • true if successful

  • false otherwise

Parameter | Description
hIiop | Handle to a CORBA object.
nChar | Character that is assigned to the instance of the Any type and then associated with the CORBA object.

Example

dcltrans
  transaction TMain
  const
    HOST   := "192.168.20.21"; // server
    PORT   := 1052; // port
    KEY    := "...\h00"; // key
    KEYLEN := 4; // key length
  var
    hIiop: number; // handle to CORBA object
  begin
    IiopSetMaxGiopVersion("1.2");
    IiopSetByteOrder(IIOP_BIG_ENDIAN);

    // retrieve handle to server
    IiopObjectCreate(hIiop, "IDL:DemoObject:1.0", "1.2",
                     HOST, PORT, KEY, KEYLEN);

    // pass character parameter to request
    IiopSetAnyAsChar(hIiop, ord('A'));
    // call operation "Print" with character parameter
    IiopRequest(hIiop, "Print");
    IiopObjectRelease(hIiop);
  end TMain;
Parent topic: Parameter Setting Functions
Related reference
IiopRequest Function


IiopSetAnyAsDouble Function

Action

Assigns a double value to an instance of the Any type and associates the instance with a CORBA object. The instance of the Any type is created and released automatically. This function can be used to set parameters of a request in advance of calling the IiopRequest function.

Include file

IIOP.bdh

Syntax

IiopSetAnyAsDouble( in hIiop  : number,
                    in fValue : float ): boolean;

Return value

  • true if successful

  • false otherwise

Parameter | Description
hIiop | Handle to a CORBA object.
fValue | Double value that is assigned to the instance of the Any type and then associated with the CORBA object.

Example

dcltrans
  transaction TMain
  const
    HOST   := "192.168.20.21"; // server
    PORT   := 1052; // port
    KEY    := "...\h00"; // key
    KEYLEN := 4; // key length
  var
    hIiop: number; // handle to CORBA object
  begin
    IiopSetMaxGiopVersion("1.2");
    IiopSetByteOrder(IIOP_BIG_ENDIAN);

    // retrieve handle to server
    IiopObjectCreate(hIiop, "IDL:DemoObject:1.0", "1.2",
                     HOST, PORT, KEY, KEYLEN);
    // pass double value parameter to request
    IiopSetAnyAsDouble(hIiop, 2545.58);
    // call operation "Print" with double value parameter
    IiopRequest(hIiop, "Print");
    IiopObjectRelease(hIiop);
  end TMain;
Parent topic: Parameter Setting Functions
Related reference
IiopRequest Function


IiopSetAnyAsFloat Function

Action

Assigns a floating-point value to an instance of the Any type and associates the instance with a CORBA object. The instance of the Any type is created and released automatically. This function can be used to set parameters of a request in advance of calling the IiopRequest function.

Include file

IIOP.bdh

Syntax

IiopSetAnyAsFloat( in hIiop  : number,
                   in fValue : float ): boolean;

Return value

  • true if successful

  • false otherwise

Parameter | Description
hIiop | Handle to a CORBA object.
fValue | Floating-point value that is assigned to the instance of the Any type and then associated with the CORBA object.

Example

dcltrans
  transaction TMain
  const
    HOST   := "192.168.20.21"; // server
    PORT   := 1052; // port
    KEY    := "...\h00"; // key
    KEYLEN := 4; // key length
  var
    hIiop: number; // handle to CORBA object
  begin
    IiopSetMaxGiopVersion("1.2");
    IiopSetByteOrder(IIOP_BIG_ENDIAN);
    // retrieve handle to server
    IiopObjectCreate(hIiop, "IDL:DemoObject:1.0", "1.2",
                     HOST, PORT, KEY, KEYLEN);
    // pass floating-point value parameter to request
    IiopSetAnyAsFloat(hIiop, 5474.05);
    // call operation "Print" with floating-point value parameter
    IiopRequest(hIiop, "Print");
    IiopObjectRelease(hIiop);
  end TMain;
Parent topic: Parameter Setting Functions
Related reference
IiopRequest Function


IiopSetAnyAsLLong Function

Action

Assigns an 8-byte long value to an instance of the Any type and associates the instance with a CORBA object.

Include file

IIOP.bdh

Syntax

IiopSetAnyAsLLong( in hIiop  : number,
                   in nValue : number ): boolean;

Return value

  • true if successful

  • false otherwise

Parameter | Description
hIiop | Handle to a CORBA object.
nValue | 8-byte long value that is assigned to the instance of the Any type and then associated with the CORBA object.

Example

dcltrans
  transaction TMain
  const
    HOST   := "192.168.20.21"; // server
    PORT   := 1052; // port
    KEY    := "...\h00"; // key
    KEYLEN := 4; // key length
  var
    hIiop: number; // handle to CORBA object
  begin
    IiopSetMaxGiopVersion("1.2");
    IiopSetByteOrder(IIOP_BIG_ENDIAN);

    // retrieve handle to server
    IiopObjectCreate(hIiop, "IDL:DemoObject:1.0", "1.2",
                     HOST, PORT, KEY, KEYLEN);

    // pass 8-byte long value to request
    IiopSetAnyAsLLong(hIiop, 1043385);
    // call operation "Print" with 8-byte long value
    IiopRequest(hIiop, "Print");
    IiopObjectRelease(hIiop);
  end TMain;
Parent topic: Parameter Setting Functions
Related reference
IiopRequest Function


IiopSetAnyAsLong Function

Action

Assigns a long value to an instance of the Any type and associates the instance with a CORBA object. The instance of the Any type is created and released automatically. This function can be used to set parameters of a request in advance of calling the IiopRequest function.

Include file

IIOP.bdh

Syntax

IiopSetAnyAsLong( in hIiop  : number,
                  in nValue : number ): boolean;

Return value

  • true if successful

  • false otherwise

Parameter | Description
hIiop | Handle to a CORBA object.
nValue | Long value that is assigned to the instance of the Any type and then associated with the CORBA object.

Example

dcltrans
  transaction TMain
  const
    HOST   := "192.168.20.21"; // server
    PORT   := 1052; // port
    KEY    := "...\h00"; // key
    KEYLEN := 4; // key length
  var
    hIiop: number; // handle to CORBA object
  begin
    IiopSetMaxGiopVersion("1.2");
    IiopSetByteOrder(IIOP_BIG_ENDIAN);

    // retrieve handle to server
    IiopObjectCreate(hIiop, "IDL:DemoObject:1.0", "1.2",
                     HOST, PORT, KEY, KEYLEN);

    // pass long value parameter to request
    IiopSetAnyAsLong(hIiop, 1043385);

    // call operation "Print" with long value parameter
    IiopRequest(hIiop, "Print");
    IiopObjectRelease(hIiop);
  end TMain;
Parent topic: Parameter Setting Functions
Related reference
IiopRequest Function


IiopSetAnyAsObject Function

Action

Assigns an object to an instance of the Any type and associates the instance with a CORBA object. The instance of the Any type is created and released automatically. This function can be used to set parameters of a request in advance of calling the IiopRequest function.

Include file

IIOP.bdh

Syntax

IiopSetAnyAsObject( in hIiop   : number,
                    in hObject : number ): boolean;

Return value

  • true if successful

  • false otherwise

Parameter | Description
hIiop | Handle to a CORBA object
hObject | Object that is assigned to the instance of the Any type and then associated with the CORBA object.

Example

var
  hObject: number;

dcltrans
  transaction TMain
  const
    HOST   := "192.168.20.21"; // server
    PORT   := 1052; // port
    KEY    := "...\h00"; // key
    KEYLEN := 4; // key length
  var
    hIiop: number; // handle to CORBA object
  begin
    IiopSetMaxGiopVersion("1.2");    IiopSetByteOrder(IIOP_BIG_ENDIAN);

    // retrieve handle to server
    IiopObjectCreate(hIiop, "IDL:DemoObject:1.0", "1.2",
                     HOST, PORT, KEY, KEYLEN);
    // pass object parameter to request
    IiopSetAnyAsObject(hIiop, hObject);

    // call request "GetInfo" with object parameter
    IiopRequest(hIiop, "GetInfo");
    ...
    IiopObjectRelease(hIiop);
  end TMain;
Parent topic: Parameter Setting Functions
Related reference
IiopRequest Function


IiopSetAnyAsOctet Function

Action

Assigns an octet to an instance of the Any type and associates the instance with a CORBA object. The instance of the Any type is created and released automatically. This function can be used to set parameters of a request in advance of calling the IiopRequest function.

Include file

IIOP.bdh

Syntax

IiopSetAnyAsOctet( in hIiop  : number,
                   in nOctet : number ): boolean;

Return value

  • true if successful

  • false otherwise

Parameter | Description
hIiop | Handle to a CORBA object.
nOctet | Octet that is assigned to the instance of the Any type and then associated with the CORBA object.

Example

dcltrans
  transaction TMain
  const
    HOST   := "192.168.20.21"; // server
    PORT   := 1052; // port
    KEY    := "...\h00"; // key
    KEYLEN := 4; // key length
  var
    hIiop: number; // handle to CORBA object
  begin
    IiopSetMaxGiopVersion("1.2");
    IiopSetByteOrder(IIOP_BIG_ENDIAN);

    // retrieve handle to server
    IiopObjectCreate(hIiop, "IDL:DemoObject:1.0", "1.2",
                     HOST, PORT, KEY, KEYLEN);

    // pass octet parameter to request
    IiopSetAnyAsOctet(hIiop, ord('A'));

    // call operation "Print" with octet parameter
    IiopRequest(hIiop, "Print");
    IiopObjectRelease(hIiop);
  end TMain;
Parent topic: Parameter Setting Functions


IiopSetAnyAsShort Function

Action

Assigns a short value to an instance of the Any type and associates the instance with a CORBA object. The instance of the Any type is created and released automatically. This function can be used to set parameters of a request in advance of calling the IiopRequest function.

Include file

IIOP.bdh

Syntax

IiopSetAnyAsShort( in hIiop  : number,
                   in nValue : number ): boolean;

Return value

  • true if successful

  • false otherwise

Parameter | Description
hIiop | Handle to a CORBA object.
nValue | Short value that is assigned to the instance of the Any type and then associated with the CORBA object.

Example

dcltrans
  transaction TMain
  const
    HOST   := "192.168.20.21"; // server
    PORT   := 1052; // port
    KEY    := "...\h00"; // key
    KEYLEN := 4; // key length
  var
    hIiop: number; // handle to CORBA object
  begin
    IiopSetMaxGiopVersion("1.2");
    IiopSetByteOrder(IIOP_BIG_ENDIAN);

    // retrieve handle to server
    IiopObjectCreate(hIiop, "IDL:DemoObject:1.0", "1.2",
                     HOST, PORT, KEY, KEYLEN);

    // pass short value parameter to request
    IiopSetAnyAsShort(hIiop, 5);

    // call operation "Print" with short value parameter
    IiopRequest(hIiop, "Print");
    IiopObjectRelease(hIiop);
  end TMain;
Parent topic: Parameter Setting Functions
Related reference
IiopRequest Function


IiopSetAnyAsString Function

Action

Assigns a string to an instance of the Any type and associates the instance with a CORBA object. The instance of the Any type is created and released automatically. This function can be used to set parameters of a request in advance of calling the IiopRequest function.

Include file

IIOP.bdh

Syntax

IiopSetAnyAsString( in hIiop   : number,
                    in sString : string,
                    in nFlags  : number optional,
                    in nMaxLen : number optional ): boolean;

Return value

  • true if successful

  • false otherwise

Parameter | Description
hIiop | Handle to a CORBA object.
sString | String that is assigned to the instance of the Any type and then associated with the CORBA object.
nFlags | Specifies whether to pass the string as a sequence of ASCII characters or wide characters (optional). By default, the string is passed as a sequence of ASCII characters.
nMaxLen | Specifies the maximum string length of sString.

Example

dcltrans
  transaction TMain
  const
    HOST   := "192.168.20.21"; // server
    PORT   := 1052; // port
    KEY    := "...\h00"; // key
    KEYLEN := 4; // key length
  var
    hIiop: number; // handle to CORBA object
  begin
    IiopSetMaxGiopVersion("1.2");
    IiopSetByteOrder(IIOP_BIG_ENDIAN);

    // retrieve handle to server
    IiopObjectCreate(hIiop, "IDL:DemoObject:1.0", "1.2",
                     HOST, PORT, KEY, KEYLEN);

    // pass string parameter to request
    IiopSetAnyAsString(hIiop, "Hello world!");

    // call operation "Print" with string parameter
    IiopRequest(hIiop, "Print");
    IiopObjectRelease(hIiop);
  end TMain;
Parent topic: Parameter Setting Functions
Related reference
IiopRequest Function


IiopSetAnyAsULLong Function

Action

Assigns an unsigned 8-byte long value to an instance of the Any type and associates the instance with a CORBA object.

Include file

IIOP.bdh

Syntax

IiopSetAnyAsULLong( in hIiop  : number,
                    in nValue : number ): boolean;

Return value

  • true if successful

  • false otherwise

Parameter | Description
hIiop | Handle to a CORBA object.
nValue | Unsigned 8-byte long value that is assigned to the instance of the Any type and then associated with the CORBA object.

Example

dcltrans
  transaction TMain
  const
    HOST   := "192.168.20.21"; // server
    PORT   := 1052; // port
    KEY    := "...\h00"; // key
    KEYLEN := 4; // key length
  var
    hIiop: number; // handle to CORBA object
  begin
    IiopSetMaxGiopVersion("1.2");
    IiopSetByteOrder(IIOP_BIG_ENDIAN);

    // retrieve handle to server
    IiopObjectCreate(hIiop, "IDL:DemoObject:1.0", "1.2",
                     HOST, PORT, KEY, KEYLEN);

    // pass unsigned 8-byte long value to request
    IiopSetAnyAsULLong(hIiop, 5496303);

    // call operation with 8-byte unsigned long value
    IiopRequest(hIiop, "Print");
    IiopObjectRelease(hIiop);
  end TMain;
Parent topic: Parameter Setting Functions
Related reference
IiopRequest Function


IiopSetAnyAsULong Function

Action

Assigns an unsigned long value to an instance of the Any type and associates the instance with a CORBA object. The instance of the Any type is created and released automatically. This function can be used to set parameters of a request in advance of calling the IiopRequest function.

Include file

IIOP.bdh

Syntax

IiopSetAnyAsULong( in hIiop  : number,
                   in nValue : number ): boolean;

Return value

  • true if successful

  • false otherwise

Parameter | Description
hIiop | Handle to a CORBA object.
nValue | Unsigned long value that is assigned to the instance of the Any type and then associated with the CORBA object.

Example

dcltrans
  transaction TMain
  const
    HOST   := "192.168.20.21"; // server
    PORT   := 1052; // port
    KEY    := "...\h00"; // key
    KEYLEN := 4; // key length
  var
    hIiop: number; // handle to CORBA object
  begin
    IiopSetMaxGiopVersion("1.2");
    IiopSetByteOrder(IIOP_BIG_ENDIAN);

    // retrieve handle to server
    IiopObjectCreate(hIiop, "IDL:DemoObject:1.0", "1.2",
                     HOST, PORT, KEY, KEYLEN);

    // pass unsigned long value parameter to request
    IiopSetAnyAsULong(hIiop, 5496303);

    // call operation "Print" with unsigned long value parameter
    IiopRequest(hIiop, "Print");
    IiopObjectRelease(hIiop);
  end TMain;
Parent topic: Parameter Setting Functions
Related reference
IiopRequest Function


IiopSetAnyAsUShort Function

Action

Assigns an unsigned short value to an instance of the Any type and associates the instance with a CORBA object. The instance of the Any type is created and released automatically. This function can be used to set parameters of a request in advance of calling the IiopRequest function.

Include file

IIOP.bdh

Syntax

IiopSetAnyAsUShort( in hIiop  : number,
                    in nValue : number ): boolean;

Return value

  • true if successful

  • false otherwise

Parameter | Description
hIiop | Handle to a CORBA object.
nValue | Unsigned short value that is assigned to the instance of the Any type and then associated with the CORBA object.

Example

dcltrans
  transaction TMain
  const
    HOST   := "192.168.20.21"; // server
    PORT   := 1052;            // port
    KEY    := "...\h00";       // key
    KEYLEN := 4;               // key length
  var
    hIiop: number; // handle to CORBA object
  begin
    IiopSetMaxGiopVersion("1.2");
    IiopSetByteOrder(IIOP_BIG_ENDIAN);

    // retrieve handle to server
    IiopObjectCreate(hIiop, "IDL:DemoObject:1.0", "1.2",
                     HOST, PORT, KEY, KEYLEN);
    // pass unsigned short value parameter to request
    IiopSetAnyAsUShort(hIiop, 175);

    // call operation "Print" with unsigned short value parameter
    IiopRequest(hIiop, "Print");
    IiopObjectRelease(hIiop);
  end TMain;
Parent topic: Parameter Setting Functions
Related reference
IiopRequest Function


IiopSetAnyAsWChar Function

Action

Assigns a wide character to an instance of the Any type and associates the instance with a CORBA object. The instance of the Any type is created and released automatically. This function can be used to set parameters of a request in advance of calling the IiopRequest function.

Include file

IIOP.bdh

Syntax

IiopSetAnyAsWChar( in hIiop  : number,
                   in nWChar : number,
                   in nType  : number optional ): boolean;

Return value

  • true if successful

  • false otherwise

Parameter | Description
hIiop | Handle to a CORBA object.
nWChar | Wide character that is assigned to the instance of the Any type and then associated with the CORBA object.
nType

Defines the byte order of the wide character (optional). Pass one of the following flags to the function:

  • IIOP_BYTE_ORIENTED (default)

  • IIOP_WIDE_LITTLE_ENDIAN

  • IIOP_WIDE_BIG_ENDIAN

Example

var
  nWChar: number;

dcltrans
  transaction TMain
  const
    HOST   := "192.168.20.21"; // server
    PORT   := 1052;            // port
    KEY    := "...\h00";       // key
    KEYLEN := 4;               // key length
  var
    hIiop: number; // handle to CORBA object
  begin
    IiopSetMaxGiopVersion("1.0");
    IiopSetByteOrder(IIOP_BIG_ENDIAN);

    // retrieve handle to server
    IiopObjectCreate(hIiop, "IDL:DemoObject:1.0", "1.2",
                     HOST, PORT, KEY, KEYLEN);

    // pass wide character parameter to request
    IiopSetAnyAsWChar(hIiop, nWChar);

    // call operation "Print" with wide character parameter
    IiopRequest(hIiop, "Print");
    IiopObjectRelease(hIiop);
  end TMain;
Parent topic: Parameter Setting Functions
Related reference
IiopRequest Function


IiopSetAnyAsWString Function

Action

Assigns a wide character string to an instance of the Any type and associates the instance with a CORBA object. The instance of the Any type is created and released automatically. This function can be used to set parameters of a request in advance of calling the IiopRequest function.

Include file

IIOP.bdh

Syntax

IiopSetAnyAsWString( in hIiop      : number,
                     in sString    : string,
                     in nStringLen : number ): boolean;

Return value

  • true if successful

  • false otherwise

Parameter | Description
hIiop | Handle to a CORBA object.
sString | Wide character string that is assigned to the instance of the Any type and then associated with the CORBA object.
nStringLen | Length of the wide character string.

Example

var
  sString: string;

dcltrans
  transaction TMain
  const
    HOST   := "192.168.20.21"; // server
    PORT   := 1052;            // port
    KEY    := "...\h00";       // key
    KEYLEN := 4;               // key length
  var
    hIiop: number; // handle to CORBA object
  begin
    IiopSetMaxGiopVersion("1.2");
    IiopSetByteOrder(IIOP_BIG_ENDIAN);

    // retrieve handle to server
    IiopObjectCreate(hIiop, "IDL:DemoObject:1.0", "1.2",
                     HOST, PORT, KEY, KEYLEN);

    // pass wide character string to request
    IiopSetAnyAsWString(hIiop, sString, 32);

     // call operation "Print" with wide character string parameter
    IiopRequest(hIiop, "Print");
    IiopObjectRelease(hIiop);
  end TMain;
Parent topic: Parameter Setting Functions
Related reference
IiopRequest Function


IiopSetBinary Function

Action

Associates a parameter containing binary data with a CORBA object. This function can be used to set parameters of a request in advance of calling the IiopRequest function.

Include file

IIOP.bdh

Syntax

IiopSetBinary( in hIiop      : number,
               in sBuffer    : string,
               in nBufferLen : number optional,
               in nAlign     : number optional): boolean;

Return value

  • true if successful

  • false otherwise

Parameter | Description
hIiop | Handle to a CORBA object
sBuffer | Buffer containing the binary data that will be associated with the CORBA object
nBufferLen

Number of binary data bytes that are associated with the CORBA object (optional). If specified, make sure to set

nDataLen <= size of sBuffer

nAlign

Binary data alignment (optional). Possible options are:

  • IIOP_ALIGN_2. Alignment to 2-byte boundaries

  • IIOP_ALIGN_4. Alignment to 4-byte boundaries

  • IIOP_ALIGN_8. Alignment to 8-byte boundaries

  • IIOP_ALIGN_16. Alignment to 16-byte boundaries

Default setting is alignment to 1-byte boundaries.

In addition, the byte order within the binary data can be specified:

  • IIOP_BIG_ENDIAN. Most significant byte is sent first

  • IIOP_LITTLE_ENDIAN. Least significant byte is sent first

Example

dcltrans
  transaction TSetBinary
  const
    HOST   := "192.168.20.21"; // server
    PORT   := 1052;            // port
    KEY    := "...\h00";       // key
    KEYLEN := 4;               // key length
  var
    hIiop : number; // handle to CORBA object
    sBuffer : string(512);
  begin
    IiopSetMaxGiopVersion("1.0");
    IiopSetByteOrder(IIOP_BIG_ENDIAN);

    // retrieve handle to server
    IiopObjectCreate(hIiop, "IDL:DemoObject:1.0", "1.2",HOST, PORT, KEY, KEYLEN);
    // initialize buffer
    ...
    // pass parameter to request
    IiopSetBinary(hIiop, sBuffer, STRING_COMPLETE, IIOP_ALIGN_16 | IIOP_BIG_ENDIAN);
    // call request "Print" to print data
    IiopRequest(hIiop, "Print", IIOP_ONEWAY);
    IiopObjectRelease(hIiop);
  end TSetBinary;

Sample scripts

AnyDemo.bdf, Conf.bdf, DynAny.bdf

You can find the sample script(s) here: <Public documents>\Silk Performer <version>\Samples\Corba

Parent topic: Parameter Setting Functions
Related reference
IiopGetBinary Function
IiopRequest Function


IiopSetBinaryFromFile Function

Action

Reads binary data from a file and associates the data with a CORBA object. This function can be used to set parameters of a request in advance of calling the IiopRequest function.

Include file

IIOP.bdh

Syntax

IiopSetBinaryFromFile(in hIiop : number,
                      in sFile : string,
                      in nBytes : number optional,
                      in nAlign : number optional): boolean;

Return value

  • true if successful

  • false otherwise

Parameter | Description
hIiop | Handle to a CORBA object
sFile | Name of the file containing the binary data. If NULL, the filename passed to the previous IiopSetBinaryFromFile function call (belonging to the same request) is used
nBytes | Number of bytes to read from the file. If omitted or zero, the whole file is read.
nAlign

Binary data alignment (optional). Possible options are:

  • IIOP_ALIGN_2. Alignment to 2-byte boundaries

  • IIOP_ALIGN_4. Alignment to 4-byte boundaries

  • IIOP_ALIGN_8. Alignment to 8-byte boundaries

  • IIOP_ALIGN_16. Alignment to 16-byte boundaries

Default setting is alignment to 1-byte boundaries.

Example

// send a large graphic file to a printer object
dcltrans
  transaction TSetBinaryFromFile
  const
    FRAGMENTSIZE := 4096;
    FILENAME := "IMAGE.GIF";
  var
    hIiop, nFragments, nFilesize, i: number;
  begin
    // retrieve handle to CORBA object, filesize and
    // number of fragments
    ...
    // send fragmented messageIiopSetBinaryFromFile(hIiop, FILENAME, nFilesize MOD FRAGMENTSIZE);
    for i := 1 to nFragments do

    // indicate begin of new fragment
    IiopSetFragment(hIiop);

    // send next fragment
    IiopSetBinaryFromFile(hIiop, NULL, FRAGMENTSIZE);
    end;
    IiopRequest(hIiop, "print", IIOP_USE_V11);
  end TSetBinaryFromFile;
Parent topic: Parameter Setting Functions
Related reference
IiopRequest Function


IiopSetBoolean Function

Action

Associates a boolean parameter with a CORBA object. This function can be used to set parameters of a request in advance of calling the IiopRequest function.

Include file

IIOP.bdh

Syntax

IiopSetBoolean( in hIiop : number,
                in bBool : boolean ): boolean;

Return value

  • true if successful

  • false otherwise

Parameter | Description
hIiop | Handle to a CORBA object
bBool | Boolean value that will be associated with the CORBA object or with the Any data type

Example

dcltrans
  transaction TSetBoolean
  const
    HOST   := "192.168.20.21"; // server
    PORT   := 1052; // port
    KEY    := "...\h00"; // key
    KEYLEN := 4; // key length
  var
    hIiop: number; // handle to CORBA object
  begin
    IiopSetMaxGiopVersion("1.2");
    IiopSetByteOrder(IIOP_BIG_ENDIAN);

    // retrieve handle to server
    IiopObjectCreate(hIiop, "IDL:DemoObject:1.0", "1.2",
                     HOST, PORT, KEY, KEYLEN);
    // pass boolean parameter to request
    IiopSetBoolean(hIiop, true);

    // call request "Init" with boolean parameter
    IiopRequest(hIiop, "Init", IIOP_ONEWAY);
    IiopObjectRelease(hIiop);
  end TSetBoolean;

Sample scripts

Conf.bdf

You can find the sample script(s) here: <Public documents>\Silk Performer <version>\Samples\Corba

Parent topic: Parameter Setting Functions
Related reference
IiopGetBoolean Function
IiopRequest Function


IiopSetChar Function

Action

Associates a character parameter with a CORBA object. This function can be used to set parameters of a request in advance of calling the IiopRequest function.

Include file

IIOP.bdh

Syntax

IiopSetChar( in hIiop : number,
             in nChar : number ): boolean;

Return value

  • true if successful

  • false otherwise

Parameter | Description
hIiop | Handle to a CORBA object
nChar | Character that will be associated with the CORBA object

Example

dcltrans
  transaction TSetChar
  const
    HOST   := "192.168.20.21"; // server
    PORT   := 1052;            // port
    KEY    := "...\h00";       // key
    KEYLEN := 4;               // key length
  var
    hIiop: number; // handle to CORBA object
  begin
    IiopSetMaxGiopVersion("1.2");
    IiopSetByteOrder(IIOP_BIG_ENDIAN);

    // retrieve handle to server
    IiopObjectCreate(hIiop, "IDL:DemoObject:1.0", "1.2",
                     HOST, PORT, KEY, KEYLEN);

    // pass character parameter to request
    IiopSetChar(hIiop, ord('A'));

    // call request "Convert" with character parameter
    IiopRequest(hIiop, "Convert");
    ...
    IiopObjectRelease(hIiop);
  end TSetChar;

Sample scripts

TypeTest.bdf, Conf.bdf

You can find the sample script(s) here: <Public documents>\Silk Performer <version>\Samples\Corba

Parent topic: Parameter Setting Functions
Related reference
IiopGetChar Function
IiopRequest Function


IiopSetDouble Function

Action

Associates a double value parameter with a CORBA object. This function can be used to set parameters of a request in advance of calling the IiopRequest function.

Include file

IIOP.bdh

Syntax

IiopSetDouble( in hIiop  : number,
               in fValue : float ): boolean;

Return value

  • true if successful

  • false otherwise

Parameter | Description
hIiop | Handle to a CORBA object
fValue | Double value that will be associated with the CORBA object

Example

dcltrans
  transaction TSetDouble
  const
    HOST   := "192.168.20.21"; // server
    PORT   := 1052;            // port
    KEY    := "...\h00";       // key
    KEYLEN := 4;               // key length
  var
    hIiop: number; // handle to CORBA object
  begin
    IiopSetMaxGiopVersion("1.2");    IiopSetByteOrder(IIOP_BIG_ENDIAN);

    // retrieve handle to server
    IiopObjectCreate(hIiop, "IDL:DemoObject:1.0", "1.2",
                     HOST, PORT, KEY, KEYLEN);

    // pass double value parameter to request
    IiopSetDouble(hIiop, 53985.81);

    // call request "SquareRoot" with double value parameter
    IiopRequest(hIiop, "SquareRoot");
    ...
    IiopObjectRelease(hIiop);
  end TSetDouble;

Sample scripts

TypeTest.bdf, Conf.bdf

You can find the sample script(s) here: <Public documents>\Silk Performer <version>\Samples\Corba

Parent topic: Parameter Setting Functions
Related reference
IiopGetDouble Function
IiopRequest Function


IiopSetFloat Function

Action

Associates a float value parameter with a CORBA object. This function can be used to set parameters of a request in advance of calling the IiopRequest function.

Include file

IIOP.bdh

Syntax

IiopSetFloat( in hIiop  : number,
              in fValue : float ): boolean;

Return value

  • true if successful

  • false otherwise

Parameter | Description
hIiop | Handle to a CORBA object
fValue | Float value that will be associated with the CORBA object

Example

dcltrans
  transaction TSetFloat
  const
    HOST   := "192.168.20.21"; // server
    PORT   := 1052;            // port
    KEY    := "...\h00";       // key
    KEYLEN := 4;               // key length
  var
    hIiop: number; // handle to CORBA object
  begin
    IiopSetMaxGiopVersion("1.2");
    IiopSetByteOrder(IIOP_BIG_ENDIAN);

    // retrieve handle to server
    IiopObjectCreate(hIiop, "IDL:DemoObject:1.0", "1.2",
                     HOST, PORT, KEY, KEYLEN);

    // pass float value parameter to request
    IiopSetFloat(hIiop, 401.09);

    // call request "Square" with float value parameter
    IiopRequest(hIiop, "Square");
    ...
    IiopObjectRelease(hIiop);
  end TSetFloat;

Sample scripts

AsyncBank.bdf, Bank.bdf, SimpleAsyncBank.bdf, TypeTest.bdf, Conf.bdf

You can find the sample script(s) here: <Public documents>\Silk Performer <version>\Samples\Corba

Parent topic: Parameter Setting Functions
Related reference
IiopGetFloat Function
IiopRequest Function


IiopSetFragment Function

Action

Indicates the begin of a new fragment. This function causes data (subsequentially set via IiopSet functions) to be sent by means of a new fragment.

Include file

IIOP.bdh

Syntax

IiopSetFragment( in hIiop : number ): boolean;

Return value

  • true if successful

  • false otherwise

Parameter | Description
hIiop | Handle to a CORBA object

Example

dcltrans
  transaction TSetFragment
  var
    hIiop: number;
  begin
    ...
    IiopSetChar(hIiop, ord('A'));
    IiopSetFragment(hIiop);
    IiopSetChar(hIiop, ord('B'));
    IiopSetChar(hIiop, ord('C'));
    IiopSetFragment(hIiop);
    IiopSetChar(hIiop, ord('D'));

    // send a request with two fragments

    // request contains 'A'

    // fragment 1 contains 'B' and 'C'

    // fragment 2 contains 'D'

    IiopRequest(hIiop, "print");
  end TSetFragment;
Parent topic: Parameter Setting Functions
Related reference
IiopRequest Function


IiopSetLLong Function

Action

Associates an 8-byte long parameter with a CORBA object or with an Any data type.

Include file

IIOP.bdh

Syntax

IiopSetLLong( in hIiop  : number,
              in nValue : number ): boolean;

Return value

  • true if successful

  • false otherwise

Parameter | Description
hIiop | Handle to a CORBA object.
nValue | 8-byte long value that will be associated with the CORBA object.

Example

dcltrans
  transaction TSetLong
  const
    HOST   := "192.168.20.21"; // server
    PORT   := 1052;            // port
    KEY    := "...\h00";       // key
    KEYLEN := 4;               // key length
  var
    hIiop: number; // handle to CORBA object
  begin
    IiopSetMaxGiopVersion("1.2");
    IiopSetByteOrder(IIOP_BIG_ENDIAN);

    // retrieve handle to server
    IiopObjectCreate(hIiop, "IDL:DemoObject:1.0", "1.2",
                     HOST, PORT, KEY, KEYLEN);
     // pass 8-byte long value to request
    IiopSetLLong(hIiop, 593814064);

    // call request "DecToHex" with long parameter
    IiopRequest(hIiop, "DecToHex");
    ...
    IiopObjectRelease(hIiop);
  end TSetLong;
Parent topic: Parameter Setting Functions
Related reference
IiopRequest Function


IiopSetLong Function

Action

Associates a long value parameter with a CORBA object. This function can be used to set parameters of a request in advance of calling the IiopRequest function.

Include file

IIOP.bdh

Syntax

IiopSetLong( in hIiop  : number,
             in nValue : number ): boolean;

Return value

  • true if successful

  • false otherwise

Parameter | Description
hIiop | Handle to a CORBA object
nValue | Long value that will be associated with the CORBA object

Example

dcltrans
  transaction TSetLong
  const
    HOST   := "192.168.20.21"; // server
    PORT   := 1052;            // port
    KEY    := "...\h00";       // key
    KEYLEN := 4;               // key length
  var
   hIiop: number; // handle to CORBA object
  begin
    IiopSetMaxGiopVersion("1.2");
    IiopSetByteOrder(IIOP_BIG_ENDIAN);

    // retrieve handle to server
    IiopObjectCreate(hIiop, "IDL:DemoObject:1.0", "1.2",
                      HOST, PORT, KEY, KEYLEN);

    // pass long value parameter to request
    IiopSetLong(hIiop, 593814064);

    // call request "DecToHex" with long parameter
    IiopRequest(hIiop, "DecToHex");
    ...
    IiopObjectRelease(hIiop);
  end TSetLong;

Sample scripts

UnivB.bdf, TypeTest.bdf, AsyncFact.bdf, Conf.bdf, Factory.bdf

You can find the sample script(s) here: <Public documents>\Silk Performer <version>\Samples\Corba

Parent topic: Parameter Setting Functions
Related reference
IiopGetLong Function
IiopRequest Function


IiopSetObject Function

Action

Associates an object parameter with a CORBA object. This function can be used to set parameters of a request in advance of calling the IiopRequest function.

Include file

IIOP.bdh

Syntax

IiopSetObject( in hIiop   : number,
               in hObject : number ): boolean;

Return value

  • true if successful

  • false otherwise

Parameter | Description
hIiop | Handle to a CORBA object
hObject | Handle to the object that will be associated with the CORBA object

Example

var
  hObject: number;

dcltrans
  transaction TMain
  const
    HOST   := "192.168.20.21"; // server
    PORT   := 1052;            // port
    KEY    := "...\h00";       // key
    KEYLEN := 4;               // key length
  var
    hIiop: number; // handle to CORBA object
  begin
    IiopSetMaxGiopVersion("1.2");
    IiopSetByteOrder(IIOP_BIG_ENDIAN);

    // retrieve handle to server
    IiopObjectCreate(hIiop, "IDL:DemoObject:1.0", "1.2",
                     HOST, PORT, KEY, KEYLEN);

    // pass object parameter to request
    IiopSetObject(hIiop, hObject);

    // call request "GetInfo" with object parameter
    IiopRequest(hIiop, "GetInfo");
    ...
    IiopObjectRelease(hIiop);
  end TMain;

Sample scripts

AnyDemo.bdf, Bank.bdf, Callback.bdf, SimpleAsyncBank.bdf, Conf.bdf

You can find the sample script(s) here: <Public documents>\Silk Performer <version>\Samples\Corba

Parent topic: Parameter Setting Functions
Related reference
IiopGetObject Function
IiopRequest Function


IiopSetOctet Function

Action

Associates an octet parameter with a CORBA object. This function can be used to set parameters of a request in advance of calling the IiopRequest function.

Include file

IIOP.bdh

Syntax

IiopSetOctet( in hIiop  : number,
              in nOctet : number ): boolean;

Return value

  • true if successful

  • false otherwise

Parameter | Description
hIiop | Handle to a CORBA object
nOctet | Octet that will be associated with the CORBA object

Example

dcltrans
  transaction TSetOctet
  const
    HOST   := "192.168.20.21"; // server
    PORT   := 1052;            // port
    KEY    := "...\h00";       // key
    KEYLEN := 4;               // key length
  var
    hIiop: number; // handle to CORBA object
  begin
    IiopSetMaxGiopVersion("1.2");
    IiopSetByteOrder(IIOP_BIG_ENDIAN);

    // retrieve handle to server
    IiopObjectCreate(hIiop, "IDL:DemoObject:1.0", "1.2",
                     HOST, PORT, KEY, KEYLEN);

    // pass octet parameter to request
    IiopSetOctet(hIiop, ord('A'));

    // call request "Convert" with octet parameter
    IiopRequest(hIiop, "Convert");
    ...
    IiopObjectRelease(hIiop);
  end TSetOctet;
Parent topic: Parameter Setting Functions
Related reference
IiopGetOctet Function
IiopRequest Function


IiopSetOctetSequence Function

Action

Associates a octet sequence parameter with a CORBA object. This function can be used to set parameters of a request in advance of calling the IiopRequest function.

Include file

IIOP.bdh

Syntax

IiopSetOctetSequence( in hIiop      : number,
                      in sBuffer    : string allownull,
                      in nBufferLen : number optional ): boolean;

Return value

  • true if successful

  • false otherwise

Parameter | Description
hIiop | Handle to a CORBA object.
sBuffer | Buffer containing the octet sequence that will be associated with the CORBA object.
nBufferLen | Number of bytes that are associated with the CORBA object (optional). If specified, make sure to set nBufferLen <= StrSize(sBuffer).

Example

dcltrans
  transaction TSetOctetSequence
  const
    HOST   := "192.168.20.21"; // server
    PORT   := 1052;            // port
    KEY    := "...\h00";       // key
    KEYLEN := 4;               // key length
  var
    hIiop   : number; // handle to CORBA object
    sBuffer : string;
  begin
    IiopSetMaxGiopVersion("1.2");
    IiopSetByteOrder(IIOP_BIG_ENDIAN);

    // retrieve handle to server
    IiopObjectCreate(hIiop, "IDL:DemoObject:1.0", "1.2", HOST, PORT, KEY, KEYLEN);

    // initialize buffer
    ...

    // pass parameter to request
    IiopSetOctetSequence(hIiop, sBuffer);

    // call request "Print" to print data
    IiopRequest(hIiop, "Print", IIOP_ONEWAY);
    IiopObjectRelease(hIiop);
  end TSetOctetSequence;
Parent topic: Parameter Setting Functions
Related reference
IiopGetOctetSequence Function
IiopRequest Function


IiopSetShort Function

Action

Associates a short value parameter with a CORBA object. This function can be used to set parameters of a request in advance of calling the IiopRequest function.

Include file

IIOP.bdh

Syntax

IiopSetShort( in hIiop  : number,
              in nValue : number ): boolean;

Return value

  • true if successful

  • false otherwise

Parameter | Description
hIiop | Handle to a CORBA object
nValue | Short value that will be associated with the CORBA object

Example

dcltrans
  transaction TSetShort
  const
    HOST   := "192.168.20.21"; // server
    PORT   := 1052;            // port
    KEY    := "...\h00";       // key
    KEYLEN := 4;               // key length
  var
    hIiop: number; // handle to CORBA object
  begin
    IiopSetMaxGiopVersion("1.2");
    IiopSetByteOrder(IIOP_BIG_ENDIAN);

    // retrieve handle to server
    IiopObjectCreate(hIiop, "IDL:DemoObject:1.0", "1.2",
                     HOST, PORT, KEY, KEYLEN);

    // pass short value parameter to request
    IiopSetShort(hIiop, 5);

    // call request "GetMsg" with short value parameter
    IiopRequest(hIiop, "GetMsg");
    ...
    IiopObjectRelease(hIiop);
  end TSetShort;

Sample scripts

TypeTest.bdf, Conf.bdf

You can find the sample script(s) here: <Public documents>\Silk Performer <version>\Samples\Corba

Parent topic: Parameter Setting Functions
Related reference
IiopGetShort Function
IiopRequest Function


IiopSetString Function

Action

Associates a string parameter with a CORBA object. This function can be used to set parameters of a request in advance of calling the IiopRequest function.

Include file

IIOP.bdh

Syntax

IiopSetString( in hIiop   : number,
               in sString : string
               in nFlags  : number optional ): boolean;

Return value

  • true if successful

  • false otherwise

Parameter | Description
hIiop | Handle to a CORBA object.
sString | String that will be associated with the CORBA object.
nFlags | If the string should be set as wide string set this parameter to IIOP_USE_WCHAR (optional).

Example

dcltrans
  transaction TSetString
  const
    HOST   := "192.168.20.21"; // server
    PORT   := 1052;            // port
    KEY    := "...\h00";       // key
    KEYLEN := 4;               // key length
  var
    hIiop: number; // handle to CORBA object
  begin
    IiopSetMaxGiopVersion("1.2");
    IiopSetByteOrder(IIOP_BIG_ENDIAN);

    // retrieve handle to server
    IiopObjectCreate(hIiop, "IDL:DemoObject:1.0", "1.2", HOST, PORT, KEY, KEYLEN);

    // pass string parameter to request
    IiopSetString(hIiop, "Hello world!");

    // call request "Write" with string parameter
    IiopRequest(hIiop, "Write", IIOP_ONEWAY);
    IiopObjectRelease(hIiop);
  end TSetString;

Sample scripts

UnivB.bdf, AnyDemo.bdf, AsyncBank.bdf, Bank.bdf, SimpleAsyncBank.bdf, TypeTest.bdf, AsyncFact.bdf, AsyncOdb.bdf, Conf.bdf, Factory.bdf, Odb.bdf, Vbrokerbank01.bdf, Vbrokerbank02.bdf, VBrokerBankGate.bdf

You can find the sample script(s) here: <Public documents>\Silk Performer <version>\Samples\Corba

Parent topic: Parameter Setting Functions
Related reference
IiopRequest Function


IiopSetULLong Function

Action

Associates an 8-byte long parameter with a CORBA object or with an Any data type.

Include file

IIOP.bdh

Syntax

IiopSetULLong( in hIiop  : number,
               in nValue : number ): boolean;

Return value

  • true if successful

  • false otherwise

Parameter | Description
hIiop | Handle to a CORBA object
nValue | Unsigned 8-byte long value that will be associated with the CORBA object.

Example

dcltrans
  transaction TSetLong
  const
    HOST   := "192.168.20.21"; // server
    PORT   := 1052;            // port
    KEY    := "...\h00";       // key
    KEYLEN := 4;               // key length
  var
    hIiop: number; // handle to CORBA object
  begin
    IiopSetMaxGiopVersion("1.2");
    IiopSetByteOrder(IIOP_BIG_ENDIAN);
    // retrieve handle to server
    IiopObjectCreate(hIiop, "IDL:DemoObject:1.0", "1.2",
                     HOST, PORT, KEY, KEYLEN);
    // pass unsigned 8-byte long parameter to request
    IiopSetULLong(hIiop, 593814064);
    // call request "DecToHex" with long parameter
    IiopRequest(hIiop, "DecToHex");
    ...
    IiopObjectRelease(hIiop);
  end TSetLong;
Parent topic: Parameter Setting Functions
Related reference
IiopRequest Function


IiopSetULong Function

Action

Associates an unsigned long value parameter with a CORBA object. This function can be used to set parameters of a request in advance of calling the IiopRequest function.

Include file

IIOP.bdh

Syntax

IiopSetULong( in hIiop  : number,
              in nValue : number ): boolean;

Return value

  • true if successful

  • false otherwise

Parameter | Description
hIiop | Object handle representing a pointer to a CORBA object
nValue | Unsigned long value that will be associated with the CORBA object Note: If you specify values greater than 2147483647, you have to use the hexadecimal notation.

Example

dcltrans
  transaction TSetULong
  const
    HOST   := "192.168.20.21"; // server
    PORT   := 1052;            // port
    KEY    := "...\h00";       // key
    KEYLEN := 4;               // key length
  var
    hIiop: number; // handle to CORBA object
  begin
    IiopSetMaxGiopVersion("1.2");
    IiopSetByteOrder(IIOP_BIG_ENDIAN);

    // retrieve handle to server
    IiopObjectCreate(hIiop, "IDL:DemoObject:1.0", "1.2",
                     HOST, PORT, KEY, KEYLEN);
    // pass two unsigned long value parameters to request
    IiopSetULong(hIiop, 14501835);
    IiopSetULong(hIiop, 1933766921);

    // call request "Sum" with two unsigned long value parameters
    IiopRequest(hIiop, "Sum");
    ...
    IiopObjectRelease(hIiop);
  end TSetULong;

Sample scripts

UnivB.bdf, Conf.bdf

You can find the sample script(s) here: <Public documents>\Silk Performer <version>\Samples\Corba

Parent topic: Parameter Setting Functions
Related reference
IiopRequest Function


IiopSetUShort Function

Action

Associates an unsigned short value parameter with a CORBA object. This function can be used to set parameters of a request in advance of calling the IiopRequest function.

Include file

IIOP.bdh

Syntax

IiopSetUShort( in hIiop  : number,
               in nValue : number ): boolean;

Return value

  • true if successful

  • false otherwise

Parameter | Description
hIiop | Handle to a CORBA object
nValue | Unsigned short value that will be associated with the CORBA object

Example

dcltrans
  transaction TSetUShort
  const
    HOST   := "192.168.20.21"; // server
    PORT   := 1052;            // port
    KEY    := "...\h00";       // key
    KEYLEN := 4;               // key length
  var
    hIiop: number; // handle to CORBA object
  begin
    IiopSetMaxGiopVersion("1.2");
    IiopSetByteOrder(IIOP_BIG_ENDIAN);

    // retrieve handle to server
    IiopObjectCreate(hIiop, "IDL:DemoObject:1.0", "1.2",
                     HOST, PORT, KEY, KEYLEN);

    // pass two unsigned short value parameters to request
    IiopSetUShort(hIiop, 41);
    IiopSetUShort(hIiop, 117);

    // call request "Product" with two unsigned short value parameters
    IiopRequest(hIiop, "Product");
    ...
    IiopObjectRelease(hIiop);
  end TSetUShort;

Sample scripts

Conf.bdf

You can find the sample script(s) here: <Public documents>\Silk Performer <version>\Samples\Corba

Parent topic: Parameter Setting Functions
Related reference
IiopRequest Function


IiopSetValueIndirect Function

Action

Associates a value type indirection parameter with a CORBA object. This function can be used to set the parameters of a request in advance of calling the IiopRequest function.

Include file

Iiop.bdh

Syntax

IiopSetValueIndirect( in hIiop    : number,
                      in nValueId : number ): boolean;

Return value

  • true if successful

  • false otherwise

Parameter | Description
hIiop | Handle to a CORBA object.
nValueId | ID of the value that is indirected to.

Example

dcltrans
  transaction TSetValue
  const
    HOST        := "192.168.20.21"; // server
    PORT        := 1052;            // port
    KEY         := "...\h00";       // key
    KEYLEN      := 4;               // key length
    REP_ID      := "IDL:SetValueType:1.0";
    REP_ID_LIST := " IDL:DerivedValue:1.0 IDL:BaseValue:1.0 IDL:AbstractValue:1.0";
    CODE_BASE   := "www.codebase.com";
  var
    hIiop : number; // Handle to CORBA object
  begin
    IiopSetMaxGiopVersion("1.2");
    IiopSetByteOrder(IIOP_BIG_ENDIAN);

    // retrieve handle to server
    IiopObjectCreate(hIiop, "IDL:DemoObject:1.0", "1.2", HOST, PORT, KEY, KEYLEN);

    // set value
    IiopSetValue(hIiop, REP_ID, "", FALSE, 1);
    IiopSetLong(hIiop, 5);    IiopEndValue(hIiop);

    // set another value
    IiopSetValue(hIiop, REP_ID_LIST, CODE_BASE, TRUE);
    IiopSetBoolean(hIiop, TRUE);
    IiopSetLong(hIiop, 3);
    IiopSetValueIndirect(hIiop, 1);
    IiopSetString(hIiop, "This is a string");
    IiopEndValue(hIiop);

    // call request "SetValue"
    IiopRequest(hIiop, "SetValue");
    IiopObjectRelease(hIiop);
  end TSetValue;
Parent topic: Parameter Setting Functions
Related reference
IiopRequest Function


IiopSetValue Function

Action

Sets the header of a value type parameter that is associated with a CORBA object. This function can be used to set parameters of a request in advance of calling the IiopRequest function.

Include file

Iiop.bdh

Syntax

IiopSetValue( in hIiop     : number,
              in sRepId    : string optional,
              in sCodeBase : string optionl,
              in bChunked  : boolean optional,
              in nValueId  : number optional ): boolean;

Return value

  • true if successful

  • false otherwise

Parameter | Description
hIiop | Handle to a CORBA object.
sRepId | Repository ID of the following value type (optional). This can also be a list of repository IDs. A list of repository IDs is encoded as a concatenation of a separator character (for example, a blank) followed by a repository ID.
sCodeBase | Code base URL (optional).
bChunked | Specifies whether the value should be chunked encoded (optional).
nValueId | Used to reference this value with an indirection (IiopSetValueIndirect; optional).

Example

dcltrans
  transaction TSetValue
  const
    HOST        := "192.168.20.21"; // server
    PORT        := 1052;            // port
    KEY         := "...\h00";       // key
    KEYLEN      := 4;               // key length
    REP_ID      := "IDL:SetValueType:1.0";
    REP_ID_LIST := " IDL:DerivedValue:1.0 IDL:BaseValue:1.0 IDL:AbstractValue:1.0";
    CODE_BASE   := "www.codebase.com";
  var
   hIiop : number; // Handle to CORBA object
  begin
    IiopSetMaxGiopVersion("1.2");
    IiopSetByteOrder(IIOP_BIG_ENDIAN);

     // retrieve handle to server
    IiopObjectCreate(hIiop, "IDL:DemoObject:1.0", "1.2", HOST, PORT, KEY, KEYLEN);

    // set value
    IiopSetValue(hIiop, REP_ID);
    IiopSetLong(hIiop, 5);
    IiopEndValue(hIiop );

    // set another value
    IiopSetValue(hIiop, REP_ID_LIST, CODE_BASE, TRUE);
    IiopSetBoolean(hIiop, TRUE);
    IiopSetLong(hIiop, 3);
    IiopSetValue(hIiop, REP_Id, "", TRUE);
    IiopSetLong(hIiop, 12);
    IiopEndValue(hIiop );
    IiopSetString(hIiop, "This is a string");
    IiopEndValue(hIiop );

    // call request "SetValue"
    IiopRequest(hIiop, "SetValue");
    IiopObjectRelease(hIiop);
  end TSetValue;
Parent topic: Parameter Setting Functions
Related reference
IiopRequest Function


IiopSetWChar Function

Action

Associates a wide character parameter with a CORBA object. This function can be used to set parameters of a request in advance of calling the IiopRequest function.

Include file

IIOP.bdh

Syntax

IiopSetWChar(in hIiop : number,in nWChar : number,in nType : number optional): boolean;

Return value

  • true if successful

  • false otherwise

Parameter | Description
hIiop | Handle to a CORBA object.
nWChar | Wide character that will be associated with the CORBA object.
nType

Defines the byte order of the wide character (optional). Pass one of the following flags to the function:

  • IIOP_BYTE_ORIENTED (default)

  • IIOP_WIDE_LITTLE_ENDIAN

  • IIOP_WIDE_BIG_ENDIAN

Example

var
    nWChar: number;
  dcltrans
  transaction TMain
  const
    HOST := "192.168.20.21"; // server
    PORT := 1052; // port
    KEY := "...\h00"; // key
    KEYLEN := 4; // key length
  var
    hIiop: number; // handle to CORBA object
  begin
    IiopSetMaxGiopVersion("1.0");IiopSetByteOrder(IIOP_BIG_ENDIAN);

    // retrieve handle to server
    IiopObjectCreate(hIiop, "IDL:DemoObject:1.0", "1.2",HOST, PORT, KEY, KEYLEN);

    // pass wide character parameter to request
    IiopSetWChar(hIiop, nWChar);

   // call operation "Print" with wide character parameter
    IiopRequest(hIiop, "Print");
    IiopObjectRelease(hIiop);
  end TMain;
Parent topic: Parameter Setting Functions
Related reference
IiopGetWChar Function
IiopRequest Function


IiopSetWString Function

Action

Associates a wide character string parameter with a CORBA object. This function can be used to set parameters of a request in advance of calling the IiopRequest function.

Include file

IIOP.bdh

Syntax

IiopSetWString( in hIiop      : number,
                in sString    : string,
                in nStringLen : number optional ): boolean;

Return value

  • true if successful

  • false otherwise

Parameter | Description
hIiop | Handle to a CORBA object.
sString | Wide character string that will be associated with the CORBA object.
nStringLen | Length of the wide character string (optional).

Example

var
  sString: string;
 dcltrans
  transaction TMain
  const
    HOST   := "192.168.20.21"; // server
    PORT   := 1052;            // port
    KEY    := "...\h00";       // key
    KEYLEN := 4;               // key length
  var
    hIiop   : number;  // handle to CORBA object
    sString : string; // handle to CORBA object
  begin
    IiopSetMaxGiopVersion("1.2");
    IiopSetByteOrder(IIOP_BIG_ENDIAN);

    // retrieve handle to server
    IiopObjectCreate(hIiop, "IDL:DemoObject:1.0", "1.2",    HOST, PORT, KEY, KEYLEN);

    // pass wide character string to request
    StrAnsi2Unicode(sString, STRING_COMPLETE, "hello");
    IiopSetWString(hIiop, sString);

    // call operation "Print" with wide character string parameter
    IiopRequest(hIiop, "Print");
    IiopObjectRelease(hIiop);
  end TMain;
Parent topic: Parameter Setting Functions
Related reference
IiopGetWString Function
IiopRequest Function


Parameter Getting Functions

  • IiopGetBinary Function
    Retrieves a return parameter containing binary data from a CORBA object.
  • IiopGetBoolean Function
    Retrieves a boolean return parameter from a CORBA object.
  • IiopGetChar Function
    Retrieves a character return parameter from a CORBA object.
  • IiopGetDouble Function
    Retrieves a double value return parameter from a CORBA object.
  • IiopGetFloat Function
    Retrieves a float value return parameter from a CORBA object.
  • IiopGetLong Function
    Retrieves a long value return parameter from a CORBA object.
  • IiopGetObject Function
    Retrieves an object return parameter from a CORBA object.
  • IiopGetOctet Function
    Retrieves an octet return parameter from a CORBA object.
  • IiopGetOctetSequence Function
    Retrieves an octet sequence return parameter from a CORBA object.
  • IiopGetShort Function
    Retrieves a short value return parameter from a CORBA object.
  • IiopGetString Function
    Retrieves a string return parameter from a CORBA object.
  • IiopGetTypecode Function
    Retrieves a type code return parameter from a CORBA object.
  • IiopGetUShort Function
    Retrieves an unsigned short value return parameter from a CORBA object.
  • IiopGetValue Function
    Retrieves a value type return parameter from a CORBA object.
  • IiopGetValueHeader Function
    Retrieves information about a value type return parameter from a CORBA object based on the return value, either true or false.
  • IiopGetWChar Function
    Retrieves a wide character return parameter from a CORBA object.
  • IiopGetWString Function
    Retrieves a wide string return parameter from a CORBA object.
  • IiopGetDataByTypeCode Function
    Retrieves a certain amount of data from a CORBA object.
Parent topic: Parameter Setting and Getting Functions Overview


IiopGetBinary Function

Action

Retrieves a return parameter containing binary data from a CORBA object. This function can be used to get the return parameters of an operation.

Include file

IIOP.bdh

Syntax

IiopGetBinary( in  hIiop       : number,
               out sBuffer     : string,
               in  nBufferSize : number optional,
               out nDataLen    : number optional,
               in  nAlign      : number optional): boolean;

Return value

  • true if successful

  • false otherwise

Parameter | Description
hIiop | Handle to a CORBA object
sBuffer | Buffer receiving the binary data associated with the CORBA object
nBufferSize | Size of the buffer receiving the binary data (optional). If specified, make sure to set nBufferSize <= StrSize(sBuffer).
nDataLen | Variable receiving the number of bytes retrieved (optional)
nAlign

Binary data alignment (optional). Possible options are:

  • IIOP_ALIGN_2. Alignment to 2-byte boundaries

  • IIOP_ALIGN_4. Alignment to 4-byte boundaries

  • IIOP_ALIGN_8. Alignment to 8-byte boundaries

  • IIOP_ALIGN_16. Alignment to 16-byte boundaries

Default setting is alignment to 1-byte boundaries.

In addition, the byte order within the binary data can be specified:

  • IIOP_BIG_ENDIAN. Most significant byte is sent first

  • IIOP_LITTLE_ENDIAN. Least significant byte is sent first

Example

dcltrans
  transaction TGetBinary
  const
    HOST   := "192.168.20.21"; // server
    PORT   := 1052;            // port
    KEY    := "...\h00";       // key
    KEYLEN := 4;               // key length
  var
    hIiop   : number; // handle to CORBA object
    sBuffer : string(512);
  begin
    IiopSetMaxGiopVersion("1.0");
    IiopSetByteOrder(IIOP_BIG_ENDIAN);
    // retrieve handle to server
    IiopObjectCreate(hIiop, "IDL:DemoObject:1.0", "1.2",
    HOST, PORT, KEY, KEYLEN);

    // call request "GetBuffer"
    IiopRequest(hIiop, "GetBuffer");

    // retrieve return parameter
    IiopGetBinary(hIiop, sBuffer, STRING_COMPLETE,
    0, IIOP_ALIGN_16 | IIOP_BIG_ENDIAN);
    IiopObjectRelease(hIiop);
  end TGetBinary;

Sample scripts

Conf.bdf

You can find the sample script(s) here: <Public documents>\Silk Performer <version>\Samples\Corba

Parent topic: Parameter Getting Functions
Related reference
IiopSetBinary Function


IiopGetBoolean Function

Action

Retrieves a boolean return parameter from a CORBA object. This function can be used to get the return parameters of an operation.

Include file

IIOP.bdh

Syntax

IiopGetBoolean( in hIiop  : number,
                out bBool : boolean optional ): boolean;

Return value

Boolean value associated with the CORBA object

Parameter | Description
hIiop | Handle to a CORBA object
bBool | Variable receiving the boolean value associated with the CORBA object (optional)

Example

dcltrans
  transaction TGetBoolean
  const
    HOST   := "192.168.20.21"; // server
    PORT   := 1052; // port
    KEY    := "...\h00"; // key
    KEYLEN := 4; // key length
  var
    hIiop : number; // Handle to CORBA object
    bOk   : boolean;
  begin
    IiopSetMaxGiopVersion("1.2");
    IiopSetByteOrder(IIOP_BIG_ENDIAN);

    // retrieve handle to server
    IiopObjectCreate(hIiop, "IDL:DemoObject:1.0", "1.2",
                     HOST, PORT, KEY, KEYLEN);

    // call request "Init"
    IiopRequest(hIiop, "Init");
    // retrieve boolean return parameter
    bOk := IiopGetBoolean(hIiop);
    IiopObjectRelease(hIiop);
  end TGetBoolean;

Sample scripts

Conf.bdf

You can find the sample script(s) here: <Public documents>\Silk Performer <version>\Samples\Corba

Parent topic: Parameter Getting Functions
Related reference
IiopSetBoolean Function


IiopGetChar Function

Action

Retrieves a character return parameter from a CORBA object. This function can be used to get the return parameters of an operation.

Include file

IIOP.bdh

Syntax

IiopGetChar( in  hIiop : number,
             out nChar : number optional ): number;

Return value

Character associated with the CORBA object

Parameter | Description
hIiop | Handle to a CORBA object
nChar | Variable receiving the character associated with the CORBA object (optional)

Example

dcltrans
  transaction TGetChar
  const
    HOST   := "192.168.20.21"; // server
    PORT   := 1052;            // port
    KEY    := "...\h00";       // key
    KEYLEN := 4;               // key length
  var
    hIiop : number; // Handle to CORBA object
    nChar : number;
  begin
    IiopSetMaxGiopVersion("1.2");
    IiopSetByteOrder(IIOP_BIG_ENDIAN);
     // retrieve handle to server
    IiopObjectCreate(hIiop, "IDL:DemoObject:1.0", "1.2", HOST, PORT, KEY, KEYLEN);
     // call request "NextChar"
    IiopRequest(hIiop, "NextChar");
     // retrieve character return parameter
    nChar := IiopGetChar(hIiop);
    write("retrieved character = "); write(chr(nChar)); writeln;
    IiopObjectRelease(hIiop);
  end TGetChar;

Output

retrieved character = A

Sample scripts

TypeTest.bdf, Conf.bdf

You can find the sample script(s) here: <Public documents>\Silk Performer <version>\Samples\Corba

Parent topic: Parameter Getting Functions
Related reference
IiopSetChar Function


IiopGetDouble Function

Action

Retrieves a double value return parameter from a CORBA object. This function can be used to get the return parameters of an operation.

Include file

IIOP.bdh

Syntax

IiopGetDouble( in  hIiop  : number,
               out fValue : float optional ): float;

Return value

Double value associated with the CORBA object

Parameter | Description
hIiop | Handle to a CORBA object
fValue | Variable receiving the double value associated with the CORBA object (optional)

Example

dcltrans
  transaction TGetDouble
  const
    HOST   := "192.168.20.21"; // server
    PORT   := 1052; // port
    KEY    := "...\h00"; // key
    KEYLEN := 4; // key length
  var
    hIiop : number; // Handle to CORBA object
    fSqrt : float;
  begin
    IiopSetMaxGiopVersion("1.2");
    IiopSetByteOrder(IIOP_BIG_ENDIAN);

    // retrieve handle to server
    IiopObjectCreate(hIiop, "IDL:DemoObject:1.0", "1.2",
                     HOST, PORT, KEY, KEYLEN);

    // call request "SquareRoot" with double value parameter
    IiopSetDouble(hIiop, 685083.117);
    IiopRequest(hIiop, "SquareRoot");

    // retrieve double value return parameter
    fSqrt := IiopGetDouble(hIiop);

    write("square root = "); write(fSqrt); writeln;
    IiopObjectRelease(hIiop);
  end TGetDouble;

Output

square root = 827.697479

Sample scripts

UnivB.bdf, TypeTest.bdf, Conf.bdf

You can find the sample script(s) here: <Public documents>\Silk Performer <version>\Samples\Corba

Parent topic: Parameter Getting Functions
Related reference
IiopSetDouble Function


IiopGetFloat Function

Action

Retrieves a float value return parameter from a CORBA object. This function can be used to get the return parameters of an operation.

Include file

IIOP.bdh

Syntax

IiopGetFloat( in  hIiop  : number,
              out fValue : float optional ): float;

Return value

float value associated with the CORBA object

Parameter | Description
hIiop | Handle to a CORBA object
fValue | Variable receiving the float value associated with the CORBA object (optional)

Example

dcltrans
  transaction TGetFloat
  const
    HOST   := "192.168.20.21"; // server
    PORT   := 1052; // port
    KEY    := "...\h00"; // key
    KEYLEN := 4; // key length
  var
    hIiop : number; // Handle to CORBA object
    fSqr  : float;
  begin
    IiopSetMaxGiopVersion("1.2");
    IiopSetByteOrder(IIOP_BIG_ENDIAN);

    // retrieve handle to server
    IiopObjectCreate(hIiop, "IDL:DemoObject:1.0", "1.2",
                     HOST, PORT, KEY, KEYLEN);

    // call request "Square" with float value parameter
    IiopSetFloat(hIiop, 934.71);
    IiopRequest(hIiop, "Square");

    // retrieve float value return parameter
    fSqr := IiopGetFloat(hIiop);
    write("square = "); write(fSqr); writeln;
    IiopObjectRelease(hIiop);
  end TGetFloat;

Output

square = 873682.784100

Sample scripts

AsyncBank.bdf, Bank.bdf, SimpleAsyncBank.bdf, TypeTest.bdf, Conf.bdf, Vbrokerbank01.bdf, Vbrokerbank02.bdf, VBrokerBankGate.bdf

You can find the sample script(s) here: <Public documents>\Silk Performer <version>\Samples\Corba

Parent topic: Parameter Getting Functions
Related reference
IiopSetFloat Function


IiopGetLong Function

Action

Retrieves a long value return parameter from a CORBA object. This function can be used to get the return parameters of an operation.

Include file

IIOP.bdh

Syntax

IiopGetLong( in  hIiop  : number,
             out nValue : number optional ):number;

Return value

Long value associated with the CORBA object

Parameter | Description
hIiop | Handle to a CORBA object
nValue | Variable receiving the long value associated with the CORBA object (optional)

Example

dcltrans
  transaction TGetLong
  const
    HOST   := "192.168.20.21"; // server
    PORT   := 1052; // port
    KEY    := "...\h00"; // key
    KEYLEN := 4; // key length
  var
    hIiop    : number; // Handle to CORBA object
    nProduct : number;
  begin
    IiopSetMaxGiopVersion("1.2");
    IiopSetByteOrder(IIOP_BIG_ENDIAN);

    // retrieve handle to server
    IiopObjectCreate(hIiop, "IDL:DemoObject:1.0", "1.2",
                     HOST, PORT, KEY, KEYLEN);

    // call request "Product" with two long value parameters
    IiopSetLong(hIiop, 2854);    IiopSetLong(hIiop, 489);
    IiopRequest(hIiop, "Product");

    // retrieve long value return parameter
    nProduct := IiopGetLong(hIiop);
    write("product = "); write(nProduct); writeln;
    IiopObjectRelease(hIiop);
  end TGetLong;

Output

product = 1395606

Sample scripts

UnivB.bdf, TypeTest.bdf, AsyncFact.bdf, Conf.bdf, Factory.bdf

You can find the sample script(s) here: <Public documents>\Silk Performer <version>\Samples\Corba

Parent topic: Parameter Getting Functions
Related reference
IiopSetLong Function


IiopGetObject Function

Action

Retrieves an object return parameter from a CORBA object. This function can be used to get the return parameters of an operation.

Include file

IIOP.bdh

Syntax

IiopGetObject( in    hIiop   : number,
               inout hObject : number ): boolean;

Return value

  • true if successful

  • false otherwise

Parameter | Description
hIiop | Handle to a CORBA object
hObject | Variable receiving the object associated with the CORBA object

Example

dcltrans
  transaction TMain
  const
    HOST   := "192.168.20.21"; // server
    PORT   := 1052; // port
    KEY    := "...\h00" // key
    KEYLEN := 4; // key length
  var
    hIiop, hObject: number; // Handle to CORBA object
  begin
    IiopSetMaxGiopVersion("1.2");
    IiopSetByteOrder(IIOP_BIG_ENDIAN);

    // retrieve handle to server
    IiopObjectCreate(hIiop, "IDL:DemoObject:1.0", "1.2",
                     HOST, PORT, KEY, KEYLEN);

    // call request "Duplicate"
    IiopRequest(hIiop, "Duplicate");

    // retrieve object return parameter
    IiopGetObject(hIiop, hObject);
    IiopObjectRelease(hIiop);
  end TMain;

Sample scripts

UnivB.bdf, AnyDemo.bdf, AsyncBank.bdf, Bank.bdf, SimpleAsyncBank.bdf, AsyncFact.bdf, AsyncOdb.bdf, Conf.bdf, Factory.bdf, Odb.bdf, Vbrokerbank01.bdf, Vbrokerbank02.bdf, VBrokerBankGate.bdf

You can find the sample script(s) here: <Public documents>\Silk Performer <version>\Samples\Corba

Parent topic: Parameter Getting Functions
Related reference
IiopSetObject Function


IiopGetOctet Function

Action

Retrieves an octet return parameter from a CORBA object. This function can be used to get the return parameters of an operation.

Include file

IIOP.bdh

Syntax

IiopGetOctet( in  hIiop  : number,
              out nOctet : number optional ): number;

Return value

Octet associated with the CORBA object

Parameter | Description
hIiop | Handle to a CORBA object
nOctet | Variable receiving the octet associated with the CORBA object (optional)

Example

dcltrans
  transaction TGetOctet
  const
    HOST   := "192.168.20.21"; // server
    PORT   := 1052; // port
    KEY    := "...\h00"; // key
    KEYLEN := 4; // key length
  var
    hIiop  : number; // Handle to CORBA object
    nOctet : number;
  begin
    IiopSetMaxGiopVersion("1.2");
    IiopSetByteOrder(IIOP_BIG_ENDIAN);

    // retrieve handle to server
    IiopObjectCreate(hIiop, "IDL:DemoObject:1.0", "1.2",
                     HOST, PORT, KEY, KEYLEN);

    // call request "Update"
    IiopRequest(hIiop, "Update");

    // retrieve octet return parameter
    nOctet := IiopGetOctet(hIiop);

    write("return value = "); write(nOctet); writeln;
    IiopObjectRelease(hIiop);
  end TGetOctet;

Output

return value = 54
Parent topic: Parameter Getting Functions
Related reference
IiopSetOctet Function


IiopGetOctetSequence Function

Action

Retrieves an octet sequence return parameter from a CORBA object. This function can be used to get the return parameters of an operation.

Include file

IIOP.bdh

Syntax

IiopGetOctetSequence( in  hIiop        : number,
                      out sBuffer      : string optional,
                      in  nBufferSize  : number optional,
                      out nSequenceLen : number optional ): boolean;

Return value

  • true if successful

  • false otherwise

Parameter | Description
hIiop | Handle to a CORBA object
sBuffer | Buffer receiving the octet sequence associated with the CORBA object (optional).
nBufferSize | Size of the buffer receiving the octet sequence (optional). Make sure to set nBufferSize <= size of sBuffer
nSequenceLen | Variable receiving the number of bytes retrieved (optional).

Example

dcltrans
  transaction TGetOctetSequence
  const
    HOST := "192.168.20.21"; // server
    PORT := 1052; // port
    KEY := "...\h00"; // key
    KEYLEN := 4; // key length
  var
    hIiop, nLen : number; // Handle to CORBA object
    sBuffer : string(512);
  begin
    IiopSetMaxGiopVersion("1.2");
    IiopSetByteOrder(IIOP_BIG_ENDIAN); // retrieve handle to server
    IiopObjectCreate(hIiop, "IDL:DemoObject:1.0", "1.2",    HOST, PORT, KEY, KEYLEN);

    // call request "GetMsg"
    IiopRequest(hIiop, "GetMsg");

    // retrieve return parameter
    IiopGetOctetSequence(hIiop, sBuffer, STRING_COMPLETE, nLen);
    IiopObjectRelease(hIiop);
  end TGetOctetSequence;
Parent topic: Parameter Getting Functions
Related reference
IiopSetOctetSequence Function


IiopGetShort Function

Action

Retrieves a short value return parameter from a CORBA object. This function can be used to get the return parameters of an operation.

Include file

IIOP.bdh

Syntax

IiopGetShort( in  hIiop  : number,
              out nValue : number optional ): number;

Return value

Short value associated with the CORBA object

Parameter | Description
hIiop | Handle to a CORBA object
nValue | Variable receiving the short value associated with the CORBA object (optional)

Example

dcltrans
  transaction TGetShort
  const
    HOST   := "192.168.20.21"; // server
    PORT   := 1052; // port
    KEY    := "...\h00"; // key
    KEYLEN := 4; // key length
  var
    hIiop : number;
    // Handle to CORBA object
    nAbs  : number;
  begin
    IiopSetMaxGiopVersion("1.2");
    IiopSetByteOrder(IIOP_BIG_ENDIAN);

    // retrieve handle to server
    IiopObjectCreate(hIiop, "IDL:DemoObject:1.0", "1.2",
                     HOST, PORT, KEY, KEYLEN);

   // call request "Abs" with short value parameter
    IiopSetShort(hIiop, -104);
    IiopRequest(hIiop, "Abs");

    // retrieve short value return parameter
    nAbs := IiopGetShort(hIiop);
    write("absolute value = "); write(nAbs); writeln;
    IiopObjectRelease(hIiop);
  end TGetShort;

Output

absolute value = 104

Sample scripts

TypeTest.bdf, Conf.bdf

You can find the sample script(s) here: <Public documents>\Silk Performer <version>\Samples\Corba

Parent topic: Parameter Getting Functions
Related reference
IiopSetShort Function


IiopGetString Function

Action

Retrieves a string return parameter from a CORBA object. This function can be used to get the return parameters of an operation.

Include file

IIOP.bdh

Syntax

IiopGetString( in  hIiop       : number,
               in  sBuffer     : string optional,
               in  nBufferSize : number optional,
               out nStringLen  : number optional ): boolean;

Return value

  • true if successful

  • false otherwise

Parameter | Description
hIiop | Handle to a CORBA object
sBuffer | Buffer receiving the string associated with the CORBA object (optional).
nBufferSize | Size of the buffer receiving the string (optional). If specified, make sure to set nBufferSize <= StrSize(sBuffer).
nStringLen | Variable receiving the length of the string retrieved (optional)

Example

dcltrans
  transaction TGetString
  const
    HOST   := "192.168.20.21"; // server
    PORT   := 1052;            // port
    KEY    := "...\h00";       // key
    KEYLEN := 4;               // key length
  var
    hIiop : number; // Handle to CORBA object
    sUpper : string;
  begin
    IiopSetMaxGiopVersion("1.2");
    IiopSetByteOrder(IIOP_BIG_ENDIAN);
    // retrieve handle to server
    IiopObjectCreate(hIiop, "IDL:DemoObject:1.0", "1.2",
    HOST, PORT, KEY, KEYLEN);

    // call request "ToUpper" with string parameter
    IiopSetString(hIiop, "Convert To Uppercase");
    IiopRequest(hIiop, "ToUpper");

    // retrieve string return parameter
    IiopGetString(hIiop, sUpper);
    write("converted string = "); write(sUpper); writeln;
    IiopObjectRelease(hIiop);
  end TGetString;

Output

converted string = CONVERT TO UPPERCASE

Sample scripts

UnivB.bdf, AnyDemo.bdf, TypeTest.bdf, AsyncOdb.bdf, Conf.bdf, Odb.bdf

You can find the sample script(s) here: <Public documents>\Silk Performer <version>\Samples\Corba

Parent topic: Parameter Getting Functions


IiopGetTypecode Function

Action

Retrieves a type code return parameter from a CORBA object. This function can be used to get the return parameters of an operation.

Include file

IIOP.bdh

Syntax

IiopGetTypecode( in  hIiop       : number,
                 out sBuffer     : string optional,
                 in  nBufferSize : number optional,
                 out nBufferLen  : number optional): number;

Return value

Type code. This can be any of the following:

IIOP_TK_ABSTRACT_INTERFACE | IIOP_TK_ALIAS | IIOP_TK_ANY
IIOP_TK_ARRAY | IIOP_TK_BOOLEAN | IIOP_TK_CHAR
IIOP_TK_DOUBLE | IIOP_TK_ENUM | IIOP_TK_EXCEPT
IIOP_TK_FIXED | IIOP_TK_FLOAT | IIOP_TK_INDIRECTION
IIOP_TK_LDOUBLE | IIOP_TK_LLONG | IIOP_TK_LONG
IIOP_TK_NATIVE | IIOP_TK_NULL | IIOP_TK_OBJREF
IIOP_TK_OCTET | IIOP_TK_PRINCIPAL | IIOP_TK_SEQUENCE
IIOP_TK_SHORT | IIOP_TK_STRING | IIOP_TK_STRUCT
IIOP_TK_TYPECODE | IIOP_TK_ULLONG | IIOP_TK_ULONG
IIOP_TK_UNION | IIOP_TK_USHORT | IIOP_TK_VALUE
IIOP_TK_VALUEBOX | IIOP_TK_VOID | IIOP_TK_WCHAR
IIOP_TK_WSTRING |  |
Parameter | Description
hIiop | Handle to a CORBA object.
sBuffer | Buffer receiving the type code associated with the CORBA object (optional).
nBufferSize | Size of the buffer receiving the type code associate with the CORBA object (optional).
nBufferLen | Variable receiving the actual size of the type code (optional).

Example

dcltrans
  transaction TMain
  const
    HOST   := "192.168.20.21"; // server
    PORT   := 1052;            // port
    KEY    := "...\h00";       // key
    KEYLEN := 4;               // key length
  var
    hIiop     : number;
    sBuffer   : string;
    nTypecode : number;
  begin
    IiopSetMaxGiopVersion("1.0");
    IiopSetByteOrder(IIOP_BIG_ENDIAN);

    // retrieve handle to server
    IiopObjectCreate(hIiop, "IDL:DemoObject:1.0", "1.2", HOST, PORT, KEY, KEYLEN);
    // call request "GetInfo"
    IiopRequest(hIiop, "GetInfo");

    // check return parameter
    nTypecode := IiopGetTypecode(hIiop, sBuffer);
    ...
    IiopObjectRelease(hIiop);
  end TMain;

Sample scripts

AnyDemo.bdf, Conf.bdf

You can find the sample script(s) here: <Public documents>\Silk Performer <version>\Samples\Corba

Parent topic: Parameter Getting Functions


IiopGetUShort Function

Action

Retrieves an unsigned short value return parameter from a CORBA object. This function can be used to get the return parameters of an operation.

Include file

IIOP.bdh

Syntax

IiopGetUShort( in  hIiop  : number,
               out nValue : number optional ):number;

Return value

unsigned short value associated with the CORBA object

Parameter | Description
hIiop | Handle to a CORBA object
nValue | Variable receiving the unsigned short value associated with the CORBA object (optional)

Example

dcltrans
  transaction TGetUShort
  const
    HOST   := "192.168.20.21"; // server
    PORT   := 1052; // port
    KEY    := "...\h00"; // key
    KEYLEN := 4; // key length
  var
    hIiop : number; // Handle to CORBA object
    nSum  : number;
  begin
    IiopSetMaxGiopVersion("1.2");
    IiopSetByteOrder(IIOP_BIG_ENDIAN);

    // retrieve handle to server
    IiopObjectCreate(hIiop, "IDL:DemoObject:1.0", "1.2",
                     HOST, PORT, KEY, KEYLEN);

    // call request "Sum" with two unsigned short value parameters
    IiopSetUShort(hIiop, 1195);
    IiopSetUShort(hIiop, 477);
    IiopRequest(hIiop, "Sum");

    // retrieve unsigned short value return parameter
    nSum := IiopGetUShort(hIiop);
    write("sum = "); write(nSum); writeln;
    IiopObjectRelease(hIiop);
  end TGetUShort;

Output

sum = 1672

Sample scripts

UnivB.bdf, Conf.bdf

You can find the sample script(s) here: <Public documents>\Silk Performer <version>\Samples\Corba

Parent topic: Parameter Getting Functions


IiopGetValue Function

Action

Retrieves a value type return parameter from a CORBA object. This function can be used to get the return parameters of an operation. This function is the same as the IiopGetDataByTypecode function;

Include file

Iiop.bdh

Syntax

IiopGetValue( in  hIiop     : number,
              in  sTypecode : string,
              in  nTcLen    : number optional,
              out sBuf      : string optional,
              in  nBufLen   : number optional,
              out nUsed     : number optional ): boolean;

Return value

  • true if successful

  • false otherwise

Parameter | Description
hIiop | Handle to a CORBA object.
sTypecode | Typecode needed for parsing the value type from the IIOP reply messages.
nTcLen | Length of sTypecode (optional).
sBuf | Buffer where the value is copied to (optional).
nBufLen | Length of the buffer where the value is copied to (optional).
nUsed | Number of bytes that are copied to sBuf (optional).

Example

dcltrans
  transaction TGetValue
  const
    HOST   := "192.168.20.21"; // server
    PORT   := 1052;            // port
    KEY    := "...\h00";       // key
    KEYLEN := 4;               // key length
    csTypecode := "\h0000001D000000C20000000000000038524D49"
      "\h3A6A6176612E6C616E672E496E74656765723A363444343743"
      "\h314430313938304235453A3132453241304134463738313837"
      "\h33380000000008496E746567657200000000000000001D0000"
      "\h00580000000000000036524D493A6A6176612E6C616E672E4E"
      "\h756D6265723A3731444138424537463937313132383A383641"
      "\h43393531443042393445303842000000000000074E756D6265"
      "\h72000000020000000000000000000000000001000000010000"
      "\h0000000000030000";
  var
    hIiop  : number; // Handle to CORBA object
    sValue : string(4096);
  begin
    IiopSetMaxGiopVersion("1.2");
    IiopSetByteOrder(IIOP_BIG_ENDIAN);

    // retrieve handle to server
    IiopObjectCreate(hIiop, "IDL:DemoObject:1.0", "1.2", HOST, PORT, KEY, KEYLEN);

    // call request "NextValue"
    IiopRequest(hIiop, "NextValue");

     // retrieve value type return parameter
    IiopGetValue(hIiop, csTypecode, STRING_COMPLETE, sValue);
    write("retrieved value type:"); writeln;    WriteData(sValue, STRING_COMPLETE, OPT_WRITEDATA_HEX);
     IiopObjectRelease(hIiop);
  end TGetValue;

Output

retrieved value type: 00000000 ·······8RMI:java 7F FF FF 02 00 00 00 38 52 4D
49 3A 6A 61 76 61 00000010 .lang.Integer:64 2E 6C 61 6E 67 2E 49 6E 74 65
67 65 72 3A 36 34 00000020 D47C1D01980B5E:1 44 34 37 43 31 44 30 31 39 38
30 42 35 45 3A 31 00000030 2E2A0A4F7818738· 32 45 32 41 30 41 34 46 37 38
31 38 37 33 38 00 00000040 ···· 00 00 00 01
Parent topic: Parameter Getting Functions
Related reference
IiopGetValueHeader Function


IiopGetValueHeader Function

Action

Retrieves information about a value type return parameter from a CORBA object based on the return value, either true or false. This function can be used to get the return parameters of an operation. If the return value is true, then only the header part is returned. If the return value is false, then the whole value is returned.

Include file

Iiop.bdh

Syntax

IiopGetValueHeader( in  hIiop     : number,
                    in  sTypecode : string,
                    in  nTcLen    : number optional,
                    out sBuf      : string optional,
                    in  nBufLen   : number optional,
                    out nUsed     : number optional): boolean;

Return value

  • true if the current value is a non-derived value (the repository IDs of the value and the typecode match) that does not contain other values.

  • false otherwise; the value may be a derived type or may contain other values, indirections, or null-values.

Parameter | Description
hIiop | Handle to a CORBA object.
sTypecode | Typecode needed for parsing the value type from the IIOP reply messages.
nTcLen | Length of sTypecode (optional).
sBuf | Buffer where the value header is copied to in case the return value is true (optional). If the return value is false the whole value is copied to this buffer.
sBufLen | Length of the buffer where the value is copied to (optional).
nUsed | Number of bytes that are copied to sBuf (optional).

Example

dcltrans
  transaction TGetValueHeader
  const
    HOST       := "192.168.20.21"; // server
    PORT       := 1052;            // port
    KEY        := "...\h00";       // key
    KEYLEN     := 4;               // key length
    csTypecode := "\h0000001D000000C20000000000000038524D49"
      "\h3A6A6176612E6C616E672E496E74656765723A363444343743"
      "\h314430313938304235453A3132453241304134463738313837"
      "\h33380000000008496E746567657200000000000000001D0000"
      "\h00580000000000000036524D493A6A6176612E6C616E672E4E"
      "\h756D6265723A3731444138424537463937313132383A383641"
      "\h43393531443042393445303842000000000000074E756D6265"
      "\h72000000020000000000000000000000000001000000010000"
      "\h0000000000030000";
  var
    hIiop : number; // Handle to CORBA object
    sValueHeader : string(4096);
  begin
    IiopSetMaxGiopVersion("1.2");
    IiopSetByteOrder(IIOP_BIG_ENDIAN);

    // retrieve handle to server
    IiopObjectCreate(hIiop, "IDL:DemoObject:1.0", "1.2", HOST, PORT, KEY, KEYLEN);

    // call request "NextValue
    IiopRequest(hIiop, "NextValue");

    // retrieve value type return parameter
    if IiopGetValueHeader(hIiop, csTypecode, STRING_COMPLETE, sValueHeader) then
    writeln("retrieved value header:");
      WriteData(sValueHeader, STRING_COMPLETE, OPT_WRITEDATA_HEX);
    writeln("retrieved value: ");      write(IiopGetLong(hIiop));    else
    writeln("retrieved value type:");      WriteData(sValue, STRING_COMPLETE, OPT_WRITEDATA_HEX);
    end;
     IiopObjectRelease(hIiop);
  end TGetValueHeader;

Output

retrieved value header:00000000 ·······8RMI:java 7F FF FF 02 00 00 00 38 52 4D
49 3A 6A 61 76 6100000010 .lang.Integer:64 2E 6C 61 6E 67 2E 49 6E 74 65
67 65 72 3A 36 3400000020 D47C1D01980B5E:1 44 34 37 43 31 44 30 31 39 38
30 42 35 45 3A 3100000030 2E2A0A4F7818738· 32 45 32 41 30 41 34 46 37 38
31 38 37 33 38 00retrieved value: 1

or:

retrieved complete value:00000000 ·······8RMI:java 7F FF FF 02 00 00 00 38 52 4D
49 3A 6A 61 76 6100000010 .lang.Integer:64 2E 6C 61 6E 67 2E 49 6E 74 65
67 65 72 3A 36 3400000020 D47C1D01980B5E:1 44 34 37 43 31 44 30 31 39 38
30 42 35 45 3A 3100000030 2E2A0A4F7818738· 32 45 32 41 30 41 34 46 37 38
31 38 37 33 38 0000000040 ···· 00 00 00 01
Parent topic: Parameter Getting Functions
Related reference
IiopGetValue Function


IiopGetWChar Function

Action

Retrieves a wide character return parameter from a CORBA object. This function can be used to get the return parameters of an operation.

Include file

IIOP.bdh

Syntax

IiopGetWChar( in  hIiop      : number,
              out nWCharSize : number optional ): number;

Return value

Wide character associated with the CORBA object

Parameter | Description
hIiop | Handle to a CORBA object.
nWCharSize | Variable that receives the wide character size associated with the CORBA object (optional).

Example

dcltrans
  transaction TGetWChar
  const
    HOST   := "192.168.20.21"; // server
    PORT   := 1052; // port
    KEY    := "...\h00"; // key
    KEYLEN := 4; // key length
  var    hIiop, nWChar : number;
  begin
    IiopSetMaxGiopVersion("1.2");
    IiopSetByteOrder(IIOP_BIG_ENDIAN);
    // retrieve handle to server
    IiopObjectCreate(hIiop, "IDL:DemoObject:1.0", "1.2", HOST, PORT, KEY, KEYLEN);
    // call request "NextWChar"
    IiopRequest(hIiop, "NextWChar");
    // retrieve wide character return parameter
    nWChar := IiopGetWChar(hIiop);
    write("retrieved wide character as number = "); writeln(nWChar);
    IiopObjectRelease(hIiop);
  end TGetChar;

Output

retrieved character as number = 4321

Sample scripts

TypeTest.bdf, Conf.bdf

You can find the sample script(s) here: <Public documents>\Silk Performer <version>\Samples\Corba

Parent topic: Parameter Getting Functions
Related reference
IiopSetWChar Function


IiopGetWString Function

Action

Retrieves a wide string return parameter from a CORBA object. This function can be used to get the return parameters of an operation.

Include file

IIOP.bdh

Syntax

IiopGetWString( in  hIiop     : number,
                out sBuffer   : string optional,
                in  nSize     : number optional,
                out nReceived : number optional ): boolean;

Return value

  • true if successful

  • false otherwise

Parameter | Description
hIiop | Handle to a CORBA object.
sBuffer | Buffer that will receive the wide string return parameter from the CORBA object (optional).
nSize | Size of the buffer that will receive the wide string return parameter from the CORBA object (optional).
nReceived | Variable that will receive the number of bytes that were actually retrieved from the CORBA object (optional).

Example

dcltrans
  transaction TGetWChar
  const
    HOST   := "192.168.20.21"; // server
    PORT   := 1052;            // port
    KEY    := "...\h00";       // key
    KEYLEN := 4;               // key length
  var
    hIiop   : number;
    sString : string;
  begin
    IiopSetMaxGiopVersion("1.2");
    IiopSetByteOrder(IIOP_BIG_ENDIAN);

    // retrieve handle to server
    IiopObjectCreate(hIiop, "IDL:DemoObject:1.0", "1.2", HOST, PORT, KEY, KEYLEN);

    // call request "NextWString"
    IiopRequest(hIiop, "NextWString");

     // retrieve wide character return parameter
    IiopGetWString(hIiop, sString);
    IiopObjectRelease(hIiop);
  end TGetChar;
Parent topic: Parameter Getting Functions
Related reference
IiopSetWString Function


IiopGetDataByTypeCode Function

Action

Retrieves a certain amount of data from a CORBA object. The data is described by a type code. This function is used, for example, to retrieve recursive data structures.

Include file

IIOP.bdh

Syntax

IiopGetDataByTypecode( in  hIiop       : number,
                       in  sTypeCode   : string,
                       in  nCodeLength : number optional,
                       out sBuffer     : string optional,
                       in  nSize       : number optional,
                       out nReceived   : number optional ): boolean;

Return value

  • true if successful

  • false otherwise

Parameter | Description
hIiop | Handle to a CORBA object.
sTypeCode | Type code that specifies which data is to be retrieved from the CORBA object.
nCodeLength | Length of the type code that specifies which data is to be retrieved from the CORBA object (optional).
sBuffer | Buffer that will receive the data from the CORBA object (optional).
nSize | Size of the buffer that will receive the data from the CORBA object (optional).
nReceived | Variable that will receive the number of bytes that were actually retrieved from the CORBA object (optional).

Example

dcltrans  transaction
 TGetChar
  const
    HOST   := "192.168.20.21"; // server
    PORT   := 1052;            // port
    KEY    := "...\h00";       // key
    KEYLEN := 4;               // key length
  var
    hIiop              : number; // Handle to CORBA object
    sBuffer, sTypecode : string;    nTypecode, nLength : number;
  begin    IiopSetMaxGiopVersion("1.0");
    IiopSetByteOrder(IIOP_BIG_ENDIAN);

    // retrieve handle to server
    IiopObjectCreate(hIiop, "IDL:DemoObject:1.0", "1.2", HOST, PORT, KEY, KEYLEN);

    // call request "GetLong"
    IiopRequest(hIiop, "GetLong");
    SetLong(sTypecode, 1, IIOP_TK_LONG);
    IiopGetDataByTypecode(hIiop, sTypecode, STRING_COMPLETE, sBuffer);

    Print("GetLong returned: " + string(GetLong(sBuffer, 1)));
    IiopObjectRelease(hIiop);
  end TGetChar;
Parent topic: Parameter Getting Functions


Measurement Functions

  • IiopGetStatistics Function
    Measures a specified time or delay and the number of location forwards that were necessary to handle the request.
  • IiopObjectSetMeasures Function
    By default a timer is associated with any CORBA object in order to measure all operation calls and write the results to the Silk Performer results repository.
Parent topic: CORBA Functions Reference


IiopGetStatistics Function

Action

Measures a specified time or delay and the number of location forwards that were necessary to handle the request.

Include file

IIOP.bdh

Syntax

IiopGetStatistics( in  hIiop     : number,
                   in  nMeasure  : number,
                   out nForwards : number,
                   out fTime     : float ): boolean;

Return value

  • true if successful

  • false otherwise

Parameter | Description
hIiop | Handle to a CORBA object
nMeasure

Specifies which time or delay to measure. Possible values are:

  • IIOP_ROUNDTRIP. Total delay between starting and finishing processing the IIOP request

  • IIOP_SERVER_BUSY. Time passing from sending the last byte until receiving the first byte
nForwards | Variable receiving the number of location forwards that were necessary to handle the request
fTime | Variable receiving the time or delay (as the case may be) in seconds

Example

dcltrans
  transaction TGetStatistics
  const
    HOST   := "192.168.20.21"; // server
    PORT   := 1052; // port
    KEY    := "...\h00"; // key
    KEYLEN := 4; // key length
  var
    hIiop     : number; // handle to CORBA object
    nForwards : number;
    fTime     : float;
  begin
    IiopSetMaxGiopVersion("1.0");
    IiopSetByteOrder(IIOP_BIG_ENDIAN);

    // retrieve handle to server
    IiopObjectCreate(hIiop, "IDL:DemoObject:1.0", "1.2",
                     HOST, PORT, KEY, KEYLEN);

    // call request "Init"
    IiopRequest(hIiop, "Init");

    // retrieve statistics
    IiopGetStatistics(hIiop, IIOP_ROUNDTRIP, nForwards, fTime);
    write("location forwards = "); write(nForwards); writeln;
    write("total delay = "); write(fTime); writeln;
    IiopObjectRelease(hIiop);
  end TGetStatistics;

Output

location forwards = 1total delay = 0.051000
Parent topic: Measurement Functions
Related reference
IiopGetReplyDataLen Function
IiopGetReplyStatus Function


IiopObjectSetMeasures Function

Action

By default a timer is associated with any CORBA object in order to measure all operation calls and write the results to the Silk Performer results repository. This function must be called in order to specify a name for the default timer. Otherwise the default timer is not named.

Include file

IIOP.bdh

Syntax

IiopObjectSetMeasures( in hIiop    : number,
                       in sMeasure : string ): boolean;

Return value

  • true if successful

  • false otherwise

Parameter | Description
hIiop | Handle to a CORBA object
sMeasure | Name used to identify the measure

Example

dcltrans
  transaction TMain
  const
    HOST   := "192.168.20.21"; // server
    PORT   := 1052; // port
    KEY    := "...\h00"; // key
    KEYLEN := 4; // key length
  var
    hIiop     : number; // handle to CORBA object
    nForwards : number;
    fTime     : float;
  begin
    IiopSetMaxGiopVersion("1.2");
    IiopSetByteOrder(IIOP_BIG_ENDIAN);

    // retrieve handle to server
    IiopObjectCreate(hIiop, "IDL:DemoObject:1.0", "1.2",
                     HOST, PORT, KEY, KEYLEN);
    IiopObjectSetMeasures(hIiop, "Math object");
    ...
    IiopObjectRelease(hIiop);
  end TMain;

Sample scripts

AnyDemo.bdf, AsyncBank.bdf, Bank.bdf, SimpleAsyncBank.bdf, TypeTest.bdf, AsyncFact.bdf, AsyncOdb.bdf, Conf.bdf, DynAny.bdf, Factory.bdf, Odb.bdf, Vbrokerbank02.bdf

You can find the sample script(s) here: <Public documents>\Silk Performer <version>\Samples\Corba

Parent topic: Measurement Functions
Related reference
IiopGetStatistics Function


Wonderwall Functions Overview

Orbix Wonderwall represents the very latest in cutting edge technology for Internet security. With Wonderwall, system administrators can have all of the security provided by a firewall for Internet Inter-ORB Protocol (IIOP) communication. Wonderwall looks and feels very much like a familiar Internet firewall and allows the examination, filtering, and logging of IIOP requests.

Silk Performer provides a number of functions to load test CORBA applications that make use of the Orbix Wonderwall:

Note: You should use these functions only for earlier versions than Wonderwall 3.0. For Wonderwall 3.0 and later versions, use the common CORBA functions.
  • IiopWWBind Function
    Initializes Silk Performer’s Wonderwall module.
  • IiopWWDaemonBind Function
    Returns a handle to the Orbix Daemon that is protected by the Wonderwall.
  • IiopWWServerBind Function
    Returns a handle to a proxified server object that is protected by the Wonderwall.
  • IiopWWRequest Function
    Sends a request to an object through the Wonderwall.
  • IiopWWGetObject Function
    Gets a proxy object (used to access the respective server object) that was returned by a preceding IiopWWRequest function call.
  • IiopWWPing Function
    Performs the _IT_PING operation for calls through the Wonderwall.
  • IiopWWIsA Function
    Performs the same check as the CORBA standard _is_a function.
Parent topic: CORBA Functions Reference


IiopWWBind Function

Action

Initializes Silk Performer’s Wonderwall module. This function must be called before any Wonderwall access from within a test script.

Note: You should use this function only for earlier versions than Wonderwall 3.0. For Wonderwall 3.0 and later versions, use the common CORBA functions.

Include file

Wonderwall.bdh

Syntax

IiopWWBind( in sHost : string,
            in nPort : number ): number;

Return value

Handle to the Wonderwall object.

Parameter | Description
sHost | Wonderwall host
nPort | Wonderwall port

Example

dcltrans
  transaction TWWRequest
  const
    WW_HOST := "192.168.20.35"; // Wonderwall host
    WW_PORT := 16000;           // Wonderwall port
    HOST    := "192.168.20.21"; // server
    PORT    := 1052;            // port
  var
    hDaemon: number;
  begin
    IiopSetMaxGiopVersion("1.2");
    IiopSetByteOrder(IIOP_BIG_ENDIAN);
    IiopWWBind(WW_HOST, WW_PORT);

    // OrbixWeb bootstrapping with Wonderwall
    hDaemon := IiopWWDaemonBind(HOST, PORT);
    ...
  end TWWRequest;
Parent topic: Wonderwall Functions Overview


IiopWWDaemonBind Function

Action

Returns a handle to the Orbix Daemon that is protected by the Wonderwall.

Note: You should use this function only for earlier versions than Wonderwall 3.0. For Wonderwall 3.0 and later versions, use the common CORBA functions.

Include file

Wonderwall.bdh

Syntax

IiopWWDaemonBind( in sHost : string,
                  in nPort : number ): number;

Return value

Handle to a proxy object to Orbix Daemon.

Parameter | Description
sHost | Orbix Daemon host.
nPort | Orbix Daemon port .

Example

dcltrans
  transaction TWWRequest
  const
    WW_HOST := "192.168.20.35"; // Wonderwall host
    WW_PORT := 16000;           // Wonderwall port
    HOST    := "192.168.20.21"; // server
    PORT    := 1052;            // port
  var
    hDaemon, hBank, hAccount: number;
  begin
    IiopSetMaxGiopVersion("1.2");
    IiopSetByteOrder(IIOP_BIG_ENDIAN);
    IiopWWBind(WW_HOST, WW_PORT);

    // OrbixWeb bootstrapping with Wonderwall
    hDaemon := IiopWWDaemonBind(HOST, PORT);

    // get proxy object reference to bank object
    hBank := IiopWWServerBind(hDaemon, HOST, "bank", "", "bank");

    // Create an account
    IiopSetString(hBank, "John Dow");
    IiopWWRequest(hBank, "newAccount");

    // extract new account object
    IiopWWGetObject(hBank, hAccount);
    ...
  end TWWRequest;
Parent topic: Wonderwall Functions Overview


IiopWWServerBind Function

Action

Returns a handle to a proxified server object that is protected by the Wonderwall.

Note: You should use this function only for earlier versions than Wonderwall 3.0. For Wonderwall 3.0 and later versions, use the common CORBA functions.

Include file

Wonderwall.bdh

Syntax

IiopWWServerBind(in hDaemon : number,
in sHost : string,
in sServer : string,
in sMarker : string,
in sIfrName : string): number;

Return value

Handle to a proxified server object

Parameter | Description
hDaemon | Handle to the proxified Orbix Daemon object.
sHost | Server host.
sServer | Server name.
sMarker | Marker name of the object. If NULL, any Orbix(Web) object will match.
sIfrName | Interface Repository name of the object. Pass only the object name to the function, neither the "IDL:" prefix, nor the "1.2" suffix.

Example

dcltrans
transaction TWWRequest
const
WW_HOST := "192.168.20.35"; // Wonderwall host
WW_PORT := 16000; // Wonderwall port
HOST := "192.168.20.21"; // server
PORT := 1052; // port
var
hDaemon, hBank, hAccount : number;
begin
IiopSetMaxGiopVersion("1.2");
IiopSetByteOrder(IIOP_BIG_ENDIAN);
IiopWWBind(WW_HOST, WW_PORT);
// OrbixWeb bootstrapping with Wonderwall
hDaemon := IiopWWDaemonBind(HOST, PORT);
// get proxy object reference to bank object
hBank := IiopWWServerBind(hDaemon, HOST, "bank", "", "bank");
// Create an account
IiopSetString(hBank, "John Dow");
IiopWWRequest(hBank, "newAccount");
// extract new account object
IiopWWGetObject(hBank, hAccount);
...
end TWWRequest;
Parent topic: Wonderwall Functions Overview


IiopWWRequest Function

Action

Sends a request to an object through the Wonderwall. When accessing an object through the Wonderwall, always use this function instead of IiopRequest.

Due to a Wonderwall misbehavior, you should not use the standard procedure in case of a location forward during a request.

Note: You should use this function only for earlier versions than Wonderwall 3.0. For Wonderwall 3.0 and later versions, use the common CORBA functions.

Include file

Wonderwall.bdh

Syntax

IiopWWRequest(in hIiop : number,
in sRequest : string,
in nFlag : number optional,
in nId : number optional): number;

Return value

  • REQUEST_SUCCESS if successful

  • REQUEST_FORWARD if a location forward occurred. It is up to the user to resend the request.

  • REQUEST_FAILED otherwise

Parameter | Description
hIiop | Handle to a CORBA object.
sRequest | Name of the requested operation.
nFlag

Specifies the request message variant sent to the server (optional). Possible values are:

  • IIOP_RESPONSE_EXPECTED. Waits for a response (default).

  • IIOP_ONEWAY. Expects no response from the server.

  • IIOP_NON_BLOCKING. Indicates that the caller will not wait for an immediate reply. This flag can be used to generate asynchronous IIOP traffic.

This parameter may be combined with the following flag:

  • IIOP_IGNORE_EXCEPTION. Avoids the generation of error messages.
nId

Identification number for this request (optional).

Note: This parameter affects the function behavior only if nFlag is set to IIOP_NON_BLOCKING.

If an identification number is associated with a request, the IiopWaitForReply function can be used to wait for a reply from the request. Exceptional cases:

  • 0. Return parameters will not be stored, consequently no reply data can be retrieved (default).

  • -1 is not allowed.

Example

dcltrans
transaction TWWRequest
const
WW_HOST := "192.168.20.35"; // Wonderwall host
WW_PORT := 16000; // Wonderwall port
HOST := "192.168.20.21"; // server
PORT := 1052; // port
var
hDaemon, hBank, hAccount: number;
begin
IiopSetMaxGiopVersion("1.0");
IiopSetByteOrder(IIOP_BIG_ENDIAN);IiopWWBind(WW_HOST, WW_PORT);
// OrbixWeb bootstrapping with Wonderwall
hDaemon := IiopWWDaemonBind(HOST, PORT);
// get proxy object reference to bank object
hBank := IiopWWServerBind(hDaemon, HOST, "bank", "","bank");
// Create an account
IiopSetString(hBank, “John Dow”);
IiopWWRequest(hBank, "newAccount");
// extract new account object
IiopWWGetObject(hBank, hAccount);
end TWWRequest;
Parent topic: Wonderwall Functions Overview


IiopWWGetObject Function

Action

Gets a proxy object (used to access the respective server object) that was returned by a preceding IiopWWRequest function call.

Note: You should use this function only for earlier versions than Wonderwall 3.0. For Wonderwall 3.0 and later versions, use the common CORBA functions.

Include file

Wonderwall.bdh

Syntax

IiopWWGetObject( in  hIiop   : number,
                 out hObject : number );
Parameter | Description
hIiop | Handle to a CORBA object
hObject | Variable receiving the proxy object to the server object

Example

dcltrans
  transaction TWWRequest
  const
    WW_HOST := "192.168.20.35"; // Wonderwall host
    WW_PORT := 16000;           // Wonderwall port
    HOST    := "192.168.20.21"; // server
    PORT    := 1052;            // port
  var
    hDaemon, hBank, hAccount: number;
  begin
    IiopSetMaxGiopVersion("1.2");
    IiopSetByteOrder(IIOP_BIG_ENDIAN);
    IiopWWBind(WW_HOST, WW_PORT);

    // OrbixWeb bootstrapping with Wonderwall
    hDaemon := IiopWWDaemonBind(HOST, PORT);

    // get proxy object reference to bank object
    hBank := IiopWWServerBind(hDaemon, HOST, "bank", "", "bank");

    // Create an account
    IiopSetString(hBank, "John Dow");
    IiopWWRequest(hBank, "newAccount");

    // extract new account object
    IiopWWGetObject(hBank, hAccount);
  end TWWRequest;
Parent topic: Wonderwall Functions Overview


IiopWWPing Function

Action

Performs the _IT_PING operation for calls through the Wonderwall.

Note: You should use this function only for earlier versions than Wonderwall 3.0. For Wonderwall 3.0 and later versions, use the common CORBA functions.

Include file

Wonderwall.bdh

Syntax

IiopWWPing( in hIiop : number );
Parameter | Description
hIiop | Handle to a CORBA object

Example

dcltrans
  transaction TWWRequest
  const
    WW_HOST := "192.168.20.35"; // Wonderwall host
    WW_PORT := 16000;           // Wonderwall port
    HOST    := "192.168.20.21"; // server
    PORT    := 1052;            // port
  var
    hDaemon, hBank: number;
  begin
    IiopSetMaxGiopVersion("1.2");
    IiopSetByteOrder(IIOP_BIG_ENDIAN);
    IiopWWBind(WW_HOST, WW_PORT);

    // OrbixWeb bootstrapping with Wonderwall
    hDaemon := IiopWWDaemonBind(HOST, PORT);

    // get proxy object reference to bank object
    hBank := IiopWWServerBind(hDaemon, HOST, "bank", "", "bank");
    IiopWWPing(hBank);
    ...
  end TWWRequest;
Parent topic: Wonderwall Functions Overview


IiopWWIsA Function

Action

Performs the same check as the CORBA standard _is_a function.

Note: You should use this function only for earlier versions than Wonderwall 3.0. For Wonderwall 3.0 and later versions, use the common CORBA functions.

Include file

Wonderwall.bdh

Syntax

IiopWWIsA( in hIiop       : number,
           in sIdentifier : string ): boolean;

Return value

  • true if the object’s interface matches sIdentifier

  • false otherwise

Parameter | Description
hIiop | Handle to a CORBA object.
sIdentifier | Interface repository string, eg.“IDL:<InterfaceName>:1.0”.

Example

dcltrans
  transaction TWWRequest
  const
    WW_HOST := "192.168.20.35"; // Wonderwall host
    WW_PORT := 16000;           // Wonderwall port
    HOST    := "192.168.20.21"; // server
    PORT    := 1052;            // port
  var
    hDaemon, hBank : number;
    bRet           : boolean;
  begin
    IiopSetMaxGiopVersion("1.2");
    IiopSetByteOrder(IIOP_BIG_ENDIAN);
    IiopWWBind(WW_HOST, WW_PORT);

    // OrbixWeb bootstrapping with Wonderwall
    hDaemon := IiopWWDaemonBind(HOST, PORT);

   // get proxy object reference to bank object
    hBank := IiopWWServerBind(hDaemon, HOST, "bank", "", "bank");
    bRet := IiopWWIsA(hBank, "IDL:bank:1.0");
    ...
  end TWWRequest;
Parent topic: Wonderwall Functions Overview


Jolt Functions Reference

Silk Performer provides functions to simulate Jolt-based client/server interaction. The following Jolt objects are relevant for the simulation of such interaction:

JoltSessionAttributes:
Determines the server location and communication properties.
JoltSession:
Enables the client to create and shutdown Jolt sessions.
JoltRemoteService:
Provides the client’s view at a TUXEDO service and allows service invocation and data exchange.
JoltTransaction:
Required for transaction control.
JoltUserEvent:
Needed for event subscription and unsubscription.
  • Initialization Functions
    Lists BDL functions for initializing and starting the Java Virtual Machine.
  • Object Allocation Functions
    Lists BDL functions for creating and releasing Jolt objects.
  • Object Customization Functions
    Lists BDL functions for customizing Jolt object attributes.
  • Session Handling Functions
    Lists BDL functions for checking and terminating session objects.
  • Service Handling Functions
    Lists BDL functions for calling Jolt services and retrieving information from services.
  • Transaction Handling Functions
    Lists BDL functions for committing and rolling back transactions for a JoltTransaction object.
  • Event Handling Functions
    Lists BDL functions for deleting event subscriptions.
Parent topic: Application Server Functions


Initialization Functions

  • JoltInit Function
    Initializes and starts the Java Virtual Machine.
Parent topic: Jolt Functions Reference


JoltInit Function

Action

Initializes and starts the Java Virtual Machine. Silk Performer requires the JVM from Sun Microsystems and the Jolt packages from BEA Systems.

Include file

Jolt.bdh

Syntax

JoltInit( in nVersion   : number optional ): boolean;

Return value

  • true if successful

  • false otherwise

Parameter Description
nVersion

Version number of the Java Virtual Machine (optional). This parameter can be one of the following:

  • JVM_11. Java 1 Platform (Java 1.1.x)

  • JVM_12. Java 2 Platform (Java 1.2.x and later versions)

By default, the VM version, specified by the profile settings, is used.

Note: The JavaSetOption function overrides the profile setting.

Example

dcltrans
  transaction TInit
  begin
    JavaSetOption(JAVA_VERSION, JAVA_V11);
    JavaSetOption(JAVA_HOME, "c:/jdk1.1.7");
    JavaSetOption(JAVA_CLASSPATH, "c:/jdk1.1.7");
    JoltInit();
  end TInit;
Parent topic: Initialization Functions
Related reference
JavaSetOption Function


Object Allocation Functions

  • JoltSessionAttributesNew Function
    Creates a new JoltSessionAttributes object.
  • JoltSessionNew Function
    Creates a new JoltSession object.
  • JoltRemoteServiceNew Function
    Creates a new JoltRemoteService object.
  • JoltTransactionNew Function
    Creates a new JoltTransaction object.
  • JoltUserEventNew Function
    Creates a new JoltUserEvent object.
  • JoltFreeObject Function
    Releases a Jolt object created with JoltSessionAttributesNew, JoltSessionNew, JoltRemoteServiceNew, JoltTransactionNew or JoltUserEventNew and enables the Java Virtual machine to collect the related garbage object.
Parent topic: Jolt Functions Reference


JoltSessionAttributesNew Function

Action

Creates a new JoltSessionAttributes object. A JoltSessionAttributes object defines the parameters for the JoltSessionNew function.

A JoltSessionAttributes object contains the following attributes:

  • APPADDRESS (string). Host name and port number of the Jolt Service Listener (JSL), separated by a colon (:)

  • IDLETIMEOUT (integer)

  • SENDTIMEOUT (integer)

  • RECVTIMEOUT (integer)

  • SESSIONTIMEOUT (integer). This attribute is read-only.

Include file

Jolt.bdh

Syntax

JoltSessionAttributesNew(): number;

Return value

Handle to the new JoltSessionAttributes object.

Example

var
  hSessionAttr: number;

dcltrans
  transaction TInit
  begin
    JavaSetOption(JAVA_VERSION, JAVA_V11);
    JavaSetOption(JAVA_HOME, "c:/jdk1.1.7");
    JavaSetOption(JAVA_CLASSPATH, "c:/jdk1.1.7");
    JoltInit();

    hSessionAttr := JoltSessionAttributesNew();
    JoltSetString(hSessionAttr, APPADDRESS, "//lab:8000");
  end TInit;

  transaction TShutdown
  begin
    JoltFreeObject(hSessionAttr);
  end TShutdown;

See also

Java: bea.jolt.JoltSessionAttributes class

Parent topic: Object Allocation Functions
Related reference
JoltFreeObject Function
JoltRemoteServiceNew Function
JoltSessionNew Function
JoltTransactionNew Function
JoltUserEventNew Function


JoltSessionNew Function

Action

Creates a new JoltSession object. A JoltSession object represents the logon session object and is used to access available TUXEDO services. The JoltCheckAuthenticationLevel function can be used to retrieve the type of authentication that is required.

Include file

Jolt.bdh

Syntax

JoltSessionNew( in hSessionAttr  : number,
                in sUserName     : string allownull,
                in sUserRole     : string allownull,
                in sUserPassword : string allownull,
                in sAppPassword  : string allownull ): number;

Return value

Handle to the new JoltSession object.

Parameter | Description
hSessionAttr | Handle to a JoltSessionAttributes object that was created with JoltSessionAttributesNew
sUserName | Name that identifies the user to the Jolt/TUXEDO System. This parameter represents the name of the caller commonly entered in logon dialogs
sUserRole | Group name. This parameter is used to associate the client with a resource manager group name
sUserPassword | User password in unencrypted format. This parameter is used for validation against the user password
sAppPassword | Application password in unencrypted format. This parameter is used for validation against the application password

Example

var
  hSession, hSessionAttr: number;
dcltrans
  transaction TInit
  begin
    JavaSetOption(JAVA_VERSION, JAVA_V11);
    JavaSetOption(JAVA_HOME, "c:/jdk1.1.7");
    JavaSetOption(JAVA_CLASSPATH, "c:/jdk1.1.7");
    JoltInit();    hSessionAttr := JoltSessionAttributesNew();
    JoltSetString(hSessionAttr, APPADDRESS, "//lab:8000");
    hSession := JoltSessionNew(hSessionAttr, "", "ATM", "", "");
  end TInit;
  transaction TShutdown
  begin
    JoltEndSession(hSession);
    JoltFreeObject(hSession);
    JoltFreeObject(hSessionAttr);
  end TShutdown;

See also

Java: bea.jolt.JoltSession class

Parent topic: Object Allocation Functions
Related reference
JoltFreeObject Function
JoltRemoteServiceNew Function
JoltSessionAttributesNew Function
JoltTransactionNew Function
JoltUserEventNew Function


JoltRemoteServiceNew Function

Action

Creates a new JoltRemoteService object. A JoltRemoteService object is used to perform a Request/Reply call. To make a call it is necessary to

  • instantiate an object of this class for the service,

  • set the parameters using the JoltSet functions,

  • send the request by calling the JoltCall function,

  • and to retrieve the parameters using the JoltGet functions.

Include file

Jolt.bdh

Syntax

JoltRemoteServiceNew( in sServiceName : string,
                      in hSession     : number,
                      in nVersion     : number optional ): number;

Return value

Handle to the new JoltRemoteService object

Parameter | Description
sServiceName | Name of the service
hSession | Handle to a JoltSession object the was created with JoltSessionNew
nVersion | Version number required by JoltRemoteService constructors to check the compatibility between the server and the client (optional). This parameter is not required for the Jolt 1.1 client package.

Example

var
  hSession, hSessionAttr, hInquiry: number;

dcltrans
  transaction TInit
  begin
  JavaSetOption(JAVA_VERSION, JAVA_V11);
    JavaSetOption(JAVA_HOME, "c:/jdk1.1.7");
    JavaSetOption(JAVA_CLASSPATH, "c:/jdk1.1.7");
    JoltInit();
    hSessionAttr := JoltSessionAttributesNew();
    JoltSetString(hSessionAttr, APPADDRESS, "//lab:8000");
    hSession := JoltSessionNew(hSessionAttr, "", "ATM", "", "");
    hInquiry := JoltRemoteServiceNew("INQUIRY", hSession);
  end TInit;

  transaction TShutdown
  begin
    JoltEndSession(hSession);
    JoltFreeObject(hInquiry);
    JoltFreeObject(hSession);
    JoltFreeObject(hSessionAttr);
  end TShutdown;

See also

Java: bea.jolt.JoltRemoteService class

Parent topic: Object Allocation Functions
Related reference
JoltFreeObject Function
JoltSessionAttributesNew Function
JoltSessionNew Function
JoltTransactionNew Function
JoltUserEventNew Function


JoltTransactionNew Function

Action

Creates a new JoltTransaction object. A JoltTransaction object can be used to include several services into a single transaction. Calling this function implies the beginning of the transaction. When a transaction is timed out, the user must rollback the transaction immediately. Service calls become part of a transaction when the associated transaction object is passed to the service call (see JoltCall function).

Include file

Jolt.bdh

Syntax

JoltTransactionNew( in nTimeout : number,
                    in hSession : number ): number;

Return value

Handle to the new JoltTransaction object.

Parameter | Description
nTimeout | Timeout for the transaction. If the transaction is not completed within this period of time, Jolt generates a transaction exception. Specifying a timeout of 0 sets the timeout to the maximum value for the system
hSession | Handle to a JoltSession object created with JoltSessionNew

Example

var
  hSession, hSessionAttr, hTransaction: number;
dcltrans
  transaction TInit
  begin
    JavaSetOption(JAVA_VERSION, JAVA_V11);
    JavaSetOption(JAVA_HOME, "c:/jdk1.1.7");
    JavaSetOption(JAVA_CLASSPATH, "c:/jdk1.1.7");
    JoltInit();     hSessionAttr := JoltSessionAttributesNew();
    JoltSetString(hSessionAttr, APPADDRESS, "//lab:8000");
    hSession := JoltSessionNew(hSessionAttr, "", "ATM", "", "");
  end TInit;

  transaction TMain
  begin
    hTransaction := JoltTransactionNew(0, hSession);
    ...
    JoltCommit(hTransaction);
  end TMain;
  transaction TShutdown
  begin
    JoltEndSession(hSession);
    JoltFreeObject(hTransaction);
    JoltFreeObject(hSession);
    JoltFreeObject(hSessionAttr);
  end TShutdown;

See also

Java: bea.jolt.JoltTransaction class

Parent topic: Object Allocation Functions
Related reference
JoltFreeObject Function
JoltRemoteServiceNew Function
JoltSessionAttributesNew Function
JoltSessionNew Function
JoltUserEventNew Function


JoltUserEventNew Function

Action

Creates a new JoltUserEvent object. A JoltUserEvent object represents a subscription to an asynchronous notification event. An asynchronous notification is either an unsolicited event notification or event notification from the TUXEDO Event Broker. In Silk Performer, the Jolt default event handler is used for all events.

Include file

Jolt.bdh

Syntax

JoltUserEventNew( in sExpression : string,
                  in sFilter     : string allownull,
                  in hSession    : number ): number;

Return value

Handle to the new JoltUserEvent object.

Parameter | Description
sExpression | Regular expression for event notification. This parameter is a string containing a regular expression of the same format as the event expression used in Tux_tpsubscribe. To subscribe unsolicited messages, use the constant ULSOLMSG.
sFilter | String of the same format as the filter parameter passed to Tux_tpsubscribe. Filter rules are specific to the buffers to which they are applied
hSession | Handle to a JoltSession object that was created with JoltSessionNew

Example

var
  hSession, hSessionAttr, hUserEvent: number;
 dcltrans
  transaction TInit
  begin
    JavaSetOption(JAVA_VERSION, JAVA_V11);
    JavaSetOption(JAVA_HOME, "c:/jdk1.1.7");
    JavaSetOption(JAVA_CLASSPATH, "c:/jdk1.1.7");
    JoltInit();     hSessionAttr := JoltSessionAttributesNew();
    JoltSetString(hSessionAttr, APPADDRESS, "//lab:8000");
    hSession := JoltSessionNew(hSessionAttr, "", "ATM", "", "");
    hUserEvent := JoltUserEventNew(UNSOLMSG, NULL, hSession);
  end TInit;
  transaction TShutdown
  begin
    JoltUnsubscribe(hUserEvent);
    JoltEndSession(hSession);
    JoltFreeObject(hUserEvent);
    JoltFreeObject(hSession);
    JoltFreeObject(hSessionAttr);
  end TShutdown;

See also

Java: bea.jolt.JoltUserEvent class

Parent topic: Object Allocation Functions
Related reference
JoltFreeObject Function
JoltRemoteServiceNew Function
JoltSessionAttributesNew Function
JoltSessionNew Function
JoltTransactionNew Function


JoltFreeObject Function

Action

Releases a Jolt object created with JoltSessionAttributesNew, JoltSessionNew, JoltRemoteServiceNew, JoltTransactionNew or JoltUserEventNew and enables the Java Virtual machine to collect the related garbage object.

Include file

Jolt.bdh

Syntax

JoltFreeObject( inout hJolt : number ): boolean;

Return value

  • true if successful

  • false otherwise

Parameter | Description
hJolt | Handle to the Jolt object that is to be released

Example

var
  hSession, hSessionAttr, hInquiry: number;
 dcltrans
  transaction TInit
  begin
    JavaSetOption(JAVA_VERSION, JAVA_V11);
    JavaSetOption(JAVA_HOME, "c:/jdk1.1.7");
    JavaSetOption(JAVA_CLASSPATH, "c:/jdk1.1.7");
    JoltInit();     hSessionAttr := JoltSessionAttributesNew();
    JoltSetString(hSessionAttr, APPADDRESS, "//lab:8000");
    hSession := JoltSessionNew(hSessionAttr, "", "ATM", "", "");
    hInquiry := JoltRemoteServiceNew("INQUIRY", hSession);
  end TInit;
  transaction TShutdown
  begin
    JoltEndSession(hSession);
    JoltFreeObject(hInquiry);
    JoltFreeObject(hSession);
    JoltFreeObject(hSessionAttr);
  end TShutdown;
Parent topic: Object Allocation Functions
Related reference
JoltRemoteServiceNew Function
JoltSessionAttributesNew Function
JoltSessionNew Function
JoltTransactionNew Function
JoltUserEventNew Function


Object Customization Functions

  • JoltSetByte Function
    Assigns a specified value to a one-byte item (“byte” in Java) of a Jolt object attribute.
  • JoltSetCarray Function
    Assigns specified data to a binary data item (“byte[]” in Java) of a Jolt object attribute.
  • JoltSetDouble Function
    Assigns a specified value to an eight-byte floating-point item (“double” in Java) of a Jolt object attribute.
  • JoltSetFloat Function
    Assigns a specified value to a four-byte floating-point item (“float” in Java) of a Jolt object attribute.
  • JoltSetInt Function
    Assigns a specified value to a four-byte item (“int” in Java) of a Jolt object attribute.
  • JoltSetShort Function
    Assigns a specified value to a two-byte item (“short” in Java) of a Jolt object attribute.
  • JoltSetString Function
    Assigns a specified string to a string item (“java.lang.String” in Java) of a Jolt object attribute.
  • JoltGetByte Function
    Retrieves the value of a one-byte item (“byte” in Java) of a Jolt object attribute.
  • JoltGetCarray Function
    Retrieves data from a binary byte item (“byte[]” in Java) of a Jolt object attribute.
  • JoltGetDouble Function
    Retrieves the value of an eight-byte floating-point item (“double” in Java) of a Jolt object attribute.
  • JoltGetFloat Function
    Retrieves the value of a four-byte floating-point item (“float” in Java) of a Jolt object attribute.
  • JoltGetInt Function
    Retrieves the value of a four-byte item (“int” in Java) of a Jolt object attribute.
  • JoltGetShort Function
    Retrieves the value of a two-byte item (“short” in Java) of a Jolt object attribute.
  • JoltGetString Function
    Retrieves the string from a string item (“java.lang.String” in Java) of a Jolt object attribute.
  • JoltClear Function
    Clears all input/output data of a Jolt object.
  • JoltDelete Function
    Deletes an item of a Jolt object attribute.
Parent topic: Jolt Functions Reference


JoltSetByte Function

Action

Assigns a specified value to a one-byte item (“byte” in Java) of a Jolt object attribute. This function is provided to set values of both JoltSessionAttributes and JoltRemoteService object attributes. Besides, this function can be used to add new items to existing attributes as well as to create new attributes.

Include file

Jolt.bdh

Syntax

JoltSetByte( in hJolt       : number,
             in sAttribute  : string,
             in nValue      : number,
             in nOccurrence : number optional): boolean;

Return value

  • true if successful

  • false otherwise

Parameter | Description
hJolt | Handle to a JoltSessionAttributes or JoltRemoteService object that was created with JoltSessionAttributesNew or JoltRemoteServiceNew, respectively
sAttribute | Name of the attribute that is to be accessed
nValue | Value that is assigned to the specified attribute
nOccurrence | Index of the item that is to be set (optional). The index of an attribute’s first item is 1 (not 0). If this parameter is omitted, the attribute’s first item is set. If this parameter is set to ADD_VALUE, a new item is appended to the attribute (provided that the specified attribute already exists; otherwise, if the specified attribute does not yet exist, a new attribute with the given properties is created) Note: This parameter is ignored if hJolt represents a JoltSessionAttributes object.

Example

var
  hSession, hSessionAttr, hRemoteService: number;
 dcltrans
  transaction TInit
  begin
    JavaSetOption(JAVA_VERSION, JAVA_V11);
    JavaSetOption(JAVA_HOME, "c:/jdk1.1.7");
    JavaSetOption(JAVA_CLASSPATH, "c:/jdk1.1.7");
    JoltInit();
    hSessionAttr := JoltSessionAttributesNew();
    JoltSetString(hSessionAttr, APPADDRESS, "//lab:8000");
    hSession := JoltSessionNew(hSessionAttr, "", "ATM", "", "");
    hRemoteService := JoltRemoteServiceNew("TOUPPER", hSession);
  end TInit;

  transaction TMain
  var
    nChar: number;
  begin
    JoltSetByte(hRemoteService, "ASCII_CODE", ord('a'));
    JoltCall(hRemoteService);
    nChar := JoltGetByte(hRemoteService, "ASCII_CODE", 0);
    writeln(nChar);
  end TMain;
  transaction TShutdown
  begin
    JoltEndSession(hSession);
    JoltFreeObject(hRemoteService);
    JoltFreeObject(hSession);
    JoltFreeObject(hSessionAttr);
  end TShutdown;

See also

Java: bea.jolt.JoltSessionAttributes class, bea.jolt.JoltRemoteService class

Parent topic: Object Customization Functions
Related reference
JoltRemoteServiceNew Function
JoltSessionAttributesNew Function
JoltDelete Function
JoltClear Function


JoltSetCarray Function

Action

Assigns specified data to a binary data item (“byte[]” in Java) of a Jolt object attribute. This function is provided to set data of both JoltSessionAttributes and JoltRemoteService object attributes. Besides, this function can be used to add new items to existing attributes as well as to create new attributes.

Include file

Jolt.bdh

Syntax

JoltSetCarray( in hJolt       :number,
               in sAttribute  : string,
               in sBinary     : string allownull,
               in nBinarySize : number optional,
               in nOccurrence : number optional ): boolean;

Return value

  • true if successful

  • false otherwise

Parameter | Description
hJolt | Handle to a JoltSessionAttributes or JoltRemoteService object that was created with JoltSessionAttributesNew or JoltRemoteServiceNew, respectively
sAttribute | Name of the attribute that is to be accessed
sBinary | Binary data that is assigned to the specified attribute
nBinarySize | Amount of binary data (in bytes) that is assigned to the specified attribute (optional).
nOccurrence | Index of the item that is to be set (optional). The index of an attribute’s first item is 1 (not 0). If this parameter is omitted, the attribute’s first item is set. If this parameter is set to ADD_VALUE, a new item is appended to the attribute (provided that the specified attribute already exists; otherwise, if the specified attribute does not yet exist, a new attribute with the given properties is created) Note: This parameter is ignored if hJolt represents a JoltSessionAttributes object.

Example

var
  hSession, hSessionAttr, hRemoteService: number;
 dcltrans
  transaction TInit
  begin
    JavaSetOption(JAVA_VERSION, JAVA_V11);
    JavaSetOption(JAVA_HOME, "c:/jdk1.1.7");
    JavaSetOption(JAVA_CLASSPATH, "c:/jdk1.1.7");
    JoltInit();
    hSessionAttr := JoltSessionAttributesNew();
    JoltSetString(hSessionAttr, APPADDRESS, "//lab:8000");
    hSession := JoltSessionNew(hSessionAttr, "", "ATM", "", "");
    hRemoteService := JoltRemoteServiceNew("XOR", hSession);
  end TInit;

transaction TMain
  var
    sBinary    : string;
    nBinaryLen : number;
  begin
     JoltSetCarray(hRemoteService, "PLAIN", "\h45E295AFD03B631200");
     JoltSetCarray(hRemoteService, "PASSWORD", "secret\x00");
    JoltCall(hRemoteService);
    JoltGetCarray(hRemoteService, "CODE", NULL, 0, sBinary);
  end TMain;

transaction TShutdown
  begin
    JoltEndSession(hSession);
    JoltFreeObject(hRemoteService);
    JoltFreeObject(hSession);
    JoltFreeObject(hSessionAttr);
  end TShutdown;

See also

Java: bea.jolt.JoltSessionAttributes class, bea.jolt.JoltRemoteService class

Parent topic: Object Customization Functions
Related reference
JoltRemoteServiceNew Function
JoltSessionAttributesNew Function
JoltDelete Function
JoltClear Function


JoltSetDouble Function

Action

Assigns a specified value to an eight-byte floating-point item (“double” in Java) of a Jolt object attribute. This function is provided to set values of both JoltSessionAttributes and JoltRemoteService object attributes. Besides, this function can be used to add new items to existing attributes as well as to create new attributes.

Include file

Jolt.bdh

Syntax

JoltSetDouble( in hJolt       : number,
               in sAttribute  : string,
               in fValue      : float,
               in nOccurrence : number optional ): boolean;

Return value

  • true if successful

  • false otherwise

Parameter | Description
hJolt | Handle to a JoltSessionAttributes or JoltRemoteService object that was created with JoltSessionAttributesNew or JoltRemoteServiceNew, respectively
sAttribute | Name of the attribute that is to be accessed
fValue | Floating-point value that is assigned to the specified attribute
nOccurrence | Index of the item that is to be set (optional). The index of an attribute’s first item is 1 (not 0). If this parameter is omitted, the attribute’s first item is set. If this parameter is set to ADD_VALUE, a new item is appended to the attribute (provided that the specified attribute already exists; otherwise, if the specified attribute does not yet exist, a new attribute with the given properties is created) Note: This parameter is ignored if hJolt represents a JoltSessionAttributes object.

Example

var
  hSession, hSessionAttr, hRemoteService: number;
 dcltrans
  transaction TInit
  begin
    JavaSetOption(JAVA_VERSION, JAVA_V11);
    JavaSetOption(JAVA_HOME, "c:/jdk1.1.7");
    JavaSetOption(JAVA_CLASSPATH, "c:/jdk1.1.7");
    JoltInit();
    hSessionAttr := JoltSessionAttributesNew();
    JoltSetString(hSessionAttr, APPADDRESS, "//lab:8000");
    hSession := JoltSessionNew(hSessionAttr, "", "ATM", "", "");
    hRemoteService := JoltRemoteServiceNew("SUM", hSession);
  end TInit;
  transaction TMain
  var
    fSum: float;
  begin
    JoltSetDouble(hRemoteService, "DVALUE", 23.7, ADD_VALUE);
    JoltSetDouble(hRemoteService, "DVALUE", 11.91, ADD_VALUE);
    JoltCall(hRemoteService);
    fSum := JoltGetDouble(hRemoteService, "RESULT", 0.0);
    writeln(fSum);
  end TMain;

  transaction TShutdown
  begin
    JoltEndSession(hSession);
    JoltFreeObject(hRemoteService);
    JoltFreeObject(hSession);
    JoltFreeObject(hSessionAttr);
  end TShutdown;

See also

Java: bea.jolt.JoltSessionAttributes class, bea.jolt.JoltRemoteService class

Parent topic: Object Customization Functions
Related reference
JoltRemoteServiceNew Function
JoltSessionAttributesNew Function
JoltDelete Function
JoltClear Function


JoltSetFloat Function

Action

Assigns a specified value to a four-byte floating-point item (“float” in Java) of a Jolt object attribute. This function is provided to set values of both JoltSessionAttributes and JoltRemoteService object attributes. Besides, this function can be used to add new items to existing attributes as well as to create new attributes.

Include file

Jolt.bdh

Syntax

JoltSetFloat( in hJolt       : number,
              in sAttribute  : string,
              in fValue      : float,
              in nOccurrence : number optional): boolean;

Return value

  • true if successful

  • false otherwise

Parameter | Description
hJolt | Handle to a JoltSessionAttributes or JoltRemoteService object that was created with JoltSessionAttributesNew or JoltRemoteServiceNew, respectively
sAttribute | Name of the attribute that is to be accessed
fValue | Floating-point value that is assigned to the specified attribute
nOccurrence | Index of the item that is to be set (optional). The index of an attribute’s first item is 1 (not 0). If this parameter is omitted, the attribute’s first item is set. If this parameter is set to ADD_VALUE, a new item is appended to the attribute (provided that the specified attribute already exists; otherwise, if the specified attribute does not yet exist, a new attribute with the given properties is created) Note: This parameter is ignored if hJolt represents a JoltSessionAttributes object.

Example

var
  hSession, hSessionAttr, hRemoteService: number;
 dcltrans
  transaction TInit
  begin
    JavaSetOption(JAVA_VERSION, JAVA_V11);
    JavaSetOption(JAVA_HOME, "c:/jdk1.1.7");
    JavaSetOption(JAVA_CLASSPATH, "c:/jdk1.1.7");
    JoltInit();
    hSessionAttr := JoltSessionAttributesNew();
    JoltSetString(hSessionAttr, APPADDRESS, "//lab:8000");
    hSession := JoltSessionNew(hSessionAttr, "", "ATM", "", "");
    hRemoteService := JoltRemoteServiceNew("SUM", hSession);
  end TInit;
  transaction TMain
  var
    fSum: float;
  begin
    JoltSetFloat(hRemoteService, "FVALUE", 23.7, ADD_VALUE);
    JoltSetFloat(hRemoteService, "FVALUE", 11.91, ADD_VALUE);
    JoltCall(hRemoteService);
    fSum := JoltGetFloat(hRemoteService, "RESULT", 0.0);
    writeln(fSum);
  end TMain;
  transaction TShutdown
  begin
    JoltEndSession(hSession);
    JoltFreeObject(hRemoteService);
    JoltFreeObject(hSession);
    JoltFreeObject(hSessionAttr);
  end TShutdown;

See also

Java: bea.jolt.JoltSessionAttributes class, bea.jolt.JoltRemoteService class

Parent topic: Object Customization Functions
Related reference
JoltRemoteServiceNew Function
JoltSessionAttributesNew Function
JoltDelete Function
JoltClear Function


JoltSetInt Function

Action

Assigns a specified value to a four-byte item (“int” in Java) of a Jolt object attribute. This function is provided to set values of both JoltSessionAttributes and JoltRemoteService object attributes. Besides, this function can be used to add new items to existing attributes as well as to create new attributes.

Include file

Jolt.bdh

Syntax

JoltSetInt( in hJolt       : number,
            in sAttribute  : string,
            in nValue      : number,
            in nOccurrence : number optional): boolean;

Return value

  • true if successful

  • false otherwise

Parameter | Description
hJolt | Handle to a JoltSessionAttributes or JoltRemoteService object that was created with JoltSessionAttributesNew or JoltRemoteServiceNew, respectively
sAttribute | Name of the attribute that is to be accessed
nValue | Value that is assigned to the specified attribute
nOccurrence | Index of the item that is to be set (optional). The index of an attribute’s first item is 1 (not 0). If this parameter is omitted, the attribute’s first item is set. If this parameter is set to ADD_VALUE, a new item is appended to the attribute (provided that the specified attribute already exists; otherwise, if the specified attribute does not yet exist, a new attribute with the given properties is created) Note: This parameter is ignored if hJolt represents a JoltSessionAttributes object.

Example

var
  hSession, hSessionAttr, hRemoteService: number;
 dcltrans
  transaction TInit
  begin
    JavaSetOption(JAVA_VERSION, JAVA_V11);
    JavaSetOption(JAVA_HOME, "c:/jdk1.1.7");
    JavaSetOption(JAVA_CLASSPATH, "c:/jdk1.1.7");
    JoltInit();
    hSessionAttr := JoltSessionAttributesNew();
    JoltSetString(hSessionAttr, APPADDRESS, "//lab:8000");
    hSession := JoltSessionNew(hSessionAttr, "", "ATM", "", "");
    hRemoteService := JoltRemoteServiceNew("SUM", hSession);
  end TInit;

transaction TMain
  var
    nSum: number;
  begin
    JoltSetInt(hRemoteService, "IVALUE", 23, ADD_VALUE);
    JoltSetInt(hRemoteService, "IVALUE", 11, ADD_VALUE);
    JoltCall(hRemoteService);
    nSum := JoltGetInt(hRemoteService, "RESULT", 0);
    writeln(nSum);
  end TMain;

  transaction TShutdown
  begin
    JoltEndSession(hSession);
    JoltFreeObject(hRemoteService);
    JoltFreeObject(hSession);
    JoltFreeObject(hSessionAttr);
  end TShutdown;

See also

Java: bea.jolt.JoltSessionAttributes class, bea.jolt.JoltRemoteService class

Parent topic: Object Customization Functions
Related reference
JoltRemoteServiceNew Function
JoltSessionAttributesNew Function
JoltDelete Function
JoltClear Function


JoltSetShort Function

Action

Assigns a specified value to a two-byte item (“short” in Java) of a Jolt object attribute. This function is provided to set values of both JoltSessionAttributes and JoltRemoteService object attributes. Besides, this function can be used to add new items to existing attributes as well as to create new attributes.

Include file

Jolt.bdh

Syntax

JoltSetShort( in hJolt       : number,
              in sAttribute  : string,
              in nValue      : number,
              in nOccurrence : number optional ): boolean;

Return value

  • true if successful

  • false otherwise

Parameter | Description
hJolt | Handle to a JoltSessionAttributes or JoltRemoteService object that was created with JoltSessionAttributesNew or JoltRemoteServiceNew, respectively
sAttribute | Name of the attribute that is to be accessed
nValue | Value that is assigned to the specified attribute
nOccurrence | Index of the item that is to be set (optional). The index of an attribute’s first item is 1 (not 0). If this parameter is omitted, the attribute’s first item is set. If this parameter is set to ADD_VALUE, a new item is appended to the attribute (provided that the specified attribute already exists; otherwise, if the specified attribute does not yet exist, a new attribute with the given properties is created) Note: This parameter is ignored if hJolt represents a JoltSessionAttributes object.

Example

var
  hSession, hSessionAttr, hRemoteService: number;
dcltrans
  transaction TInit
  begin
    JavaSetOption(JAVA_VERSION, JAVA_V11);
    JavaSetOption(JAVA_HOME, "c:/jdk1.1.7");
    JavaSetOption(JAVA_CLASSPATH, "c:/jdk1.1.7");
    JoltInit();
     hSessionAttr := JoltSessionAttributesNew();
    JoltSetString(hSessionAttr, APPADDRESS, "//lab:8000");
    hSession := JoltSessionNew(hSessionAttr, "", "ATM", "", "");
    hRemoteService := JoltRemoteServiceNew("SUM", hSession);
  end TInit;

  transaction TMain
  var
    nSum: number;
  begin
    JoltSetShort(hRemoteService, "SVALUE", 23, ADD_VALUE);
    JoltSetShort(hRemoteService, "SVALUE", 11, ADD_VALUE);
    JoltCall(hRemoteService);
    nSum := JoltGetShort(hRemoteService, "RESULT", 0);
    writeln(nSum);
  end TMain;

  transaction TShutdown
  begin
    JoltEndSession(hSession);
    JoltFreeObject(hRemoteService);
    JoltFreeObject(hSession);
    JoltFreeObject(hSessionAttr);
  end TShutdown;

See also

Java: bea.jolt.JoltSessionAttributes class, bea.jolt.JoltRemoteService class

Parent topic: Object Customization Functions
Related reference
JoltRemoteServiceNew Function
JoltSessionAttributesNew Function
JoltDelete Function
JoltClear Function


JoltSetString Function

Action

Assigns a specified string to a string item (“java.lang.String” in Java) of a Jolt object attribute. This function is provided to set strings of both JoltSessionAttributes and JoltRemoteService object attributes. Besides, this function can be used to add new items to existing attributes as well as to create new attributes.

Include file

Jolt.bdh

Syntax

JoltSetString( in hJolt       : number,
               in sAttribute  : string,
               in sString     : string,
               in nOccurrence : number optional ): boolean;

Return value

  • true if successful

  • false otherwise

Parameter | Description
hJolt | Handle to a JoltSessionAttributes or JoltRemoteService object that was created with JoltSessionAttributesNew or JoltRemoteServiceNew, respectively
sAttribute | Name of the attribute that is to be accessed
sString | String that is assigned to the specified attribute
nOccurrence | Index of the item that is to be set (optional). The index of an attribute’s first item is 1 (not 0). If this parameter is omitted, the attribute’s first item is set. If this parameter is set to ADD_VALUE, a new item is appended to the attribute (provided that the specified attribute already exists; otherwise, if the specified attribute does not yet exist, a new attribute with the given properties is created) Note: This parameter is ignored if hJolt represents a JoltSessionAttributes object.

Example

var
  hSession, hSessionAttr, hRemoteService: number;
 dcltrans
  transaction TInit
  begin
    JavaSetOption(JAVA_VERSION, AVA_V11);
    JavaSetOption(JAVA_HOME, "c:/jdk1.1.7");
    JavaSetOption(JAVA_CLASSPATH, "c:/jdk1.1.7");
    JoltInit();
    hSessionAttr := JoltSessionAttributesNew();
    JoltSetString(hSessionAttr, APPADDRESS, "//lab:8000");
    hSession := JoltSessionNew(hSessionAttr, "", "ATM", "", "");
    hRemoteService := JoltRemoteServiceNew("TOUPPER", hSession);
  end TInit;
  transaction TMain
  var
    sString: string;
  begin
    JoltSetString(hRemoteService, "STRARG", "hello  world!");
    JoltCall(hRemoteService);
    JoltGetString(hRemoteService, "RESULT", "", sString);
    writeln(sString);
  end TMain;

  transaction TShutdown
  begin
    JoltEndSession(hSession);
    JoltFreeObject(hRemoteService);
    JoltFreeObject(hSession);
    JoltFreeObject(hSessionAttr);
  end TShutdown;

See also

Java: bea.jolt.JoltSessionAttributes class, bea.jolt.JoltRemoteService class

Parent topic: Object Customization Functions
Related reference
JoltRemoteServiceNew Function
JoltSessionAttributesNew Function
JoltDelete Function
JoltClear Function


JoltGetByte Function

Action

Retrieves the value of a one-byte item (“byte” in Java) of a Jolt object attribute. This function is provided to retrieve values from both JoltSessionAttributes and JoltRemoteService object attributes.

Include file

Jolt.bdh

Syntax

JoltGetByte( in hJolt       : number,
             in sAttribute  : string,
             in nDefault    : number,
             in nOccurrence : number optional ): number;

Return value

Value of the specified one-byte item of the Jolt object attribute.

Parameter | Description
hJolt | Handle to a JoltSessionAttributes or JoltRemoteService object that was created with JoltSessionAttributesNew or JoltRemoteServiceNew, respectively
sAttribute | Name of the attribute that is to be accessed
nDefault | Value that the function returns if the specified attribute or item does not exist
nOccurrence | Index of the item that is to be retrieved (optional). The index of an attribute’s first item is 1 (not 0). If this parameter is omitted, the attribute’s first item is retrieved. Note: This parameter is ignored if hJolt represents a JoltSessionAttributes object.

Example

var
  hSession, hSessionAttr, hRemoteService: number;
dcltrans
  transaction TInit
  begin
    JavaSetOption(JAVA_VERSION, JAVA_V11);
    JavaSetOption(JAVA_HOME, "c:/jdk1.1.7");
    JavaSetOption(JAVA_CLASSPATH, "c:/jdk1.1.7");
    JoltInit();     hSessionAttr := JoltSessionAttributesNew();
    JoltSetString(hSessionAttr, APPADDRESS, "//lab:8000");
    hSession := JoltSessionNew(hSessionAttr, "", "ATM", "", "");
    hRemoteService := JoltRemoteServiceNew("TOUPPER", hSession);
  end TInit;

  transaction TMain
  var
    nChar: number;
  begin
    JoltSetByte(hRemoteService, "ASCII_CODE", ord('a'));
    JoltCall(hRemoteService);
    nChar := JoltGetByte(hRemoteService, "ASCII_CODE", 0);
    writeln(nChar);
  end TMain;

  transaction TShutdown
  begin
    JoltEndSession(hSession);
    JoltFreeObject(hRemoteService);
    JoltFreeObject(hSession);
    JoltFreeObject(hSessionAttr);
  end TShutdown;

See also

Java: bea.jolt.JoltSessionAttributes class, bea.jolt.JoltRemoteService class

Parent topic: Object Customization Functions
Related reference
JoltRemoteServiceNew Function
JoltSessionAttributesNew Function
JoltDelete Function
JoltClear Function


JoltGetCarray Function

Action

Retrieves data from a binary byte item (“byte[]” in Java) of a Jolt object attribute. This function is provided to retrieve data from both JoltSessionAttributes and JoltRemoteService object attributes.

Include file

Jolt.bdh

Syntax

JoltGetCarray( in  hJolt        : number,
               in  sAttribute   : string,
               in  sDefault     : string allownull,
               in  nDefaultSize : number,
               out sBinary      : string allownull,
               in  nBinarySize  : number optional,
               out nBinaryLen   : number optional,
               in  nOccurrence  : number optional): boolean;

Return value

  • true if successful

  • false otherwise

Parameter | Description
hJolt | Handle to a JoltSessionAttributes or JoltRemoteService object that was created with JoltSessionAttributesNew or JoltRemoteServiceNew, respectively
sAttribute | Name of the attribute that is to be accessed
sDefault | Binary data that the function accesses if the specified attribute or item does not exist
nDefaultSize | Amount of binary data (in bytes) that the function accesses if the specified attribute or item does not exist
sBinary | Buffer receiving the binary data
nBinarySize | Size of the buffer that receives the binary data (optional).
nBinaryLen | Variable receiving the actual amount of data (in bytes) that was received (optional).
nOccurrence | Index of the item that is to be retrieved (optional). The index of an attribute’s first item is 1 (not 0). If this parameter is omitted, the attribute’s first item is retrieved. Note: This parameter is ignored if hJolt represents a JoltSessionAttributes object.

Example

var
  hSession, hSessionAttr, hRemoteService: number;

dcltrans
  transaction TInit
  begin
    JavaSetOption(JAVA_VERSION, JAVA_V11);
    JavaSetOption(JAVA_HOME, "c:/jdk1.1.7");
    JavaSetOption(JAVA_CLASSPATH, "c:/jdk1.1.7");
    JoltInit();    hSessionAttr := JoltSessionAttributesNew();
    JoltSetString(hSessionAttr, APPADDRESS, "//lab:8000");
    hSession := JoltSessionNew(hSessionAttr, "", "ATM", "", "");
    hRemoteService := JoltRemoteServiceNew("XOR", hSession);
  end TInit;

  transaction TMain
  var
    sBinary : string;
    nBinaryLen : number;
  begin
    JoltSetCarray(hRemoteService, "PLAIN", "\h45E295AFD03B631200");
    JoltSetCarray(hRemoteService, "PASSWORD", "secret\x00");
    JoltCall(hRemoteService);
    JoltGetCarray(hRemoteService, "CODE", NULL, 0, sBinary);
  end TMain;
  transaction TShutdown
  begin
    JoltEndSession(hSession);
    JoltFreeObject(hRemoteService);
    JoltFreeObject(hSession);
    JoltFreeObject(hSessionAttr);
  end TShutdown;

See also

Java: bea.jolt.JoltSessionAttributes class, bea.jolt.JoltRemoteService class

Parent topic: Object Customization Functions
Related reference
JoltRemoteServiceNew Function
JoltSessionAttributesNew Function
JoltDelete Function
JoltClear Function


JoltGetDouble Function

Action

Retrieves the value of an eight-byte floating-point item (“double” in Java) of a Jolt object attribute. This function is provided to retrieve values from both JoltSessionAttributes and JoltRemoteService object attributes.

Include file

Jolt.bdh

Syntax

JoltGetDouble( in hJolt       : number,
               in sAttribute  : string,
               in fDefault    : float,
               in nOccurrence : number optional): float;

Return value

Value of the specified eight-byte floating-point item of the Jolt object attribute.

Parameter | Description
hJolt | Handle to a JoltSessionAttributes or JoltRemoteService object that was created with JoltSessionAttributesNew or JoltRemoteServiceNew, respectively
sAttribute | Name of the attribute that is to be accessed
fDefault | Floating-point value that the function returns if the specified attribute or item does not exist
nOccurrence | Index of the item that is to be retrieved (optional). The index of an attribute’s first item is 1 (not 0). If this parameter is omitted, the attribute’s first item is retrieved. Note: This parameter is ignored if hJolt represents a JoltSessionAttributes object.

Example

var
  hSession, hSessionAttr, hRemoteService: number;
dcltrans
  transaction TInit
  begin
    JavaSetOption(JAVA_VERSION, JAVA_V11);
    JavaSetOption(JAVA_HOME, "c:/jdk1.1.7");
    JavaSetOption(JAVA_CLASSPATH, "c:/jdk1.1.7");
    JoltInit();     hSessionAttr := JoltSessionAttributesNew();
    JoltSetString(hSessionAttr, APPADDRESS, "//lab:8000");
    hSession := JoltSessionNew(hSessionAttr, "", "ATM", "", "");
    hRemoteService := JoltRemoteServiceNew("SUM", hSession);
  end TInit;

  transaction TMain
  var
    fSum: float;

  begin
    JoltSetDouble(hRemoteService, "DVALUE", 23.7, ADD_VALUE);
    JoltSetDouble(hRemoteService, "DVALUE", 11.91, ADD_VALUE);
    JoltCall(hRemoteService);
    fSum := JoltGetDouble(hRemoteService, "RESULT", 0.0);
    writeln(fSum);
  end TMain;

  transaction TShutdown
  begin
    JoltEndSession(hSession);
    JoltFreeObject(hRemoteService);
    JoltFreeObject(hSession);
    JoltFreeObject(hSessionAttr);
  end TShutdown;

See also

Java: bea.jolt.JoltSessionAttributes class, bea.jolt.JoltRemoteService class

Parent topic: Object Customization Functions
Related reference
JoltRemoteServiceNew Function
JoltSessionAttributesNew Function
JoltDelete Function
JoltClear Function


JoltGetFloat Function

Action

Retrieves the value of a four-byte floating-point item (“float” in Java) of a Jolt object attribute. This function is provided to retrieve values from both JoltSessionAttributes and JoltRemoteService object attributes.

Include file

Jolt.bdh

Syntax

JoltGetFloat( in hJolt       : number,
              in sAttribute  : string,
              in fDefault    : float,
              in nOccurrence : number optional ): float;

Return value

Value of the specified four-byte floating-point item of the Jolt object attribute.

Parameter | Description
hJolt | Handle to a JoltSessionAttributes or JoltRemoteService object that was created with JoltSessionAttributesNew or JoltRemoteServiceNew, respectively
sAttribute | Name of the attribute that is to be accessed
fDefault | Floating-point value that the function returns if the specified attribute or item does not exist
nOccurrence | Index of the item that is to be retrieved (optional). The index of an attribute’s first item is 1 (not 0). If this parameter is omitted, the attribute’s first item is retrieved. Note: This parameter is ignored if hJolt represents a JoltSessionAttributes object.

Example

var
  hSession, hSessionAttr, hRemoteService: number;
 dcltrans  transaction TInit
  begin
    JavaSetOption(JAVA_VERSION, JAVA_V11);
    JavaSetOption(JAVA_HOME, "c:/jdk1.1.7");
    JavaSetOption(JAVA_CLASSPATH, "c:/jdk1.1.7");
    JoltInit();
     hSessionAttr := JoltSessionAttributesNew();
    JoltSetString(hSessionAttr, APPADDRESS, "//lab:8000");
    hSession := JoltSessionNew(hSessionAttr, "", "ATM", "", "");
    hRemoteService := JoltRemoteServiceNew("SUM", hSession);
  end TInit;

  transaction TMain
  var
    fSum: float;
  begin
    JoltSetFloat(hRemoteService, "FVALUE", 23.7, ADD_VALUE);
    JoltSetFloat(hRemoteService, "FVALUE", 11.91, ADD_VALUE);
    JoltCall(hRemoteService);
    fSum := JoltGetFloat(hRemoteService, "RESULT", 0.0);
    writeln(fSum);
  end TMain;
  transaction TShutdown
  begin
    JoltEndSession(hSession);
    JoltFreeObject(hRemoteService);
    JoltFreeObject(hSession);
    JoltFreeObject(hSessionAttr);
  end TShutdown;

See also

Java: bea.jolt.JoltSessionAttributes class, bea.jolt.JoltRemoteService class

Parent topic: Object Customization Functions
Related reference
JoltRemoteServiceNew Function
JoltSessionAttributesNew Function
JoltDelete Function
JoltClear Function


JoltGetInt Function

Action

Retrieves the value of a four-byte item (“int” in Java) of a Jolt object attribute. This function is provided to retrieve values from both JoltSessionAttributes and JoltRemoteService object attributes.

Include file

Jolt.bdh

Syntax

JoltGetInt( in hJolt       : number,
            in sAttribute  : string,
            in nDefault    : number,
            in nOccurrence : number optional ): number;

Return value

Value of the specified four-byte item of the Jolt object attribute.

Parameter | Description
hJolt | Handle to a JoltSessionAttributes or JoltRemoteService object that was created with JoltSessionAttributesNew or JoltRemoteServiceNew, respectively
sAttribute | Name of the attribute that is to be accessed
nDefault | Value that the function returns if the specified attribute or item does not exist
nOccurrence | Index of the item that is to be retrieved (optional). The index of an attribute’s first item is 1 (not 0). If this parameter is omitted, the attribute’s first item is retrieved. Note: This parameter is ignored if hJolt represents a JoltSessionAttributes object.

Example

var
  hSession, hSessionAttr, hRemoteService: number;
 dcltrans
  transaction TInit
  begin
    JavaSetOption(JAVA_VERSION, JAVA_V11);
    JavaSetOption(JAVA_HOME, "c:/jdk1.1.7");
    JavaSetOption(JAVA_CLASSPATH, "c:/jdk1.1.7");
    JoltInit();
    hSessionAttr := JoltSessionAttributesNew();
    JoltSetString(hSessionAttr, APPADDRESS, "//lab:8000");
    hSession := JoltSessionNew(hSessionAttr, "", "ATM", "", "");
    hRemoteService := JoltRemoteServiceNew("SUM", hSession);
  end TInit;

  transaction TMain
  var
    nSum: number;
  begin
    JoltSetInt(hRemoteService, "IVALUE", 23, ADD_VALUE);
    JoltSetInt(hRemoteService, "IVALUE", 11, ADD_VALUE);
    JoltCall(hRemoteService);    nSum := JoltGetInt(hRemoteService, "RESULT", 0);
    writeln(nSum);
  end TMain;

  transaction TShutdown
  begin
    JoltEndSession(hSession);
    JoltFreeObject(hRemoteService);
    JoltFreeObject(hSession);
    JoltFreeObject(hSessionAttr);
  end TShutdown;

See also

Java: bea.jolt.JoltSessionAttributes class, bea.jolt.JoltRemoteService class

Parent topic: Object Customization Functions
Related reference
JoltRemoteServiceNew Function
JoltSessionAttributesNew Function
JoltDelete Function
JoltClear Function


JoltGetShort Function

Action

Retrieves the value of a two-byte item (“short” in Java) of a Jolt object attribute. This function is provided to retrieve values from both JoltSessionAttributes and JoltRemoteService object attributes.

Include file

Jolt.bdh

Syntax

JoltGetShort( in hJolt       : number,
              in sAttribute  : string,
              in nDefault    : number,
              in nOccurrence : number optional ): number;

Return value

Value of the specified two-byte item of the Jolt object attribute.

Parameter | Description
hJolt | Handle to a JoltSessionAttributes or JoltRemoteService object that was created with JoltSessionAttributesNew or JoltRemoteServiceNew, respectively
sAttribute | Name of the attribute that is to be accessed
nDefault | Value that the function returns if the specified attribute or item does not exist
nOccurrence | Index of the item that is to be retrieved (optional). The index of an attribute’s first item is 1 (not 0). If this parameter is omitted, the attribute’s first item is retrieved. Note: This parameter is ignored if hJolt represents a JoltSessionAttributes object.

Example

var
  hSession, hSessionAttr, hRemoteService: number;
 dcltrans
  transaction TInit
  begin
    JavaSetOption(JAVA_VERSION, JAVA_V11);
    JavaSetOption(JAVA_HOME, "c:/jdk1.1.7");
    JavaSetOption(JAVA_CLASSPATH, "c:/jdk1.1.7");
    JoltInit();
     hSessionAttr := JoltSessionAttributesNew();
    JoltSetString(hSessionAttr, APPADDRESS, "//lab:8000");
    hSession := JoltSessionNew(hSessionAttr, "", "ATM", "", "");
    hRemoteService := JoltRemoteServiceNew("SUM", hSession);
  end TInit;
  transaction TMain
  var
    nSum: number;
  begin
    JoltSetShort(hRemoteService, "SVALUE", 23, ADD_VALUE);
    JoltSetShort(hRemoteService, "SVALUE", 11, ADD_VALUE);
    JoltCall(hRemoteService);
    nSum := JoltGetShort(hRemoteService, "RESULT", 0);
  writeln(nSum);
  end TMain;
  transaction TShutdown
  begin
    JoltEndSession(hSession);
    JoltFreeObject(hRemoteService);
    JoltFreeObject(hSession);
    JoltFreeObject(hSessionAttr);
  end TShutdown;

See also

Java: bea.jolt.JoltSessionAttributes class, bea.jolt.JoltRemoteService class

Parent topic: Object Customization Functions
Related reference
JoltRemoteServiceNew Function
JoltSessionAttributesNew Function
JoltDelete Function
JoltClear Function


JoltGetString Function

Action

Retrieves the string from a string item (“java.lang.String” in Java) of a Jolt object attribute. This function is provided to retrieve strings from both JoltSessionAttributes and JoltRemoteService object attributes.

Include file

Jolt.bdh

Syntax

JoltGetString( in  hJolt       : number,
               in  sAttribute  : string,
               in  sDefault    : string,
               out sString     : string,
               in  nStringSize : number optional,
               in  nOccurrence : number optional): boolean;

Return value

  • true if successful

  • false otherwise

Parameter | Description
hJolt | Handle to a JoltSessionAttributes or JoltRemoteService object that was created with JoltSessionAttributesNew or JoltRemoteServiceNew, respectively
sAttribute | Name of the attribute that is to be accessed
sDefault | String that the function returns if the specified attribute or item does not exist
sString | Buffer receiving the string
nStringSize | Size of the buffer that receives the string (optional).
nOccurrence | Index of the item that is to be retrieved (optional). The index of an attribute’s first item is 1 (not 0). If this parameter is omitted, the attribute’s first item is retrieved. Note: This parameter is ignored if hJolt represents a JoltSessionAttributes object.

Example

var
  hSession, hSessionAttr, hRemoteService: number;
 dcltrans
  transaction TInit
  begin
    JavaSetOption(JAVA_VERSION, JAVA_V11);
    JavaSetOption(JAVA_HOME, "c:/jdk1.1.7");
    JavaSetOption(JAVA_CLASSPATH, "c:/jdk1.1.7");
    JoltInit();    hSessionAttr := JoltSessionAttributesNew();
    JoltSetString(hSessionAttr, APPADDRESS, "//lab:8000");
    hSession := JoltSessionNew(hSessionAttr, "", "ATM", "", "");
    hRemoteService := JoltRemoteServiceNew("TOUPPER", hSession);
  end TInit;

  transaction TMain
  var
    sString: string;
  begin
    JoltSetString(hRemoteService, "STRARG", "hello world!");
    JoltCall(hRemoteService);
    JoltGetString(hRemoteService, "RESULT", "", sString);
    writeln(sString);
  end TMain;
  transaction TShutdown
  begin
    JoltEndSession(hSession);
    JoltFreeObject(hRemoteService);
    JoltFreeObject(hSession);
    JoltFreeObject(hSessionAttr);
  end TShutdown;

See also

Java: bea.jolt.JoltSessionAttributes class, bea.jolt.JoltRemoteService class

Parent topic: Object Customization Functions
Related reference
JoltRemoteServiceNew Function
JoltSessionAttributesNew Function
JoltDelete Function
JoltClear Function


JoltClear Function

Action

Clears all input/output data of a Jolt object. This function is provided to clear data of both JoltSessionAttributes and JoltRemoteService objects.

Include file

Jolt.bdh

Syntax

JoltClear( in hJolt: number ): boolean;

Return value

  • true if successful

  • false otherwise

Parameter | Description
hJolt | Handle to a JoltSessionAttributes or JoltRemoteService object that was created with JoltSessionAttributesNew or JoltRemoteServiceNew, respectively

Example

var
  hSession, hSessionAttr, hRemoteService: number;

dcltrans
  transaction TMain
  begin
    JavaSetOption(JAVA_VERSION, JAVA_V11);
    JavaSetOption(JAVA_HOME, "c:/jdk1.1.7");
    JavaSetOption(JAVA_CLASSPATH, "c:/jdk1.1.7");
    JoltInit();    hSessionAttr := JoltSessionAttributesNew();
    JoltSetString(hSessionAttr, APPADDRESS, "//lab:8000");
    hSession := JoltSessionNew(hSessionAttr, "", "ATM", "", "");
    hRemoteService := JoltRemoteServiceNew("SERVICE1", hSession);
    JoltCall(hRemoteService);
    JoltClear(hRemoteService);
     hRemoteService := JoltRemoteServiceNew("SERVICE2", hSession);
    JoltCall(hRemoteService);
    JoltEndSession(hSession);
    JoltFreeObject(hRemoteService);
    JoltFreeObject(hSession);
    JoltFreeObject(hSessionAttr);
  end TMain;

See also

Java: bea.jolt.JoltSessionAttributes class, bea.jolt.JoltRemoteService class

Parent topic: Object Customization Functions
Related reference
JoltRemoteServiceNew Function
JoltSessionAttributesNew Function


JoltDelete Function

Action

Deletes an item of a Jolt object attribute. If an attribute consists of only one item, the complete attribute is deleted. This function is provided to delete items from both JoltSessionAttributes and JoltRemoteService object attributes.

Include file

Jolt.bdh

Syntax

JoltDelete( in hRemoteService : number,
            in sAttribute     : string,
            in nOccurrence    : number optional ): boolean;

Return value

  • true if successful

  • false otherwise

Parameter | Description
hRemoteService | Handle to a JoltRemoteService object that was created with JoltRemoteServiceNew
nAttribute | Name of the attribute that is to be modified
nOccurrence | Index of the item that is to be deleted (optional). The index of an attribute’s first item is 1 (not 0). If this parameter is omitted, the attribute’s first item is deleted

Example

var
  hSession, hSessionAttr, hRemoteService: number;
dcltrans
  transaction TInit
  begin
    JavaSetOption(JAVA_VERSION, JAVA_V11);
    JavaSetOption(JAVA_HOME, "c:/jdk1.1.7");
    JavaSetOption(JAVA_CLASSPATH, "c:/jdk1.1.7");
    JoltInit();
    hSessionAttr := JoltSessionAttributesNew();
    JoltSetString(hSessionAttr, APPADDRESS, "//lab:8000");
    hSession := JoltSessionNew(hSessionAttr, "", "ATM", "", "");
    hRemoteService := JoltRemoteServiceNew("SUM", hSession);
  end TInit;

  transaction TMain
  var
    nSum: number;
  begin
    JoltSetInt(hRemoteService, "IVALUE", 23, ADD_VALUE);
    JoltSetInt(hRemoteService, "IVALUE", 11, ADD_VALUE);
    JoltSetInt(hRemoteService, "IVALUE", 38, ADD_VALUE);
    JoltDelete(hRemoteService, "IVALUE", 2);
    JoltCall(hRemoteService);
    nSum := JoltGetInt(hRemoteService, "RESULT", 0);
    writeln(nSum);
  end TMain;

  transaction TShutdown
  begin
    JoltEndSession(hSession);
    JoltFreeObject(hRemoteService);
    JoltFreeObject(hSession);
    JoltFreeObject(hSessionAttr);
  end TShutdown;

See also

Java: bea.jolt.JoltSessionAttributes class, bea.jolt.JoltRemoteService class

Parent topic: Object Customization Functions
Related reference
JoltRemoteServiceNew Function
JoltSessionAttributesNew Function


Session Handling Functions

  • JoltCheckAuthenticationLevel Function
    Retrieves the authentication level set by the TUXEDO administrator.
  • JoltIsAlive Function
    Checks whether a session is still alive.
  • JoltEndSession Function
    Terminate a specified session and obsoletes the session object.
Parent topic: Jolt Functions Reference


JoltCheckAuthenticationLevel Function

Action

Retrieves the authentication level set by the TUXEDO administrator. The authentication level determines which attributes of the JoltSessionAttributes object must necessarily be set.

Include file

Jolt.bdh

Syntax

JoltCheckAuthenticationLevel( in hSessionAttr: number ): number;

Return value

Authentication level, one of the following:

  • NOAUTH. No authentication

  • APPASSWORD. User name, user role and application password required

  • USRPASSWORD. Like APPASSWORD, in addition the user password is required

Parameter | Description
hSessionAttr | Handle to a JoltSessionAttributes object that was created with JoltSessionAttributesNew

Example

var
  hSessionAttr: number;
 dcltrans
  transaction TInit
  var
    nLevel: number;
  begin
    JavaSetOption(JAVA_VERSION, JAVA_V11);
    JavaSetOption(JAVA_HOME, "c:/jdk1.1.7");
    JavaSetOption(JAVA_CLASSPATH, "c:/jdk1.1.7");
    JoltInit();    hSessionAttr := JoltSessionAttributesNew();
    JoltSetString(hSessionAttr, APPADDRESS, "//lab:8000");

    nLevel := JoltCheckAuthenticationLevel(hSessionAttr);
    if nLevel = NOAUTH then
      writeln("no authentication required");
    elseif nLevel = APPASSWORD then
      writeln("user name, user role and app password required");
    elseif nLevel = USRASSWORD then
      writeln("user name, user password, "
           "user role and app password required");

     end;
  end TInit;

  transaction TShutdown
  begin
    JoltFreeObject(hSessionAttr);
  end TShutdown;

See also

Java: bea.jolt.JoltSessionAttributes class

Parent topic: Session Handling Functions
Related reference
JoltEndSession Function
JoltIsAlive Function
JoltSessionAttributesNew Function


JoltIsAlive Function

Action

Checks whether a session is still alive.

Include file

Jolt.bdh

Syntax

JoltIsAlive( in hSession : number ): boolean;

Return value

  • true if the specified session is still alive

  • false otherwise

Parameter | Description
hSession | Handle to a JoltSession object that was created with JoltSessionNew

Example

var
  hSession, hSessionAttr: number;

dcltrans
  transaction TInit
  begin
    JavaSetOption(JAVA_VERSION, JAVA_V11);
    JavaSetOption(JAVA_HOME, "c:/jdk1.1.7");
    JavaSetOption(JAVA_CLASSPATH, "c:/jdk1.1.7");
    JoltInit();
     hSessionAttr := JoltSessionAttributesNew();
    JoltSetString(hSessionAttr, APPADDRESS, "//lab:8000");
    hSession := JoltSessionNew(hSessionAttr, "", "ATM", "", "");
  end TInit;

  transaction TMain
  begin
    if JoltIsAlive(hSession) then
      ...
    end;
  end TMain;
  transaction TShutdown
  begin
    JoltEndSession(hSession);
    JoltFreeObject(hSession);
    JoltFreeObject(hSessionAttr);
  end TShutdown;

See also

Java: bea.jolt.JoltSession class

Parent topic: Session Handling Functions
Related reference
JoltCheckAuthenticationLevel Function
JoltEndSession Function


JoltEndSession Function

Action

Terminate a specified session and obsoletes the session object.

Include file

Jolt.bdh

Syntax

JoltEndSession( in hSession: number ): boolean;

Return value

  • true if successful

  • false otherwise

Parameter | Description
hSession | Handle to a JoltSession object that was created with JoltSessionNew

Example

var
  hSession, hSessionAttr: number;

dcltrans
  transaction TInit
  begin
    JavaSetOption(JAVA_VERSION, JAVA_V11);
    JavaSetOption(JAVA_HOME, "c:/jdk1.1.7");
    JavaSetOption(JAVA_CLASSPATH, "c:/jdk1.1.7");
    JoltInit();
    hSessionAttr := JoltSessionAttributesNew();
    JoltSetString(hSessionAttr, APPADDRESS,"//lab:8000");
    hSession := JoltSessionNew(hSessionAttr, "", "ATM", "", "");
  end TInit;

  transaction TShutdown
  begin
    JoltEndSession(hSession);
    JoltFreeObject(hSession);
    JoltFreeObject(hSessionAttr);
  end TShutdown;

See also

Java: bea.jolt.JoltSessionAttributes class

Parent topic: Session Handling Functions
Related reference
JoltCheckAuthenticationLevel Function
JoltIsAlive Function


Service Handling Functions

  • JoltCall Function
    Calls a specified service.
  • JoltSetRequestPriority Function
    Sets the request priority service attribute.
  • JoltGetOccurrenceCount Function
    Retrieves the number of occurrences of a specified JoltRemoteService object attribute item.
  • JoltGetName Function
    Retrieves the name of the service.
  • JoltGetApplicationCode Function
    Retrieves the application code (user return code in TUXEDO ATMI)returned by a specified service.
Parent topic: Jolt Functions Reference


JoltCall Function

Action

Calls a specified service.

Include file

Jolt.bdh

Syntax

JoltCall( in hRemoteService : number,
          in hTransaction   : number optional ): boolean;

Return value

  • true if successful

  • false otherwise

Parameter | Description
hRemoteService | Handle to a JoltRemoteService object that was created with JoltRemoteServiceNew
hTransaction | Handle to a JoltTransaction object that was created with JoltTransactionNew (optional). If this parameter is omitted, the specified service is excluded from any transaction.

Example

var
  hSession, hSessionAttr, hInquiry: number;
dcltrans
  transaction TInit
  begin
    JavaSetOption(JAVA_VERSION, JAVA_V11);
    JavaSetOption(JAVA_HOME, "c:/jdk1.1.7");
    JavaSetOption(JAVA_CLASSPATH, "c:/jdk1.1.7");
    JoltInit();    hSessionAttr := JoltSessionAttributesNew();
    JoltSetString(hSessionAttr, APPADDRESS, "//lab:8000");
    hSession := JoltSessionNew(hSessionAttr, "", "ATM", "", "");
    hInquiry := JoltRemoteServiceNew("INQUIRY", hSession);
  end TInit;

  transaction TMain
  var
    sBalance: string;
  begin
    JoltSetInt(hInquiry, "ACCOUNT_ID", 10001);
    JoltCall(hInquiry);
    JoltGetString(hInquiry, "SBALANCE", "", sBalance);
    writeln(sBalance);
  end TMain;

  transaction TShutdown
  begin
    JoltEndSession(hSession);
    JoltFreeObject(hInquiry);
    JoltFreeObject(hSession);
    JoltFreeObject(hSessionAttr);
  end TShutdown;

See also

Java: bea.jolt.JoltRemoteService class

Parent topic: Service Handling Functions


JoltSetRequestPriority Function

Action

Sets the request priority service attribute.

Include file

Jolt.bdh

Syntax

JoltSetRequestPriority( in hRemoteService : number,
                        in nPriority      : number ): boolean;

Return value

  • true if successful

  • false otherwise

Parameter | Description
hRemoteService | Handle to a JoltRemoteService object that was created with JoltRemoteServiceNew
nPriority | Service priority value between 1 and 100 inclusive

Example

var
  hSession, hSessionAttr, hInquiry: number;
 dcltrans
  transaction TInit
  begin
    JavaSetOption(JAVA_VERSION, JAVA_V11);
    JavaSetOption(JAVA_HOME, "c:/jdk1.1.7");
    JavaSetOption(JAVA_CLASSPATH, "c:/jdk1.1.7");
    JoltInit();    hSessionAttr := JoltSessionAttributesNew();
    JoltSetString(hSessionAttr, APPADDRESS, "//lab:8000");
    hSession := JoltSessionNew(hSessionAttr, "", "ATM", "", "");
    hInquiry := JoltRemoteServiceNew("INQUIRY", hSession);
  end TInit;

  transaction TMain
  var
    sBalance: string;
  begin
    JoltSetRequestPriority(hInquiry, 1);
    JoltSetInt(hInquiry, "ACCOUNT_ID", 10001);
    JoltCall(hInquiry);
    JoltGetString(hInquiry, "SBALANCE", "", sBalance);
  end TMain;

  transaction TShutdown
  begin
    JoltEndSession(hSession);
    JoltFreeObject(hInquiry);
    JoltFreeObject(hSession);
    JoltFreeObject(hSessionAttr);
  end TShutdown;

See also

Java: bea.jolt.JoltRemoteService class

Parent topic: Service Handling Functions


JoltGetOccurrenceCount Function

Action

Retrieves the number of occurrences of a specified JoltRemoteService object attribute item.

Include file

Jolt.bdh

Syntax

JoltGetOccurrenceCount( in hRemoteService : number,
                        in sAttribute     : string ): number;

Return value

Number of occurrences of the specified JoltRemoteService object attribute item.

Parameter | Description
hRemoteService | Handle to a JoltRemoteService object that was created with JoltRemoteServiceNew
sAttribute | Name of the attribute item

Example

var
  hSession, hSessionAttr, hRemoteService: number;
dcltrans
  transaction TInit
  begin
    JavaSetOption(JAVA_VERSION, JAVA_V11);
    JavaSetOption(JAVA_HOME, "c:/jdk1.1.7");
    JavaSetOption(JAVA_CLASSPATH, "c:/jdk1.1.7");
    JoltInit();
    hSessionAttr := JoltSessionAttributesNew();
    JoltSetString(hSessionAttr, APPADDRESS, "//lab:8000");
    hSession := JoltSessionNew(hSessionAttr, "", "ATM", "", "");
    hRemoteService := JoltRemoteServiceNew("SUM", hSession);
  end TInit;
    transaction TMain
  var
    nSum: number;
  begin
    JoltSetInt(hRemoteService, "IVALUE", 23, ADD_VALUE);
    JoltSetInt(hRemoteService, "IVALUE", 11, ADD_VALUE);
    JoltSetInt(hRemoteService, "IVALUE", 38, ADD_VALUE);
    write(JoltGetOccurrenceCount(hRemoteService, "IVALUE"));
    JoltCall(hRemoteService);
    nSum := JoltGetInt(hRemoteService, "RESULT", 0);
    writeln(nSum);
  end TMain;

  transaction TShutdown
  begin
    JoltEndSession(hSession);
    JoltFreeObject(hRemoteService);
    JoltFreeObject(hSession);
    JoltFreeObject(hSessionAttr);
  end TShutdown;

See also

Java: bea.jolt.JoltRemoteService class

Parent topic: Service Handling Functions


JoltGetName Function

Action

Retrieves the name of the service.

Include file

Jolt.bdh

Syntax

JoltGetName( in  hRemoteService : number,
             out sName          : string,
             in  nNameSize      : number optional ): boolean;

Return value

  • true if successful

  • false otherwise

Parameter | Description
hRemoteService | Handle to a JoltRemoteService object that was created with JoltRemoteServiceNew
sName | String variable receiving the service name
nNameSize | Size of the string variable that receives the service name (optional).

Example

var
  hSession, hSessionAttr, hInquiry: number;
 dcltrans
  transaction TInit
  var
    sName: string;
  begin
    JavaSetOption(JAVA_VERSION, JAVA_V11);
    JavaSetOption(JAVA_HOME, "c:/jdk1.1.7");
    JavaSetOption(JAVA_CLASSPATH, "c:/jdk1.1.7");
    JoltInit();
    hSessionAttr := JoltSessionAttributesNew();
    JoltSetString(hSessionAttr, APPADDRESS, "//lab:8000");
    hSession := JoltSessionNew(hSessionAttr, "", "ATM", "", "");
    hInquiry := JoltRemoteServiceNew("INQUIRY", hSession);
    JoltGetName(hInquiry, sName);
    writeln(sName);
  end TInit;

  transaction TShutdown
  begin    JoltEndSession(hSession);
    JoltFreeObject(hInquiry);
    JoltFreeObject(hSession);
    JoltFreeObject(hSessionAttr);
  end TShutdown;

See also

Java: bea.jolt.JoltRemoteService class

Parent topic: Service Handling Functions
Related reference
JoltRemoteServiceNew Function
JoltSessionAttributesNew Function
JoltDelete Function
JoltClear Function


JoltGetApplicationCode Function

Action

Retrieves the application code (user return code in TUXEDO ATMI)returned by a specified service.

Include file

Jolt.bdh

Syntax

JoltGetApplicationCode( in hRemoteService : number ): number;

Return value

Application code that was returned by the specified service.

Parameter | Description
hRemoteService | Handle to a JoltRemoteService object that was created with JoltRemoteServiceNew

Example

var
  hSession, hSessionAttr, hInquiry: number;
 dcltrans
  transaction TInit
  begin
    JavaSetOption(JAVA_VERSION, JAVA_V11);
    JavaSetOption(JAVA_HOME, "c:/jdk1.1.7");
    JavaSetOption(JAVA_CLASSPATH, "c:/jdk1.1.7");
    JoltInit();

    hSessionAttr := JoltSessionAttributesNew();
    JoltSetString(hSessionAttr, APPADDRESS, "//lab:8000");
    hSession := JoltSessionNew(hSessionAttr, "", "ATM", "", "");
    hInquiry := JoltRemoteServiceNew("INQUIRY", hSession);
  end TInit;

  transaction TMain
  begin
    JoltSetInt(hInquiry, "ACCOUNT_ID", 10001);
    JoltCall(hInquiry);
    writeln(JoltGetApplicationCode(hInquiry));
  end TMain;

  transaction TShutdown
  begin
    JoltEndSession(hSession);
    JoltFreeObject(hInquiry);
    JoltFreeObject(hSession);
    JoltFreeObject(hSessionAttr);
  end TShutdown;

See also

Java: bea.jolt.JoltRemoteService class

Parent topic: Service Handling Functions


Transaction Handling Functions

  • JoltCommit Function
    Performs the transaction commit for a JoltTransaction object.
  • JoltRollback Function
    Performs the transaction rollback for a JoltTransaction object.
Parent topic: Jolt Functions Reference


JoltCommit Function

Action

Performs the transaction commit for a JoltTransaction object.

Include file

Jolt.bdh

Syntax

JoltCommit( in hTransaction: number ):boolean;

Return value

  • true if successful

  • false otherwise

Parameter | Description
hTransaction | Handle to a JoltTransaction object that was created with JoltTransactionNew

Example

var
  hSession, hSessionAttr, hTransaction: number;

dcltrans
  transaction TInit
  begin
    JavaSetOption(JAVA_VERSION, JAVA_V11);
    JavaSetOption(JAVA_HOME, "c:/jdk1.1.7");
    JavaSetOption(JAVA_CLASSPATH, "c:/jdk1.1.7");
    JoltInit();     hSessionAttr := JoltSessionAttributesNew();
    JoltSetString(hSessionAttr, APPADDRESS, "//lab:8000");
    hSession := JoltSessionNew(hSessionAttr, "", "ATM", "", "");
  end TInit;

  transaction TMain
  begin
    hTransaction := JoltTransactionNew(0, hSession);
    ...
    JoltCommit(hTransaction);
  end TMain;

  transaction TShutdown
  begin
    JoltEndSession(hSession);
    JoltFreeObject(hTransaction);
    JoltFreeObject(hSession);
    JoltFreeObject(hSessionAttr);
  end TShutdown;

See also

Java: bea.jolt.JoltTransaction class

Parent topic: Transaction Handling Functions
Related reference
JoltRollback Function
JoltTransactionNew Function


JoltRollback Function

Action

Performs the transaction rollback for a JoltTransaction object.

Include file

Jolt.bdh

Syntax

JoltRollback( in hTransaction : number ):boolean;

Return value

  • true if successful

  • false otherwise

Parameter | Description
hTransaction | Handle to a JoltTransaction object that was created with JoltTransactionNew

Example

var
  hSession, hSessionAttr, hTransaction: number;
 dcltrans
  transaction TInit
  begin
     JavaSetOption(JAVA_VERSION, JAVA_V11);
     JavaSetOption(JAVA_HOME, "c:/jdk1.1.7");
     JavaSetOption(JAVA_CLASSPATH, "c:/jdk1.1.7");
     JoltInit();
     hSessionAttr := JoltSessionAttributesNew();
    JoltSetString(hSessionAttr, APPADDRESS, "//lab:8000");
    hSession := JoltSessionNew(hSessionAttr, "", "ATM", "", "");
  end TInit;
  transaction TMain
  begin
    hTransaction := JoltTransactionNew(0, hSession);
    ...
    JoltRollback(hTransaction);
  end TMain;

  transaction TShutdown
  begin
    JoltEndSession(hSession);
    JoltFreeObject(hTransaction);
    JoltFreeObject(hSession);
    JoltFreeObject(hSessionAttr);
  end TShutdown;

See also

Java: bea.jolt.JoltTransaction class

Parent topic: Transaction Handling Functions
Related reference
JoltCommit Function
JoltTransactionNew Function


Event Handling Functions

  • JoltUnsubscribe Function
    Deletes the subscription to an event.
  • JoltUnsubscribeAll Function
    Unsubscribes all event subscriptions in a specified session.
Parent topic: Jolt Functions Reference


JoltUnsubscribe Function

Action

Deletes the subscription to an event.

Include file

Jolt.bdh

Syntax

JoltUnsubscribe( in hUserEvent : number ):number;

Return value

Number of subscriptions deleted.

Parameter | Description
hUserEvent | Handle to a JoltUserEvent object that was created with JoltUserEventNew

Example

var
  hSession, hSessionAttr, hUserEvent: number;

dcltrans
  transaction TInit
  begin
    JavaSetOption(JAVA_VERSION, JAVA_V11);
    JavaSetOption(JAVA_HOME, "c:/jdk1.1.7");
    JavaSetOption(JAVA_CLASSPATH, "c:/jdk1.1.7");
    JoltInit();

    hSessionAttr := JoltSessionAttributesNew();
    JoltSetString(hSessionAttr, APPADDRESS, "//lab:8000");
    hSession := JoltSessionNew(hSessionAttr, "", "ATM", "", "");
    hUserEvent := JoltUserEventNew("*", NULL, hSession);
  end TInit;

  transaction TShutdown
  begin
    JoltUnsubscribe(hUserEvent);
    JoltEndSession(hSession);
    JoltFreeObject(hUserEvent);
    JoltFreeObject(hSession);
    JoltFreeObject(hSessionAttr);
  end TShutdown;

See also

Java: bea.jolt.JoltUserEvent class

Parent topic: Event Handling Functions
Related reference
JoltUnsubscribeAll Function
JoltUserEventNew Function


JoltUnsubscribeAll Function

Action

Unsubscribes all event subscriptions in a specified session.

Include file

Jolt.bdh

Syntax

JoltUnsubscribeAll( in hSession : number ): number;

Return value

Number of subscriptions deleted.

Parameter | Description
hSession | Handle to a JoltSession object that was created with JoltSessionNew

Example

var
  hSession, hSessionAttr, hUserEvent: number;

dcltrans
  transaction TInit
  begin
    JavaSetOption(JAVA_VERSION, JAVA_V11);
    JavaSetOption(JAVA_HOME, "c:/jdk1.1.7");
    JavaSetOption(JAVA_CLASSPATH, "c:/jdk1.1.7");
    JoltInit();

    hSessionAttr := JoltSessionAttributesNew();
    JoltSetString(hSessionAttr, APPADDRESS, "//lab:8000");
    hSession := JoltSessionNew(hSessionAttr, "", "ATM", "", "");
    hUserEvent := JoltUserEventNew("*", NULL, hSession);
  end TInit;

  transaction TShutdown
  begin
    JoltUnsubscribeAll(hSession);
    JoltEndSession(hSession);
    JoltFreeObject(hUserEvent);
    JoltFreeObject(hSession);
    JoltFreeObject(hSessionAttr);
  end TShutdown;

See also

Java: bea.jolt.JoltUserEvent class

Parent topic: Event Handling Functions
Related reference
JoltUnsubscribe Function


Oracle Forms Functions Reference

Silk Performer introduces support for Oracle Web Forms applications (Oracle Forms 6i, 9i, 10g, 11g, 12c). Oracle finance and ERP applications that are based on Oracle Forms 6i, 9i, 10g, 11g, 12c can be tested with Silk Performer.

  • Testing Oracle Forms Applications
    Provides an overview of how to test Oracle Forms applications.
  • Oracle Forms Properties
    Describes what Oracle Forms Properties are and how to access them.
  • Oracle Forms SSO (Single Sign On)
    Explains Oracle9iAS Single Sign-On, built around the Single Sign-On Server, which enables users to log in to multiple Web-based applications using a single username and password.
  • Oracle Forms Memory Usage
    Explains the memory usage of VUsers simulating Oracle Forms applications.
  • Connecting Functions
    Lists BDL functions for handling the connection between an Oracle Forms client and an Oracle Forms Server.
  • Control Functions
    Lists BDL functions for handling Oracle Forms UI controls.
  • Properties Functions
    Lists BDL functions to add, modify, and retrieve properties in Oracle Forms applications.
  • Parsing Functions
    Lists BDL functions for parsing properties of Oracle Forms UI controls.
  • Verifying Functions
    Lists BDL functions that allow you to verify control values and certain control properties.
  • Synchronization Functions
    Lists BDL functions for synchronizing your test script with the behavior of the Oracle Forms application under test.
Parent topic: Application Server Functions
Related concepts
Java Settings


Testing Oracle Forms Applications

Oracle Web Forms allows you to run Oracle Forms applications in a Java applet that runs in a browser. The applet displays the user interface and interacts with the server. Complete business logic and database access is executed on the Oracle Forms server. A special protocol that is used for communication between the server and client protocol allows the server to define how the user interface is displayed in the applet. The client uses this protocol to inform the server about user interactions such as key and mouse input.

Because of a technological shift between Oracle Web Forms versions that require alternate record/replay approaches, Silk Performer offers the following project types:

  • Oracle Forms 6i, 9i, 10g, 11g, 12c
  • Oracle EBS 11i, 12.x
  • Oracle Fusion 10g, 11g, 12c

See the Oracle Forms Tutorial for a complete walkthrough of the process of testing Oracle Forms applications.

Recording

When you create a new project based on one of the new project types, an additional recording profile is configured for your web browser. Recording profile settings are configured automatically for the version of Oracle Forms that you are recording.

Prerequisites

To record an Oracle Forms application you need to verify that you have downloaded all client-side software that’s required to run the Oracle Forms applet on your system. Typically all required software is downloaded automatically when you access an Oracle Forms application for the first time. Oracle uses a browser plug-in called Java Runtime Environment (JRE) to host the Java applet. Please verify that the Oracle Forms application under test is running in your browser before you begin recording.
Note: Some older Oracle Forms versions use the "JInitiator" plugin instead of a JRE.

Silk Performer’s recording approach requires a Java runtime. You must therefore configure a Java runtime for your Silk Performer project. The Java settings of your active profile will be used for recording.

Note that you must configure the base directory of your JDK and that a newer JDK will increase record and replay speed.

If you are recording on Oracle Forms 6i you must disable the Java JIT (Just-In-Time Compiler). There are several ways of accomplishing this:

  • Define "-Djava.compiler=NONE" in the Java runtime settings of the JInitiator properties

  • Define an environment variable: SET JAVA_COMPILER=NONE

  • Use the check box to disable the jitter in the JInitiator properties (only available since version 1.1.8.x)

If your Oracle Forms application uses a socket connection between the client and the server you must disable TCP/IP recording on the communication port. This is done via SOCKS proxy settings on the System Settings dialog.

Record the application

Begin recording by clicking the "Model Script" workflow button. Select the "Oracle Forms" recording profile in the following dialog. Enter the application's URL and begin recording.

Replaying

Recorded scripts can be replayed immediately. You can run a TryScript and use TrueLog Explorer’s enhanced feature for customizing Oracle Forms scripts. With TrueLog Explorer you can add verifications, parse values, and customize input data.

TrueLog Explorer

TrueLog Explorer shows each newly activated window as a new top-level node in a TrueLog. All actions that are performed on a window are displayed as sub nodes. When you click on a node you see all controls on the window and the state of the controls at the point of the selected action. This makes it easy for you to track the actions that transpire during replay, seeing exactly which values are changed by which actions. TrueLogs not only show you which values are changed by the client, they show you which values are changed by the server (e.g., controls may change when a button is clicked).

Parent topic: Oracle Forms Functions Reference


Oracle Forms Properties

What Are Properties?

Controls on an Oracle Forms Form Window have several internal properties that can be defined, for example current value, cursor position, editablilty, and visibility. Each property has a unique ID that is used internally to identify a certain property. Each possible property is defined as a constant in OraForms.bdh. The following is a short list of commonly used properties:
  • ORA_PID_VALUE
  • ORA_PID_TITLE
  • ORA_PID_PARENT
  • ...

The properties are set by the server or are modified by actions that the client performs on the controls, for example the ORA_PID_VALUE property will be changed to the next value of a text control if the user alters the control's content.

How To Access Properties

You can access the property values of each control in your application. There are several OraFormsGetProp{Type} functions that allow you to retrieve the values of certain properties that are identified by their unique ID's.

It is not possible to change properties in a direct way. Properties are changed via various API functions that allow you to interact with controls as a user would in a user interface.

Parent topic: Oracle Forms Functions Reference


Oracle Forms SSO (Single Sign On)

Overview

Oracle9iAS Single Sign-On is built around the Single Sign-On Server, which enables users to log in to multiple Web-based applications using a single username and password.

To enable replay of scripts that test SSO enabled Oracle Forms applications, some customization steps are required to ensure use of the correct user ID’s for the Oracle Forms applications that are returned by logon procedures.

Customization

After you record an Oracle Forms script and run a TryScript you will probably encounter an error situation due to the recorded script containing the user ID that was used during recording. The user ID that is used during recording is passed as part of the first parameter to the OraFormsConnect method. The following code shows an OraFormsConnect function after recording:

OraFormsConnect(
  "server module=mymodule.fmx userid=1234567890   sso_userid= record= names",
  "http://myserver:7779/forms90/l90servlet?ifcfs=/forms90/f90servlet?config= myapp",
  "http://myserver:7779/forms90/");

The user ID in the recorded OraFormsConnect is "1234567890" but this ID will probably change each time the user logs on to the system. To customize this value the following steps are required:

  • Open the TryScript TrueLog

  • Click the "Analyze Test" button on the Workflow Bar and choose "Compare your test run" so that the recorded TrueLog will open in compare mode

  • Browse to the HTML page that contains the <OBJECT> tag that instantiates the Oracle Forms applet. You will find this page just before the OraFormsConnect node.

  • Select the Response tab

  • You will see the difference between the recorded and replayed log files

  • Select the difference for the user ID value and parse this value into a variable. Select the "Parse Selected Text into a variable" command from the context menu

  • Specify a name for the variable

  • Return to Silk Performer and replace the recorded user ID value with the parsed variable

After customization your script should resemble the following:

dclparam
  sUserId : string;
...
WebParseDataBoundEx(sUserId, STRING_COMPLETE, "userid=", 4, "\"",
WEB_FLAG_IGNORE_WHITE_SPACE | WEB_FLAG_CASE_SENSITIVE, 1);
WebPageSubmit("Logon", WSSO_LOGINSERVLET001);
Print("sUserId: " + sUserId);
...
OraFormsConnect(
  "server module=mymodule.fmx userid=" + sUserId + " sso_userid= record=names",
  "http://myserver:7779/forms90/l90servlet?ifcfs=/forms90/f90servlet?config=myapp",
  "http://myserver:7779/forms90/");

There may be other parameters that differ between record and replay. If you find such parameter values as constant strings contained in any of the Oracle Forms API functions, customize them in the same way that you customized the user ID.

Silk Performer's Oracle Forms Recorder will be enhanced in future versions to automate this customization process.

Parent topic: Oracle Forms Functions Reference


Connecting Functions

  • OraFormsConnect Function
    Establishes a connection between an Oracle Forms client and an Oracle Forms Server.
  • OraFormsDestroy Function
    Shuts down the Oracle Forms replay engine.
  • OraFormsDisconnect Function
    Closes the connection between server and client.
  • OraFormsFree Function
    This function frees resources or handles created by other OraForms functions such as OraFormsCreateMessage.
  • OraFormsGetTimeout Function
    Returns the value of the connection timeout.
  • OraFormsSetTimeout Function
    Sets the timeout for connections to the Oracle Forms server.
  • OraFormsSetHost Function
    Specifies the host that is to be connected by the replay engine.
  • OraFormsInit Function
    Initializes the Oracle Forms replay engine.
  • OraFormsIsConnected Function
    Returns “true” if the user is connected to the Oracle Forms Runtime on the Oracle Forms server.
  • OraFormsSetConnectMode Function
    Sets the type of connection that should be used during replay.
  • OraFormsSetLocalIpAddress Function
    Specifies the client IP address that is to be used by the virtual user.
  • OraFormsSetPort Function
    Specifies the port that is to be connected by the replay engine.
  • OraFormsSetServlet Function
    Specifies the servlet that is to be connected by the replay engine.
  • OraFormsHandlePendingOnExit Function
    May be used for Oracle Forms 10g services.
Parent topic: Oracle Forms Functions Reference


OraFormsConnect Function

Action

Establishes a connection between an Oracle Forms client and an Oracle Forms Server.

Include file

OraForms.bdh

Syntax

OraFormsConnect( in ssInitialCommandLine : string,
                 in  sServerUrl          : string optional,
                 in sDocumentBase        : string optional ): boolean;

Return Value

  • true if successful
  • false otherwise
Parameter | Description
sInitialCommandLine | The module that will be called by the client.
sServerUrl | (optional) allows to pass the complete ServerURL parameter that is used to initialize the Oracle Forms Applet. This parameter should be defined for Oracle Forms 9i and Oracle Forms 6i >= PatchSet4.
sDocumentBase | (optional) allows to pass the document base of the Oracle Forms Applet. This parameter should be defined for Oracle Forms 9i and Oracle Forms 6i >= PatchSet4.

Example

dcltrans
  transaction TMain
  begin
    OraFormsSetBoolean ("WINSYS_REQUIREDVA_LIST", false);
    OraFormsSetString ("DEFAULT_LOCAL_TZ", "Europe/Berlin");
    OraFormsConnect ("server module=javamail90.fmx usesdi=yes userid= "
                     "sso_userid= temp_dir=C:\\orant\\forms90\\demos\\temp");
  end TMain;
Parent topic: Connecting Functions


OraFormsDestroy Function

Action

Shuts down the Oracle Forms replay engine. This function may only be called in the TShutdown transaction.

Include

OraFroms.bdh

Syntax

OraFormsDestroy( ) : boolean;

Return value

  • true if successful
  • false otherwise

Example

dcltrans
  transaction TInit
  begin
    WebSetBrowser(WEB_BROWSER_MSIE6);
    WebModifyHttpHeader ("Accept-Language", "en,de-at;q=0.5);
    OraFormsInit ("http://vangelis:8888/forms90demo/190servlet", "vangelis", 9000, ORA_FORMS_9I);
  end TInit;

  transaction TShutdown
  begin
    OraFormsDestroy();
  end TShutdown;
Parent topic: Connecting Functions


OraFormsDisconnect Function

Action

Closes the connection between server and client. This is done automatically when a transaction exits due to an error.

Note: You must call this method to disconnect from the server. Otherwise the Oracle Forms Runtime on the server will continue running.

Include file

.bdh

Syntax

OraFormsDisconnect(
    ParamType ParamName : ParamValueType,): boolean;

Return value

  • true if successful

  • false otherwise

Parameter | Description
hObject | Handle to a .NET Object
nReturn | Integer variable that will receive the return value of the last DotNetCallMethod call

Example

dcltrans
  transaction TMain
  begin
    ...
    OraFormsConnect ( "server module=javamail90.fmx usesdi=yes userid= "
                      "sso_userid= temp_dir=C:\\orant\\forms90\\demos\\temp",
                      "http://myserver:8888/forms90demo/l90servlet?ifcfs=/forms90demo/f90servlet?config=iorg",
                      "http://myserver:8888/forms90demo/"):
    ...

   OraFormsDisconnect();
  end TMain;
Parent topic: Connecting Functions


OraFormsFree Function

Action

This function frees resources or handles created by other OraForms functions such as OraFormsCreateMessage.

Include file

OraForms.bdh

Syntax

OraFormsFree( in nMsg : number );
Parameter | Description
nMsg | The handle to a message

Example

  transaction TMain
  var
    nFlexId : number;
    gnUmsg  : number;
    subMsg  : number;
  begin
    OraFormsSetConnectMode(ORA_HTTP_CONNECTION);
    // Connect - with connection properties
    OraFormsSetInt("INITIAL_VERSION", 608);
    OraFormsSetPoint("INITIAL_RESOLUTION", 96, 96);
    OraFormsSetPoint("INITIAL_DISP_SIZE", 1024, 768);
    OraFormsSetInt("INITIAL_COLOR_DEPTH", 256);
    OraFormsSetString("FONT_NAME", "Dialog");
    OraFormsSetPoint("INITIAL_SCALE_INFO", 8, 18);
    OraFormsSetBoolean("WINSYS_REQUIREDVA_LIST", false);
    OraFormsConnect("server module=Person3.fmx userid= useSDI=yes record=names");
    // New window activated: Logon
    OraFormsSetWindow("Logon");
    OraFormsLogon("user", "password", "orcl_server");

    OraFormsBeginMessageBlock("Block#2");
    gnUmsg := OraFormsCreateMessage(20, 40, ORA_MSG_TYPE_UPDATE);
    subMsg := OraFormsCreateMessage(30, 40, ORA_MSG_TYPE_UPDATE);
    OraFormsAddPropertyMessage(gnUmsg, ORA_PID_BP_FOREFILLCOL, subMsg);
    OraFormsAddPropertyInt(gnUmsg, 2601, 91);
    OraFormsAddPropertyInt(gnUmsg, 2600, 0);
    OraFormsAddPropertyBoolean(gnUmsg, 2600, false);
    OraFormsAddPropertyPoint(gnUmsg, ORA_PID_INITIAL_RESOLUTION, 0, 0);
    OraFormsAddPropertyString(gnUmsg, 2600, "E");
    OraFormsPutMessage(gnUmsg);
    OraFormsPutTerminalAndWait();
    OraFormsFree(gnUmsg);
    OraFormsEndMessageBlock("Block#2")

  end TMain;
Parent topic: Connecting Functions


OraFormsGetTimeout Function

Action

OraFormsGetTimeout returns the value of the connection timeout.

Include file

OraForms.bdh

Syntax

OraFormsGetTimeout( ): number;

Return value

  • The configured timeout

Example

dcltrans
  transaction TMain
  var
    sValue   : string;
    nTimeout : number;
  begin
    OraFormsSetConnectMode(ORA_SOCKET_CONNECTION);
    // Connect - with connection properties
    OraFormsSetInt("INITIAL_VERSION", 608);
    OraFormsSetPoint("INITIAL_RESOLUTION", 96, 96);
    OraFormsSetPoint("INITIAL_DISP_SIZE", 1024, 768);
    OraFormsSetInt("INITIAL_COLOR_DEPTH", 256);
    OraFormsSetString("FONT_NAME", "Dialog");
    OraFormsSetPoint("INITIAL_SCALE_INFO", 8, 18);
    OraFormsSetBoolean("WINSYS_REQUIREDVA_LIST", false);
    OraFormsConnect("server module=Person3.fmx userid= useSDI=yes record=names");
    OraFormsSetWindow("Logon");
    OraFormsLogon("user", "password", "orcl_server");
    // ---
    // New window activated: WINDOW1
    OraFormsSetWindow("WINDOW1");
    nTimeout := OraFormsGetTimeout();
  end TMain;
Parent topic: Connecting Functions


OraFormsSetTimeout Function

Action

OraFormsSetTimeout sets the timeout for connections to the Oracle Forms server.

Include file

OraForms.bdh

Syntax

OraFormsSetTimeout( in nTimeout : number );
Parameter | Description
nTimeout | The connection timeout, set in ms.

Example

dcltrans
  transaction TMain
  var
    sValue   : string;
  begin
    OraFormsSetConnectMode(ORA_SOCKET_CONNECTION);
    // Connect - with connection properties
    OraFormsSetInt("INITIAL_VERSION", 608);
    OraFormsSetPoint("INITIAL_RESOLUTION", 96, 96);
    OraFormsSetPoint("INITIAL_DISP_SIZE", 1024, 768);
    OraFormsSetInt("INITIAL_COLOR_DEPTH", 256);
    OraFormsSetString("FONT_NAME", "Dialog");
    OraFormsSetPoint("INITIAL_SCALE_INFO", 8, 18);
    OraFormsSetBoolean("WINSYS_REQUIREDVA_LIST", false);
    OraFormsSetTimeout(300000);
    OraFormsConnect("server
module=Person3.fmx userid= useSDI=yes record=names");
    OraFormsSetWindow("Logon");
    OraFormsLogon("user",
"password", "orcl_server");
    // ---
    // New window activated: WINDOW1
    OraFormsSetWindow("WINDOW1");
  end TMain;

Parent topic: Connecting Functions


OraFormsSetHost Function

Action

OraFormsSetHost specifies the host that is to be connected by the replay engine. During replay the Oracle Forms server may advise the client to connect to a specific server for load balancing. Call this function just before OraFormsConnect to specify the host that is to be connected. This function overrides the second parameter specified in OraFormsInit.

Include file

OraForms.bdh

Syntax

OraFormsSetHost( in sHost : string );
Parameter | Description
sHost | The host to be connected by the replay engine.

Example

dcltrans
  transaction TMain
  var
    sValue   : string;
  begin
    OraFormsSetConnectMode(ORA_SOCKET_CONNECTION);
    // Connect - with connection properties
    OraFormsSetInt("INITIAL_VERSION", 608);
    OraFormsSetPoint("INITIAL_RESOLUTION", 96, 96);
    OraFormsSetPoint("INITIAL_DISP_SIZE", 1024, 768);
    OraFormsSetInt("INITIAL_COLOR_DEPTH", 256);
    OraFormsSetString("FONT_NAME", "Dialog");
    OraFormsSetPoint("INITIAL_SCALE_INFO", 8, 18);
    OraFormsSetBoolean("WINSYS_REQUIREDVA_LIST", false);
    OraFormsSetHost("host");
    OraFormsSetPort(9000);
    OraFormsConnect("server module=Person3.fmx userid= useSDI=yes record=names");
    OraFormsSetWindow("Logon");
    OraFormsLogon("user", "password", "orcl_server");
    // ---
    // New window activated: WINDOW1
    OraFormsSetWindow("WINDOW1");
  end TMain;
Parent topic: Connecting Functions


OraFormsInit Function

Action

Initializes the Oracle Forms replay engine. This function must be called prior to any other Oracle Forms function. Oracle Forms clients may directly communicate with an Oracle Forms server or they may communicate via an HTTP server that forwards requests to an Oracle Forms server. This function is used to specify how communication is to work.

Include file

OraForms.bdh

Syntax

OraFormsInit( in sServlet : string allownull,
              in sHost    : string optional,
              in nPort    : number optional,
              in nVersion : number optional ): boolean;

Return value

  • true if successful
  • false otherwise
Parameter | Description
sServlet | The servlet URL, if the client connects to the Oracle Forms server via a servlet. Otherwise NULL.
sHost | The Oracle Forms server, if communication between client and server is done directly by leaving the HTTP server. This value is ignored if the first parameter is not NULL.
nPort | The port where the Oracle Forms server is listening for client requests. Usually 9000.
nVersion
  • ORA_FORMS_6I
  • ORA_FORMS_9I
  • ORA_FORMS_10G
  • ORA_FORMS_11G
  • ORA_APPS_11I
  • ORA_APPS_12I

Example

dcltrans
  transaction TInit
  begin
    WebSetBrowser(WEB_BROWSER_MSIE6);
    WebModifyHttpHeader("Accept-Language", "en,de-at;q=0.5);
    OraFormsInit("http://vangelis:8888/forms90demo/l90servlet", "vangelis", 9000, ORA_FORMS_9I);
  end TInit;

  transaction TShutdown
  begin
    OraFormsDestroy();
  end TShutdown;
Parent topic: Connecting Functions


OraFormsIsConnected Function

Action

Returns “true” if the user is connected to the Oracle Forms Runtime on the Oracle Forms server.

This function can be used to implement a function that ensures an established connection at the start of a new transaction. When a transaction is aborted, the connection to the server is terminated. To continue in a subsequent iteration of the same main transaction, a new connection must be established.

Include file

OraForms.bdh

Syntax

OraFormsIsConnected( ): boolean;

Return value

  • true if successful

  • false otherwise

Example

dclfunc
function DoConnect
begin
    if(not OraFormsIsConnected()) then
      OraFormsSetBoolean("WINSYS_REQUIREDVA_LIST", false);
      OraFormsSetString("DEFAULT_LOCAL_TZ", "Europe/Berlin");
      ...
      OraFormsConnect("server module=javamail90.fmx usesdi=yes userid= "
                      "sso_userid=  temp_dir=C:\\orant\\forms90\\demos\\temp",
                      "http://myserver:8888/forms90demo/l90servlet?ifcfs=/forms90demo/f90servlet?config=iorg",
                      "http://myserver:8888/forms90demo/");
      OraFormsGetSessionId(gsSSessionID);

      WebCookieSet(gsSSessionID, "http://myserver:8888/forms90demo/java/");

    end;
  end DoConnect;

dcltrans
  transaction TAddAppointment
  begin
    DoConnect();

    ...
  end TAddAppointment;

  transaction TAddToDo
  begin
    DoConnect();

     ...
  end TAddToDo;
Parent topic: Connecting Functions


OraFormsSetConnectMode Function

Action

Sets the type of connection that should be used during replay. Oracle Forms clients may communicate with servers using socket connections, HTTP connections or HTTPS connections. This function overrides a profile's connection setting.

Include file

OraForms.bdh

Syntax

OraFormsSetConnectMode ( in nMode :  number ) : boolean;

Return Value

  • true if successful
  • false otherwise
Parameter | Description
nMode | Can be one of the following values:
 | ORA_SOCKET_CONNECTION
 | ORA_HTTP_CONNECTION
 | ORA_HTTPS_CONNECTION

Example

 dcltrans
   transaction TMain
 begin
   OraFormsSetConnectMode (ORA_HTTP_CONNECTION);
   OraFormsConnect(
      "server module=fileuploader90.fmx usesdi=yes userid=oe8/oe8@ORCL_sunserver  sso_userid="
      "debug=no buffer_records=no debug"
       "_messages=no array=no query_only=no quiet=no render=no host= port= tracegroup= log=testlog.log"
      "term= record=names");

  end TMain;
Parent topic: Connecting Functions


OraFormsSetLocalIpAddress Function

Action

OraFormsSetLocalIpAddress specifies the client IP address that is to be used by the virtual user. This is sometimes referred to as “IP spoofing”.

Include file

OraForms.bdh

Syntax

OraFormsSetLocalIpAddress( in sIp : string );
Parameter | Description
sIp | The IP address to be assigned to the virtual user.

Example

dcltrans
  transaction TInit
  begin
    OraFormsInit(NULL, "host", 9000);
    OraFormsSetLocalIpAddress("10.4.89.9");
  end TInit;
  transaction TMain
  var
    sValue   : string;
  begin
    OraFormsSetConnectMode(ORA_SOCKET_CONNECTION);
    // Connect - with connection properties
    OraFormsSetInt("INITIAL_VERSION", 608);
    OraFormsSetPoint("INITIAL_RESOLUTION", 96, 96);
    OraFormsSetPoint("INITIAL_DISP_SIZE", 1024, 768);
    OraFormsSetInt("INITIAL_COLOR_DEPTH", 256);
    OraFormsSetString("FONT_NAME", "Dialog");
    OraFormsSetPoint("INITIAL_SCALE_INFO", 8, 18);
    OraFormsSetBoolean("WINSYS_REQUIREDVA_LIST", false);
    OraFormsConnect("server module=Person3.fmx userid= useSDI=yes record=names");
    OraFormsSetWindow("Logon");
    OraFormsLogon("user", "password", "orcl_server");
    // ---
    // New window activated: WINDOW1
    OraFormsSetWindow("WINDOW1");
  end TMain;
Parent topic: Connecting Functions


OraFormsSetPort Function

Action

OraFormsSetPort specifies the port that is to be connected by the replay engine. During replay the Oracle Forms server may advise the client to connect to a specific server to manage load balancing. Call this function just before OraFormsConnect to specify the host that is to be connected. This function overrides the third parameter specified in OraFormsInit.

Include file

OraForms.bdh

Syntax

OraFormsSetPort( in nPort : number );
Parameter | Description
nPort | The port to be connected by the replay engine.

Example

dcltrans
  transaction TMain
  var
    sValue   : string;
  begin
    OraFormsSetConnectMode(ORA_SOCKET_CONNECTION);
    // Connect - with connection properties
    OraFormsSetInt("INITIAL_VERSION", 608);
    OraFormsSetPoint("INITIAL_RESOLUTION", 96, 96);
    OraFormsSetPoint("INITIAL_DISP_SIZE", 1024, 768);
    OraFormsSetInt("INITIAL_COLOR_DEPTH", 256);
    OraFormsSetString("FONT_NAME", "Dialog");
    OraFormsSetPoint("INITIAL_SCALE_INFO", 8, 18);
    OraFormsSetBoolean("WINSYS_REQUIREDVA_LIST", false);
    OraFormsSetHost("host");    OraFormsSetPort(9000);
    OraFormsConnect("server
module=Person3.fmx userid= useSDI=yes record=names");
    OraFormsSetWindow("Logon");
    OraFormsLogon("user",
"password", "orcl_server");
    // ---
    // New window activated: WINDOW1
    OraFormsSetWindow("WINDOW1");
  end TMain;

Parent topic: Connecting Functions


OraFormsSetServlet Function

Action

OraFormsSetServlet specifies the servlet that is to be connected by the replay engine. During replay the Oracle Forms server may advise the client to connect to a specific server to manage load balancing. Call this function just before OraFormsConnect to specify the host that is to be connected. This function overrides the first parameter specified in OraFormsInit.

Include file

OraForms.bdh

Syntax

OraFormsSetServlet( in sServlet : string );
Parameter | Description
sServlet | The Oracle Forms servlet to be connected by the replay engine.

Example

dcltrans
  transaction TMain
  var
    sValue   : string;
  begin
    OraFormsSetConnectMode(ORA_SOCKET_CONNECTION);
    // Connect - with connection properties
    OraFormsSetInt("INITIAL_VERSION", 608);
    OraFormsSetPoint("INITIAL_RESOLUTION", 96, 96);
    OraFormsSetPoint("INITIAL_DISP_SIZE", 1024, 768);
    OraFormsSetInt("INITIAL_COLOR_DEPTH", 256);
    OraFormsSetString("FONT_NAME", "Dialog");
    OraFormsSetPoint("INITIAL_SCALE_INFO", 8, 18);
    OraFormsSetBoolean("WINSYS_REQUIREDVA_LIST", false);
    OraFormsSetServlet("http://office:8888/forms90demo/l90servlet");

    OraFormsConnect("server module=Person3.fmx userid= useSDI=yes record=names");
    OraFormsSetWindow("Logon");
    OraFormsLogon("user", "password", "orcl_server");
    // ---
    // New window activated: WINDOW1
    OraFormsSetWindow("WINDOW1");
  end TMain;
Parent topic: Connecting Functions


OraFormsHandlePendingOnExit Function

Action

OraFormsHandlePendingOnExit may be used for Oracle Forms 10g services. Script this function for scripts that run against 10 g Forms services. Insert just before the script logs off from the server.

Include file

OraForms.bdh

Syntax

OraFormsHandlePendingOnExit( ): boolean;

Return value

  • true if successful

  • false otherwise

Example

dcltrans
  transaction TMain
  var
    sValue   : string;
  begin
    OraFormsSetConnectMode(ORA_SOCKET_CONNECTION);
    // Connect - with connection properties
    OraFormsSetInt("INITIAL_VERSION", 608);
    OraFormsSetPoint("INITIAL_RESOLUTION", 96, 96);
    OraFormsSetPoint("INITIAL_DISP_SIZE", 1024, 768);
    OraFormsSetInt("INITIAL_COLOR_DEPTH", 256);
    OraFormsSetString("FONT_NAME", "Dialog");
    OraFormsSetPoint("INITIAL_SCALE_INFO", 8, 18);
    OraFormsSetBoolean("WINSYS_REQUIREDVA_LIST", false);
    OraFormsConnect("server module=Person3.fmx userid= useSDI=yes record=names");
    OraFormsSetWindow("Logon");
    OraFormsLogon("user", "password", "orcl_server");
    // ---
    // New window activated: WINDOW1
    OraFormsSetWindow("WINDOW1");
    OraFormsHandlePendingOnExit();
    OraFormsDisconnect();
  end TMain;
Parent topic: Connecting Functions


Control Functions

  • OraFormsBeginMessageBlock Function
    Bundles a set of requests that must be sent within a single round trip.
  • OraFormsButtonPress Function
    Presses a button on the current active window.
  • OraFormsCheckBoxSet Function
    Changes the state of a check box control.
  • OraFormsChoiceBoxButton Function
    Presses a button on the specified choice box messenger control.
  • OraFormsCloseCancelQueryDialog Function
    Performs a cancel action on a Cancel Query dialog.
  • OraFormsCloseDialog Function
    Closes an active dialog that is identified by its unique name or ID.
  • OraFormsCloseWindow Function
    Closes the specified window.
  • OraFormsComboActivate Function
    Sends an activate message for an element in a combo box control.
  • OraFormsComboClose Function
    Used to close an open combo box without selecting a new value.
  • OraFormsComboSelect Function
    Selects an entry in a combo box.
  • OraFormsCreateMessageFromHandler Function
    Creates a new message with same handler id and class id as the handler specified in the function call.
  • OraFormsEditorDialogOK Function
    Closes this dialog and returns the edited value to the text control.
  • OraFormsEditSet Function
    Allows you to set a new value to a text control.
  • OraFormsEndMessageBlock Function
    Bundle a set of requests that must be sent within a single round trip.
  • OraFormsFindAndSetWindow Function
    Finds a window (based on any portion of the window’s name or the window’s full name) and sets it as the active window.
  • OraFormsFlexDefaultBlock Function
    Sends a special default block message to the Forms server.
  • OraFormsFlexDefaultField Function
    Sends a default field message for a flex window.
  • OraFormsFlexFieldFocus Function
    Sets the focus to the specified flex field.
  • OraFormsFlexPressCancel Function
    Closes a flex window.
  • OraFormsFlexPressClear Function
    Clears the values of a flex window.
  • OraFormsFlexPressFind Function
    Presses the Find (or corresponding key combination) button in a flex field window.
  • OraFormsFlexPressHelp Function
    Opens the help content associated with the flex window.
  • OraFormsFlexPressLov Function
    Opens a LOV box for a flex field.
  • OraFormsFlexPressOk Function
    Confirms a flex window by pressing the OK button.
  • OraFormsFlexSetCellData Function
    Sets a the value for the specified flex field without closing the window.
  • OraFormsFlexSetCellDataOk Function
    Sets the value for the specified flex field and confirms the flex window.
  • OraFormsFlexShowActions Function
    OraFormsFlexShowActions sends the show actions message to the Forms server.
  • OraFormsFlexShowValues Function
    OraFormsFlexShowValues sends the show values message to the Forms server.
  • OraFormsGetClassIdFromControl Function
    This function returns the class id of a control specified by its handler title.
  • OraFormsGetInterceptedControlId Function
    Returns the id of the intercepted control.
  • OraFormsGetInterceptedControlTitle Function
    Returns the title property of the intercepted control.
  • OraFormsGetSessionId Function
    Used to capture the session ID cookie that was returned by the server during the connect process.
  • OraFormsKeyStroke Function
    Sends a special key to the server (e.g., a tab key).
  • OraFormsJavaContainerAction Function
    Allows you to call a function of the Java object that is hosted in the Java container on the current window.
  • OraFormsMenuCreate Function
    Can be used to activate a pop-up menu that is assigned to a control on a window.
  • OraFormsMenuItem Function
    Can select a menu item from a pop-up menu that is assigned to a control or from a main menu that is assigned to a form window.
  • OraFormsMessageBoxButton Function
    Can be used to close a message box by choosing one of the available buttons (YES, NO, or CANCEL).
  • OraFormsMouseClick Function
    Can be used to simulate a single mouse click on a control or form window.
  • OraFormsMouseDblClick Function
    Can be used to simulate a double mouse click on a control or form window.
  • OraFormsOnMessageGet Function
    Allows you to define properties that can be queried by the server.
  • OraFormsListActivate Function
    Sends an activate message for an element in a list box control.
  • OraFormsListClose Function
    Can be used to close an open list box without selecting a new value.
  • OraFormsListSelect Function
    Selects an entry in a list box.
  • OraFormsLogon Function
    Performs a logon to an Oracle Forms Server.
  • OraFormsLogonCancel Function
    Cancels a logon dialog by pressing the "Cancel" button.
  • OraFormsLovAutoReduceChar Function
    Sends an auto-reduce message to a List Of Values dialog.
  • OraFormsLovFind Function
    Allows you to define a new search pattern for the List Of Values dialog.
  • OraFormsLovGetItems Function
    Retrieves a specified of number of LOV box entries from the server. OraFormsLovGetItems uses a 1-based index.
  • OraFormsLovOpen Function
    Opens a List Of Values dialog for a text control that has a LOV assigned to it.
  • OraFormsLovSelect Function
    Allows you to select an entry of the search result in the List Of Values dialog.
  • OraFormsLovUnReduce Function
    Sends an un-reduce message to a List Of Values dialog.
  • OraFormsRadioSet Function
    Changes the selected state of a radio button control.
  • OraFormsPopListActivate Function
    Sends an activate message for an element in a pop-up list box control.
  • OraFormsPopListClose Function
    Used to close an open pop-up list box without selecting a new value.
  • OraFormsPopListSelect Function
    Selects an entry in a pop-up list.
  • OraFormsPutMessage Function
    Adds a new message to the virtual users message pump.
  • OraFormsPutTerminalAndWait Function
    Adds a terminal message to the message queue, performs a flush and returns when the message is processed.
  • OraFormsRegisterMessageInterceptor Function
    Registers a message interceptor that will determine the handler id and the handler title of controls of a specified class.
  • OraFormsUnregisterMessageInterceptor Function
    Unregisters and frees a message interceptor.
  • OraFormsResponseBoxCancel Function
    Presses the Cancel button on a response dialog.
  • OraFormsResponseBoxOk Function
    Presses the OK button on a Response dialog.
  • OraFormsResponseBoxValidate Function
    Sends a validation message for a response dialog.
  • OraFormsScrollerDrag Function
    Drags and drops the scroller to a specified position.
  • OraFormsScrollerLine Function
    Performs a scroll up or scroll down action on a scroller by a specified number of lines.
  • OraFormsScrollerPage Function
    Performs a page scroll up or page scroll down action on a scroller by a specified number of pages.
  • OraFormsTreeSelectNode Function
    Selects the specified tree node of a tree control.
  • OraFormsSetCancelQueryWindow Function
    Marks the specified Cancel Query dialog as the current active window.
  • OraFormsSetFocus Function
    Sets the focus for the specified control.
  • OraFormsSetWindow Function
    Marks the specified window as the current activate window.
  • OraFormsTabSelect Function
    Activates a tab page.
  • OraFormsTreeActivateNode Function
    Sends an activate message for the specified tree node of the tree control.
  • OraFormsTreeCollapseNode Function
    Collapses the specified node in a tree control.
  • OraFormsTreeExpandNode Function
    Expands the selected branch in a tree control.
  • OraFormsWindowMove Function
    Moves a specified window by provided coordinates.
  • OraFormsWindowResize Function
    Resizes a given window by specified coordinates.
  • OraFormsWindowUpdate Function
    Modifies the status of a specified window.
Parent topic: Oracle Forms Functions Reference


OraFormsBeginMessageBlock Function

Action

OraFormsBeginMessageBlock and OraFormsEndMessageBlock bundle a set of requests that must be sent within a single round trip. The Silk Performer Recorder automatically detects which requests must be bundled as a message block.

Include file

OraForms.bdh

Syntax

OraFormsBeginMessageBlock( in sTimer : string ) : boolean;

Return value

  • true

    if successful

  • false

    otherwise
Parameter | Description
sTimer | The name of the message block. This is the same name as used for the corresponding OraFormsBeginMessageBlock function.

Example

 dcltrans
  transaction TMain
  begin
    ThinkTime(12.8);
    OraFormsBeginMessageBlock("Create Appointment#1");
    OraFormsWindowMove("Create Appointment", 200, 0);
    OraFormsSetFocus("CONTROL_PB_HOME_0"); //Home
    OraFormsEndMessageBlock("Create Appointment#1");
  end TMain;
Parent topic: Control Functions
Related reference
OraFormsEndMessageBlock Function


OraFormsButtonPress Function

Action

OraFormsButtonPress presses a button on the current active window. The button is either identified by its logical name or its unique ID.

Include file

OraForms.bdh

Syntax

OraFormsButtonPress( in sName : string ) : boolean;

Return value

  • true

    if successful

  • false

    otherwise
Parameter | Description
sName | The control's unique name.

Example

 dcltrans
  transaction TMain
  var
    sValue :  string;
  begin
    OraFormsSetConnectMode(ORA_SOCKET_CONNECTION);
    // Connect - with connection properties
    OraFormsSetInt( "INITIAL_VERSION", 608);
    OraFormsSetPoint( "INITIAL_RESOLUTION", 96,  96);
    OraFormsSetPoint( "INITIAL_DISP_SIZE", 1024,  768);
    OraFormsSetInt( "INITIAL_COLOR_DEPTH", 256);
    OraFormsSetString( "FONT_NAME" , "Dialog" );
    OraFormsSetPoint( "INITIAL_SCALE_INFO", 8,  18);
    OraFormsSetBoolean( "WINSYS_REQUIREDVA_LIST",  false);
    OraFormsConnect( "server module=Person3.fmx userid= useSDI=yes record=names");
    OraFormsSetWindow( "Logon");
    OraFormsLogon( "user",  "password",  "orcl_server");
    // ---
    // New window activated: WINDOW1
    OraFormsSetWindow( "WINDOW1");
    OraFormsSetFocus( "EXIT1");
    OraFormsButtonPress( "EXIT1");

  end TMain;
Parent topic: Control Functions


OraFormsCheckBoxSet Function

Action

OraFormsCheckBoxSet changes the state of a check box control.

Include file

OraForms.bdh

Syntax

OraFormsCheckBoxSet( in sName    : string,
                  in bChecked : boolean ) : boolean;

Return value

  • true if successful
  • false otherwise
Parameter | Description
sName | The control's unique name.
bChecked

The new checked value of the control.

  • TRUE: to check the control
  • FALSE: to uncheck the control.

Example

dcltrans
  transaction TMain
  var
    sValue :  string;
  begin
    OraFormsSetConnectMode(ORA_SOCKET_CONNECTION);
    // Connect - with connection properties
    OraFormsSetInt( "INITIAL_VERSION", 608);
    OraFormsSetPoint( "INITIAL_RESOLUTION", 96,  96);
    OraFormsSetPoint( "INITIAL_DISP_SIZE", 1024,  768);
    OraFormsSetInt( "INITIAL_COLOR_DEPTH", 256);
    OraFormsSetString( "FONT_NAME" , "Dialog" );
    OraFormsSetPoint( "INITIAL_SCALE_INFO", 8,  18);
    OraFormsSetBoolean( "WINSYS_REQUIREDVA_LIST",  false);
    OraFormsConnect( "server module=Person3.fmx userid= useSDI=yes record=names");
    OraFormsSetWindow( "Logon");
    OraFormsLogon( "user",  "password",  "orcl_server");
    // ---
    // New window activated: WINDOW1
    OraFormsSetWindow( "WINDOW1");
    OraFormsSetFocus( "PERSON_GENDER_MALE");
    OraFormsCheckBoxSet( "PERSON_GENDER_MALE",  true);

  end TMain;
Parent topic: Control Functions


OraFormsChoiceBoxButton Function

Action

OraFormsChoiceBoxButton presses a button on the specified choice box messenger control. The control is either identified by its logical name or its unique ID. The button is identified by its label.

Include file

OraForms.bdh

Syntax

OraFormsChoiceBoxButton(    in sName  : string,
                            in sLabel : string ): boolean;

Return value

  • true if successful

  • false otherwise

Parameter | Description
sName | The control? unique ID.
sLabel | The button with the defined label (textual representation) will be pressed.

Example

dcltrans
  transaction TMain
  var
    sValue : string;
  begin
    OraFormsSetConnectMode(ORA_SOCKET_CONNECTION);
    // Connect - with connection properties
    OraFormsSetInt("INITIAL_VERSION", 608);
    OraFormsSetPoint("INITIAL_RESOLUTION", 96, 96);
    OraFormsSetPoint("INITIAL_DISP_SIZE", 1024, 768);
    OraFormsSetInt("INITIAL_COLOR_DEPTH", 256);
    OraFormsSetString("FONT_NAME", "Dialog");
    OraFormsSetPoint("INITIAL_SCALE_INFO", 8, 18);
    OraFormsSetBoolean("WINSYS_REQUIREDVA_LIST", false);
    OraFormsConnect("server module=Person3.fmx userid= useSDI=yes record=names");
    OraFormsSetWindow("Logon");
    OraFormsLogon("user", "password", "orcl_server");
    // ---
    // New window activated: WINDOW1    OraFormsSetWindow("WINDOW1");
    OraFormsMenuItem("WINDOW1", "Action::Exit");
    // ---
    // New window activated: Caution
    OraFormsSetWindow("Caution");
    // Exit Oracle Applications?    ThinkTime(4.3);
    OraFormsChoiceBoxButton("Caution", "OK");
  end TMain;
Parent topic: Control Functions


OraFormsCloseCancelQueryDialog Function

Action

OraFormsCloseCancelQueryDialog performs a cancel action on a Cancel Query dialog.

Include file

OraForms.bdh

Syntax

OraFormsCloseCancelQueryDialog( in sName : string ) : boolean;

Return value

  • true if successful

  • false otherwise

Parameter | Description
sName | The window’s unique name.

Example

dcltrans
  transaction TMain
  begin
    OraFormsSetString("DEFAULT_LOCAL_TZ", "Europe/Berlin");
    OraFormsConnect("server module=javamail90.fmx usesdi=yes");
    OraFormsSetCancelQueryWindow("Cancel Query");
    OraFormsCloseCancelQueryDialog("Cancel Query");
  end TMain;
Parent topic: Control Functions


OraFormsCloseDialog Function

Action

OraFormsCloseDialog closes an active dialog that is identified by its unique name or ID. A standard dialog can be closed by clicking either the OK or CANCEL button, where two different constant values can be used to indicate which button is to be used to close the dialog.

Inlcude file

OraForms.bdh

Syntax

 OraFormsCloseDialog( in sName : string,
                      in nButton : number ) : boolean;

Return value

  • true if successful
  • false otherwise
Parameter | Description
sName | The unique name of the dialog window that is to be closed.
nButton The button that is to be pressed to close the dialog:
  • ORA_DIALOG_OK
  • ORA_DIALOG_CANCEL

Example

 dcltrans
 transaction TMain
 var
    sValue :  string;
 begin
    OraFormsSetConnectMode(ORA_SOCKET_CONNECTION);
    // Connect - with connection properties
    OraFormsSetInt( "INITIAL_VERSION", 608);
    OraFormsSetPoint( "INITIAL_RESOLUTION", 96,  96);
    OraFormsSetPoint( "INITIAL_DISP_SIZE", 1024,  768);
    OraFormsSetInt( "INITIAL_COLOR_DEPTH", 256);
    OraFormsSetString( "FONT_NAME" , "Dialog" );
    OraFormsSetPoint( "INITIAL_SCALE_INFO", 8,  18);
    OraFormsSetBoolean( "WINSYS_REQUIREDVA_LIST",  false);
    OraFormsConnect( "server module=Person3.fmx userid= useSDI=yes record=names");
    OraFormsSetWindow( "Logon");
    OraFormsLogon( "user",  "password",  "orcl_server");
    // ---
    // New window activated: WINDOW1
    OraFormsSetWindow( "WINDOW1");
    OraFormsMenuItem( "WINDOW1",  "Action::Calculator");
    // ---
    // New window activated: CALC_PROMPT
    OraFormsSetWindow( "CALC_PROMPT");
    OraFormsCloseDialog( "CALC_PROMPT", ORA_DIALOG_OK);
    // ---
    // New window activated: WINDOW1
    OraFormsSetWindow( "WINDOW1");
    OraFormsMenuItem( "WINDOW1",  "Action::Exit");
  end TMain;
Parent topic: Control Functions


OraFormsCloseWindow Function

Action

Closes the specified window.

Include file

OraForms.bdh

Syntax

OraFormsCloseWindow( in sName : string ) : boolean;

Return value

  • true if successful
  • false otherwise
Parameter | Description
sName | The window's unique name

Example

dcltrans
  transaction TMain
  var
  begin
    OraFormsSetPoint( "INITIAL_SCALE_INFO", 8,  20);
    OraFormsSetBoolean( "WINSYS_REQUIREDVA_LIST",  false);
    OraFormsSetString( "DEFAULT_LOCAL_TZ", "Europe/Berlin");
    OraFormsConnect( "server module=iorganizer.fmx userid=iorg/iorg@ORCL_server sso_userid= usesdi=yes record=names");
    OraFormsSetFocus( "LOGIN_PB_ENTER_0");
    // Enter OraFormsButtonPress( "LOGIN_PB_ENTER_0");
    //Enter
    // Incorrect Login Information. Do you want to register?
    OraFormsMessageBoxButton( "Incorrect Login", ORA_ALERT_NO);
    OraFormsCloseWindow( "Oracle iOrganizer");
  end TMain;
Parent topic: Control Functions


OraFormsComboActivate Function

Action

OraFormsComboActivate is used to send an activate message for an element in a combo box control. A control is identified by a unique name or ID.

Include file

OraForms.bdh

Syntax

OraFormsComboActivate(    in sName     : string,
                          in sLabel    : string,
                          in nIndex    : number optional,
                          in nPosition : number optional ): boolean;

Return value

  • true if successful

  • false otherwise

Parameter | Description
sName | The control's unique ID.
sLabel | (if not NULL) The element with the defined label (textual representation) will be activated. If you pass NULL, you must define the index of the item that is to be activated in the next parameter.
nIndex | (if sLabel is NULL) This parameter defines the index of the element that is to be activated. The index of the first element is 0.
nPosition | If the control contains multiple entries with the same label, this parameter will be used to specify the nth position. The default value is 0.

Example

dcltrans
  transaction TMain
  var
    sValue : string;
  begin
    OraFormsSetConnectMode(ORA_SOCKET_CONNECTION);
    // Connect - with connection properties
    OraFormsSetInt("INITIAL_VERSION", 608);
    OraFormsSetPoint("INITIAL_RESOLUTION", 96, 96);
    OraFormsSetPoint("INITIAL_DISP_SIZE", 1024, 768);
    OraFormsSetInt("INITIAL_COLOR_DEPTH", 256);
    OraFormsSetString("FONT_NAME", "Dialog");
    OraFormsSetPoint("INITIAL_SCALE_INFO", 8, 18);
    OraFormsSetBoolean("WINSYS_REQUIREDVA_LIST", false);
    OraFormsConnect("server module=Person3.fmx userid= useSDI=yes record=names");
    OraFormsSetWindow("Logon");
    OraFormsLogon("user", "password", "orcl_server");
    // ---
    // New window activated: WINDOW1
    OraFormsSetWindow("WINDOW1");
    OraFormsSetFocus("PERSON_GENDER");
    OraFormsComboActivate("PERSON_GENDER", "Male", 0);
    OraFormsComboClose("PERSON_GENDER");
    OraFormsMenuItem("WINDOW1", "Action::Exit");
  end TMain;
Parent topic: Control Functions


OraFormsComboClose Function

Action

OraFormsComboClose can be used to close an open combo box without selecting a new value. There is no actual command that opens the box. This method simulates the complete sequence of opening and closing a combo box without selecting a value. To select a value, use OraFormsComboSelect. The combo box is identified by its unique name or unique ID.

Include file

OraForms.bdh

Syntax

OraFormsComboClose( in sName : string ) : boolean;

Return value

  • true

    if successful

  • false

    otherwise
Parameter | Description
sName | The unique name of the dialog window that is to be closed.
nButton The button that is to be pressed to close the dialog:
  • ORA_DIALOG_OK
  • ORA_DIALOG_CANCEL

Example

dcltrans
  transaction TMain
  var
    sValue :  string;
  begin
    OraFormsSetConnectMode(ORA_SOCKET_CONNECTION);
    // Connect - with connection properties
    OraFormsSetInt("INITIAL_VERSION", 608);
    OraFormsSetPoint("INITIAL_RESOLUTION", 96, 96);
    OraFormsSetPoint("INITIAL_DISP_SIZE", 1024, 768);
    OraFormsSetInt("INITIAL_COLOR_DEPTH", 256);
    OraFormsSetString("FONT_NAME" , "Dialog" );
    OraFormsSetPoint("INITIAL_SCALE_INFO", 8,  18);
    OraFormsSetBoolean("WINSYS_REQUIREDVA_LIST",  false);
    OraFormsConnect("server module=Person3.fmx userid= useSDI=yes record=names");
    OraFormsSetWindow("Logon");
    OraFormsLogon("user", "password", "orcl_server");
    // ---
    // New window activated: WINDOW1
    OraFormsSetWindow("WINDOW1");
    OraFormsSetFocus("PERSON_GENDER", "Male", 0);
    OraFormsComboSelect("PERSON_GENDER", "Male", 0);
    OraFormsComboClose("PERSON_GENDER");

    OraFormsMenuItem( "WINDOW1",  "Action::Exit");
  end TMain;
Parent topic: Control Functions


OraFormsComboSelect Function

Action

OraFormsComboSelect selects an entry in a combo box. The element that is to be selected can either be defined by its textual representation or by its index. A combo box is identified by its unique name or ID.

Include file

OraForms.bdh

Syntax

OraFormsComboSelect(    in sName     : string,
                        in sLabel    : string,
                        in nIndex    : number optional,
                        in nPosition : number optional): boolean;

Return value

  • true if successful

  • false otherwise

Parameter | Description
sName | The control's unique ID.
sLabel | (if not NULL) The element with the defined label (textual representation) will be activated. If you pass NULL, you must define the index of the item that is to be activated in the next parameter.
nIndex | (if sLabel is NULL) This parameter defines the index of the element that is to be activated. The index of the first element is 0.
nPosition | If the control contains multiple entries with the same label, this parameter will be used to specify the nth position. The default value is 0.

Example

dcltrans
  transaction TMain
  var
    sValue : string;
  begin
    OraFormsSetConnectMode(ORA_SOCKET_CONNECTION);
    // Connect - with connection properties
    OraFormsSetInt("INITIAL_VERSION", 608);
    OraFormsSetPoint("INITIAL_RESOLUTION", 96, 96);
    OraFormsSetPoint("INITIAL_DISP_SIZE", 1024, 768);
    OraFormsSetInt("INITIAL_COLOR_DEPTH", 256);
    OraFormsSetString("FONT_NAME", "Dialog");
    OraFormsSetPoint("INITIAL_SCALE_INFO", 8, 18);
    OraFormsSetBoolean("WINSYS_REQUIREDVA_LIST", false);
    OraFormsConnect("server module=Person3.fmx userid= useSDI=yes record=names");
    OraFormsSetWindow("Logon");
    OraFormsLogon("user", "password", "orcl_server");
    // ---
    // New window activated: WINDOW1
    OraFormsSetWindow("WINDOW1");
    OraFormsSetFocus("PERSON_GENDER");
    OraFormsComboSelect("PERSON_GENDER", "Male", 0);
    OraFormsComboClose("PERSON_GENDER");
    OraFormsMenuItem("WINDOW1", "Action::Exit");
  end TMain;
Parent topic: Control Functions


OraFormsCreateMessageFromHandler Function

Action

This function creates a new message with same handler id and class id as the handler specified in the function call.

Include file

OraForms.bdh

Syntax

OraFormsCreateMessageFromHandler(
     in nHandlerName : number,
     in nType        : number) : number;

Return value

  • A handle to the created message on success.

  • 0 otherwise.

Parameter | Description
nHandlerName | The name of an existing handler. The message to be created will inherit the handler id and class id of this handler.
nType

Type of message to be created. Available options are:

  • ORA_MSG_TYPE_CREATE

  • ORA_MSG_TYPE_UPDATE

  • ORA_MSG_TYPE_DESTROY

  • ORA_MSG_TYPE_GET

  • ORA_MSG_TYPE_TERMINAL

Example

  transaction TMain
  var
    nFlexId : number;
    gnUmsg  : number;
    subMsg  : number;
  begin
    OraFormsSetConnectMode(ORA_HTTP_CONNECTION);
    // Connect - with connection properties
    OraFormsSetInt("INITIAL_VERSION", 608);
    OraFormsSetPoint("INITIAL_RESOLUTION", 96, 96);
    OraFormsSetPoint("INITIAL_DISP_SIZE", 1024, 768);
    OraFormsSetInt("INITIAL_COLOR_DEPTH", 256);
    OraFormsSetString("FONT_NAME", "Dialog");
    OraFormsSetPoint("INITIAL_SCALE_INFO", 8, 18);
    OraFormsSetBoolean("WINSYS_REQUIREDVA_LIST", false);
    OraFormsConnect("server module=Person3.fmx userid= useSDI=yes record=names");
    // New window activated: Logon
    OraFormsSetWindow("Logon");
    OraFormsLogon("user", "password", "orcl_server");
    OraFormsBeginMessageBlock("Block#2");
    gnUmsg := OraFormsCreateMessageFromHandler("handler", ORA_MSG_TYPE_UPDATE);
    subMsg := OraFormsCreateMessage(30, 40, ORA_MSG_TYPE_UPDATE);
    OraFormsAddPropertyMessage(gnUmsg, ORA_PID_BP_FOREFILLCOL, subMsg);
    OraFormsAddPropertyInt(gnUmsg, 2601, 91);
    OraFormsAddPropertyInt(gnUmsg, 2600, 0);
    OraFormsAddPropertyByte(gnUmsg, 2600, 0);
    OraFormsAddPropertyPoint(gnUmsg, ORA_PID_INITIAL_RESOLUTION, 0, 0);
    OraFormsAddPropertyString(gnUmsg,  2600, "E");
    OraFormsPutMessage(gnUmsg);
    OraFormsPutTerminalAndWait();
    OraFormsFree(gnUmsg);
    OraFormsEndMessageBlock("Block#2")
  end TMain;

Parent topic: Control Functions


OraFormsEditorDialogOK Function

Action

Text controls allow you to open an editor dialog to edit the value of the control in a more advanced way. OraFormsEditorDialogOK closes this dialog and returns the edited value to the text control.

Include file

OraForms.bdh

Syntax

OraFormsEditorDialogOK( in sWindowName : string,
                        in sValue : string ) : boolean;

Return value

  • true if successful

  • false otherwise

Parameter | Description
sWindowName | Name of the editor dialog window that should be closed.
sValue | The edited value that should be returned to the text control.

Example

dcltrans
  transaction TMain
  var
    sValue :  string;
  begin
    OraFormsSetConnectMode(ORA_SOCKET_CONNECTION);
    // Connect - with connection properties
    OraFormsSetInt( "INITIAL_VERSION", 608);
    OraFormsSetPoint( "INITIAL_RESOLUTION", 96,  96);
    OraFormsSetPoint( "INITIAL_DISP_SIZE", 1024,  768);
    OraFormsSetInt( "INITIAL_COLOR_DEPTH", 256);
    OraFormsSetString( "FONT_NAME" , "Dialog" );
    OraFormsSetPoint( "INITIAL_SCALE_INFO", 8,  18);
    OraFormsSetBoolean( "WINSYS_REQUIREDVA_LIST",  false);
    OraFormsConnect( "server module=Person3.fmx userid= useSDI=yes record=names");
    OraFormsSetWindow( "Logon");
    OraFormsLogon( "user",  "password",  "orcl_server");
    // ---
    // New window activated: WINDOW1 OraFormsSetWindow( "WINDOW1");
    OraFormsMenuItem( "WINDOW1",  "Edit::Edit");
    // ---
    // New window activated: Editor OraFormsSetWindow( "Editor");
    OraFormsEditorDialogOK( "Editor",  "Edited value");
    // ---
    // New window activated: WINDOW1
    OraFormsSetWindow( "WINDOW1");
    OraFormsMenuItem( "WINDOW1",  "Action::Exit");
  end TMain;
Parent topic: Control Functions


OraFormsEditSet Function

Action

OraFormsEditSet allows you to set a new value to a text control. The control is identified by its unique name or unique ID. Text controls have a special behavior in Oracle Forms Applications. Whenever a control becomes dirty (a value is changed by the client), the control sends a dirty message to the server. This happens when entering the first character in the text control. The complete value is sent when the control loses its focus (e.g., using the tab key to jump to a different control or changing the focus by clicking another control).

OraFormsEditSet allows you to either use the default method of dirty value handling (using the first character of the entered value) or a different dirty value can be defined. A different dirty value as the first character can occur if the user pastes a new value into a control that already contains a different value.

OraFormsEditSet also allows you to completely omit sending a dirty value.

Include file

OraForms.bdh

Syntax

OraFormsEditSet( in sName :  string,
                 in sValue :  string,
                 in nOption :  number optional,
                 in sDirtyVal :  string optional ) :  boolean;

Return value

  • true

    if successful

  • false

    otherwise
Parameter | Description
sName | The unique name of the edit control.
sValue | The new value that should be set for the control.
nOption

(optional):

There are two options for how the function should handle a dirty message that is sent when setting a new value to a text control:

  • ORA_EDIT_SEND_DIRTY (default):

    This option causes the function to send a dirty message with either the text defined in the parameter sDirtyVal or the first character of sValue if sDirtyVal is null or omitted.

  • ORA_EDIT_NO_DIRTY: No dirty value will be sent.
sDirtyVal

(optional):

If nOption is defined with ORA_EDIT_SEND_DIRTY, the function first sends a dirty notification to the server and then sends the real new value. By default, when recording an application, the dirty value is the first character of the new value that is entered in a text control. If sDirtyVal is omitted or null is passed, the first character of sValue will be sent as a dirty value. Otherwise the value defined in this parameter will be used.

Example

dcltrans
  transaction TMain
  var
    sValue :  string;
  begin
    OraFormsSetConnectMode(ORA_SOCKET_CONNECTION);
    // Connect - with connection properties
    OraFormsSetInt( "INITIAL_VERSION",  608);
    OraFormsSetPoint( "INITIAL_RESOLUTION",  96,  96);
    OraFormsSetPoint( "INITIAL_DISP_SIZE", 1024,  768);
    OraFormsSetInt( "INITIAL_COLOR_DEPTH", 256);
    OraFormsSetString( "FONT_NAME" , "Dialog" );
    OraFormsSetPoint( "INITIAL_SCALE_INFO",  8,  18);
    OraFormsSetBoolean( "WINSYS_REQUIREDVA_LIST",  false);
    OraFormsConnect( "server module=Person3.fmx userid= useSDI=yes record=names");
    OraFormsSetWindow( "Logon");
    OraFormsLogon( "user",  "password",  "orcl_server");
    // ---
    // New window activated: WINDOW1
    OraFormsSetWindow( "WINDOW1");
    OraFormsEditSet( "PERSON_FIRST_NAME",  "Andi");
    OraFormsKeyStroke( "PERSON_FIRST_NAME", ORA_KEY_TAB,  0);
    OraFormsEditSet( "PERSON_LAST_NAME",  "GRABNER", ORA_EDIT_SEND_DIRTY,  "Reithmayr");
    OraFormsMenuItem( "WINDOW1",  "Action::Exit");
  end TMain;
Parent topic: Control Functions


OraFormsEndMessageBlock Function

Action

OraFormsBeginMessageBlock and OraFormsEndMessageBlock bundle a set of requests that must be sent within a single round trip. The Silk Performer Recorder automatically detects which requests must be bundled as a message block.

Include file

OraForms.bdh

Syntax

OraFormsEndMessageBlock( in sTimer : string ) : boolean;

Return value

  • true if successful
  • false otherwise
Parameter | Description
sTimer | The name of the message block. This is the same name as used for the corresponding OraFormsBeginMessageBlock function.

Example

dcltrans
  transaction TMain
  begin
    ThinkTime(12.8);
    OraFromsBeginMessageBlock("Create Appointment#1");
    OraFormsWindowMove("Create Appointment", 200, 0);
    OraFormsSetFocus("CONTROL_PB_HOME0"); // Home
    OraFormsEndMessageBlock("Create Appointment#1);
  end TMain
Parent topic: Control Functions
Related reference
OraFormsBeginMessageBlock Function


OraFormsFindAndSetWindow Function

Action

OraFormsFindAndSetWindow finds a window (based on any portion of the window’s name or the window’s full name) and sets it as the active window. On success, it returns the handler ID of the window. If the window cannot be found, it returns -1.

Include file

OraForms.bdh

Syntax

OraFormsFindAndSetWindow(    in sPartName : string,
                             in nCount    : number optional,
                             in nSearch   : number optional ): number;

Return value

  • The ID of the window on success.

  • -1 otherwise

Parameter | Description
sPartName | Substring of the window name to be matched.
nCount | More than one window may match the pattern. Specify the index of the window that is to be returned and set it as the active window.
nSearch

Serach options:

  • ORA_SEARCH_STARTSWITH

  • ORA_SEARCH_ENDSWITH

  • ORA_SEARCH_CONTAINS

Example

dcltrans
  transaction TMain
  var
    sValue : string;
    Id     : number;
  begin
    OraFormsSetConnectMode(ORA_SOCKET_CONNECTION);
    // Connect - with connection properties
    OraFormsSetInt("INITIAL_VERSION", 608);
    OraFormsSetPoint("INITIAL_RESOLUTION", 96, 96);
    OraFormsSetPoint("INITIAL_DISP_SIZE", 1024, 768);
    OraFormsSetInt("INITIAL_COLOR_DEPTH", 256);
    OraFormsSetString("FONT_NAME", "Dialog");
    OraFormsSetPoint("INITIAL_SCALE_INFO", 8, 18);
    OraFormsSetBoolean("WINSYS_REQUIREDVA_LIST", false);
    OraFormsConnect("server module=Person3.fmx userid= useSDI=yes record=names");
    OraFormsSetWindow("Logon");
    OraFormsLogon("user",
"password", "orcl_server");
    // ---
    // New window activated: WINDOW1
    Id := OraFormsFindAndSetWindow("WIND", 0, ORA_SEARCH_STARTSWITH);
  end TMain;

Parent topic: Control Functions


OraFormsFlexDefaultBlock Function

Action

OraFormsFlexDefaultBlock sends a special default block message to the Forms server.

Include file

OraForms.bdh

Syntax

OraFormsFlexDefaultBlock( in sName : string ): boolean;

Return value

  • true if successful

  • false otherwise

Parameter | Description
sName | The control's unique name.

Example

dcltrans
  transaction TMain
  begin
    OraFormsSetConnectMode(ORA_SOCKET_CONNECTION);
    // Connect - with connection properties
    OraFormsSetInt("INITIAL_VERSION", 608);
    OraFormsSetPoint("INITIAL_RESOLUTION", 96, 96);
    OraFormsSetPoint("INITIAL_DISP_SIZE", 1024, 768);
    OraFormsSetInt("INITIAL_COLOR_DEPTH", 256);
    OraFormsSetString("FONT_NAME", "Dialog");
    OraFormsSetPoint("INITIAL_SCALE_INFO", 8, 18);
    OraFormsSetBoolean("WINSYS_REQUIREDVA_LIST", false);
    OraFormsConnect("server module=Person3.fmx userid= useSDI=yes record=names");
    OraFormsSetWindow("Logon");
    OraFormsLogon("user", "password", "orcl_server");
    // ---
    // New window activated: WINDOW1
    OraFormsSetWindow("WINDOW1");
    OraFormsFlexDefaultBlock("ADB Account");
  end TMain;
Parent topic: Control Functions


OraFormsFlexDefaultField Function

Action

OraFormsFlexDefaultField sends a default field message for a flex window.

Include file

OraForms.bdh

Syntax

OraFormsFlexDefaultField(    in sName : string,
                             in sRow  : string,
                             in sCol  : string ) : boolean;

Return value

  • true if successful

  • false otherwise

Parameter | Description
sName | The control's unique name.
sRow | The name of the field’s row.
sCol | The name of the field’s column.

Example

dcltrans
  transaction TMain
  begin
    OraFormsSetConnectMode(ORA_SOCKET_CONNECTION);
    // Connect - with connection properties
    OraFormsSetInt("INITIAL_VERSION", 608);
    OraFormsSetPoint("INITIAL_RESOLUTION", 96, 96);
    OraFormsSetPoint("INITIAL_DISP_SIZE", 1024, 768);
    OraFormsSetInt("INITIAL_COLOR_DEPTH", 256);
    OraFormsSetString("FONT_NAME", "Dialog");
    OraFormsSetPoint("INITIAL_SCALE_INFO", 8, 18);
    OraFormsSetBoolean("WINSYS_REQUIREDVA_LIST", false);
    OraFormsConnect("server module=Person3.fmx userid= useSDI=yes record=names");
    OraFormsSetWindow("Logon");
    OraFormsLogon("user", "password", "orcl_server");
    // ---
    // New window activated: WINDOW1
    OraFormsSetWindow("WINDOW1");
    OraFormsFlexDefaultField("ADB Account", "Transfer", "Low");
  end TMain;
Parent topic: Control Functions


OraFormsFlexFieldFocus Function

Action

OraFormsFlexFieldFocus sets the focus to the specified flex field.

Include file

OraForms.bdh

Syntax

OraFormsFlexFieldFocus(    in sName : string,
                           in sRow  : string,
                           in sCol  : string ) : boolean;

Return value

  • true if successful

  • false otherwise

Parameter | Description
sName | The control's unique name.
sRow | The field’s row.
sCol | The field’s column.

Example

dcltrans
  transaction TMain
  var
    sValue : string;
  begin
    OraFormsSetConnectMode(ORA_SOCKET_CONNECTION);
    // Connect - with connection properties
    OraFormsSetInt("INITIAL_VERSION", 608);
    OraFormsSetPoint("INITIAL_RESOLUTION", 96, 96);
    OraFormsSetPoint("INITIAL_DISP_SIZE", 1024, 768);
    OraFormsSetInt("INITIAL_COLOR_DEPTH", 256);
    OraFormsSetString("FONT_NAME", "Dialog");
    OraFormsSetPoint("INITIAL_SCALE_INFO", 8, 18);
    OraFormsSetBoolean("WINSYS_REQUIREDVA_LIST", false);
    OraFormsConnect("server module=Person3.fmx userid= useSDI=yes record=names");
    OraFormsSetWindow("Logon");
    OraFormsLogon("user", "password", "orcl_server");
    // ---
    // New window activated: WINDOW1
    OraFormsSetWindow("WINDOW1");
    OraFormsFlexFieldFocus("ADB Account", "Transfer", "Low");
  end TMain;

Parent topic: Control Functions


OraFormsFlexPressCancel Function

Action

OraFormsFlexPressCancel closes a flex window.

Include file

OraForms.bdh

Syntax

OraFormsFlexPressCancel( in sName : string ) : boolean;

Return value

  • true if successful

  • false otherwise

Parameter | Description
sName | The control's unique name.

Example

dcltrans
  transaction TMain
  var
    sValue : string;
  begin
    OraFormsSetConnectMode(ORA_SOCKET_CONNECTION);
    // Connect - with connection properties
    OraFormsSetInt("INITIAL_VERSION", 608);
    OraFormsSetPoint("INITIAL_RESOLUTION", 96, 96);
    OraFormsSetPoint("INITIAL_DISP_SIZE", 1024, 768);
    OraFormsSetInt("INITIAL_COLOR_DEPTH", 256);
    OraFormsSetString("FONT_NAME", "Dialog");
    OraFormsSetPoint("INITIAL_SCALE_INFO", 8, 18);
    OraFormsSetBoolean("WINSYS_REQUIREDVA_LIST", false);
    OraFormsConnect("server module=Person3.fmx userid= useSDI=yes record=names");
    OraFormsSetWindow("Logon");
    OraFormsLogon("user", "password", "orcl_server");
    // ---
    // New window activated: WINDOW1
    OraFormsSetWindow("WINDOW1");
    OraFormsFlexPressCancel("ADB Account");
  end TMain;

Parent topic: Control Functions


OraFormsFlexPressClear Function

Action

OraFormsFlexPressClear clears the values of a flex window.

Include file

OraForms.bdh

Syntax

OraFormsFlexPressClear( in sName : string ) : boolean;

Return value

  • true if successful

  • false otherwise

Parameter | Description
sName | The control's unique name.

Example

dcltrans
  transaction TMain
  var
    sValue : string;
  begin
    OraFormsSetConnectMode(ORA_SOCKET_CONNECTION);
    // Connect - with connection properties
    OraFormsSetInt("INITIAL_VERSION", 608);
    OraFormsSetPoint("INITIAL_RESOLUTION", 96, 96);
    OraFormsSetPoint("INITIAL_DISP_SIZE", 1024, 768);
    OraFormsSetInt("INITIAL_COLOR_DEPTH", 256);
    OraFormsSetString("FONT_NAME", "Dialog");
    OraFormsSetPoint("INITIAL_SCALE_INFO", 8, 18);
    OraFormsSetBoolean("WINSYS_REQUIREDVA_LIST", false);
    OraFormsConnect("server module=Person3.fmx userid= useSDI=yes record=names");
    OraFormsSetWindow("Logon");
    OraFormsLogon("user",
"password", "orcl_server");
    // ---
    // New window activated: WINDOW1
    OraFormsSetWindow("WINDOW1");
    OraFormsFlexPressClear("ADB Account");
  end TMain;
Parent topic: Control Functions


OraFormsFlexPressFind Function

Action

OraFormsFlexPressFind presses the Find (or corresponding key combination) button in a flex field window.

Include file

OraForms.bdh

Syntax

OraFormsFlexPressFind( in sName : string ): boolean;

Return value

  • true if successful

  • false otherwise

Parameter | Description
sName | The control's unique name.

Example

dcltrans
  transaction TMain
  var
    sValue : string;
  begin
    OraFormsSetConnectMode(ORA_SOCKET_CONNECTION);
    // Connect - with connection properties
    OraFormsSetInt("INITIAL_VERSION", 608);
    OraFormsSetPoint("INITIAL_RESOLUTION", 96, 96);
    OraFormsSetPoint("INITIAL_DISP_SIZE", 1024, 768);
    OraFormsSetInt("INITIAL_COLOR_DEPTH", 256);
    OraFormsSetString("FONT_NAME", "Dialog");
    OraFormsSetPoint("INITIAL_SCALE_INFO", 8, 18);
    OraFormsSetBoolean("WINSYS_REQUIREDVA_LIST", false);
    OraFormsConnect("server
module=Person3.fmx userid= useSDI=yes record=names");
    OraFormsSetWindow("Logon");
    OraFormsLogon("user",
"password", "orcl_server");
    // ---
    // New window activated: WINDOW1
    OraFormsSetWindow("WINDOW1");
    OraFormsFlexPressFind("ADB Account");
  end TMain;

Parent topic: Control Functions


OraFormsFlexPressHelp Function

Action

OraFormsFlexPressHelp opens the help content associated with the flex window.

Include file

OraForms.bdh

Syntax

OraFormsFlexPressHelp( in sName : string ) : boolean;

Return value

  • true if successful

  • false otherwise

Parameter | Description
sName | The control's unique name.

Example

dcltrans
  transaction TMain
  var
    sValue : string;
  begin
    OraFormsSetConnectMode(ORA_SOCKET_CONNECTION);
    // Connect - with connection properties
    OraFormsSetInt("INITIAL_VERSION", 608);
    OraFormsSetPoint("INITIAL_RESOLUTION", 96, 96);
    OraFormsSetPoint("INITIAL_DISP_SIZE", 1024, 768);
    OraFormsSetInt("INITIAL_COLOR_DEPTH", 256);
    OraFormsSetString("FONT_NAME", "Dialog");
    OraFormsSetPoint("INITIAL_SCALE_INFO", 8, 18);
    OraFormsSetBoolean("WINSYS_REQUIREDVA_LIST", false);
    OraFormsConnect("server module=Person3.fmx userid= useSDI=yes record=names");
    OraFormsSetWindow("Logon");
    OraFormsLogon("user", "password", "orcl_server");
    // ---
    // New window activated: WINDOW1
    OraFormsSetWindow("WINDOW1");
    OraFormsFlexPressHelp("ADB Account");
  end TMain;
Parent topic: Control Functions


OraFormsFlexPressLov Function

Action

OraFormsFlexPressLov opens a LOV box for a flex field.

Include file

OraForms.bdh

Syntax

OraFormsFlexPressLov( in sName : string;
                      in sRow  : string;
                      in sCol  : string ) : boolean;

Return value

  • true if successful

  • false otherwise

Parameter | Description
sName | The control's unique name.
sRow | The name of the field’s row.
sCol | The name of the field’s column.

Example

dcltrans
  transaction TMain
  var
    sValue : string;
  begin
    OraFormsSetConnectMode(ORA_SOCKET_CONNECTION);
    // Connect - with connection properties
    OraFormsSetInt("INITIAL_VERSION", 608);
    OraFormsSetPoint("INITIAL_RESOLUTION", 96, 96);
    OraFormsSetPoint("INITIAL_DISP_SIZE", 1024, 768);
    OraFormsSetInt("INITIAL_COLOR_DEPTH", 256);
    OraFormsSetString("FONT_NAME", "Dialog");
    OraFormsSetPoint("INITIAL_SCALE_INFO", 8, 18);
    OraFormsSetBoolean("WINSYS_REQUIREDVA_LIST", false);
    OraFormsConnect("server module=Person3.fmx userid= useSDI=yes record=names");
    OraFormsSetWindow("Logon");
    OraFormsLogon("user", "password", "orcl_server");
    // ---
    // New window activated: WINDOW1
    OraFormsSetWindow("WINDOW1");
    OraFormsFlexPressLov("ADB Account", "Transfer", "Low");
  end TMain;

Parent topic: Control Functions


OraFormsFlexPressOk Function

Action

OraFormsFlexPressOk confirms a flex window by pressing the OK button.

Include file

OraForms.bdh

Syntax

OraFormsFlexPressOk( in sName : string  ) : boolean;

Return value

  • true if successful

  • false otherwise

Parameter | Description
sName | The control's unique name.

Example

dcltrans
  transaction TMain
  var
    sValue : string;
  begin
    OraFormsSetConnectMode(ORA_SOCKET_CONNECTION);
    // Connect - with connection properties
    OraFormsSetInt("INITIAL_VERSION", 608);
    OraFormsSetPoint("INITIAL_RESOLUTION", 96, 96);
    OraFormsSetPoint("INITIAL_DISP_SIZE", 1024, 768);
    OraFormsSetInt("INITIAL_COLOR_DEPTH", 256);
    OraFormsSetString("FONT_NAME", "Dialog");
    OraFormsSetPoint("INITIAL_SCALE_INFO", 8, 18);
    OraFormsSetBoolean("WINSYS_REQUIREDVA_LIST", false);
    OraFormsConnect("server module=Person3.fmx userid= useSDI=yes record=names");
    OraFormsSetWindow("Logon");
    OraFormsLogon("user", "password", "orcl_server");
    // ---
    // New window activated: WINDOW1
    OraFormsSetWindow("WINDOW1");
    OraFormsFlexPressOk("ADB Account");
  end TMain;
Parent topic: Control Functions


OraFormsFlexSetCellData Function

Action

OraFormsFlexSetCellData sets a the value for the specified flex field without closing the window.

Include file

OraForms.bdh

Syntax

OraFormsFlexSetCellData( in sName  : string,
                         in sRow   : string,
                         in sCol   : string,
                         in sValue : string ): boolean;

Return value

  • true if successful

  • false otherwise

Parameter | Description
sName | The control's unique name.
sRow | The name of the field’s row.
sCol | The name of the field’s column.
sValue | The value to be set for the flex field.

Example

dcltrans
  transaction TMain
  var
    sValue : string;
  begin
    OraFormsSetConnectMode(ORA_SOCKET_CONNECTION);
    // Connect - with connection properties
    OraFormsSetInt("INITIAL_VERSION", 608);
    OraFormsSetPoint("INITIAL_RESOLUTION", 96, 96);
    OraFormsSetPoint("INITIAL_DISP_SIZE", 1024, 768);
    OraFormsSetInt("INITIAL_COLOR_DEPTH", 256);
    OraFormsSetString("FONT_NAME", "Dialog");
    OraFormsSetPoint("INITIAL_SCALE_INFO", 8, 18);
    OraFormsSetBoolean("WINSYS_REQUIREDVA_LIST", false);
    OraFormsConnect("server module=Person3.fmx userid= useSDI=yes record=names");
    OraFormsSetWindow("Logon");
    OraFormsLogon("user", "password", "orcl_server");
    // ---
    // New window activated: WINDOW1
    OraFormsSetWindow("WINDOW1");
    OraFormsFlexSetCellData("ADB Account", "Transfer", "Low", "TV");
  end TMain;
Parent topic: Control Functions


OraFormsFlexSetCellDataOk Function

Action

OraFormsFlexSetCellDataOk sets the value for the specified flex field and confirms the flex window.

Include file

OraForms.bdh

Syntax

OraFormsFlexSetCellDataOk( in sName  : string,
                           in sRow   : string,
                           in sCol   : string,
                           in sValue : string ): boolean;

Return value

  • true if successful

  • false otherwise

Parameter | Description
sName | The control's unique name.
sRow | The name of the field’s row.
sCol | The name of the field’s column.
sValue | The value to be set for the flex field.

Example

dcltrans
  transaction TMain
  var
    sValue : string;
  begin
    OraFormsSetConnectMode(ORA_SOCKET_CONNECTION);
    // Connect - with connection properties
    OraFormsSetInt("INITIAL_VERSION", 608);
    OraFormsSetPoint("INITIAL_RESOLUTION", 96, 96);
    OraFormsSetPoint("INITIAL_DISP_SIZE", 1024, 768);
    OraFormsSetInt("INITIAL_COLOR_DEPTH", 256);
    OraFormsSetString("FONT_NAME", "Dialog");
    OraFormsSetPoint("INITIAL_SCALE_INFO", 8, 18);
    OraFormsSetBoolean("WINSYS_REQUIREDVA_LIST", false);
    OraFormsConnect("server module=Person3.fmx userid= useSDI=yes record=names");
    OraFormsSetWindow("Logon");
    OraFormsLogon("user", "password", "orcl_server");
    // ---
    // New window activated: WINDOW1
    OraFormsSetWindow("WINDOW1");
    OraFormsFlexSetCellDataOk("ADB Account", "Transfer", "Low", "TV");
  end TMain;
Parent topic: Control Functions


OraFormsFlexShowActions Function

Action

OraFormsFlexShowActions sends the show actions message to the Forms server.

Include file

OraForms.bdh

Syntax

OraFormsFlexShowActions( in sName : string ) : boolean;

Return value

  • true if successful

  • false otherwise

Parameter | Description
sName | The control's unique name.

Example

dcltrans
  transaction TMain
  var
    sValue : string;
  begin
    OraFormsSetConnectMode(ORA_SOCKET_CONNECTION);
    // Connect - with connection properties
    OraFormsSetInt("INITIAL_VERSION", 608);
    OraFormsSetPoint("INITIAL_RESOLUTION", 96, 96);
    OraFormsSetPoint("INITIAL_DISP_SIZE", 1024, 768);
    OraFormsSetInt("INITIAL_COLOR_DEPTH", 256);
    OraFormsSetString("FONT_NAME", "Dialog");
    OraFormsSetPoint("INITIAL_SCALE_INFO", 8, 18);
    OraFormsSetBoolean("WINSYS_REQUIREDVA_LIST", false);
    OraFormsConnect("server module=Person3.fmx userid= useSDI=yes record=names");
    OraFormsSetWindow("Logon");
    OraFormsLogon("user",
"password", "orcl_server");
    // ---
    // New window activated: WINDOW1
    OraFormsSetWindow("WINDOW1");
    OraFormsFlexShowActions("ADB Account");
  end TMain;

Parent topic: Control Functions


OraFormsFlexShowValues Function

Action

OraFormsFlexShowValues sends the show values message to the Forms server.

Include file

OraForms.bdh

Syntax

OraFormsFlexShowValues( in sName : string ) : boolean;

Return value

  • true if successful

  • false otherwise

Parameter | Description
sName | The control's unique name.

Example

dcltrans
  transaction TMain
  var
    sValue : string;
  begin
    OraFormsSetConnectMode(ORA_SOCKET_CONNECTION);
    // Connect - with connection properties
    OraFormsSetInt("INITIAL_VERSION", 608);
    OraFormsSetPoint("INITIAL_RESOLUTION", 96, 96);
    OraFormsSetPoint("INITIAL_DISP_SIZE", 1024, 768);
    OraFormsSetInt("INITIAL_COLOR_DEPTH", 256);
    OraFormsSetString("FONT_NAME", "Dialog");
    OraFormsSetPoint("INITIAL_SCALE_INFO", 8, 18);
    OraFormsSetBoolean("WINSYS_REQUIREDVA_LIST", false);
    OraFormsConnect("server module=Person3.fmx userid= useSDI=yes record=names");
    OraFormsSetWindow("Logon");
    OraFormsLogon("user", "password", "orcl_server");
    // ---
    // New window activated: WINDOW1
    OraFormsSetWindow("WINDOW1");
    OraFormsFlexShowValues("ADB Account");
  end TMain;

Parent topic: Control Functions


OraFormsGetClassIdFromControl Function

Action

This function returns the class id of a control specified by its handler title.

Include file

OraForms.bdh

Syntax

OraFormsGetClassIdFromControl(in sControl : string ) : number;

Return value

  • The class id of the control on success

  • 0 otherwise

Parameter | Description
sControl | The uniquely identifying id of the control.

Example

  transaction TMain
  var
    nFlexId : number;
    gnUmsg  : number;
    subMsg  : number;
    nClassId: number;
    nId     : number;  begin
    OraFormsSetConnectMode(ORA_HTTP_CONNECTION);
    // Connect - with connection properties
    OraFormsSetInt("INITIAL_VERSION", 608);
    OraFormsSetPoint("INITIAL_RESOLUTION", 96, 96);
    OraFormsSetPoint("INITIAL_DISP_SIZE", 1024, 768);
    OraFormsSetInt("INITIAL_COLOR_DEPTH", 256);
    OraFormsSetString("FONT_NAME", "Dialog");
    OraFormsSetPoint("INITIAL_SCALE_INFO", 8, 18);
    OraFormsSetBoolean("WINSYS_REQUIREDVA_LIST", false);
    OraFormsConnect("server module=Person3.fmx userid= useSDI=yes record=names");
    // New window activated: Logon
    OraFormsSetWindow("Logon");
    OraFormsLogon("user", "password", "orcl_server");

    OraFormsBeginMessageBlock("Block#2");
    gnUmsg := OraFormsCreateMessage(20, 40, ORA_MSG_TYPE_UPDATE);
    subMsg := OraFormsCreateMessage(30, 40, ORA_MSG_TYPE_UPDATE);
    nClassId := OraFormsGetClassIdFromControl("pass_undersc");
    nId := OraFormsGetIdFromControl("pass_undersc");
    OraFormsAddPropertyMessage(gnUmsg, ORA_PID_BP_FOREFILLCOL, subMsg);
    OraFormsAddPropertyInt(gnUmsg, 2601, 91);
    OraFormsAddPropertyInt(gnUmsg, 2600, 0);
    OraFormsAddPropertyBoolean(gnUmsg, 2600, false);
    OraFormsAddPropertyPoint(gnUmsg, ORA_PID_INITIAL_RESOLUTION, 0, 0);
    OraFormsAddPropertyString(gnUmsg, 2600, "E");
    OraFormsPutMessage(gnUmsg);
    OraFormsPutTerminalAndWait();
    OraFormsFree(gnUmsg);
    OraFormsEndMessageBlock("Block#2")
  end TMain;
Parent topic: Control Functions


OraFormsGetInterceptedControlId Function

Action

Returns the id of the intercepted control.

Include file

OraForms.bdh

Syntax

OraFormsGetInterceptedControlId( ) : number;

Return value

  • The id of the control on success

  • 0 otherwise

Example

  transaction TMain
  var
    nFlexId : number;
    nItc    : number;
    gnUmsg  : number;
    subMsg  : number;
    nClassId: number;
    nId     : number;
  begin
    OraFormsSetConnectMode(ORA_HTTP_CONNECTION);
    // Connect - with connection properties
    OraFormsSetInt("INITIAL_VERSION", 608);
    OraFormsSetPoint("INITIAL_RESOLUTION", 96, 96);
    OraFormsSetPoint("INITIAL_DISP_SIZE", 1024, 768);
    OraFormsSetInt("INITIAL_COLOR_DEPTH", 256);
    OraFormsSetString("FONT_NAME", "Dialog");
    OraFormsSetPoint("INITIAL_SCALE_INFO", 8, 18);
    OraFormsSetBoolean("WINSYS_REQUIREDVA_LIST", false);
    OraFormsConnect("server module=Person3.fmx userid= useSDI=yes record=names");
    // New window activated: Logon
    OraFormsSetWindow("Logon");
    OraFormsLogon("user", "password", "orcl_server");

    OraFormsBeginMessageBlock("Block#2");
    gnUmsg := OraFormsCreateMessage(20, 40, ORA_MSG_TYPE_UPDATE);
    subMsg := OraFormsCreateMessage(30, 40, ORA_MSG_TYPE_UPDATE);
    nClassId := OraFormsGetClassIdFromControl("pass_undersc");
    nId := OraFormsGetIdFromControl("pass_undersc");
    OraFormsAddPropertyMessage(gnUmsg, ORA_PID_BP_FOREFILLCOL, subMsg);
    OraFormsAddPropertyInt(gnUmsg, 2601, 91);
    OraFormsAddPropertyInt(gnUmsg, 2600, 0);
    OraFormsAddPropertyBoolean(gnUmsg, 2600, false);
    OraFormsAddPropertyPoint(gnUmsg, ORA_PID_INITIAL_RESOLUTION, 0, 0);
    OraFormsAddPropertyString(gnUmsg, 2600, "E");
    OraFormsPutMessage(gnUmsg);
    OraFormsPutTerminalAndWait();
    OraFormsFree(gnUmsg);
    OraFormsEndMessageBlock("Block#2");

    nItc := OraFormsRegisterMessageInterceptor(1020);
    OraFormsKeyStroke("VNDR_END_DATE_ACTIVE_MIR_0", ORA_KEY_TAB, 0);// Inactive On
    nFlexId := OraFormsGetInterceptedControlId();
    OraFormsUnregisterMessageInterceptor(nItc);
    Print ("here is the id");
    Print(string(nflexId));
  end TMain;
Parent topic: Control Functions


OraFormsGetInterceptedControlTitle Function

Action

Returns the title property of the intercepted control.

Include file

OraForms.bdh

Syntax

OraFormsGetInterceptedControlTitle( ) : string;

Return value

  • The title on success

  • Null otherwise

Example

  transaction TMain
  var
    nFlexId : number;
    nItc    : number;
    gnUmsg  : number;
    subMsg  : number;
    nClassId: number;
    nId     : number;
    sTitle  : string;
  begin
    OraFormsSetConnectMode(ORA_HTTP_CONNECTION);
    // Connect - with connection properties
    OraFormsSetInt("INITIAL_VERSION", 608);
    OraFormsSetPoint("INITIAL_RESOLUTION", 96, 96);
    OraFormsSetPoint("INITIAL_DISP_SIZE", 1024, 768);
    OraFormsSetInt("INITIAL_COLOR_DEPTH", 256);
    OraFormsSetString("FONT_NAME", "Dialog");
    OraFormsSetPoint("INITIAL_SCALE_INFO", 8, 18);
    OraFormsSetBoolean("WINSYS_REQUIREDVA_LIST", false);
    OraFormsConnect("server module=Person3.fmx userid= useSDI=yes record=names");
    // New window activated: Logon
    OraFormsSetWindow("Logon");
    OraFormsLogon("user", "password", "orcl_server");

    OraFormsBeginMessageBlock("Block#2");
    gnUmsg := OraFormsCreateMessage(20, 40, ORA_MSG_TYPE_UPDATE);
    subMsg := OraFormsCreateMessage(30, 40, ORA_MSG_TYPE_UPDATE);
    nClassId := OraFormsGetClassIdFromControl("pass_undersc");
    nId := OraFormsGetIdFromControl("pass_undersc");
    OraFormsAddPropertyMessage(gnUmsg, ORA_PID_BP_FOREFILLCOL, subMsg);
    OraFormsAddPropertyInt(gnUmsg, 2601, 91);
    OraFormsAddPropertyInt(gnUmsg, 2600, 0);
    OraFormsAddPropertyBoolean(gnUmsg, 2600, false);
    OraFormsAddPropertyPoint(gnUmsg, ORA_PID_INITIAL_RESOLUTION, 0, 0);
    OraFormsAddPropertyString(gnUmsg, 2600, "E");
    OraFormsPutMessage(gnUmsg);
    OraFormsPutTerminalAndWait();
    OraFormsFree(gnUmsg);
    OraFormsEndMessageBlock("Block#2");
    nItc := OraFormsRegisterMessageInterceptor(1020);
    OraFormsKeyStroke("VNDR_END_DATE_ACTIVE_MIR_0", ORA_KEY_TAB, 0);

    // Inactive On
    sTitle := OraFormsGetInterceptedControlTitle();
    OraFormsUnregisterMessageInterceptor(nItc);
    Print ("here is the title");
    Print(string(nflexId));
  end TMain;
Parent topic: Control Functions


OraFormsGetSessionId Function

Action

Once a connection with the Oracle Forms server is established, OraFormsGetSessionId can be used to capture the session ID cookie that was returned by the server during the connect process. The Recorder automatically scripts OraFormsGetSessionId and a WebCookieSet with the session ID on the applet's codebase. This ensures that all recorded HTTP requests use the session ID when additional files are requested that require valid session ID’s.

Include file

OraForms.bdh

Syntax

OraFormsGetSessionId( out sSessionId : string ) : boolean;

Return value

  • true if successful

  • false otherwise

Parameter | Description
sSessionId | Contains the session cookie returned by the server during the connection process.

Example

dcltrans
  transaction TMain
  begin
    OraFormsSetBoolean("WINSYS_REQUIREDVA_LIST", false);
    OraFormsSetString("DEFAULT_LOCAL_TZ", "Europe/Berlin");
    OraFormsConnect("server module=javamail90.fmx usesdi=yes userid= "
                    "sso_userid=  temp_dir=C:\\orant\\forms90\\demos\\temp",
                    "http://myserver:8888/forms90demo/l90servlet?ifcfs=/forms90demo/f90servlet?config=iorg",
                    "http://myserver:8888/forms90demo/");
    OraFormsGetSessionId(gsSSessionID);
    WebCookieSet(gsSSessionID, "http://myserver:8888/forms90demo/java/");
  end TMain;
Parent topic: Control Functions


OraFormsKeyStroke Function

Action

OraFormsKeyStroke sends a special key to the server (e.g., a tab key).

Include file

OraForms.bdh

Syntax

OraFormsEditSet(  in sName :  string,
                  in nChar :  number,
                  in nMod  :  number ) :  boolean;

Return value

  • true if successful
  • false otherwise
Parameter | Description
sName | The unique name of the control where the special key is pressed.
nChar The ascii code of the special key that should be pressed. There are some constants that can be used for the most common special keys:
  • ORA_KEY_TAB
  • ORA_KEY_ENTER
  • ORA_KEY_PAGEUP
  • ORA_KEY_PAGEDOWN
  • ORA_KEY_LINEUP
  • ORA_KEY_LINEDOWN
nMod This parameter can be used to define a key modifier. A key modifier is a special key that is additionally pressed when pressing a special key. The following constants are available:
  • ORA_SKEY_ALTGR
  • ORA_SKEY_SHIFT
  • ORA_SKEY_CTRL
  • ORA_SKEY_META
  • ORA_SKEY_ALT
If no modifier should be used, pass 0 for this parameter.

Example

dcltrans
  transaction TMain
  var
    sValue :  string;
  begin
    OraFormsSetConnectMode(ORA_SOCKET_CONNECTION);
    // Connect - with connection properties
    OraFormsSetInt( "INITIAL_VERSION", 608);
    OraFormsSetPoint( "INITIAL_RESOLUTION", 96,  96);
    OraFormsSetPoint( "INITIAL_DISP_SIZE", 1024,  768);
    OraFormsSetInt( "INITIAL_COLOR_DEPTH", 256);
    OraFormsSetString( "FONT_NAME" , "Dialog" );
    OraFormsSetPoint( "INITIAL_SCALE_INFO",  8,  18);
    OraFormsSetBoolean( "WINSYS_REQUIREDVA_LIST",  false);
    OraFormsConnect( "server module=Person3.fmx userid= useSDI=yes record=names");
    OraFormsSetWindow( "Logon");
    OraFormsLogon( "user",  "password",  "orcl_server");
    // ---
    // New window activated: WINDOW1
    OraFormsSetWindow( "WINDOW1");
    OraFormsEditSet( "PERSON_FIRST_NAME", "Andi");
    OraFormsKeyStroke( "PERSON_FIRST_NAME", ORA_KEY_TAB,  0);
    OraFormsEditSet( "PERSON_LAST_NAME", "GRABNER", ORA_EDIT_SEND_DIRTY,  "Reithmayr");
    OraFormsMenuItem( "WINDOW1",  "Action::Exit");
  end TMain;
Parent topic: Control Functions


OraFormsJavaContainerAction Function

Action

OraFormsJavaContainerAction allows you to call a function of the Java object that is hosted in the Java container on the current window. Different parameters for the function call can be set by preceding OraFormsSet{Type} calls. For each parameter, EVENT_ARGNAME and EVENT_ARGVALUE must be set. See the sample below.

Include file

OraForms.bdh

Syntax

OraFormsJavaContainerAction(  in sName :  string,
                              in sAction :  string ) :  boolean;

Return value

  • true if successful
  • false otherwise
Parameter | Description
sName | Name of the Java container that is hosted in the current application.
sAction | The name of the function that should be called.

Example

dcltrans
  transaction TMain
  var
    sValue :  string;
  begin
    OraFormsSetConnectMode(ORA_SOCKET_CONNECTION);
    // Connect - with connection properties
    OraFormsSetInt( "INITIAL_VERSION", 608);
    OraFormsSetPoint( "INITIAL_RESOLUTION", 96,  96);
    OraFormsSetPoint( "INITIAL_DISP_SIZE", 1024,  768);
    OraFormsSetInt( "INITIAL_COLOR_DEPTH", 256);
    OraFormsSetString( "FONT_NAME" , "Dialog" );
    OraFormsSetPoint( "INITIAL_SCALE_INFO", 8,  18);
    OraFormsSetBoolean( "WINSYS_REQUIREDVA_LIST",  false);
    OraFormsConnect( "server module=Person3.fmx userid= useSDI=yes record=names");
    OraFormsSetWindow( "Logon");
    OraFormsLogon( "user",  "password",  "orcl_server");
    OraFormsSetString( "EVENT_ARGNAME", "FileName");
    OraFormsSetString( "EVENT_ARGVALUE", "test.txt");
    OraFormsJavaContainerAction( "JAVA_UPLOAD",  "UploadFile");
    OraFormsMenuItem( "WINDOW1",  "Action::Exit");
  end TMain;
Parent topic: Control Functions


OraFormsMenuCreate Function

Action

OraFormsMenuCreate can be used to activate a pop-up menu that is assigned to a control on a window. Popup menus are normally activated by a right-click in the control area.

Include file

OraForms.bdh

Syntax

OraFormsMenuCreate(  in sWindowName :  string,
                     in nX          :  number optional,
                     in nY          :  number optional ) : boolean;

Return value

  • true if successful
  • false otherwise

Example

 transaction TMain
  var
    sValue :  string;
    nFetched :  number;
  begin
    OraFormsSetConnectMode(ORA_SOCKET_CONNECTION);
    // Connect - with connection properties OraFormsSetInt( "INITIAL_VERSION", 608);
    OraFormsSetPoint( "INITIAL_RESOLUTION", 96,  96);
    OraFormsSetPoint( "INITIAL_DISP_SIZE", 1024,  768);
    OraFormsSetInt( "INITIAL_COLOR_DEPTH", 256);
    OraFormsSetString( "FONT_NAME" , "Dialog" );
    OraFormsSetPoint( "INITIAL_SCALE_INFO", 8,  18);
    OraFormsSetBoolean( "WINSYS_REQUIREDVA_LIST",  false);
    OraFormsConnect( "server module=Person3.fmx userid= useSDI=yes record=names");
    OraFormsSetWindow( "Logon"); OraFormsLogon( "user",  "password",  "orcl_server");
    // ---
    // New window activated: WINDOW1
    OraFormsSetWindow( "WINDOW1");
    OraFormsSetFocus( "PERSON_JOB_0");
    OraFormsMenuCreate( "PERSON_JOB_0",  109, 12);
    OraFormsMenuItem( "PERSON_JOB_0",  "Action1");
    OraFormsMenuItem( "WINDOW1",  "Action::Exit");
  end  TMain;
Parent topic: Control Functions


OraFormsMenuItem Function

Action

OraFormsMenuItem can select a menu item from a pop-up menu that is assigned to a control or from a main menu that is assigned to a form window. Or it can be used to select a button in a form window's toolbar.

Include file

OraForms.bdh

Syntax

OraFormsMenuItem ( in sWindowName :  string,
                   in sMenuName   :  string) : boolean;

Return value

  • true if successful
  • false otherwise
Parameter | Description
sWindowName | Unique name of the control or window that has an assigned toolbar or main window. Or where a pop-up menu has recently been activated by OraFormsMenuCreate.
sMenuName | The name of the menu item that should be selected. For pop-up menus, the item name is sufficient. For main menu items, the name consists of several parts where different parts are separated by '::'. The last part is the menu item. The parts preceding are names of the main or sub menus.

Example

transaction TMain
  var
    sValue :  string;
    nFetched :  number;
  begin
    OraFormsSetConnectMode(ORA_SOCKET_CONNECTION);
    // Connect - with connection properties
    OraFormsSetInt( "INITIAL_VERSION", 608);
    OraFormsSetPoint( "INITIAL_RESOLUTION", 96,  96);
    OraFormsSetPoint( "INITIAL_DISP_SIZE", 1024,  768);
    OraFormsSetInt( "INITIAL_COLOR_DEPTH", 256);
    OraFormsSetString( "FONT_NAME" , "Dialog" );
    OraFormsSetPoint( "INITIAL_SCALE_INFO", 8,  18);
    OraFormsSetBoolean( "WINSYS_REQUIREDVA_LIST",  false);
    OraFormsConnect( "server module=Person3.fmx userid= useSDI=yes record=names");
    // ---
    // New window activated: WINDOW1
    OraFormsSetWindow( "WINDOW1");
    OraFormsSetFocus( "PERSON_JOB_0");
    OraFormsMenuCreate( "PERSON_JOB_0", 109,  12);
    OraFormsMenuItem( "PERSON_JOB_0",  "Action1");

    OraFormsMenuItem( "WINDOW1",  "Action::Exit");
  end  TMain;
Parent topic: Control Functions


OraFormsMessageBoxButton Function

Action

OraFormsMessageBoxButton can be used to close a message box by choosing one of the available buttons (YES, NO, or CANCEL).

Include file

OraForms.bdh

Syntax

OraFormsMessageBoxButton( in sWindowName : string,
                          in nButton     :  number ) : boolean;

Return value

  • true if successful
  • false otherwise
Parameter | Description
sWindowName | Name of the message box dialog.
nButton

The button that should be pressed to close the message box. There are some predefined constants that can be used:

  • ORA_ALERT_YES
  • ORA_ALERT_NO
  • ORA_ALERT_CANCEL

Be aware that there are Oracle Forms applications with message boxes that use labels other than YES, NO and CANCEL for their buttons.

Example

 transaction TMain
  var
    sValue :  string;
    nFetched :  number;
  begin
    OraFormsSetConnectMode(ORA_SOCKET_CONNECTION);
    // Connect - with connection properties
    OraFormsSetInt( "INITIAL_VERSION", 608);
    OraFormsSetPoint( "INITIAL_RESOLUTION", 96,  96);
    OraFormsSetPoint( "INITIAL_DISP_SIZE", 1024,  768);
    OraFormsSetInt( "INITIAL_COLOR_DEPTH", 256);
    OraFormsSetString( "FONT_NAME" , "Dialog" );
    OraFormsSetPoint( "INITIAL_SCALE_INFO", 8,  18);
    OraFormsSetBoolean( "WINSYS_REQUIREDVA_LIST",  false);
    OraFormsConnect( "server module=Person3.fmx userid= useSDI=yes record=names");
    // ---
    // New window activated: WINDOW1
    OraFormsSetWindow( "WINDOW1");
    OraFormsMenuItem( "WINDOW1",  "Action::Calculator");
    // Do you want to do the calculation?
    OraFormsMessageBoxButton( "Do the calculation?", ORA_ALERT_YES);
    OraFormsMenuItem( "WINDOW1",  "Action::Exit");
  end TMain;
Parent topic: Control Functions


OraFormsMouseClick Function

Action

OraFormsMouseClick can be used to simulate a single mouse click on a control or form window.

Include

OraForms.bdh

Syntax

OraFormsMouseClick(  in sName :  string,
                     in nX    :  number,
                     in nY    :  number,
                     in nMod  :  number optional ) :  boolean;

Return value

  • true if successful
  • false otherwise
Parameter | Description
sName | Unique name of the control or window on which the mouse click should occur.
nX | X-Coordinate of the mouse click.
nY | Y-Coordinate of the mouse click.
nMod

(optional):

This parameter can be used to define a key modifier. A key modifier is a special key that is additionally pressed when the mouse button is clicked. The following constants are available:

  • ORA_SKEY_ALTGR
  • ORA_SKEY_SHIFT
  • ORA_SKEY_CTRL
  • ORA_SKEY_META
  • ORA_SKEY_ALT

If no modifier should be used, pass 0 for this parameter.

Example

transaction TMain
  var
    sValue :  string;
    nFetched :  number;
  begin
    OraFormsSetConnectMode(ORA_SOCKET_CONNECTION);
    // Connect - with connection properties
    OraFormsSetInt( "INITIAL_VERSION", 608);
    OraFormsSetPoint( "INITIAL_RESOLUTION", 96,  96);
    OraFormsSetPoint( "INITIAL_DISP_SIZE", 1024,  768);
    OraFormsSetInt( "INITIAL_COLOR_DEPTH", 256);
    OraFormsSetString( "FONT_NAME" , "Dialog" );
    OraFormsSetPoint( "INITIAL_SCALE_INFO", 8,  18);
    OraFormsSetBoolean( "WINSYS_REQUIREDVA_LIST",  false);
    OraFormsConnect( "server module=Person3.fmx userid= useSDI=yes record=names");
    // ---
    // New window activated: WINDOW1
    OraFormsSetWindow( "WINDOW1");
    OraFormsMouseClick( "TREE_BLK_PROD_TREE_0",  65,  125,  0);
    OraFormsMouseDblClick( "TREE_BLK_PROD_TREE_0",  65,  125,  0);

    OraFormsMenuItem( "WINDOW1",  "Action::Exit");
  end  TMain;
Parent topic: Control Functions


OraFormsMouseDblClick Function

Action

OraFormsMouseDblClick can be used to simulate a double mouse click on a control or form window.

Include file

OraForms.bdh

Syntax

OraFormsMouseDblClick(  in sName :  string,
                        in nX    :  number,
                        in nY    :  number,
                        in nMod  :  number optional ) : boolean;

Return value

  • true if successful
  • false otherwise
Parameter | Description
sName | Unique name of the control or window on which the double mouse click is to occur.
nX | X-Coordinate of the double mouse click.
nY | Y-Coordinate of the double mouse click.
nMod

(optional):

This parameter can be used to define a key modifier. A key modifier is a special key that is additionally pressed when the mouse button is double clicked. The following constants are available:

  • ORA_SKEY_ALTGR
  • ORA_SKEY_SHIFT
  • ORA_SKEY_CTRL
  • ORA_SKEY_META
  • ORA_SKEY_ALT

If no modifier should be used, pass 0 for this parameter.

Example

transaction TMain
  var
    sValue :  string;
    nFetched :  number;
  begin
    OraFormsSetConnectMode(ORA_SOCKET_CONNECTION);
    // Connect - with connection properties
    OraFormsSetInt( "INITIAL_VERSION", 608);
    OraFormsSetPoint( "INITIAL_RESOLUTION", 96,  96);
    OraFormsSetPoint( "INITIAL_DISP_SIZE", 1024,  768);
    OraFormsSetInt( "INITIAL_COLOR_DEPTH", 256);
    OraFormsSetString( "FONT_NAME" , "Dialog" );
    OraFormsSetPoint( "INITIAL_SCALE_INFO", 8,  18);
    OraFormsSetBoolean( "WINSYS_REQUIREDVA_LIST",  false);
    OraFormsConnect( "server module=Person3.fmx userid= useSDI=yes record=names");
    // ---
    // New window activated: WINDOW1
    OraFormsSetWindow( "WINDOW1");
    OraFormsMouseClick( "TREE_BLK_PROD_TREE_0",  65,  125,  0);
    OraFormsMouseDblClick( "TREE_BLK_PROD_TREE_0",  65,  125,  0);
    OraFormsMenuItem( "WINDOW1",  "Action::Exit");
  end  TMain;
Parent topic: Control Functions


OraFormsOnMessageGet Function

Action

OraFormsOnMessageGet allows you to define properties that can be queried by the server. The Oracle Forms Server sometimes queries controls for their internal property values. You can use OraFormsSet{Type} methods to define several property values that will be assigned to a control in the following OraFormsOnMessageGet and will be returned to the server if there is a request message.

Include file

OraForms.bdh

Syntax

OraFormsOnMessageGet( in sName : string ) : boolean;

Return value

  • true if successful
  • false otherwise
Parameter | Description
sName | The unique name or ID of the control/component that may be queried by the server.

Example

transaction TMain
  var
    sValue :  string;
    nFetched :  number;
  begin
    OraFormsSetConnectMode(ORA_SOCKET_CONNECTION);
    // Connect - with connection properties
    OraFormsSetInt( "INITIAL_VERSION", 608);
    OraFormsSetPoint( "INITIAL_RESOLUTION", 96,  96);
    OraFormsSetPoint( "INITIAL_DISP_SIZE", 1024,  768);
    OraFormsSetInt( "INITIAL_COLOR_DEPTH", 256);
    OraFormsSetString( "FONT_NAME" , "Dialog" );
    OraFormsSetPoint( "INITIAL_SCALE_INFO", 8,  18);
    OraFormsSetBoolean( "WINSYS_REQUIREDVA_LIST",  false);
    OraFormsConnect( "server module=Person3.fmx userid= useSDI=yes record=names");
    // New window activated: Logon
    OraFormsSetWindow( "Logon");
    OraFormsLogon( "user",  "password",  "orcl_server");
    OraFormsSetRectangle("VISIBLERECT", 0, 0, 119, 24, ORA_SET_TYPE_MESSAGEGET);
    OraFormsOnMessageGet("LINE_CUSTOMER_ITEM_DSP_0"); // Requested Item
    OraFormsMouseClick("LINE_CUSTOMER_ITEM_DSP_0", 70, 18, 0); // Requested Item
  end  TMain;

Parent topic: Control Functions


OraFormsListActivate Function

Action

OraFormsListActivate is used to send an activate message for an element in a list box control. A control is identified by a unique name or ID.

Include file

OraForms.bdh

Syntax

OraFormsListActivate( in sName     : string,
                      in sLabel    : string,
                      in nIndex    : number optional,
                      in nPosition : number optional ) : boolean;

Return value

  • true if successful

  • false otherwise

Parameter | Description
sName | The control's unique ID.
sLabel | (if not NULL) The element with the defined label (textual representation) will be activated. If you pass NULL, you must define the index of the item that is to be activated in the next parameter.
nIndex | (if sLabel is NULL) This parameter defines the index of the element that is to be activated. The index of the first element is 0.
nPosition | If the control contains multiple entries with the same label, this parameter will be used to specify the nth position. The default value is 0.

Example

dcltrans
  transaction TMain
  var
    sValue   : string;
  begin
    OraFormsSetConnectMode(ORA_SOCKET_CONNECTION);
    // Connect - with connection properties
    OraFormsSetInt("INITIAL_VERSION", 608);
    OraFormsSetPoint("INITIAL_RESOLUTION", 96, 96);
    OraFormsSetPoint("INITIAL_DISP_SIZE", 1024, 768);
    OraFormsSetInt("INITIAL_COLOR_DEPTH", 256);
    OraFormsSetString("FONT_NAME", "Dialog");
    OraFormsSetPoint("INITIAL_SCALE_INFO", 8, 18);
    OraFormsSetBoolean("WINSYS_REQUIREDVA_LIST", false);
    OraFormsConnect("server module=Person3.fmx userid= useSDI=yes record=names");
    OraFormsSetWindow("Logon");
    OraFormsLogon("user", "password", "orcl_server");
    // ---
    // New window activated: WINDOW1
    OraFormsSetWindow("WINDOW1");
    OraFormsSetFocus("PERSON_GENDER");
    OraFormsListActivate("PERSON_GENDER", "Male", 0);
    OraFormsListClose("PERSON_GENDER");
  end TMain;
Parent topic: Control Functions


OraFormsListClose Function

Action

OraFormsListClose can be used to close an open list box without selecting a new value. There is no actual command that opens the box. This method simulates the complete sequence of opening and closing a list box without selecting a value. To select a value, use OraFormsListSelect. A list box is identified by its unique name or ID.

Include file

OraForms.bdh

Syntax

OraFormsListClose( in  sName : string) : boolean;

Return value

  • true if successful
  • false otherwise
Parameter | Description
sName | The control's unique name

Example

transaction TMain
  var
    sValue :  string;
    nFetched :  number;
  begin
    OraFormsSetConnectMode(ORA_SOCKET_CONNECTION);
    // Connect - with connection properties
    OraFormsSetInt( "INITIAL_VERSION",  608);
    OraFormsSetPoint( "INITIAL_RESOLUTION", 96,  96);
    OraFormsSetPoint( "INITIAL_DISP_SIZE", 1024,  768);
    OraFormsSetInt( "INITIAL_COLOR_DEPTH", 256);
    OraFormsSetString( "FONT_NAME" , "Dialog" );
    OraFormsSetPoint( "INITIAL_SCALE_INFO", 8,  18);
    OraFormsSetBoolean( "WINSYS_REQUIREDVA_LIST", false);
    OraFormsConnect( "server module=Person3.fmx userid= useSDI=yes record=names");
    // New window activated: Logon OraFormsSetWindow( "Logon");
    OraFormsLogon( "user",  "password",  "orcl_server");
    // ---
    // New window activated: WINDOW1
    OraFormsSetWindow( "WINDOW1");
    OraFormsSetFocus( "PERSON_GENDER");
    OraFormsListSelect( "PERSON_GENDER", "Male",  0);
    OraFormsListClose( "PERSON_GENDER");
    OraFormsMenuItem( "WINDOW1",  "Action::Exit");
  end  TMain;
Parent topic: Control Functions


OraFormsListSelect Function

Action

OraFormsListSelect selects an entry in a list box. The element that is to be selected can either be defined by its textual representation or by its index. A list box is identified by a unique name or ID.

Include file

OraForms.bdh

Syntax

OraFormsListSelect(    in sName     : string,
                       in sLabel    : string,
                       in nIndex    : number optional,
                       in nPosition : number optional ) : boolean;

Return value

  • true if successful

  • false otherwise

Parameter | Description
sName | The control's unique ID.
sLabel | (if not NULL) The element with the defined label (textual representation) will be selected. If you pass NULL, in the next parameter, you have to define the index of the item that is to be selected.
nIndex | (if sLabel is NULL) This parameter defines the index of the element that is to be selected. The index of the first element is 0.
nPosition | If the control contains multiple entries with the same label, this parameter will be used to specify the nth position. The default value is 0.

Example

dcltrans
  transaction TMain
  var
    sValue   : string;
  begin
    OraFormsSetConnectMode(ORA_SOCKET_CONNECTION);
    // Connect - with connection properties
    OraFormsSetInt("INITIAL_VERSION", 608);
    OraFormsSetPoint("INITIAL_RESOLUTION", 96, 96);
    OraFormsSetPoint("INITIAL_DISP_SIZE", 1024, 768);
    OraFormsSetInt("INITIAL_COLOR_DEPTH", 256);
    OraFormsSetString("FONT_NAME", "Dialog");
    OraFormsSetPoint("INITIAL_SCALE_INFO", 8, 18);
    OraFormsSetBoolean("WINSYS_REQUIREDVA_LIST", false);
    OraFormsConnect("server module=Person3.fmx userid= useSDI=yes record=names");
    OraFormsSetWindow("Logon");
    OraFormsLogon("user", "password", "orcl_server");
    // ---
    // New window activated: WINDOW1
    OraFormsSetWindow("WINDOW1");
    OraFormsSetFocus("PERSON_GENDER");
    OraFormsListSelect("PERSON_GENDER", "Male", 0);
    OraFormsListClose("PERSON_GENDER");
    OraFormsMenuItem("WINDOW1", "Action::Exit");
  end TMain;
Parent topic: Control Functions


OraFormsLogon Function

Action

Performs a logon to an Oracle Forms Server.

Include file

OraForms.bdh

Syntax

OraFormsLogon(  in sUser     :  string,
                in sPassword :  string,
                in sDatabase :  string ) :  boolean;

Return value

  • true if successful
  • false otherwise
Parameter | Description
sUser | User name for an Oracle database.
sPassword | The user's password.
sDatabase | Oracle TNS name.

Example

dcltrans
  transaction TMain
  begin
    OraFormsConnect( "server module=module.fmx userid= useSDI=yes");
    OraFormsSetWindow( "Logon");
    OraFormsLogon( "user",  "password",  "orcl_server");
  end TMain;
Parent topic: Control Functions


OraFormsLogonCancel Function

Action

Cancels a logon dialog by pressing the "Cancel" button.

Include file

OraForms.bdh

Syntax

OraFormsLogonCancel( ) : boolean;

Return value

  • true if successful
  • false otherwise

Example

dcltrans
  transaction TMain
  begin
    OraFormsConnect( "server module=module.fmx userid= useSDI=yes");
    OraFormsSetWindow( "Logon");
    OraFormsLogonCancel();
  end TMain;
Parent topic: Control Functions


OraFormsLovAutoReduceChar Function

Action

OraFormsLovAutoReduceChar sends an auto-reduce message to a List Of Values dialog.

Include file

OraForms.bdh

Syntax

OraFormsLovAutoReduceChar(    in sName      : string,
                              in nCharacter : number,
                              in nOption    : number ) : boolean;

Return value

  • true if successful

  • false otherwise

Parameter | Description
sName | Unique name of the control where the List Of Values dialog is opened.
nCharacter | The ordinal number of the character to be sent.
nOptions | (unspecified) This value is 0 by default.

Example

dcltrans
  transaction TMain
  var
    sValue   : string;
  begin
    OraFormsSetConnectMode(ORA_SOCKET_CONNECTION);
    // Connect - with connection properties
    OraFormsSetInt("INITIAL_VERSION", 608);
    OraFormsSetPoint("INITIAL_RESOLUTION", 96, 96);
    OraFormsSetPoint("INITIAL_DISP_SIZE", 1024, 768);
    OraFormsSetInt("INITIAL_COLOR_DEPTH", 256);
    OraFormsSetString("FONT_NAME", "Dialog");
    OraFormsSetPoint("INITIAL_SCALE_INFO", 8, 18);
    OraFormsSetBoolean("WINSYS_REQUIREDVA_LIST", false);
    OraFormsConnect("server module=Person3.fmx userid= useSDI=yes record=names");
    OraFormsSetWindow("Logon");
    OraFormsLogon("user", "password", "orcl_server");
    // ---
    // New window activated: WINDOW1
    OraFormsSetWindow("WINDOW1");
    OraFormsSetFocus("PERSON_GENDER");
    OraFormsLovAutoReduceChar("PERSON_GENDER", 114, 0);
    OraFormsLovUnReduce("PERSON_GENDER");
  end TMain;
Parent topic: Control Functions


OraFormsLovFind Function

Action

OraFormsLovFind allows you to define a new search pattern for the List Of Values dialog.

Include file

OraForms.bdh

Syntax

OraFormsLovFind( in sName       : string,
                 in sPattern    : string) : boolean

Return value

  • true if successful
  • false otherwise
Parameter | Description
sName | Unique name of the control where the List Of Values dialog is opened.
sPattern | The new search pattern for the List Of Values dialog.

Example

transaction TMain
  var
    sValue :  string;
    nFetched :  number;
  begin
    OraFormsSetConnectMode(ORA_SOCKET_CONNECTION);
    // Connect - with connection properties
    OraFormsSetInt( "INITIAL_VERSION", 608);
    OraFormsSetPoint( "INITIAL_RESOLUTION",  96,  96);
    OraFormsSetPoint( "INITIAL_DISP_SIZE",  1024,  768);
    OraFormsSetInt( "INITIAL_COLOR_DEPTH", 256);
    OraFormsSetString( "FONT_NAME" , "Dialog" );
    OraFormsSetPoint( "INITIAL_SCALE_INFO", 8,  18);
    OraFormsSetBoolean( "WINSYS_REQUIREDVA_LIST",  false);
    OraFormsConnect( "server module=Person3.fmx userid= useSDI=yes record=names");
    // New window activated: Logon OraFormsSetWindow( "Logon");
    OraFormsLogon( "user",  "password",  "orcl_server");
    // ---
    // New window activated: WINDOW1
    OraFormsSetWindow( "WINDOW1");
    OraFormsMenuItem( "FENSTER1",  "Edit::Display List...");
    OraFormsSetWindow( "lovjob");
    OraFormsLovOpen( "lovjob", nFetched);
    OraFormsLovFind( "lovjob",  "%S%");
    OraFormsLovSelect( "lovjob",  "SUPER-MAN");
    // ---
    // New window activated: WINDOW1
    OraFormsSetWindow( "WINDOW1");
    OraFormsMenuItem( "WINDOW1",  "Action::Exit");
  end  TMain;
Parent topic: Control Functions


OraFormsLovGetItems Function

Action

OraFormsLovGetItems retrieves a specified of number of LOV box entries from the server. OraFormsLovGetItems uses a 1-based index.

Include file

OraForms.bdh

Syntax

OraFormsLovGetItems( in sName      : string,
                     in nFirstItem : number,
                     in nItemCount : number ) : boolean;

Return value

  • true if successful

  • false otherwise

Parameter | Description
sName | The name of the LOV dialog.
nFirstItem | The index of the first item to be fetched. The index is 1-based.
nItemCount | The number of items to be fetched.

Example

dcltrans
  transaction TMain
  var
    sValue   : string;
  begin
    OraFormsSetConnectMode(ORA_SOCKET_CONNECTION);
    // Connect - with connection properties
    OraFormsSetInt("INITIAL_VERSION", 608);
    OraFormsSetPoint("INITIAL_RESOLUTION", 96, 96);
    OraFormsSetPoint("INITIAL_DISP_SIZE", 1024, 768);
    OraFormsSetInt("INITIAL_COLOR_DEPTH", 256);
    OraFormsSetString("FONT_NAME", "Dialog");
    OraFormsSetPoint("INITIAL_SCALE_INFO", 8, 18);
    OraFormsSetBoolean("WINSYS_REQUIREDVA_LIST", false);
    OraFormsConnect("server module=Person3.fmx userid= useSDI=yes record=names");
    OraFormsSetWindow("Logon");
    OraFormsLogon("user", "password", "orcl_server");
    // ---
    // New window activated: WINDOW1
    OraFormsSetWindow("WINDOW1");
    OraFormsLovOpen("Window Lov Dialog", 0, ORA_LOV_FETCHLATER);
    OraFormsLovGetItems("Window Lov Dialog", 1, 4);
  end TMain;
Parent topic: Control Functions


OraFormsLovOpen Function

Action

OraFormsLovOpen opens a List Of Values dialog for a text control that has a LOV assigned to it. The function also returns the initial number of items in the LOV when the LOV dialog is opened with the default search string.

Include file

OraForms.bdh

Syntax

OraFormsLovOpen( in sName          : string,
                 out nItemsFetched :  number,
                 in nFetchFlag     :  number optional ) :  boolean;

Return value

  • true if successful
  • false otherwise
Parameter | Description
sName | Unique name of the control where the List Of Values dialog should be opened.
nItemsFetched | Number of items that are returned by the default query string of the LOV Dialog.
nFetchFlag

(otional) Can be:

  • ORA_LOV_FETCHALL: Immediately retrieve all items for the LOV box.
  • ORA_LOV_FETCHLATER: Retrieve the items for the LOV box later with OraFormsLovGetItems.

Example

transaction TMain
  var
    sValue :  string;
    nFetched :  number;
  begin
    OraFormsSetConnectMode(ORA_SOCKET_CONNECTION);
    // Connect - with connection properties
    OraFormsSetInt( "INITIAL_VERSION", 608);
    OraFormsSetPoint( "INITIAL_RESOLUTION", 96,  96);
    OraFormsSetPoint( "INITIAL_DISP_SIZE", 1024,  768);
    OraFormsSetInt( "INITIAL_COLOR_DEPTH", 256);
    OraFormsSetString( "FONT_NAME" , "Dialog" );
    OraFormsSetPoint( "INITIAL_SCALE_INFO", 8,  18);
    OraFormsSetBoolean( "WINSYS_REQUIREDVA_LIST",  false);
    OraFormsConnect( "server module=Person3.fmx userid= useSDI=yes record=names");
    // New window activated: Logon
    OraFormsSetWindow( "Logon");
    OraFormsLogon( "user",  "password",  "orcl_server");
    // ---
    // New window activated: WINDOW1
    OraFormsSetWindow( "WINDOW1");
    OraFormsMenuItem( "FENSTER1",  "Edit::Display List...");

    OraFormsSetWindow( "lovjob");
    OraFormsLovOpen( "lovjob", nFetched);
    OraFormsLovFind( "lovjob",  "%S%");
    OraFormsLovSelect( "lovjob",  "SUPER-MAN");
    // ---
    // New window activated: WINDOW1
    OraFormsSetWindow( "WINDOW1");
    OraFormsMenuItem( "WINDOW1",  "Action::Exit");
  end  TMain;
Parent topic: Control Functions


OraFormsLovSelect Function

Action

OraFormsLovSelect allows you to select an entry of the search result in the List Of Values dialog. The value will be used in the control that has the List of Values assigned to it. The entry can either be defined by its value or by the index in the current search result.

Include file

OraForms.bdh

Syntax

OraFormsLovSelect(  in sName  :   string,
                    in sValue :  string,
                    in nIndex :  number optional ) : boolean;

Return value

  • true if successful
  • false otherwise
Parameter | Description
sName | Unique name of the control where the List Of Values dialog is opened.
sValue | The value that should be selected from the current LOV result. If NULL, the nIndex parameter can be used to define the index that should be selected.
nIndex | (optional) If sValue is NULL, this parameter can be used to define the index of the entry that should be selected.

Example

transaction TMain
  var
    sValue :  string;
    nFetched :  number;
  begin
    OraFormsSetConnectMode(ORA_SOCKET_CONNECTION);
    // Connect - with connection properties
    OraFormsSetInt( "INITIAL_VERSION", 608);
    OraFormsSetPoint( "INITIAL_RESOLUTION",96,  96);
    OraFormsSetPoint( "INITIAL_DISP_SIZE", 1024,  768);
    OraFormsSetInt( "INITIAL_COLOR_DEPTH", 256);
    OraFormsSetString( "FONT_NAME" , "Dialog" );
    OraFormsSetPoint( "INITIAL_SCALE_INFO", 8,  18);
    OraFormsSetBoolean( "WINSYS_REQUIREDVA_LIST",  false);
    OraFormsConnect( "server module=Person3.fmx userid= useSDI=yes record=names");
    // New window activated: Logon
    OraFormsSetWindow( "Logon");
    OraFormsLogon( "user",  "password",  "orcl_server");
    // ---
    // New window activated: WINDOW1
    OraFormsSetWindow( "WINDOW1");
    OraFormsMenuItem( "FENSTER1",  "Edit::Display List...");

    OraFormsSetWindow( "lovjob");
    OraFormsLovOpen( "lovjob", nFetched);
    OraFormsLovFind( "lovjob",  "%S%");
    OraFormsLovSelect( "lovjob",  "SUPER-MAN");
    // ---
    // New window activated: WINDOW1
    OraFormsSetWindow( "WINDOW1");
    OraFormsMenuItem( "WINDOW1",  "Action::Exit");
  end  TMain;
Parent topic: Control Functions


OraFormsLovUnReduce Function

Action

OraFormsLovUnReduce sends an un-reduce message to a List Of Values dialog.

Include file

OraForms.bdh

Syntax

OraFormsLovUnReduce( in sName  : string): boolean;

Return value

  • true if successful

  • false otherwise

Parameter | Description
sName | Unique name of the control where the List Of Values dialog is opened.

Example

dcltrans
  transaction TMain
  var
    sValue   : string;
  begin
    OraFormsSetConnectMode(ORA_SOCKET_CONNECTION);
    // Connect - with connection properties
    OraFormsSetInt("INITIAL_VERSION", 608);
    OraFormsSetPoint("INITIAL_RESOLUTION", 96, 96);
    OraFormsSetPoint("INITIAL_DISP_SIZE", 1024, 768);
    OraFormsSetInt("INITIAL_COLOR_DEPTH", 256);
    OraFormsSetString("FONT_NAME", "Dialog");
    OraFormsSetPoint("INITIAL_SCALE_INFO", 8, 18);
    OraFormsSetBoolean("WINSYS_REQUIREDVA_LIST", false);
    OraFormsConnect("server module=Person3.fmx userid= useSDI=yes record=names");
    OraFormsSetWindow("Logon");
    OraFormsLogon("user", "password", "orcl_server");
    // ---
    // New window activated: WINDOW1
    OraFormsSetWindow("WINDOW1");
    OraFormsSetFocus("PERSON_GENDER");
    OraFormsLovAutoReduceChar("PERSON_GENDER", 114, 0);
    OraFormsLovUnReduce("PERSON_GENDER");
  end TMain;
Parent topic: Control Functions


OraFormsRadioSet Function

Action

OraFormsRadioSet changes the selected state of a radio button control.

Include

OraForms.bdh

Syntax

OraFormsRadioSet( in sName : string, in bSet : boolean ) : boolean;

Return value

  • true if successful
  • false otherwise
Parameter | Description
sName | The control's unique name.
bSet

The new selected state value of the control.

  • TRUE: to select the control.
  • FALSE: to unselect the control.

Example

transaction TMain
  var
    sValue :  string;
  begin
    OraFormsSetConnectMode(ORA_SOCKET_CONNECTION);
    // Connect - with connection properties
    OraFormsSetInt( "INITIAL_VERSION", 608);
    OraFormsSetPoint( "INITIAL_RESOLUTION", 96,  96);
    OraFormsSetPoint( "INITIAL_DISP_SIZE", 1024,  768);
    OraFormsSetInt( "INITIAL_COLOR_DEPTH", 256);
    OraFormsSetString( "FONT_NAME" , "Dialog" );
    OraFormsSetPoint( "INITIAL_SCALE_INFO", 8,  18);
    OraFormsSetBoolean( "WINSYS_REQUIREDVA_LIST",  false);
    OraFormsConnect( "server module=Person3.fmx userid= useSDI=yes record=names");
    // New window activated: Logon
    OraFormsSetWindow( "Logon");
    OraFormsLogon( "user",  "password",  "orcl_server");
    // ---
    // New window activated: WINDOW1
    OraFormsSetWindow( "WINDOW1");
    OraFormsSetFocus( "PERSON_GENDER_MALE");
    OraFormsRadioSet( "PERSON_GENDER_MALE",  true);
  end  TMain;
Parent topic: Control Functions


OraFormsPopListActivate Function

Action

OraFormsPopListActivate is used to send an activate message for an element in a pop-up list box control. A control is identified by a unique name or ID.

Include file

OraForms.bdh

Syntax

OraFormsPopListActivate( in sName     :  string,
                         in sLabel    :  string,
                         in nIndex    :  number optional,
                         in nPosition :  number optional ) : boolean;

Return value

  • true if successful
  • false otherwise
Parameter | Description
sName | The control's unique ID.
sLabel | If not NULL - The element with the defined label (textual representation) will be activated. If you pass NULL, you have to define the index of the item that should be activated in the next parameter.
nIndex | If sLabel is NULL - This parameter defines the index of the element that should be activated. The index of the first element is 0.
nPosition | If the control contains multiple entries with the same label, this parameter will be used to specify the nth position. The default value is 0.

Example

transaction TMain
  var
    sValue :  string;
  begin
    OraFormsSetConnectMode(ORA_SOCKET_CONNECTION);
    // Connect - with connection properties
    OraFormsSetInt( "INITIAL_VERSION", 608);
    OraFormsSetPoint( "INITIAL_RESOLUTION",  96,  96);
    OraFormsSetPoint( "INITIAL_DISP_SIZE", 1024,  768);
    OraFormsSetInt( "INITIAL_COLOR_DEPTH", 256);
    OraFormsSetString( "FONT_NAME" , "Dialog" );
    OraFormsSetPoint( "INITIAL_SCALE_INFO",  8,  18);
    OraFormsSetBoolean( "WINSYS_REQUIREDVA_LIST",  false);
    OraFormsConnect( "server module=Person3.fmx userid= useSDI=yes record=names");
    // New window activated: Logon
    OraFormsSetWindow( "Logon");
    OraFormsLogon( "user",  "password",  "orcl_server");
    // ---
    // New window activated: WINDOW1
    OraFormsSetWindow( "WINDOW1");
    OraFormsSetFocus( "PERSON_GENDER");
    OraFormsPopListActivate( "PERSON_GENDER",  "Male",  0);
    OraFormsPopListClose( "PERSON_GENDER");
    OraFormsMenuItem( "WINDOW1",  "Action::Exit");
  end TMain;
Parent topic: Control Functions


OraFormsPopListClose Function

Action

OraFormsPopListClose can be used to close an open pop-up list box without selecting a new value. There is no actual command that opens the box. This method simulates the complete sequence of opening and closing a pop-up list box without selecting a value. To select a value, use OraFormsPopListSelect. A pop-up list box is identified by its unique name or ID.

Include file

OraForms.bdh

Syntax

OraFormsPopListClose( in sName : string ) : boolean;

Return value

  • true if successful
  • false otherwise
Parameter | Description
sName | The control's unique name.

Example

transaction TMain
  var
    sValue :  string;
  begin
    OraFormsSetConnectMode(ORA_SOCKET_CONNECTION);
    // Connect - with connection properties
    OraFormsSetInt( "INITIAL_VERSION", 608);
    OraFormsSetPoint( "INITIAL_RESOLUTION", 96,  96);
    OraFormsSetPoint( "INITIAL_DISP_SIZE", 1024,  768);
    OraFormsSetInt( "INITIAL_COLOR_DEPTH", 256);
    OraFormsSetString( "FONT_NAME" , "Dialog" );
    OraFormsSetPoint( "INITIAL_SCALE_INFO", 8,  18);
    OraFormsSetBoolean( "WINSYS_REQUIREDVA_LIST",  false);
    OraFormsConnect( "server module=Person3.fmx userid= useSDI=yes record=names");
    // New window activated: Logon
    OraFormsSetWindow( "Logon");
    OraFormsLogon( "user",  "password",  "orcl_server");
    // ---
    // New window activated: WINDOW1
    OraFormsSetWindow( "WINDOW1");
    OraFormsSetFocus( "PERSON_GENDER");
    OraFormsPopListSelect( "PERSON_GENDER", "Male",  0);
    OraFormsPopListClose( "PERSON_GENDER");
    OraFormsMenuItem( "WINDOW1",  "Action::Exit");
  end TMain;
Parent topic: Control Functions


OraFormsPopListSelect Function

Action

OraFormsPopListSelect selects an entry in a pop-up list. The element that is to be selected can either be defined by its textual representation or its index. A pop-up list is identified by a unique name or ID.

Include file

OraForms.bdh

Syntax

OraFormsPopListSelect( in sName    :  string;
                      in sLabel    :  string;
                      in nIndex    :  number optional,
                      in nPosition :  number optional ) : boolean;

Return value

  • true if successful
  • false otherwise
Parameter | Description
sName | The control's unique ID.
sLabel | If not NULL - The element with the defined label (textual representation) will be activated. If you pass NULL, you have to define the index of the item that should be activated in the next parameter.
nIndex | If sLabel is NULL - This parameter defines the index of the element that should be activated. The index of the first element is 0.
nPosition | If the control contains multiple entries with the same label, this parameter will be used to specify the nth position. The default value is 0.

Example

 transaction TMain
  var
    sValue :  string;
  begin
    OraFormsSetConnectMode(ORA_SOCKET_CONNECTION);
    // Connect - with connection properties
    OraFormsSetInt( "INITIAL_VERSION", 608);
    OraFormsSetPoint( "INITIAL_RESOLUTION",  96,  96);
    OraFormsSetPoint( "INITIAL_DISP_SIZE", 1024,  768);
    OraFormsSetInt( "INITIAL_COLOR_DEPTH", 256);
    OraFormsSetString( "FONT_NAME" , "Dialog" );
    OraFormsSetPoint( "INITIAL_SCALE_INFO",  8,  18);
    OraFormsSetBoolean( "WINSYS_REQUIREDVA_LIST",  false);
    OraFormsConnect( "server module=Person3.fmx userid= useSDI=yes record=names");
    // New window activated: Logon
    OraFormsSetWindow( "Logon");
    OraFormsLogon( "user",  "password",  "orcl_server");
    // ---
    // New window activated: WINDOW1
    OraFormsSetWindow( "WINDOW1");
    OraFormsSetFocus( "PERSON_GENDER");
    OraFormsPopListSelect( "PERSON_GENDER",  "Male",  0);
    OraFormsPopListClose( "PERSON_GENDER");
    OraFormsMenuItem( "WINDOW1",  "Action::Exit");
  end TMain;
Parent topic: Control Functions


OraFormsPutMessage Function

Action

This function adds a new message to the virtual users message pump.

Include file

OraForms.bdh

Syntax

OraFormsPutMessage( in nMsg   : number );
Parameter | Description
nMsg | The handler of the message to be added to the message pump.

Example

  transaction TMain
  var
    nFlexId : number;
    gnUmsg  : number;
    subMsg  : number;
  begin
    OraFormsSetConnectMode(ORA_HTTP_CONNECTION);
    // Connect - with connection properties
    OraFormsSetInt("INITIAL_VERSION", 608);
    OraFormsSetPoint("INITIAL_RESOLUTION", 96, 96);
    OraFormsSetPoint("INITIAL_DISP_SIZE", 1024, 768);
    OraFormsSetInt("INITIAL_COLOR_DEPTH", 256);
    OraFormsSetString("FONT_NAME", "Dialog");
    OraFormsSetPoint("INITIAL_SCALE_INFO", 8, 18);
    OraFormsSetBoolean("WINSYS_REQUIREDVA_LIST", false);
    OraFormsConnect("server module=Person3.fmx userid= useSDI=yes record=names");

    // New window activated: Logon
    OraFormsSetWindow("Logon");
    OraFormsLogon("user", "password", "orcl_server");

    OraFormsBeginMessageBlock("Block#2");
    gnUmsg := OraFormsCreateMessage(20, 40, ORA_MSG_TYPE_UPDATE);
    subMsg := OraFormsCreateMessage(30, 40, ORA_MSG_TYPE_UPDATE);
    OraFormsAddPropertyMessage(gnUmsg, ORA_PID_BP_FOREFILLCOL, subMsg);
    OraFormsAddPropertyInt(gnUmsg, 2601, 91);
    OraFormsAddPropertyInt(gnUmsg, 2600, 0);
    OraFormsAddPropertyBoolean(gnUmsg, 2600, false);
    OraFormsAddPropertyPoint(gnUmsg, ORA_PID_INITIAL_RESOLUTION, 0, 0);
    OraFormsAddPropertyString(gnUmsg, 2600, "E");
    OraFormsPutMessage(gnUmsg);
    OraFormsPutTerminalAndWait();
    OraFormsFree(gnUmsg);
    OraFormsEndMessageBlock("Block#2")
  end TMain;
Parent topic: Control Functions


OraFormsPutTerminalAndWait Function

Action

This function adds a terminal message to the message queue, performs a flush and returns when the message is processed.

Include file

OraForms.bdh

Syntax

OraFormsPutTerminalAndWait( );

Example

  transaction TMain
  var
    nFlexId : number;
    gnUmsg  : number;
    subMsg  : number;
  begin
    OraFormsSetConnectMode(ORA_HTTP_CONNECTION);
    // Connect - with connection properties
    OraFormsSetInt("INITIAL_VERSION", 608);
    OraFormsSetPoint("INITIAL_RESOLUTION", 96, 96);
    OraFormsSetPoint("INITIAL_DISP_SIZE", 1024, 768);
    OraFormsSetInt("INITIAL_COLOR_DEPTH", 256);
    OraFormsSetString("FONT_NAME", "Dialog");
    OraFormsSetPoint("INITIAL_SCALE_INFO", 8, 18);
    OraFormsSetBoolean("WINSYS_REQUIREDVA_LIST", false);
    OraFormsConnect("server module=Person3.fmx userid= useSDI=yes record=names");

    // New window activated: Logon
    OraFormsSetWindow("Logon");
    OraFormsLogon("user", "password", "orcl_server");

    OraFormsBeginMessageBlock("Block#2");
    gnUmsg := OraFormsCreateMessage(20, 40, ORA_MSG_TYPE_UPDATE);
    subMsg := OraFormsCreateMessage(30, 40, ORA_MSG_TYPE_UPDATE);
    OraFormsAddPropertyMessage(gnUmsg, ORA_PID_BP_FOREFILLCOL, subMsg);
    OraFormsAddPropertyInt(gnUmsg, 2601, 91);
    OraFormsAddPropertyInt(gnUmsg, 2600, 0);
    OraFormsAddPropertyBoolean(gnUmsg, 2600, false);
    OraFormsAddPropertyPoint(gnUmsg, ORA_PID_INITIAL_RESOLUTION, 0, 0);
    OraFormsAddPropertyString(gnUmsg, 2600, "E");
    OraFormsPutMessage(gnUmsg);
    OraFormsPutTerminalAndWait();
    OraFormsFree(gnUmsg);
    OraFormsEndMessageBlock("Block#2")
  end TMain;
Parent topic: Control Functions


OraFormsRegisterMessageInterceptor Function

Action

This function registers a message interceptor that will determine the handler id and the handler title of controls of a specified class. This function can be used to determine the handler id of controls during runtime, especially when these handlers do not have a title property.

Include file

OraForms.bdh

Syntax

OraFormsRegisterMessageInterceptor( in nClassId : number ) : number;

Return value

  • The handle to the message interceptor on success

  • 0 otherwise

Parameter | Description
nClassId | Register an interceptor for controls with this class id.

Example

  transaction TMain
  var
    nFlexId : number;
    gnUmsg  : number;
    subMsg  : number;
    nItc    : number;
  begin
    OraFormsSetConnectMode(ORA_HTTP_CONNECTION);
    // Connect - with connection properties
    OraFormsSetInt("INITIAL_VERSION", 608);
    OraFormsSetPoint("INITIAL_RESOLUTION", 96, 96);
    OraFormsSetPoint("INITIAL_DISP_SIZE", 1024, 768);
    OraFormsSetInt("INITIAL_COLOR_DEPTH", 256);
    OraFormsSetString("FONT_NAME", "Dialog");
    OraFormsSetPoint("INITIAL_SCALE_INFO", 8, 18);
    OraFormsSetBoolean("WINSYS_REQUIREDVA_LIST", false);
    OraFormsConnect("server module=Person3.fmx userid= useSDI=yes record=names");

    // New window activated: Logon
    OraFormsSetWindow("Logon");
    OraFormsLogon("user", "password", "orcl_server");

    OraFormsBeginMessageBlock("Block#2");
    gnUmsg := OraFormsCreateMessage(20, 40, ORA_MSG_TYPE_UPDATE);
    subMsg := OraFormsCreateMessage(30, 40, ORA_MSG_TYPE_UPDATE);
    OraFormsAddPropertyMessage(gnUmsg, ORA_PID_BP_FOREFILLCOL, subMsg);
    OraFormsAddPropertyInt(gnUmsg, 2601, 91);
    OraFormsAddPropertyInt(gnUmsg, 2600, 0);
    OraFormsAddPropertyBoolean(gnUmsg, 2600, false);
    OraFormsAddPropertyPoint(gnUmsg, ORA_PID_INITIAL_RESOLUTION, 0, 0);
    OraFormsAddPropertyString(gnUmsg, 2600, "E");
    OraFormsPutMessage(gnUmsg);
    OraFormsPutTerminalAndWait();
    OraFormsFree(gnUmsg);
    OraFormsEndMessageBlock("Block#2");

    nItc := OraFormsRegisterMessageInterceptor(1020);
    OraFormsKeyStroke("VNDR_END_DATE_ACTIVE_MIR_0", ORA_KEY_TAB, 0);

    // Inactive On
    nFlexId := OraFormsGetInterceptedControlId();
    OraFormsUnregisterMessageInterceptor(nItc);
    Print ("here is the id");
    Print(string(nFlexId));
  end TMain;
Parent topic: Control Functions


OraFormsUnregisterMessageInterceptor Function

Action

Unregisters and frees a message interceptor.

Include file

OraForms.bdh

Syntax

OraFormsUnregisterMessageInterceptor(in nHandle : number );
Parameter | Description
nHandle | Register an interceptor for controls with this class id.

Example

  transaction TMain
  var
    nFlexId : number;
    nItc    : number;
    gnUmsg  : number;
    subMsg  : number;
  begin
    OraFormsSetConnectMode(ORA_HTTP_CONNECTION);
    // Connect - with connection properties
    OraFormsSetInt("INITIAL_VERSION", 608);
    OraFormsSetPoint("INITIAL_RESOLUTION", 96, 96);
    OraFormsSetPoint("INITIAL_DISP_SIZE", 1024, 768);
    OraFormsSetInt("INITIAL_COLOR_DEPTH", 256);
    OraFormsSetString("FONT_NAME", "Dialog");
    OraFormsSetPoint("INITIAL_SCALE_INFO", 8, 18);
    OraFormsSetBoolean("WINSYS_REQUIREDVA_LIST", false);
    OraFormsConnect("server module=Person3.fmx userid= useSDI=yes record=names");
    // New window activated: Logon
    OraFormsSetWindow("Logon");
    OraFormsLogon("user", "password", "orcl_server");

    OraFormsBeginMessageBlock("Block#2");
    gnUmsg := OraFormsCreateMessage(20, 40, ORA_MSG_TYPE_UPDATE);
    subMsg := OraFormsCreateMessage(30, 40, ORA_MSG_TYPE_UPDATE);
    OraFormsAddPropertyMessage(gnUmsg, ORA_PID_BP_FOREFILLCOL, subMsg);
    OraFormsAddPropertyInt(gnUmsg, 2601, 91);
    OraFormsAddPropertyInt(gnUmsg, 2600, 0);
    OraFormsAddPropertyBoolean(gnUmsg, 2600, false);
    OraFormsAddPropertyPoint(gnUmsg, ORA_PID_INITIAL_RESOLUTION, 0, 0);
    OraFormsAddPropertyString(gnUmsg, 2600, "E");
    OraFormsPutMessage(gnUmsg);
    OraFormsPutTerminalAndWait();
    OraFormsFree(gnUmsg);
    OraFormsEndMessageBlock("Block#2");
    nItc := OraFormsRegisterMessageInterceptor(1020);
    OraFormsKeyStroke("VNDR_END_DATE_ACTIVE_MIR_0", ORA_KEY_TAB, 0);

    // Inactive On
    nflexId := OraFormsGetInterceptedControlId();
    OraFormsUnregisterMessageInterceptor(nItc);
    Print ("here is the id");
    Print(string(nflexId));
  end TMain;
Parent topic: Control Functions


OraFormsResponseBoxCancel Function

Action

OraFormsResponseBoxCancel presses the Cancel button on a response dialog.

Include file

OraForms.bdh

Syntax

OraFormsResponseBoxCancel(   in sName  : string,
                             in nIndex : number ) : boolean;

Return value

  • true if successful

  • false otherwise

Parameter | Description
sName | The control's unique name.
nIndex | Index of the selected row.

Example

dcltrans
  transaction TMain
  var
    sValue   : string;
  begin
    OraFormsSetConnectMode(ORA_SOCKET_CONNECTION);
    // Connect - with connection properties
    OraFormsSetInt("INITIAL_VERSION", 608);
    OraFormsSetPoint("INITIAL_RESOLUTION", 96, 96);
    OraFormsSetPoint("INITIAL_DISP_SIZE", 1024, 768);
    OraFormsSetInt("INITIAL_COLOR_DEPTH", 256);
    OraFormsSetString("FONT_NAME", "Dialog");
    OraFormsSetPoint("INITIAL_SCALE_INFO", 8, 18);
    OraFormsSetBoolean("WINSYS_REQUIREDVA_LIST", false);
    OraFormsConnect("server module=Person3.fmx userid= useSDI=yes record=names");
    OraFormsSetWindow("Logon");
    OraFormsLogon("user", "password", "orcl_server");
    // ---
    // New window activated: WINDOW1
    OraFormsSetWindow("WINDOW1");
    OraFormsResponseBoxCancel("ADB Account", 0);
  end TMain;
Parent topic: Control Functions


OraFormsResponseBoxOk Function

Action

OraFormsResponseBoxOk presses the OK button on a Response dialog.

Include file

OraForms.bdh

Syntax

OraFormsResponseBoxOk( in sName  : string,
                       in nIndex : number ) : boolean;

Return value

  • true if successful

  • false otherwise

Parameter | Description
sName | The control's unique name.
nIndex | The selected row.

Example

dcltrans
  transaction TMain
  var
    sValue   : string;
  begin
    OraFormsSetConnectMode(ORA_SOCKET_CONNECTION);
    // Connect - with connection properties
    OraFormsSetInt("INITIAL_VERSION", 608);
    OraFormsSetPoint("INITIAL_RESOLUTION", 96, 96);
    OraFormsSetPoint("INITIAL_DISP_SIZE", 1024, 768);
    OraFormsSetInt("INITIAL_COLOR_DEPTH", 256);
    OraFormsSetString("FONT_NAME", "Dialog");
    OraFormsSetPoint("INITIAL_SCALE_INFO", 8, 18);
    OraFormsSetBoolean("WINSYS_REQUIREDVA_LIST", false);
    OraFormsConnect("server module=Person3.fmx userid= useSDI=yes record=names");
    OraFormsSetWindow("Logon");
    OraFormsLogon("user", "password", "orcl_server");
    // ---
    // New window activated: WINDOW1
    OraFormsSetWindow("WINDOW1");
    OraFormsResponseBoxOk("ADB Account", 0);
  end TMain;
Parent topic: Control Functions


OraFormsResponseBoxValidate Function

Action

OraFormsResponseBoxValidate sends a validation message for a response dialog.

Include file

OraForms.bdh

Syntax

OraFormsResponseBoxValidate( in sName  : string,
                             in sType  : string,
                             in nIndex : number ) : boolean;

Return value

  • true if successful

  • false otherwise

Parameter | Description
sName | The control's unique name.
sType | String specifying how the verification is to be performed.
nIndex | Index of the row to be verified.

Example

dcltrans
  transaction TMain
  var
    sValue   : string;
  begin
    OraFormsSetConnectMode(ORA_SOCKET_CONNECTION);
    // Connect - with connection properties
    OraFormsSetInt("INITIAL_VERSION", 608);
    OraFormsSetPoint("INITIAL_RESOLUTION", 96, 96);
    OraFormsSetPoint("INITIAL_DISP_SIZE", 1024, 768);
    OraFormsSetInt("INITIAL_COLOR_DEPTH", 256);
    OraFormsSetString("FONT_NAME", "Dialog");
    OraFormsSetPoint("INITIAL_SCALE_INFO", 8, 18);
    OraFormsSetBoolean("WINSYS_REQUIREDVA_LIST", false);
    OraFormsConnect("server module=Person3.fmx userid= useSDI=yes record=names");
    OraFormsSetWindow("Logon");
    OraFormsLogon("user", "password", "orcl_server");
    // ---
    // New window activated: WINDOW1
    OraFormsSetWindow("WINDOW1");
    OraFormsResponseBoxValidate("ADB Account", "L", 0);
  end TMain;
Parent topic: Control Functions


OraFormsScrollerDrag Function

Action

Drags and drops the scroller to a specified position.

Include file

OraForms.bdh

Syntax

OraFormsScrollerDrag( in sName : string,
                      in nDrag : number ) : boolean;

Return value

  • true if successful
  • false otherwise
Parameter | Description
sName | The control's unique name.
nDrag | The new position of the scroller.

Example

transaction TMain
  var
    sValue :  string;
  begin
    OraFormsSetConnectMode(ORA_SOCKET_CONNECTION);
    // Connect - with connection properties
    OraFormsSetInt( "INITIAL_VERSION", 608);
    OraFormsSetPoint( "INITIAL_RESOLUTION", 96,  96);
    OraFormsSetPoint( "INITIAL_DISP_SIZE", 1024,  768);
    OraFormsSetInt( "INITIAL_COLOR_DEPTH", 256);
    OraFormsSetString( "FONT_NAME" , "Dialog" );
    OraFormsSetPoint( "INITIAL_SCALE_INFO", 8,  18);
    OraFormsSetBoolean( "WINSYS_REQUIREDVA_LIST",  false);
    OraFormsConnect( "server module=Person3.fmx userid= useSDI=yes record=names");
    // New window activated: Logon
    OraFormsSetWindow( "Logon");
    OraFormsLogon( "clemens",  "clemens",  "orcl_sunserver");
    // ---
    // New window activated: WINDOW1
    OraFormsSetWindow( "WINDOW1");
    OraFormsMenuItem( "WINDOW1",  "Query::Execute Query");
    OraFormsScrollerDrag( "SCROLLER_1",  4)
  end TMain;
Parent topic: Control Functions


OraFormsScrollerLine Function

Action

Performs a scroll up or scroll down action on a scroller by a specified number of lines.

Include file

OraForms.bdh

Syntax

OraFormsScrollerLine( in sName : string,
                      in nLines : number ) : boolean;

Return value

  • true if successful
  • false otherwise
Parameter | Description
sName | The control's unique name.
nLines | The number of lines to scroll. Positive numbers for scrolling down and negative numbers for scrolling up.

Example

transaction TMain
  var
    sValue :  string;
  begin
    OraFormsSetConnectMode(ORA_SOCKET_CONNECTION);
    // Connect - with connection properties
    OraFormsSetInt( "INITIAL_VERSION", 608);
    OraFormsSetPoint( "INITIAL_RESOLUTION", 96,  96);
    OraFormsSetPoint( "INITIAL_DISP_SIZE", 1024,  768);
    OraFormsSetInt( "INITIAL_COLOR_DEPTH", 256);
    OraFormsSetString( "FONT_NAME" , "Dialog" );
    OraFormsSetPoint( "INITIAL_SCALE_INFO", 8,  18);
    OraFormsSetBoolean( "WINSYS_REQUIREDVA_LIST",  false);
    OraFormsConnect( "server module=Person3.fmx userid= useSDI=yes record=names");
    // New window activated: Logon
    OraFormsSetWindow( "Logon");
    OraFormsLogon( "clemens",  "clemens",  "orcl_sunserver");
    // ---
    // New window activated: WINDOW1
    OraFormsSetWindow( "WINDOW1");
    OraFormsMenuItem( "WINDOW1",  "Query::Execute Query");
    // Scroll line down to position: 1
    OraFormsScrollerLine( "17",  1);
    // Scroll line down to position: 2
    OraFormsScrollerLine( "17",  1);
    // Scroll line up to position: 1
    OraFormsScrollerLine( "17",  -1);
    // Scroll line up to position: 0
    OraFormsScrollerLine( "17",  -1);
  end TMain;
Parent topic: Control Functions


OraFormsScrollerPage Function

Action

Performs a page scroll up or page scroll down action on a scroller by a specified number of pages.

Include file

OraForms.bdh

Syntax

OraFormsScrollerPage( in sName  : string,
                      in nPages : number) : boolean;

Return value

  • true if successful
  • false otherwise
Parameter | Description
sName | The control's unique name.
nPages | The number of pages to scroll. Positive numbers for scrolling down and negative numbers for scrolling up.

Example

transaction TMain
  var
    sValue :  string;
  begin
    OraFormsSetConnectMode(ORA_SOCKET_CONNECTION);
    // Connect - with connection properties
    OraFormsSetInt( "INITIAL_VERSION", 608);
    OraFormsSetPoint( "INITIAL_RESOLUTION", 96,  96);
    OraFormsSetPoint( "INITIAL_DISP_SIZE", 1024,  768);
    OraFormsSetInt( "INITIAL_COLOR_DEPTH", 256);
    OraFormsSetString( "FONT_NAME" , "Dialog" );
    OraFormsSetPoint( "INITIAL_SCALE_INFO", 8,  18);
    OraFormsSetBoolean( "WINSYS_REQUIREDVA_LIST",  false);
    OraFormsConnect( "server module=Person3.fmx userid= useSDI=yes record=names");
    // New window activated: Logon
    OraFormsSetWindow( "Logon");
    OraFormsLogon( "clemens",  "clemens",  "orcl_sunserver");
    // ---
    // New window activated: WINDOW1
    OraFormsSetWindow( "WINDOW1");
    OraFormsMenuItem( "WINDOW1",  "Query::Execute Query");
    // Scroll line down to position: 1
    OraFormsScrollerPage( "SCROLLER_1",  1);
    // Scroll line down to position: 2 OraFormsScrollerPage( "SCROLLER ",  1);
    // Scroll line up to position: 1
    OraFormsScrollerPage( "SCROLLER ",  -1);
    // Scroll line up to position: 0
    OraFormsScrollerPage( "SCROLLER ",  -1);
  end TMain;
Parent topic: Control Functions


OraFormsTreeSelectNode Function

Action

Selects the specified tree node of a tree control.

Include file

OraForms.bdh

Syntax

OraFormsTreeSelectNode(  in sName  :  string,
                         in sLabel :  string allownull,
                         in nNode  :  number optional ) : boolean;

Return value

  • true if successful
  • false otherwise
Parameter | Description
sName | The tree control's unique name.
sLabel | The value of the tree node. This value may be NULL if the node is specified by its index.
nNode | The node index. Will only be used when the previous parameter is set to NULL.

Example

transaction TMain
  var
    sValue :  string;
  begin
    OraFormsSetConnectMode(ORA_SOCKET_CONNECTION);
    // Connect - with connection properties
    OraFormsSetInt( "INITIAL_VERSION", 608);
    OraFormsSetPoint( "INITIAL_RESOLUTION", 96,  96);
    OraFormsSetPoint( "INITIAL_DISP_SIZE", 1024,  768);
    OraFormsSetInt( "INITIAL_COLOR_DEPTH", 256);
    OraFormsSetString( "FONT_NAME" , "Dialog" );
    OraFormsSetPoint( "INITIAL_SCALE_INFO", 8,  18);
    OraFormsSetBoolean( "WINSYS_REQUIREDVA_LIST",  false);
    OraFormsConnect( "server module=Person3.fmx userid= useSDI=yes record=names");
    OraFormsSetWindow( "Logon");
    OraFormsLogon( "user",  "password",  "orcl_server");
    // --- OraFormsBeginMessageBlock( "WINDOW1#1");
    OraFormsMouseClick( "24",  74,  149,  0);
    // Selected entry: Oliver Tuvault
    OraFormsTreeSelectNode( "24",  "John Russell\\Oliver Tuvault");
    OraFormsEndMessageBlock( "WINDOW1#1");
  end  TMain;
Parent topic: Control Functions
Related reference
OraFormsTreeActivateNode Function
OraFormsTreeCollapseNode Function
OraFormsTreeExpandNode Function


OraFormsSetCancelQueryWindow Function

Action

Marks the specified Cancel Query dialog as the current active window. This function doesn’t send any requests to the server. It is recorded to make the BDL script more readable.

Include file

OraForms.bdh

Syntax

OraFormsSetCancelQueryWindow( in sName : string );
Parameter | Description
sName | The window’s unique name.

Example

dcltrans
  transaction TMain
  begin
    OraFormsSetString("DEFAULT_LOCAL_TZ", "Europe/Berlin");
    OraFormsConnect("server module=javamail90.fmx usesdi=yes");
    OraFormsSetCancelQueryWindow("Cancel Query");
    OraFormsCloseCancelQueryDialog("Cancel Query");
  end TMain;
Parent topic: Control Functions


OraFormsSetFocus Function

Action

Sets the focus for the specified control.

Include file

OraForms.bdh

Syntax

OraFormsSetFocus( in sName : string) : boolean;

Return value

  • true if successful
  • false otherwise
Parameter | Description
sName | The control's unique name.

Example

transaction TMain
  var
    sValue :  string;
  begin
    OraFormsSetConnectMode(ORA_SOCKET_CONNECTION);
    // Connect - with connection properties
    OraFormsSetInt( "INITIAL_VERSION",  608);
    OraFormsSetPoint( "INITIAL_RESOLUTION", 96,  96);
    OraFormsSetPoint( "INITIAL_DISP_SIZE", 1024,  768);
    OraFormsSetInt( "INITIAL_COLOR_DEPTH", 256);
    OraFormsSetString( "FONT_NAME" , "Dialog" );
    OraFormsSetPoint( "INITIAL_SCALE_INFO", 8,  18);
    OraFormsSetBoolean( "WINSYS_REQUIREDVA_LIST",  false);
    OraFormsConnect( "server module=Person3.fmx userid= useSDI=yes record=names");
    OraFormsSetWindow( "Logon");
    OraFormsLogon( "user",  "password",  "orcl_server");
    OraFormsSetFocus( "PUSH_BUTTON");
    OraFormsButtonPress( "PUSH_BUTTON");
  end TMain;
Parent topic: Control Functions


OraFormsSetWindow Function

Action

Marks the specified window as the current activate window. This function doesn't send any requests to the server. It is recorded to make the BDL script more readable.

Include file

OraForms.bdh

Syntax

OraFormsSetWindow( in sName : string ) : boolean;

Return value

  • true if successful
  • false otherwise
Parameter | Description
sName | The window's unique name.

Example

dcltrans
  transaction TMain
  begin
    OraFormsSetString( "DEFAULT_LOCAL_TZ", "Europe/Berlin");
    OraFormsConnect( "server module=javamail90.fmx usesdi=yes");
    OraFormsSetWindow( "BASE_DEMO_WINDOW");
    OraFormsWindowMove( "BASE_DEMO_WINDOW", 0,  -24);
  end TMain;
Parent topic: Control Functions


OraFormsTabSelect Function

Action

Activates a tab page.

Include file

OraForms.bdh

Syntax

OraFormsTabSelect(  in sName  :  string,
                    in sTab   : string ,
                    in nIndex :  number optional ) : boolean;

Return value

  • true if successful
  • false otherwise
Parameter | Description
sName | The tab control's unique name.
sTab | Specifies the tab sheet to be selected. If this parameter is set to NULL the index of the tab sheet as specified in the next parameter will be taken.
nIndex | The index of the tab sheet to be selected. The index will be used whenever the sLabel parameter is set to NULL.

Example

transaction TMain
  var
    sValue :  string;
  begin
    OraFormsSetConnectMode(ORA_SOCKET_CONNECTION);
    // Connect - with connection properties
    OraFormsSetInt( "INITIAL_VERSION", 608);
    OraFormsSetPoint( "INITIAL_RESOLUTION", 96,  96);
    OraFormsSetPoint( "INITIAL_DISP_SIZE", 1024,  768);
    OraFormsSetInt( "INITIAL_COLOR_DEPTH", 256);
    OraFormsSetString( "FONT_NAME" , "Dialog" );
    OraFormsSetPoint( "INITIAL_SCALE_INFO", 8,  18);
    OraFormsSetBoolean( "WINSYS_REQUIREDVA_LIST",  false);
    OraFormsConnect( "server module=Person3.fmx userid= useSDI=yes record=names");
    OraFormsSetWindow( "Logon");
    OraFormsLogon( "user",  "password",  "orcl_server");
    OraFormsTabSelect( "FIRST_TAB",  "", 1);
  end  TMain;
Parent topic: Control Functions


OraFormsTreeActivateNode Function

Action

Sends an activate message for the specified tree node of the tree control.

Include file

OraForms.bdh

Syntax

OraFormsTreeActivateNode( in sName  : string,
                          in sLabel : string allownull,
                          in nNode  : number optional ) : boolean;

Return value

  • true if successful
  • false otherwise
Parameter | Description
sName | The tree control's unique name.
sLabel | The value of the tree node to be activated.
nNode | The index of the tree node if the previous value is NULL.

Example

 transaction TMain
  var
    sValue :  string;
  begin
    OraFormsSetConnectMode(ORA_SOCKET_CONNECTION);
    // Connect - with connection properties
    OraFormsSetInt( "INITIAL_VERSION", 608);
    OraFormsSetPoint( "INITIAL_RESOLUTION", 96,  96);
    OraFormsSetPoint( "INITIAL_DISP_SIZE", 1024,  768);
    OraFormsSetInt( "INITIAL_COLOR_DEPTH", 256);
    OraFormsSetString( "FONT_NAME" , "Dialog" );
    OraFormsSetPoint( "INITIAL_SCALE_INFO", 8,  18);
    OraFormsSetBoolean( "WINSYS_REQUIREDVA_LIST",  false);
    OraFormsConnect( "server module=Person3.fmx userid= useSDI=yes record=names");
    OraFormsSetWindow( "Logon");
    OraFormsLogon( "user",  "password",  "orcl_server");
    // ---
    OraFormsBeginMessageBlock( "WINDOW1#1");
    OraFormsMouseClick( "24",  74,  149,  0);
    // Selected entry: Oliver Tuvault
    OraFormsTreeActivateNode( "24",  "John Russell\\Oliver Tuvault");
    OraFormsEndMessageBlock( "WINDOW1#1");
  end  TMain;
Parent topic: Control Functions
Related reference
OraFormsTreeCollapseNode Function
OraFormsTreeExpandNode Function
OraFormsTreeSelectNode Function


OraFormsTreeCollapseNode Function

Action

Collapses the specified node in a tree control.

Include file

OraForms.bdh

Syntax

OraFormsTreeCollapseNode(  in sName  :  string,
                           in sLable :  string allownull,
                           in nNode  :  number optional ) : boolean;

Return value

  • true if successful
  • false otherwise
Parameter | Descripton
sName | The control's unique name.
sLable | The value of the node to be selected.
nNode | The index of the node to be selected. This value will be ignored if the previous parameter is not NULL.

Example

transaction TMain
  var
    sValue :  string;
  begin
    OraFormsSetConnectMode(ORA_SOCKET_CONNECTION);
    // Connect - with connection properties
    OraFormsSetInt( "INITIAL_VERSION", 608);
    OraFormsSetPoint( "INITIAL_RESOLUTION", 96,  96);
    OraFormsSetPoint( "INITIAL_DISP_SIZE", 1024,  768);
    OraFormsSetInt( "INITIAL_COLOR_DEPTH", 256);
    OraFormsSetString( "FONT_NAME" , "Dialog" );
    OraFormsSetPoint( "INITIAL_SCALE_INFO", 8,  18);
    OraFormsSetBoolean( "WINSYS_REQUIREDVA_LIST",  false);
    OraFormsConnect( "server module=Person3.fmx userid= useSDI=yes record=names");
    OraFormsSetWindow( "Logon");
    OraFormsLogon( "user",  "password",  "orcl_server");
    // --- OraFormsBeginMessageBlock( "WINDOW1#1");
    OraFormsMouseClick( "24",  74,  149,  0);
    // Selected entry: Oliver Tuvault
    OraFormsTreeCollapseNode( "24",  "John Russell\\Oliver Tuvault");
    OraFormsEndMessageBlock( "WINDOW1#1");
  end  TMain;
Parent topic: Control Functions
Related reference
OraFormsTreeActivateNode Function
OraFormsTreeExpandNode Function
OraFormsTreeSelectNode Function


OraFormsTreeExpandNode Function

Action

Expands the selected branch in a tree control.

Include file

OraForms.bdh

Syntax

OraFormsTreeExpandNode(  in sName  :  string,
                         in sLabel :  string allownull,
                         in nNode  :  number optional ) : boolean;

Return value

  • true if successful
  • false otherwise
Parameter | Description
sName | The control's unique name.
sLabel | The value of the node to be expanded.
nNode | The index of the node to be expanded. This value will be ignored if the previous parameter is not NULL.

Example

transaction TMain
  var
    sValue :  string;
  begin
    OraFormsSetConnectMode(ORA_SOCKET_CONNECTION);
    // Connect - with connection properties
    OraFormsSetInt( "INITIAL_VERSION", 608);
    OraFormsSetPoint( "INITIAL_RESOLUTION",  96,  96);
    OraFormsSetPoint( "INITIAL_DISP_SIZE", 1024,  768);
    OraFormsSetInt( "INITIAL_COLOR_DEPTH", 256);
    OraFormsSetString( "FONT_NAME" , "Dialog" );
    OraFormsSetPoint( "INITIAL_SCALE_INFO",  8,  18);
    OraFormsSetBoolean( "WINSYS_REQUIREDVA_LIST",  false);
    OraFormsConnect( "server module=Person3.fmx userid= useSDI=yes record=names");
    OraFormsSetWindow( "Logon");
    OraFormsLogon( "user",  "password",  "orcl_server");
    // --- OraFormsBeginMessageBlock( "WINDOW1#1");
    OraFormsMouseClick( "24",  74,  149,  0);
    // Selected entry: Oliver Tuvault
    OraFormsTreeExpandNode( "24",  "John Russell\\Oliver Tuvault");
    OraFormsEndMessageBlock( "WINDOW1#1");
  end  TMain;
Parent topic: Control Functions
Related reference
OraFormsTreeActivateNode Function
OraFormsTreeCollapseNode Function
OraFormsTreeSelectNode Function


OraFormsWindowMove Function

Action

Moves a specified window by provided coordinates.

Include file

OraForms.bdh

Syntax

OraFormsWindowMove(  in sName :  string,
                     in nX    :  number,
                     in nY    :  number ) :  boolean;

Return value

  • true if successful
  • false otherwise
Parameter | Description
sName | The window's unique name.
nX | x part of the coordinates.
nY | y part of the coordinates.

Example

dcltrans
  transaction TMain
  begin
    OraFormsSetString( "DEFAULT_LOCAL_TZ", "Europe/Berlin");
    OraFormsConnect( "server module=javamail90.fmx usesdi=yes");
    OraFormsSetWindow( "BASE_DEMO_WINDOW");
    OraFormsWindowMove( "BASE_DEMO_WINDOW",  0,  -24);
  end TMain;
Parent topic: Control Functions


OraFormsWindowResize Function

Action

Resizes a given window by specified coordinates.

Include file

OraForms.bdh

Syntax

OraFormsWindowResize(  in sName :  string,
                        in nX :  number,
                        in nY :  number ) :  boolean;

Return value

  • true if successful
  • false otherwise
Parameter | Description
sName | The window's unique name.
nX | x part of the coordinates.
nY | y part of the coordinates.

Example

 dcltrans
  transaction TMain
  begin
    OraFormsSetString( "DEFAULT_LOCAL_TZ", "Europe/Berlin");
    OraFormsConnect( "server module=javamail90.fmx usesdi=yes");
    OraFormsSetWindow( "BASE_DEMO_WINDOW");
    OraFormsWindowResize( "BASE_DEMO_WINDOW",  45,  24);
  end TMain;
Parent topic: Control Functions


OraFormsWindowUpdate Function

Action

Modifies the status of a specified window.

Include file

OraForms.bdh

Syntax

OraFormsWindowUpdate(  in sName   :  string,
                       in nAction :  number,
                       in bStatus :  boolean ) :  boolean;

Return value

  • true if successful
  • false otherwise
Parameter | Description
sName | The window's unique name.
nAction

Can be any of these values:

  • ORA_WINDOW_VISIBLE
  • ORA_WINDOW_MAXIMIZED
  • ORA_WINDOW_ICONIFIED
  • ORA_WINDOW_ACTIVATED
bStatus | Specifies whether to set the status as defined by the previous parameter.

Example

dcltrans
  transaction TMain
  var
  begin
    OraFormsSetPoint( "INITIAL_SCALE_INFO", 8,  20);
    OraFormsSetBoolean( "WINSYS_REQUIREDVA_LIST",  false);
    OraFormsSetString( "DEFAULT_LOCAL_TZ", "Europe/Berlin");
    OraFormsConnect( "server module=iorganizer.fmx userid=iorg/iorg@ORCL_server sso_userid= usesdi=yesrecord=names");
    OraFormsSetFocus( "LOGIN_PB_ENTER_0"); // Enter
    OraFormsButtonPress( "LOGIN_PB_ENTER_0");  // Enter
    // Incorrect Login Information. Do you want to register?
    OraFormsMessageBoxButton( "Incorrect Login", ORA_ALERT_NO);
    OraFormsWindowUpdate( "Oracle iOrganizer", ORA_WINDOW_ACTIVATED, true);
    OraFormsCloseWindow( "Oracle iOrganizer");
  end TMain;
Parent topic: Control Functions


Properties Functions

  • OraFormsAddPropertyBoolean Function
    Adds a property of type boolean to a message.
  • OraFormsAddPropertyByte Function
    Adds a property of type byte to a message.
  • OraFormsAddPropertyInt Function
    Adds a property of type integer to a message.
  • OraFormsAddPropertyMessage Function
    Adds a property from type message to another message.
  • OraFormsAddPropertyPoint Function
    Adds a property of type point to a message.
  • OraFormsAddPropertyRectangle Function
    Adds a property of type rectangle to a message.
  • OraFormsAddPropertyString Function
    Adds a property of type string to a message.
  • OraFormsGetFlexCellData Function
    Feturns the value of the field in a flex window.
  • OraFormsGetFlexCellPropBoolean Function
    Returns the Boolean property of a cell.
  • OraFormsGetFlexCellPropBooleanByIndex Function
    Returns the Boolean property of a cell.
  • OraFormsGetFlexCellPropInt Function
    Returns a specified cell’s integer property.
  • OraFormsGetFlexCellPropIntByIndex Function
    Returns a specified cell’s integer property.
  • OraFormsGetFlexCellPropString Function
    Returns a flex window cell’s string property.
  • OraFormsGetFlexCellPropStringByIndex function
    Returns a flex window cell’s string property.
  • OraFormsGetFlexColumnCount Function
    Returns the number of columns in a flex window.
  • OraFormsGetFlexColumnIndex Function
    Returns the index of the specified column.
  • OraFormsGetFlexColumnName Function
    Returns a column’s name.
  • OraFormsGetFlexPropBoolean Function
    Returns a specified Boolean type flex window property.
  • OraFormsGetFlexPropString Function
    Returns the specified string property of a flex window.
  • OraFormsGetFlexRowCount Function
    Returns the number of rows within a flex window.
  • OraFormsGetFlexRowIndex Function
    Returns the index of the specified row.
  • OraFormsGetFlexRowName Function
    Returns the name of the specified row within a flex window.
  • OraFormsGetPropByte Function
    Returns the specified property's value for the given control.
  • OraFormsGetPropByteArray Function
    Returns an element of a byte array for a specified property within a control.
  • OraFormsGetPropByteArrayLen Function
    Returns the length for a byte array property.
  • OraFormsGetPropInt Function
    Returns the specified property's value for the given control.
  • OraFormsGetPropNull Function
    Determines whether a property for the specified control is NULL.
  • OraFormsGetPropPoint Function
    Gets the value for a point property of a specified control.
  • OraFormsGetPropRectangle Function
    Returns the value of a rectangle property for the specified control.
  • OraFormsGetPropString Function
    Returns the specified property's value for the given control.
  • OraFormsGetPropStringArray Function
    Returns an element of a string array property at a given position.
  • OraFormsGetPropStringArrayLen Function
    Returns the length (a number) of a string array property.
  • OraFormsSetBoolean Function
    Sets a boolean property that must be sent with the next request.
  • OraFormsSetByte Function
    Sets a byte property that must be sent with the next request.
  • OraFormsSetByteArray Function
    Sets a byte array that must be sent with the next request.
  • OraFormsSetCharacter Function
    Sets a character property that must be sent with the next request.
  • OraFormsSetInt Function
    Sets an integer property that must be sent with the next request.
  • OraFormsSetPoint Function
    Sets a point property that must be sent with the next request.
  • OraFormsSetRectangle Function
    Sets a rectangle property that must be sent with the next request.
  • OraFormsSetString Function
    Sets a string property that must be sent with the next request.
  • OraFormsSetStringArray Function
    Sets an array of string properties that must be sent with the next request.
Parent topic: Oracle Forms Functions Reference


OraFormsAddPropertyBoolean Function

Action

This function adds a property of type boolean to a message.

Include file

OraForms.bdh

Syntax

OraFormsAddPropertyBoolean(in nMsg   : number,
                           in nPid   : number,
                           in bValue : boolean );
Parameter | Description
nMsg | The handle to a message
nPid | The id of the property to be added.
bValue | Value of the property.

Example

  transaction TMain
  var
    nFlexId : number;
    gnUmsg  : number;
    subMsg  : number;
  begin
    OraFormsSetConnectMode(ORA_HTTP_CONNECTION);
    // Connect - with connection properties
    OraFormsSetInt("INITIAL_VERSION", 608);
    OraFormsSetPoint("INITIAL_RESOLUTION", 96, 96);
    OraFormsSetPoint("INITIAL_DISP_SIZE", 1024, 768);
    OraFormsSetInt("INITIAL_COLOR_DEPTH", 256);
    OraFormsSetString("FONT_NAME", "Dialog");
    OraFormsSetPoint("INITIAL_SCALE_INFO", 8, 18);
    OraFormsSetBoolean("WINSYS_REQUIREDVA_LIST", false);
    OraFormsConnect("server module=Person3.fmx userid= useSDI=yes record=names");

    // New windowmactivated: Logon
    OraFormsSetWindow("Logon");
    OraFormsLogon("user", "password", "orcl_server");

    OraFormsBeginMessageBlock("Block#2");
    gnUmsg := OraFormsCreateMessage(20, 40, ORA_MSG_TYPE_UPDATE);
    subMsg := OraFormsCreateMessage(30, 40, ORA_MSG_TYPE_UPDATE);
    OraFormsAddPropertyMessage(gnUmsg, ORA_PID_BP_FOREFILLCOL, subMsg);
    OraFormsAddPropertyInt(gnUmsg, 2601, 91);
    OraFormsAddPropertyInt(gnUmsg, 2600, 0);
    OraFormsAddPropertyBoolean(gnUmsg, 2600, false);
    OraFormsAddPropertyPoint(gnUmsg, ORA_PID_INITIAL_RESOLUTION, 0, 0);
    OraFormsAddPropertyString(gnUmsg, 2600, "E");
    OraFormsPutMessage(gnUmsg);
    OraFormsPutTerminalAndWait();
    OraFormsFree(gnUmsg);
    OraFormsEndMessageBlock("Block#2")
  end TMain;
Parent topic: Properties Functions


OraFormsAddPropertyByte Function

Action

This function adds a property of type byte to a message.

Include file

OraForms.bdh

Syntax

OraFormsAddPropertyByte( in nMsg   : number,
                         in nPid   : number,
                         in nValue : number);
Parameter | Description
nMsg | The handle to a message
nPid | The id of the property to be added.
nValue | A value of type number.

Example

  transaction TMain
  var
    nFlexId : number;
    gnUmsg  : number;
    subMsg  : number;
  begin
    OraFormsSetConnectMode(ORA_HTTP_CONNECTION);
    // Connect - with connection properties
    OraFormsSetInt("INITIAL_VERSION", 608);
    OraFormsSetPoint("INITIAL_RESOLUTION", 96, 96);
    OraFormsSetPoint("INITIAL_DISP_SIZE", 1024, 768);
    OraFormsSetInt("INITIAL_COLOR_DEPTH", 256);
    OraFormsSetString("FONT_NAME", "Dialog");
    OraFormsSetPoint("INITIAL_SCALE_INFO", 8, 18);
    OraFormsSetBoolean("WINSYS_REQUIREDVA_LIST", false);
    OraFormsConnect("server module=Person3.fmx userid= useSDI=yes record=names");

    // New window activated: Logon
    OraFormsSetWindow("Logon");
    OraFormsLogon("user", "password", "orcl_server");

    OraFormsBeginMessageBlock("Block#2");
    gnUmsg := OraFormsCreateMessage(20, 40, ORA_MSG_TYPE_UPDATE);
    subMsg := OraFormsCreateMessage(30, 40, ORA_MSG_TYPE_UPDATE);
    OraFormsAddPropertyMessage(gnUmsg, ORA_PID_BP_FOREFILLCOL, subMsg);
    OraFormsAddPropertyInt(gnUmsg, 2601, 91);
    OraFormsAddPropertyInt(gnUmsg, 2600, 0);
    OraFormsAddPropertyByte(gnUmsg, 2600, 0);
    OraFormsAddPropertyPoint(gnUmsg, ORA_PID_INITIAL_RESOLUTION, 0, 0);
    OraFormsAddPropertyString(gnUmsg, 2600, "E");
    OraFormsPutMessage(gnUmsg);
    OraFormsPutTerminalAndWait();
    OraFormsFree(gnUmsg);
    OraFormsEndMessageBlock("Block#2")
  end TMain;
Parent topic: Properties Functions


OraFormsAddPropertyInt Function

Action

This function adds a property of type integer to a message.

Include file

OraForms.bdh

Syntax

OraFormsAddPropertyInt( in nMsg   : number,
                        in nPid   : number,
                        in bValue : boolean );
Parameter | Description
nMsg | The handle to a message
nPid | The id of the property to be added.
bValue | Value of the property.

Example

  transaction TMain
  var
    nFlexId : number;
    gnUmsg  : number;
    subMsg  : number;
  begin
    OraFormsSetConnectMode(ORA_HTTP_CONNECTION);
    // Connect - with connection properties
    OraFormsSetInt("INITIAL_VERSION", 608);
    OraFormsSetPoint("INITIAL_RESOLUTION", 96, 96);
    OraFormsSetPoint("INITIAL_DISP_SIZE", 1024, 768);
    OraFormsSetInt("INITIAL_COLOR_DEPTH", 256);
    OraFormsSetString("FONT_NAME", "Dialog");
    OraFormsSetPoint("INITIAL_SCALE_INFO", 8, 18);
    OraFormsSetBoolean("WINSYS_REQUIREDVA_LIST", false);
    OraFormsConnect("server module=Person3.fmx userid= useSDI=yes record=names");

    // New window activated: Logon    OraFormsSetWindow("Logon");
    OraFormsLogon("user", "password", "orcl_server");

    OraFormsBeginMessageBlock("Block#2");
    gnUmsg := OraFormsCreateMessage(20, 40, ORA_MSG_TYPE_UPDATE);
    subMsg := OraFormsCreateMessage(30, 40, ORA_MSG_TYPE_UPDATE);
    OraFormsAddPropertyMessage(gnUmsg, ORA_PID_BP_FOREFILLCOL, subMsg);
    OraFormsAddPropertyInt(gnUmsg, 2601, 91);
    OraFormsAddPropertyInt(gnUmsg, 2600, 0);
    OraFormsAddPropertyByte(gnUmsg, 2600, 0);
    OraFormsAddPropertyPoint(gnUmsg, ORA_PID_INITIAL_RESOLUTION, 0, 0);
    OraFormsAddPropertyString(gnUmsg, 2600, "E");
    OraFormsPutMessage(gnUmsg);
    OraFormsPutTerminalAndWait();
    OraFormsFree(gnUmsg);
    OraFormsEndMessageBlock("Block#2")
  end TMain;
Parent topic: Properties Functions


OraFormsAddPropertyMessage Function

Action

This function adds a property from type message to another message.

Include file

OraForms.bdh

Syntax

OraFormsAddPropertyMessage( in nMsg   : number,
                            in nPid   : number,
                            in bValue : boolean );
Parameter | Description
nMsg | The handle to a message
nPid | The id of the property to be added.
bValue | Value of the property.

Example

  transaction TMain
  var
    nFlexId : number;
    gnUmsg  : number;
    subMsg  : number;
  begin
    OraFormsSetConnectMode(ORA_HTTP_CONNECTION);
    // Connect - with connection properties
    OraFormsSetInt("INITIAL_VERSION", 608);
    OraFormsSetPoint("INITIAL_RESOLUTION", 96, 96);
    OraFormsSetPoint("INITIAL_DISP_SIZE", 1024, 768);
    OraFormsSetInt("INITIAL_COLOR_DEPTH", 256);
    OraFormsSetString("FONT_NAME", "Dialog");
    OraFormsSetPoint("INITIAL_SCALE_INFO", 8, 18);
    OraFormsSetBoolean("WINSYS_REQUIREDVA_LIST", false);
    OraFormsConnect("server module=Person3.fmx userid= useSDI=yes record=names");

    // New window activated: Logon
    OraFormsSetWindow("Logon");
    OraFormsLogon("user", "password", "orcl_server");

    OraFormsBeginMessageBlock("Block#2");
    gnUmsg := OraFormsCreateMessage(20, 40, ORA_MSG_TYPE_UPDATE);
    subMsg := OraFormsCreateMessage(30, 40, ORA_MSG_TYPE_UPDATE);
    OraFormsAddPropertyMessage(gnUmsg, ORA_PID_BP_FOREFILLCOL, subMsg);
    OraFormsAddPropertyInt(gnUmsg, 2601, 91);
    OraFormsAddPropertyInt(gnUmsg, 2600, 0);
    OraFormsAddPropertyByte(gnUmsg, 2600, 0);
    OraFormsAddPropertyPoint(gnUmsg, ORA_PID_INITIAL_RESOLUTION, 0, 0);
    OraFormsAddPropertyString(gnUmsg, 2600, "E");
    OraFormsPutMessage(gnUmsg);
    OraFormsPutTerminalAndWait();
    OraFormsFree(gnUmsg);
    OraFormsEndMessageBlock("Block#2")
  end TMain;
Parent topic: Properties Functions


OraFormsAddPropertyPoint Function

Action

This function adds a property of type point to a message.

Include file

OraForms.bdh

Syntax

OraFormsAddPropertyPoint( in nMsg   : number,
                          in nPid   : number,
                          in nX     : number,
                          in nY     : number );
Parameter | Description
nMsg | The handle to a message.
nPid | The id of the property to be added.
nX | The x part of the point structure.
nY | The y part of the point structure.

Example

  transaction TMain
  var
    nFlexId : number;
    gnUmsg  : number;
    subMsg  : number;
  begin
    OraFormsSetConnectMode(ORA_HTTP_CONNECTION);

    // Connect - with connection properties
    OraFormsSetInt("INITIAL_VERSION", 608);
    OraFormsSetPoint("INITIAL_RESOLUTION", 96, 96);
    OraFormsSetPoint("INITIAL_DISP_SIZE", 1024, 768);
    OraFormsSetInt("INITIAL_COLOR_DEPTH", 256);
    OraFormsSetString("FONT_NAME", "Dialog");
    OraFormsSetPoint("INITIAL_SCALE_INFO", 8, 18);
    OraFormsSetBoolean("WINSYS_REQUIREDVA_LIST", false);
    OraFormsConnect("server module=Person3.fmx userid= useSDI=yes record=names");

    // New window activated: Logon
    OraFormsSetWindow("Logon");
    OraFormsLogon("user", "password", "orcl_server");

    OraFormsBeginMessageBlock("Block#2");
    gnUmsg := OraFormsCreateMessage(20, 40, ORA_MSG_TYPE_UPDATE);
    subMsg := OraFormsCreateMessage(30, 40, ORA_MSG_TYPE_UPDATE);
    OraFormsAddPropertyMessage(gnUmsg, ORA_PID_BP_FOREFILLCOL, subMsg);
    OraFormsAddPropertyInt(gnUmsg, 2601, 91);
    OraFormsAddPropertyInt(gnUmsg, 2600, 0);
    OraFormsAddPropertyByte(gnUmsg, 2600, 0);
    OraFormsAddPropertyPoint(gnUmsg, ORA_PID_INITIAL_RESOLUTION, 0, 0);
    OraFormsAddPropertyString(gnUmsg, 2600, "E");
    OraFormsPutMessage(gnUmsg);
    OraFormsPutTerminalAndWait();
    OraFormsFree(gnUmsg);
    OraFormsEndMessageBlock("Block#2")
  end TMain;
Parent topic: Properties Functions


OraFormsAddPropertyRectangle Function

Action

This function adds a property of type rectangle to a message.

Include file

OraForms.bdh

Syntax

OraFormsAddPropertyRectangle( in nMsg   : number,
                              in nPid   : number,
                              in nX1    : number,
                              in nY1    : number,
                              in nX2    : number ,
                              in nY2    : number );
Parameter | Description
nMsg | The handle to a message
nPid | The id of the property to be added.
nX1 | The x part of the first coordinates.
nY1 | The y part of the first coordinates.
nX2 | The x part of the second coordinates.
nY2 | The y part of the second coordinates.

Example

  transaction TMain
  var
    nFlexId : number;
    gnUmsg  : number;
    subMsg  : number;
  begin
    OraFormsSetConnectMode(ORA_HTTP_CONNECTION);
    // Connect - with connection properties
    OraFormsSetInt("INITIAL_VERSION", 608);
    OraFormsSetPoint("INITIAL_RESOLUTION", 96, 96);
    OraFormsSetPoint("INITIAL_DISP_SIZE", 1024, 768);
    OraFormsSetInt("INITIAL_COLOR_DEPTH", 256);
    OraFormsSetString("FONT_NAME", "Dialog");
    OraFormsSetPoint("INITIAL_SCALE_INFO", 8, 18);
    OraFormsSetBoolean("WINSYS_REQUIREDVA_LIST", false);
    OraFormsConnect("server module=Person3.fmx userid= useSDI=yes record=names");

    // New window activated: Logon
    OraFormsSetWindow("Logon");
    OraFormsLogon("user", "password", "orcl_server");

    OraFormsBeginMessageBlock("Block#2");
    gnUmsg := OraFormsCreateMessage(20, 40, ORA_MSG_TYPE_UPDATE);
    subMsg := OraFormsCreateMessage(30, 40, ORA_MSG_TYPE_UPDATE);
    OraFormsAddPropertyMessage(gnUmsg, ORA_PID_BP_FOREFILLCOL, subMsg);
    OraFormsAddPropertyInt(gnUmsg, 2601, 91);
    OraFormsAddPropertyInt(gnUmsg, 2600, 0);
    OraFormsAddPropertyByte(gnUmsg, 2600, 0);
    OraFormsAddPropertyRectangle(gnUmsg, ORA_PID_INITIAL_RESOLUTION, 0, 0, 20, 30);
    OraFormsAddPropertyString(gnUmsg, 2600, "E");
    OraFormsPutMessage(gnUmsg);
    OraFormsPutTerminalAndWait();
    OraFormsFree(gnUmsg);
    OraFormsEndMessageBlock("Block#2")
  end TMain;
Parent topic: Properties Functions


OraFormsAddPropertyString Function

Action

This function adds a property of type string to a message.

Include file

OraForms.bdh

Syntax

OraFormsAddPropertyString(in nMsg   : number,
                          in nPid   : number,
                          in sValue : string );
Parameter | Description
nMsg | The handle to a message
nPid | The id of the property to be added.
sValue | Value of the property.

Example

  transaction TMain
  var
    nFlexId : number;
    gnUmsg  : number;
    subMsg  : number;
  begin
    OraFormsSetConnectMode(ORA_HTTP_CONNECTION);
    // Connect - with connection properties
    OraFormsSetInt("INITIAL_VERSION", 608);
    OraFormsSetPoint("INITIAL_RESOLUTION", 96, 96);
    OraFormsSetPoint("INITIAL_DISP_SIZE", 1024, 768);
    OraFormsSetInt("INITIAL_COLOR_DEPTH", 256);
    OraFormsSetString("FONT_NAME", "Dialog");
    OraFormsSetPoint("INITIAL_SCALE_INFO", 8, 18);
    OraFormsSetBoolean("WINSYS_REQUIREDVA_LIST", false);
    OraFormsConnect("server module=Person3.fmx userid= useSDI=yes record=names");
    // New window activated: Logon
    OraFormsSetWindow("Logon");
    OraFormsLogon("user", "password", "orcl_server");

    OraFormsBeginMessageBlock("Block#2");
    gnUmsg := OraFormsCreateMessage(20, 40, ORA_MSG_TYPE_UPDATE);
    subMsg := OraFormsCreateMessage(30, 40, ORA_MSG_TYPE_UPDATE);
    OraFormsAddPropertyMessage(gnUmsg, ORA_PID_BP_FOREFILLCOL, subMsg);
    OraFormsAddPropertyInt(gnUmsg,2601, 91);
    OraFormsAddPropertyInt(gnUmsg, 2600, 0);
    OraFormsAddPropertyByte(gnUmsg, 2600, 0);
    OraFormsAddPropertyPoint(gnUmsg, ORA_PID_INITIAL_RESOLUTION, 0, 0);
    OraFormsAddPropertyString(gnUmsg, 2600, "E");
    OraFormsPutMessage(gnUmsg);
    OraFormsPutTerminalAndWait();
    OraFormsFree(gnUmsg);
    OraFormsEndMessageBlock("Block#2")
  end TMain;
Parent topic: Properties Functions


OraFormsGetFlexCellData Function

Action

OraFormsGetFlexCellData returns the value of the field in a flex window.

Include file

OraForms.bdh

Syntax

OraFormsGetFlexCellData( in sName : string,
    in sRow  : string,
    in sCol  : string optional) : string;

Return value

  • The value of the field on success.

  • Null otherwise

Parameter | Description
sName | The control's unique name.
sRow | The field’s row.
sCol | The field’s column.

Example

dcltrans
  transaction TMain
  var
    sValue : string;
  begin
    OraFormsSetConnectMode(ORA_SOCKET_CONNECTION);
    // Connect - with connection properties
    OraFormsSetInt("INITIAL_VERSION", 608);
    OraFormsSetPoint("INITIAL_RESOLUTION", 96, 96);
    OraFormsSetPoint("INITIAL_DISP_SIZE", 1024, 768);
    OraFormsSetInt("INITIAL_COLOR_DEPTH", 256);
    OraFormsSetString("FONT_NAME", "Dialog");
    OraFormsSetPoint("INITIAL_SCALE_INFO", 8, 18);
    OraFormsSetBoolean("WINSYS_REQUIREDVA_LIST", false);
    OraFormsConnect("server module=Person3.fmx userid= useSDI=yes record=names");
    OraFormsSetWindow("Logon");
    OraFormsLogon("user", "password", "orcl_server");
    // ---
    // New window activated: WINDOW1
    OraFormsSetWindow("WINDOW1");
    sValue := bin(OraFormsGetFlexCellData("ADB Account", "Transfer", "Low"));
  end TMain;
Parent topic: Properties Functions


OraFormsGetFlexCellPropBoolean Function

Action

OraFormsGetFlexCellPropBoolean returns the Boolean property of a cell.

Include file

OraForms.bdh

Syntax

OraFormsGetFlexCellPropBoolean( in sName : string,
                                in sRow  : string,
                                in sCol  : string,
                                in nProp : number ) : boolean;

Return value

  • true or false

Parameter | Description
sName | The control's unique name.
sRow | The field’s row.
sCol | The field’s column.
nProp

Can be one of these constants:

  • ORA_FLEX_CELL_IS_QUERYABLE

  • ORA_FLEX_CELL_IS_FOCUSNOTIFY

  • ORA_FLEX_CELL_IS_REQUIRED

  • ORA_FLEX_CELL_IS_UPDATEABLE

  • ORA_FLEX_CELL_IS_FLEXFIELD

  • ORA_FLEX_CELL_IS_UPPERCASE

  • ORA_FLEX_CELL_IS_NUMERIC

Example

dcltrans
  transaction TMain
  var
    sValue : string;
  begin
    OraFormsSetConnectMode(ORA_SOCKET_CONNECTION);
    // Connect - with connection properties
    OraFormsSetInt("INITIAL_VERSION", 608);
    OraFormsSetPoint("INITIAL_RESOLUTION", 96, 96);
    OraFormsSetPoint("INITIAL_DISP_SIZE", 1024, 768);
    OraFormsSetInt("INITIAL_COLOR_DEPTH", 256);
    OraFormsSetString("FONT_NAME", "Dialog");
    OraFormsSetPoint("INITIAL_SCALE_INFO", 8, 18);
    OraFormsSetBoolean("WINSYS_REQUIREDVA_LIST", false);
    OraFormsConnect("server module=Person3.fmx userid= useSDI=yes record=names");
    OraFormsSetWindow("Logon");
    OraFormsLogon("user", "password", "orcl_server");
    // ---
    // New window activated: WINDOW1
    OraFormsSetWindow("WINDOW1");
    OraFormsGetFlexCellPropBoolean("ADB Account", "Transfer", "Low",ORA_FLEX_CELL_IS_QUERYABLE);
  end TMain;
Parent topic: Properties Functions


OraFormsGetFlexCellPropBooleanByIndex Function

Action

OraFormsGetFlexCellPropBooleanByIndex returns the Boolean property of a cell.

Include file

OraForms.bdh

Syntax

OraFormsGetFlexCellPropBooleanByIndex( in sName : string,
                                       in nRow  : number,
                                       in nCol  : number,
                                       in nProp : number ) : boolean;

Return value

  • true or false

Parameter | Description
sName | The control's unique name.
nRow | The field’s row.
nCol | The field’s column.
nProp

Can be one of these constants:

  • ORA_FLEX_CELL_IS_QUERYABLE

  • ORA_FLEX_CELL_IS_FOCUSNOTIFY

  • ORA_FLEX_CELL_IS_REQUIRED

  • ORA_FLEX_CELL_IS_UPDATEABLE

  • ORA_FLEX_CELL_IS_FLEXFIELD

  • ORA_FLEX_CELL_IS_UPPERCASE

  • ORA_FLEX_CELL_IS_NUMERIC

Example

dcltrans
  transaction TMain
  var
    sValue : string;
  begin
    OraFormsSetConnectMode(ORA_SOCKET_CONNECTION);
    // Connect - with connection properties
    OraFormsSetInt("INITIAL_VERSION", 608);
    OraFormsSetPoint("INITIAL_RESOLUTION", 96, 96);
    OraFormsSetPoint("INITIAL_DISP_SIZE", 1024, 768);
    OraFormsSetInt("INITIAL_COLOR_DEPTH", 256);
    OraFormsSetString("FONT_NAME", "Dialog");
    OraFormsSetPoint("INITIAL_SCALE_INFO", 8, 18);
    OraFormsSetBoolean("WINSYS_REQUIREDVA_LIST", false);
    OraFormsConnect("server module=Person3.fmx userid= useSDI=yes record=names");
    OraFormsSetWindow("Logon");
    OraFormsLogon("user", "password", "orcl_server");
    // ---
    // New window activated: WINDOW1
    OraFormsSetWindow("WINDOW1");
    OraFormsGetFlexCellPropBooleanByIndex("ADB Account", 0, 0,ORA_FLEX_CELL_IS_QUERYABLE);
  end TMain;
Parent topic: Properties Functions


OraFormsGetFlexCellPropInt Function

Action

OraFormsGetFlexCellPropInt returns a specified cell’s integer property.

Include file

OraForms.bdh

Syntax

OraFormsGetFlexCellPropInt( in sName : string,
                            in sRow  : string,
                            in sCol  : string,
                            in nProp : number ) : number ;

Return value

  • The value on success.

  • -1 otherwise

Parameter | Description
sName | The control's unique name.
sRow | The field’s row.
sCol | The field’s column.
nProp

Can be one of these constants:

  • ORA_FLEX_CELL_IS_QUERYABLE

  • ORA_FLEX_CELL_IS_FOCUSNOTIFY

  • ORA_FLEX_CELL_IS_REQUIRED

  • ORA_FLEX_CELL_IS_UPDATEABLE

  • ORA_FLEX_CELL_IS_FLEXFIELD

  • ORA_FLEX_CELL_IS_UPPERCASE

  • ORA_FLEX_CELL_IS_NUMERIC

Example

dcltrans
  transaction TMain
  var
    sValue : string;
  begin
    OraFormsSetConnectMode(ORA_SOCKET_CONNECTION);
    // Connect - with connection properties
    OraFormsSetInt("INITIAL_VERSION", 608);
    OraFormsSetPoint("INITIAL_RESOLUTION", 96, 96);
    OraFormsSetPoint("INITIAL_DISP_SIZE", 1024, 768);
    OraFormsSetInt("INITIAL_COLOR_DEPTH", 256);
    OraFormsSetString("FONT_NAME", "Dialog");
    OraFormsSetPoint("INITIAL_SCALE_INFO", 8, 18);
    OraFormsSetBoolean("WINSYS_REQUIREDVA_LIST", false);
    OraFormsConnect("server module=Person3.fmx userid= useSDI=yes record=names");
    OraFormsSetWindow("Logon");
    OraFormsLogon("user", "password", "orcl_server");
    // ---
    // New window activated: WINDOW1
    OraFormsSetWindow("WINDOW1");
    OraFormsGetFlexCellPropInt("ADB Account", "Transfer", "Low",ORA_FLEX_CELL_IS_QUERYABLE);
  end TMain;
Parent topic: Properties Functions


OraFormsGetFlexCellPropIntByIndex Function

Action

OraFormsGetFlexCellPropIntByIndex returns a specified cell’s integer property.

Include file

OraForms.bdh

Syntax

OraFormsGetFlexCellPropIntByIndex( in sName : string,
                                   in nRow  : number,
                                   in nCol  : number,
                                   in nProp : number ) : number;

Return value

  • The value on success

  • -1 otherwise

Parameter | Description
sName | The control's unique name.
nRow | The field’s row.
nCol | The field’s column.
nProp

Can be one of these constants:

  • ORA_FLEX_CELL_IS_QUERYABLE

  • ORA_FLEX_CELL_IS_FOCUSNOTIFY

  • ORA_FLEX_CELL_IS_REQUIRED

  • ORA_FLEX_CELL_IS_UPDATEABLE

  • ORA_FLEX_CELL_IS_FLEXFIELD

  • ORA_FLEX_CELL_IS_UPPERCASE

  • ORA_FLEX_CELL_IS_NUMERIC

Example

dcltrans
  transaction TMain
  var
    sValue : string;
  begin
    OraFormsSetConnectMode(ORA_SOCKET_CONNECTION);
    // Connect - with connection properties
    OraFormsSetInt("INITIAL_VERSION", 608);
    OraFormsSetPoint("INITIAL_RESOLUTION", 96, 96);
    OraFormsSetPoint("INITIAL_DISP_SIZE", 1024, 768);
    OraFormsSetInt("INITIAL_COLOR_DEPTH", 256);
    OraFormsSetString("FONT_NAME", "Dialog");
    OraFormsSetPoint("INITIAL_SCALE_INFO", 8, 18);
    OraFormsSetBoolean("WINSYS_REQUIREDVA_LIST", false);
    OraFormsConnect("server module=Person3.fmx userid= useSDI=yes record=names");
    OraFormsSetWindow("Logon");
    OraFormsLogon("user", "password", "orcl_server");
    // ---
    // New window activated: WINDOW1
    OraFormsSetWindow("WINDOW1");
    OraFormsGetFlexCellPropIntByIndex("ADB Account", 0, 0,ORA_FLEX_CELL_IS_QUERYABLE);
  end TMain;
Parent topic: Properties Functions


OraFormsGetFlexCellPropString Function

Action

OraFormsGetFlexPropString returns a flex window cell’s string property.

Include file

OraForms.bdh

Syntax

OraFormsGetFlexCellPropString( in sName : string,
                               in sRow  : string,
                               in sCol  : string,
                               in nProp : number ) : string;

Return value

  • The value on success.

  • NULL otherwise

Parameter | Description
sName | The control's unique name.
sRow | The field’s row.
sCol | The field’s column.
nProp

Can be one of these constants:

  • ORA_FLEX_CELL_IS_QUERYABLE

  • ORA_FLEX_CELL_IS_FOCUSNOTIFY

  • ORA_FLEX_CELL_IS_REQUIRED

  • ORA_FLEX_CELL_IS_UPDATEABLE

  • ORA_FLEX_CELL_IS_FLEXFIELD

  • ORA_FLEX_CELL_IS_UPPERCASE

  • ORA_FLEX_CELL_IS_NUMERIC

Example

dcltrans
  transaction TMain
  var
    sValue : string;
  begin
    OraFormsSetConnectMode(ORA_SOCKET_CONNECTION);
    // Connect - with connection properties
    OraFormsSetInt("INITIAL_VERSION", 608);
    OraFormsSetPoint("INITIAL_RESOLUTION", 96, 96);
    OraFormsSetPoint("INITIAL_DISP_SIZE", 1024, 768);
    OraFormsSetInt("INITIAL_COLOR_DEPTH", 256);
    OraFormsSetString("FONT_NAME", "Dialog");
    OraFormsSetPoint("INITIAL_SCALE_INFO", 8, 18);
    OraFormsSetBoolean("WINSYS_REQUIREDVA_LIST", false);
    OraFormsConnect("server module=Person3.fmx userid= useSDI=yes record=names");
    OraFormsSetWindow("Logon");
    OraFormsLogon("user", "password", "orcl_server");
    // ---
    // New window activated: WINDOW1
    OraFormsSetWindow("WINDOW1");
    OraFormsGetFlexCellPropString("ADB Account", "Transfer", "Low",ORA_FLEX_CELL_IS_QUERYABLE);
  end TMain;
Parent topic: Properties Functions


OraFormsGetFlexCellPropStringByIndex function

Action

OraFormsGetFlexPropStringByIndex returns a flex window cell’s string property.

Include file

OraForms.bdh

Syntax

OraFormsGetFlexCellPropStringByIndex( in sName : string,
                                      in nRow  : number,
                                      in nCol  : number,
                                      in nProp : number ) : string;

Return value

  • The value of the property on success.

  • NULL otherwise

Parameter | Description
sName | The control's unique name.
nRow | The field’s row.
nCol | The field’s column.
nProp

Can be one of these constants:

  • ORA_FLEX_CELL_IS_QUERYABLE

  • ORA_FLEX_CELL_IS_FOCUSNOTIFY

  • ORA_FLEX_CELL_IS_REQUIRED

  • ORA_FLEX_CELL_IS_UPDATEABLE

  • ORA_FLEX_CELL_IS_FLEXFIELD

  • ORA_FLEX_CELL_IS_UPPERCASE

  • ORA_FLEX_CELL_IS_NUMERIC

Example

dcltrans
  transaction TMain
  var
    sValue : string;
  begin
    OraFormsSetConnectMode(ORA_SOCKET_CONNECTION);
    // Connect - with connection properties
    OraFormsSetInt("INITIAL_VERSION", 608);
    OraFormsSetPoint("INITIAL_RESOLUTION", 96, 96);
    OraFormsSetPoint("INITIAL_DISP_SIZE", 1024, 768);
    OraFormsSetInt("INITIAL_COLOR_DEPTH", 256);
    OraFormsSetString("FONT_NAME", "Dialog");
    OraFormsSetPoint("INITIAL_SCALE_INFO", 8, 18);
    OraFormsSetBoolean("WINSYS_REQUIREDVA_LIST", false);
    OraFormsConnect("server module=Person3.fmx userid= useSDI=yes record=names");
    OraFormsSetWindow("Logon");
    OraFormsLogon("user", "password", "orcl_server");
    // ---
    // New window activated: WINDOW1
    OraFormsSetWindow("WINDOW1");
    OraFormsGetFlexCellPropStringByIndex("ADB Account", 0, 0,ORA_FLEX_CELL_IS_QUERYABLE);
  end TMain;
Parent topic: Properties Functions


OraFormsGetFlexColumnCount Function

Action

OraFormsGetFlexColumnCount returns the number of columns in a flex window.

Include file

OraForms.bdh

Syntax

OraFormsGetFlexColumnCount( in name : string ) : number;

Return value

  • If successful, the number of columns.

  • -1 otherwise

Parameter | Description
sName | The control's unique name.

Example

dcltrans
  transaction TMain
  var
    sValue : string;
  begin
    OraFormsSetConnectMode(ORA_SOCKET_CONNECTION);
    // Connect - with connection properties
    OraFormsSetInt("INITIAL_VERSION", 608);
    OraFormsSetPoint("INITIAL_RESOLUTION", 96, 96);
    OraFormsSetPoint("INITIAL_DISP_SIZE", 1024, 768);
    OraFormsSetInt("INITIAL_COLOR_DEPTH", 256);
    OraFormsSetString("FONT_NAME", "Dialog");
    OraFormsSetPoint("INITIAL_SCALE_INFO", 8, 18);
    OraFormsSetBoolean("WINSYS_REQUIREDVA_LIST", false);
    OraFormsConnect("server module=Person3.fmx userid= useSDI=yes record=names");
    OraFormsSetWindow("Logon");
    OraFormsLogon("user", "password", "orcl_server");
    // ---
    // New window activated: WINDOW1
    OraFormsSetWindow("WINDOW1");
    OraFormsGetFlexColumnCount("ADB Account");
  end TMain;
Parent topic: Properties Functions


OraFormsGetFlexColumnIndex Function

Action

OraFormsGetFlexColumnIndex returns the index of the specified column.

Include file

OraForms.bdh

Syntax

OraFormsGetFlexColumnIndex( in sName   : string,
                            in sColumn : string ) : number;

Return value

  • The 0-based index of the column if successful.

  • -1 otherwise

Parameter | Description
sName | The control's unique name.
sColumn | The field’s column.

Example

dcltrans
  transaction TMain
  var
    sValue : string;
  begin
    OraFormsSetConnectMode(ORA_SOCKET_CONNECTION);
    // Connect - with connection properties
    OraFormsSetInt("INITIAL_VERSION", 608);
    OraFormsSetPoint("INITIAL_RESOLUTION", 96, 96);
    OraFormsSetPoint("INITIAL_DISP_SIZE", 1024, 768);
    OraFormsSetInt("INITIAL_COLOR_DEPTH", 256);
    OraFormsSetString("FONT_NAME", "Dialog");
    OraFormsSetPoint("INITIAL_SCALE_INFO", 8, 18);
    OraFormsSetBoolean("WINSYS_REQUIREDVA_LIST", false);
    OraFormsConnect("server module=Person3.fmx userid= useSDI=yes record=names");
    OraFormsSetWindow("Logon");
    OraFormsLogon("user", "password", "orcl_server");
    // ---
    // New window activated: WINDOW1
    OraFormsSetWindow("WINDOW1");
    OraFormsGetFlexColumnIndex("ADB Account", "Low")
  end TMain;
Parent topic: Properties Functions


OraFormsGetFlexColumnName Function

Action

OraFormsGetFlexColumnName returns a column’s name.

Include file

OraForms.bdh

Syntax

OraFormsGetFlexColumnName( in sName   : string,
                           in nColumn : number ) : string;

Return value

  • The name of the row on success.

  • NULL otherwise

Parameter | Description
sName | The control's unique name.
nColumn | The 0-based index of the column.

Example

dcltrans
  transaction TMain
  var
    sValue : string;
  begin
    OraFormsSetConnectMode(ORA_SOCKET_CONNECTION);
    // Connect - with connection properties
    OraFormsSetInt("INITIAL_VERSION", 608);
    OraFormsSetPoint("INITIAL_RESOLUTION", 96, 96);
    OraFormsSetPoint("INITIAL_DISP_SIZE", 1024, 768);
    OraFormsSetInt("INITIAL_COLOR_DEPTH", 256);
    OraFormsSetString("FONT_NAME", "Dialog");
    OraFormsSetPoint("INITIAL_SCALE_INFO", 8, 18);
    OraFormsSetBoolean("WINSYS_REQUIREDVA_LIST", false);
    OraFormsConnect("server module=Person3.fmx userid= useSDI=yes record=names");
    OraFormsSetWindow("Logon");
    OraFormsLogon("user", "password", "orcl_server");
    // ---
    // New window activated: WINDOW1
    OraFormsSetWindow("WINDOW1");
    sValue := bin(OraFormsGetFlexColumnName("ADB Account", 0));
    if (StrIsNull(sValue)) then
      Print("No Column name");
    else
      Print(sValue);
    end;
  end TMain;
Parent topic: Properties Functions


OraFormsGetFlexPropBoolean Function

Action

OraFormsGetFlexPropBoolean returns a specified Boolean type flex window property.

Include file

OraForms.bdh

Syntax

OraFormsGetFlexPropBoolean( in sName : string,
                            in nProp : number ) : boolean;

Return value

  • true or false

Parameter | Description
sName | The control's unique name.
nReturn

Can be one of these constants:

  • ORA_FLEX_WND_IS_AUTOPIK

  • ORA_FLEX_WND_IS_AUTOSKIP

  • ORA_FLEX_WND_IS_COMBO_AVAILABLE

  • ORA_FLEX_WND_IS_READONLY

Example

dcltrans
  transaction TMain
  var
    sValue : string;
  begin
    OraFormsSetConnectMode(ORA_SOCKET_CONNECTION);
    // Connect - with connection properties
    OraFormsSetInt("INITIAL_VERSION", 608);
    OraFormsSetPoint("INITIAL_RESOLUTION", 96, 96);
    OraFormsSetPoint("INITIAL_DISP_SIZE", 1024, 768);
    OraFormsSetInt("INITIAL_COLOR_DEPTH", 256);
    OraFormsSetString("FONT_NAME", "Dialog");
    OraFormsSetPoint("INITIAL_SCALE_INFO", 8, 18);
    OraFormsSetBoolean("WINSYS_REQUIREDVA_LIST", false);
    OraFormsConnect("server module=Person3.fmx userid= useSDI=yes record=names");
    OraFormsSetWindow("Logon");
    OraFormsLogon("user", "password", "orcl_server");
    // ---
    // New window activated: WINDOW1
    OraFormsSetWindow("WINDOW1");
    OraFormsGetFlexPropBoolean("ADB Account", ORA_FLEX_WND_IS_READONLY);
  end TMain;
Parent topic: Properties Functions


OraFormsGetFlexPropString Function

Action

OraFormsGetFlexPropString returns the specified string property of a flex window.

Include file

OraForms.bdh

Syntax

OraFormsGetFlexPropString( in sName : string,
                           in nProp : number ) : string;

Return value

  • The value of the property on success.

  • NULL otherwisee

Parameter | Description
sName | The control's unique name.
nProp

Can be one of these constants:

  • ORA_FLEX_WND_LABEL

  • ORA_FLEX_WND_PROTOCOL

Example

dcltrans
  transaction TMain
  var
    sValue : string;
  begin
    OraFormsSetConnectMode(ORA_SOCKET_CONNECTION);
    // Connect - with connection properties
    OraFormsSetInt("INITIAL_VERSION", 608);
    OraFormsSetPoint("INITIAL_RESOLUTION", 96, 96);
    OraFormsSetPoint("INITIAL_DISP_SIZE", 1024, 768);
    OraFormsSetInt("INITIAL_COLOR_DEPTH", 256);
    OraFormsSetString("FONT_NAME", "Dialog");
    OraFormsSetPoint("INITIAL_SCALE_INFO", 8, 18);
    OraFormsSetBoolean("WINSYS_REQUIREDVA_LIST", false);
    OraFormsConnect("server module=Person3.fmx userid= useSDI=yes record=names");
    OraFormsSetWindow("Logon");
    OraFormsLogon("user", "password", "orcl_server");
    // ---
    // New window activated: WINDOW1
    OraFormsSetWindow("WINDOW1");
    OraFormsGetFlexPropString("ADB Account", ORA_FLEX_WND_LABEL);
  end TMain;
Parent topic: Properties Functions


OraFormsGetFlexRowCount Function

Action

OraFormsGetFlexRowCount returns the number of rows within a flex window.

Include file

OraForms.bdh

Syntax

OraFormsGetFlexRowCount( in sName : string ) : number;

Return value

  • The number of rows on success.

  • -1 otherwise

Parameter | Description
sName | The control's unique name.

Example

dcltrans
  transaction TMain
  var
    sValue : string;
  begin
    OraFormsSetConnectMode(ORA_SOCKET_CONNECTION);
    // Connect - with connection properties
    OraFormsSetInt("INITIAL_VERSION", 608);
    OraFormsSetPoint("INITIAL_RESOLUTION", 96, 96);
    OraFormsSetPoint("INITIAL_DISP_SIZE", 1024, 768);
    OraFormsSetInt("INITIAL_COLOR_DEPTH", 256);
    OraFormsSetString("FONT_NAME", "Dialog");
    OraFormsSetPoint("INITIAL_SCALE_INFO", 8, 18);
    OraFormsSetBoolean("WINSYS_REQUIREDVA_LIST", false);
    OraFormsConnect("server module=Person3.fmx userid= useSDI=yes record=names");
    OraFormsSetWindow("Logon");
    OraFormsLogon("user", "password", "orcl_server");
    // ---
    // New window activated: WINDOW1
    OraFormsSetWindow("WINDOW1");
    OraFormsGetFlexRowCount("ADB Account");
  end TMain;
Parent topic: Properties Functions


OraFormsGetFlexRowIndex Function

Action

OraFormsGetFlexRowIndex returns the index of the specified row.

Include file

OraForms.bdh

Syntax

OraFormsGetFlexRowIndex( in sName : string,
                         in sRow  : string ) : number;

Return value

  • The index of the row on success.

  • -1 otherwise

Parameter | Description
sName | The control's unique name.
sRow | The name of the row.

Example

dcltrans
  transaction TMain
  var
    sValue : string;
  begin
    OraFormsSetConnectMode(ORA_SOCKET_CONNECTION);
    // Connect - with connection properties
    OraFormsSetInt("INITIAL_VERSION", 608);
    OraFormsSetPoint("INITIAL_RESOLUTION", 96, 96);
    OraFormsSetPoint("INITIAL_DISP_SIZE", 1024, 768);
    OraFormsSetInt("INITIAL_COLOR_DEPTH", 256);
    OraFormsSetString("FONT_NAME", "Dialog");
    OraFormsSetPoint("INITIAL_SCALE_INFO", 8, 18);
    OraFormsSetBoolean("WINSYS_REQUIREDVA_LIST", false);
    OraFormsConnect("server module=Person3.fmx userid= useSDI=yes record=names");
    OraFormsSetWindow("Logon");
    OraFormsLogon("user", "password", "orcl_server");
    // ---
    // New window activated: WINDOW1
    OraFormsSetWindow("WINDOW1");
    OraFormsGetFlexRowIndex("ADB Account", "Transfer");
  end TMain;
Parent topic: Properties Functions


OraFormsGetFlexRowName Function

Action

OraFormsGetFlexRowName returns the name of the specified row within a flex window.

Include file

OraForms.bdh

Syntax

OraFormsGetFlexRowName( in sName : string,
                        in nRow  : number ) : string;

Return value

  • The name of the row on success.

  • NULL otherwise

Parameter | Description
sName | The control's unique name.
nRow | The 0-based index of the row.

Example

dcltrans
  transaction TMain
  var
    sValue : string;
  begin
    OraFormsSetConnectMode(ORA_SOCKET_CONNECTION);
    // Connect - with connection properties
    OraFormsSetInt("INITIAL_VERSION", 608);
    OraFormsSetPoint("INITIAL_RESOLUTION", 96, 96);
    OraFormsSetPoint("INITIAL_DISP_SIZE", 1024, 768);
    OraFormsSetInt("INITIAL_COLOR_DEPTH", 256);
    OraFormsSetString("FONT_NAME", "Dialog");
    OraFormsSetPoint("INITIAL_SCALE_INFO", 8, 18);
    OraFormsSetBoolean("WINSYS_REQUIREDVA_LIST", false);
    OraFormsConnect("server module=Person3.fmx userid= useSDI=yes record=names");
    OraFormsSetWindow("Logon");
    OraFormsLogon("user", "password", "orcl_server");
    // ---
    // New window activated: WINDOW1
    OraFormsSetWindow("WINDOW1");
    sValue := bin(OraFormsGetFlexRowName("ADB Account", 0));
    if (StrIsNull(sValue)) then
      Print("No Column name");
    else
      Print(sValue);
    end;
  end TMain;
Parent topic: Properties Functions


OraFormsGetPropByte Function

Action

Returns the specified property's value for the given control.

Include file

OraForms.bdh

Syntax

OraFormsGetPropByte( in sName   : string,
                     in nPropId : number ) : number;

Return value

The value of the property.

Parameter | Description
sName | The control's unique name.
nPropId | The ID of the property.

Example

dcltrans
  transaction TMain
  var
    nValue : number;
  begin
    OraFormsConnect("server module=javamail90.fmx usesdi=yes userid=");
    OraFormsSetWindow("BASE_DEMO_WINDOW");
    OraFormsWindowMove("BASE_DEMO_WINDOW", 0, -24);
    nValue := OraFormsGetPropByte("1", ORA_PID_IMAGE_VALUE);
  end TMain;
Parent topic: Properties Functions


OraFormsGetPropByteArray Function

Action

Returns an element of a byte array for a specified property within a control.

Include file

OraForms.bdh

Syntax

OraFormsGetPropByteArray( in sName   : string,
                          in nPropId : number,
                          in nIndex  : number) : number;

Return value

The property's value at the specified position.

Parameter | Description
sName | The control's unique name.
nPropId | The property ID for the byte array property, for example ORA_PID_BP_CHUNK.
nIndex | The position of the element to be returned. This array index is 1-based.

Example

  var i, aByte :number;
    for i := 1 to OraFormsGetPropByteArrayLen("143", ORA_PID_IMAGE_VALUE) do
      aByte := OraFormsGetPropByteArray("143", ORA_PID_IMAGE_VALUE, i-1);
      Write(string(aByte)+",");
    end;
Parent topic: Properties Functions


OraFormsGetPropByteArrayLen Function

Action

Returns the length for a byte array property.

Include file

OraForms.bdh

Syntax

OraFormsGetPropByteArrayLen(  in sName   :  string,
                               in nPropId :  number ) :  number;

Return value

  • The length of the array on success
  • -1 otherwise
Parameter | Description
sName | The control's unique name.
nPropId | The property ID for the byte array property, for example ORA_PID_BP_CHUNK.

Example

dcltrans
  transaction TMain
  var
    nLen, nIndex : number;
  begin
    OraFormsConnect("server module= iorganizer.fmx usesdi=yes userid= record=names);
    OraFormsSetWindow( "BASE_DEMO_WINDOW");
    OraFormsMessageBoxButton("Question", ORA_ALERT_YES);
    nLen := OraFormsGetPropByteArrayLen("164", ORA_PID_BP_CHUNK);
    Print("nLen = "+string(nLen));
    for nIndex := 0 to nLen - 1 do
      Print(string(OraFormsGetPropByteArray("164", ORA_PID_BP_CHUNK, nIndex)));
    end;
  end TMain;
Parent topic: Properties Functions


OraFormsGetPropInt Function

Action

Returns the specified property's value for the given control.

Include file

OraForms.bdh

Syntax

OraFormsGetPropInt(  in sName :  string,
                     in nPropId :  number ) :  number;

Return value

  • The property's value
Parameter | Description
sName | The control's unique name.
nPropId | The property to be returned.

Example

dcltrans
  transaction TMain
  var
    nValue :  number;
  begin
    OraFormsConnect( "server module=javamail90.fmx usesdi=yes userid=");
    OraFormsSetWindow( "BASE_DEMO_WINDOW");
    OraFormsWindowMove( "BASE_DEMO_WINDOW", 0,  -24);
    nValue :=  OraFormsGetPropInt( "1", ORA_PID_FONT_SIZE);
  end TMain;
Parent topic: Properties Functions


OraFormsGetPropNull Function

Action

Determines whether a property for the specified control is NULL.

Include file

OraForms.bdh

Syntax

OraFormsGetPropNull( in sName   : string,
                     in nPropId : number ) : boolean;

Return value

  • true if the property is null

  • false otherwise

Parameter | Description
sName | The control’s unique name.
nPropId | The property to be tested for NULL.

Example

dcltrans
  transaction TMain
  var
    bIsNull : boolean;
  begin
    OraFormsConnect("server module=javamail90.fmx usesdi=yes userid=");
    OraFormsSetWindow("BASE_DEMO_WINDOW");
    OraFormsWindowMove("BASE_DEMO_WINDOW", 0, -24);
    bIsNull := OraFormsGetPropNull("1", ORA_PID_IMAGE_VALUE);
  end TMain;
Parent topic: Properties Functions


OraFormsGetPropPoint Function

Action

Gets the value for a point property of a specified control.

Include file

OraForms.bdh

Syntax

OraFormsGetPropPoint(  in sName   :  string,
                       in nPropId :  number,
                       out nX     :  number,
                       out nY     :  number ) :  boolean;

Return value

  • true if successful
  • false otherwise
Parameter | Description
sName | The control's unique name.
nPropId | The property ID.
nX | Will be assigned the x value of the point property.
nY | Will be assigned the y value of the point property.

Example

dcltrans
  transaction TMain
  var
    nX :  number;
    nY :  number;
  begin
    OraFormsConnect( "server module=javamail90.fmx usesdi=yes userid=");
    OraFormsSetWindow( "BASE_DEMO_WINDOW");
    OraFormsWindowMove( "BASE_DEMO_WINDOW", 0,  -24);
    OraFormsGetPropPoint( "MAIN", ORA_PID_SIZE, nX, nY);
  end TMain;
Parent topic: Properties Functions


OraFormsGetPropRectangle Function

Action

Returns the value of a rectangle property for the specified control.

Include file

OraForms.bdh

Syntax

OraFormsGetPropRectangle(  in sName   :  string,
                           in nPropId :  number,
                           out nX0    :  number,
                           out nY0    :  number,
                           out nX1    :  number,
                           out nY0    :  number ) :  boolean;

Return value

  • true if successful
  • false otherwise
Parameter | Description
sName | The control's unique name.
nPropId | A property ID for a rectangle property.
nX0 | x part of the first coordinates.
nY0 | y part of the first coordinates.
nX1 | x part of the second coordinates.
nY1 | y part of the second coordinates.
Parent topic: Properties Functions


OraFormsGetPropString Function

Action

Returns the specified property's value for the given control. The function may also return a NULL string. Use the function StrIsNull to determine whether a string is NULL.

Include file

OraForms.bdh

Syntax

OraFormsGetPropString(  in sName   :  string,
                        in nPropId :  number ) :  string;

Return value

  • The string on success
  • NULL otherwise
Parameter | Description
sName | The control's unique name.
nPropId | The string property's ID.

Example

dcltrans
  transaction TMain
  var
    sValue :  string;
  begin
    OraFormsConnect( "server module=javamail90.fmx usesdi=yes userid=");
    OraFormsSetWindow( "BASE_DEMO_WINDOW");
    OraFormsWindowMove( "BASE_DEMO_WINDOW", 0,  -24);
    sValue:=  OraFormsGetPropString( "MAIN", ORA_PID_TITLE);
    if StrIsNull(sValue)  then
      Print( "sValue is null");
    end;
  end TMain;
Parent topic: Properties Functions


OraFormsGetPropStringArray Function

Action

Returns an element of a string array property at a given position.

Include file

OraForms.bdh

Syntax

OraFormsGetPropStringArray(  in sName   :  string,
                             in nPropId :  number,
                             in nIndex  :  number ):  string;

Return value

The string at the specified position within the array

Parameter | Description
sName | The control's unique name or ID. The ID can be retrieved from the TrueLog's In Body page.
nPropId | The property ID for the string array property, for example ORA_PID_VALUE.
nIndex | The position of the element to be returned. This index is 0-based.

Example

dcltrans
  transaction TMain
  var
    nLen   :  number;
    nIndex :  number;
  begin
    OraFormsConnect("server module= iorganizer.fmx usesdi=yes userid= record=names);
    OraFormsSetWindow("BASE_DEMO_WINDOW");
    OraFormsMessageBoxButton("Question", ORA_ALERT_YES);
    nLen := OraFormsGetPropStringArrayLen("146", ORA_PID_VALUE);
    Print("nLen = "+string(nLen));
    for nIndex := 0 to nLen - 1 do
      Print(OraFormsGetPropStringArray("146", ORA_PID_VALUE, nIndex));
    end;
  end TMain;
Parent topic: Properties Functions


OraFormsGetPropStringArrayLen Function

Action

Returns the length (a number) of a string array property.

Include file

OraForms.bdh

Syntax

OraFormsGetPropStringArrayLen(  in sName   :  string,
                                in nPropId :  number ):  number;

Return value

Number representing the length of the string array.

Parameter | Description
sName | The control's unique name or ID. The ID can be retrieved from the TrueLog's In Body page.
nPropId | The property ID for the string array property, for example ORA_PID_VALUE.

Example

dcltrans
  transaction TMain
  var
    nLen   :  number;
    nIndex :  number;
  begin
    OraFormsConnect("server module= iorganizer.fmx usesdi=yes userid= record=names);
    OraFormsSetWindow("BASE_DEMO_WINDOW");
    OraFormsMessageBoxButton("Question", ORA_ALERT_YES);
    nLen := OraFormsGetPropStringArrayLen("146", ORA_PID_VALUE);
    Print("nLen = "+string(nLen));
    for nIndex := 0 to nLen - 1 do
      Print(OraFormsGetPropStringArray("146", ORA_PID_VALUE, nIndex));
    end;
  end TMain;
Parent topic: Properties Functions


OraFormsSetBoolean Function

Action

Sets a boolean property that must be sent with the next request.

Include file

OraForms.bdh

Syntax

OraFormsSetBoolean( in sProperty : string,
                    in bValue    : boolean );
Parameter | Description
sProprety | The property name.
bValue | True or false.

Example

dcltrans
  transaction TMain
    OraFormsSetInt("INITIAL_VERSION", 90290);
    OraFormsSetPoint("INITIAL_RESOLUTION", 96, 96);
    OraFormsSetPoint("INITIAL_DISP_SIZE", 1024, 768);
    OraFormsSetInt("INITIAL_COLOR_DEPTH", 256);
    OraFormsSetInt("WINSYS_COLOR_ADD", 0);
    OraFormsSetInt("WINSYS_COLOR_ADD", 255);
    OraFormsSetInt("WINSYS_COLOR_ADD", 65535);
    OraFormsSetInt("WINSYS_COLOR_ADD", 4210752);
    OraFormsSetInt("WINSYS_COLOR_ADD", 8421504);
    OraFormsSetInt("WINSYS_COLOR_ADD", 65280);
    OraFormsSetInt("WINSYS_COLOR_ADD", 12632256);
    OraFormsSetInt("WINSYS_COLOR_ADD", 16711935);
    OraFormsSetInt("WINSYS_COLOR_ADD", 16762880);
    OraFormsSetInt("WINSYS_COLOR_ADD", 16756655);
    OraFormsSetInt("WINSYS_COLOR_ADD", 16711680);
    OraFormsSetInt("WINSYS_COLOR_ADD", 16777215);
    OraFormsSetInt("WINSYS_COLOR_ADD", 16776960);
    OraFormsSetString("FONT_NAME", "Dialog");
    OraFormsSetInt("FONT_SIZE", 900);
    OraFormsSetByte("FONT_STYLE", 0);
    OraFormsSetPoint("INITIAL_SCALE_INFO", 8, 20);
    OraFormsSetBoolean("WINSYS_REQUIREDVA_LIST", false);
    OraFormsSetString("DEFAULT_LOCAL_TZ", "Europe/Berlin");
    OraFormsConnect( "server module=c:\\orant\\forms90\\EDITCOMBO.fmx usesdi=yes userid= sso_userid=");
  end TMain;
Parent topic: Properties Functions
Related reference
OraFormsConnect Function
OraFormsOnMessageGet Function


OraFormsSetByte Function

Action

Sets a byte property that must be sent with the next request.

Include file

OraForms.bdh

Syntax

OraFormsSetByte( in sProperty : string,
                 in nValue    : number,
                 in nFlag     : number optional );
Parameter | Description
sProperty | The property name.
nValue | The property value.
nFlag

The type of function that will send the property (optional) Possible values:

  • ORA_SET_TYPE_NORMAL (default)

  • ORA_SET_TYPE_MESSAGEGET, which is currently only used for the OraFormsOnMessageGet function.

Example

dcltrans
  transaction TMain
    OraFormsSetInt("INITIAL_VERSION", 90290);
    OraFormsSetPoint("INITIAL_RESOLUTION", 96, 96);
    OraFormsSetPoint("INITIAL_DISP_SIZE", 1024, 768);
    OraFormsSetInt("INITIAL_COLOR_DEPTH", 256);
    OraFormsSetInt("WINSYS_COLOR_ADD", 0);
    OraFormsSetInt("WINSYS_COLOR_ADD", 255);
    OraFormsSetInt("WINSYS_COLOR_ADD", 65535);
    OraFormsSetInt("WINSYS_COLOR_ADD", 4210752);
    OraFormsSetInt("WINSYS_COLOR_ADD", 8421504);
    OraFormsSetInt("WINSYS_COLOR_ADD", 65280);
    OraFormsSetInt("WINSYS_COLOR_ADD", 12632256);
    OraFormsSetInt("WINSYS_COLOR_ADD", 16711935);
    OraFormsSetInt("WINSYS_COLOR_ADD", 16762880);
    OraFormsSetInt("WINSYS_COLOR_ADD", 16756655);
    OraFormsSetInt("WINSYS_COLOR_ADD", 16711680);
    OraFormsSetInt("WINSYS_COLOR_ADD", 16777215);
    OraFormsSetInt("WINSYS_COLOR_ADD", 16776960);
    OraFormsSetString("FONT_NAME", "Dialog");
    OraFormsSetInt("FONT_SIZE", 900);
    OraFormsSetByte("FONT_STYLE", 0);
    OraFormsSetPoint("INITIAL_SCALE_INFO", 8, 20);
    OraFormsSetBoolean("WINSYS_REQUIREDVA_LIST", false);
    OraFormsSetString("DEFAULT_LOCAL_TZ", "Europe/Berlin");
    OraFormsConnect( "server module=c:\\orant\\forms90\\EDITCOMBO.fmx usesdi=yes userid= sso_userid=");
  end TMain;
Parent topic: Properties Functions
Related reference
OraFormsConnect Function
OraFormsOnMessageGet Function


OraFormsSetByteArray Function

Action

Sets a byte array that must be sent with the next request.

Include file

OraForms.bdh

Syntax

OraFormsSetByteArray( in sPropertry : string,
                      in byteArray  : array of number,
                      in nLen       : number,
                      in nFlag      : number optional );
Parameter | Description
sProperty | The property name.
byteArray | The property value.
nLen | The length of the array.
nFlag

The type of function that will send the property (optional) Possible values:

  • ORA_SET_TYPE_NORMAL (default)

  • ORA_SET_TYPE_MESSAGEGET, which is currently only used for the OraFormsOnMessageGet function.

Example

dcltrans
  transaction TMain
  var    nArray : array of number init 1, 2, 3, 4, 5;  begin
    OraFormsSetInt("INITIAL_VERSION", 90290);
    OraFormsSetPoint("INITIAL_RESOLUTION", 96, 96);
    OraFormsSetPoint("INITIAL_DISP_SIZE", 1024, 768);
    OraFormsSetInt("INITIAL_COLOR_DEPTH", 256);
    OraFormsSetInt("WINSYS_COLOR_ADD", 0);
    OraFormsSetInt("WINSYS_COLOR_ADD", 255);
    OraFormsSetInt("WINSYS_COLOR_ADD", 65535);
    OraFormsSetInt("WINSYS_COLOR_ADD", 4210752);
    OraFormsSetInt("WINSYS_COLOR_ADD", 8421504);
    OraFormsSetInt("WINSYS_COLOR_ADD", 65280);
    OraFormsSetInt("WINSYS_COLOR_ADD", 12632256);
    OraFormsSetInt("WINSYS_COLOR_ADD", 16711935);
    OraFormsSetInt("WINSYS_COLOR_ADD", 16762880);
    OraFormsSetInt("WINSYS_COLOR_ADD", 16756655);
    OraFormsSetInt("WINSYS_COLOR_ADD", 16711680);
    OraFormsSetInt("WINSYS_COLOR_ADD", 16777215);
    OraFormsSetInt("WINSYS_COLOR_ADD", 16776960);
    OraFormsSetString("FONT_NAME", "Dialog");
    OraFormsSetInt("FONT_SIZE", 900);
    OraFormsSetByte("FONT_STYLE", 0);
    OraFormsSetPoint("INITIAL_SCALE_INFO", 8, 20);
    OraFormsSetBoolean("WINSYS_REQUIREDVA_LIST", false);
    OraFormsSetString("DEFAULT_LOCAL_TZ", "Europe/Berlin");    OraFormsSetByteArray("KEYBINDING", nArray, 5);
    OraFormsConnect( "server module=c:\\orant\\forms90\\EDITCOMBO.fmx usesdi=yes userid= sso_userid=");
  end TMain;
Parent topic: Properties Functions
Related reference
OraFormsConnect Function
OraFormsOnMessageGet Function


OraFormsSetCharacter Function

Action

Sets a character property that must be sent with the next request.

Include file

OraForms.bdh

Syntax

OraFormsSetCharacter( in sProperty : string,
                      in nChar     : number,
                      in nFlag     : number optional );
Parameter | Description
sProperty | The property name.
nChar | The property value.
nFlag

The type of function that will send the property (optional) Possible values:

  • ORA_SET_TYPE_NORMAL (default)

  • ORA_SET_TYPE_MESSAGEGET, which is currently only used for the OraFormsOnMessageGet function.

Example

dcltrans
  transaction TMain
    OraFormsSetInt("INITIAL_VERSION", 90290);
    OraFormsSetPoint("INITIAL_RESOLUTION", 96, 96);
    OraFormsSetPoint("INITIAL_DISP_SIZE", 1024, 768);
    OraFormsSetInt("INITIAL_COLOR_DEPTH", 256);
    OraFormsSetInt("WINSYS_COLOR_ADD", 0);
    OraFormsSetInt("WINSYS_COLOR_ADD", 255);
    OraFormsSetInt("WINSYS_COLOR_ADD", 65535);
    OraFormsSetInt("WINSYS_COLOR_ADD", 4210752);
    OraFormsSetInt("WINSYS_COLOR_ADD", 8421504);
    OraFormsSetInt("WINSYS_COLOR_ADD", 65280);
    OraFormsSetInt("WINSYS_COLOR_ADD", 12632256);
    OraFormsSetInt("WINSYS_COLOR_ADD", 16711935);
    OraFormsSetInt("WINSYS_COLOR_ADD", 16762880);
    OraFormsSetInt("WINSYS_COLOR_ADD", 16756655);
    OraFormsSetInt("WINSYS_COLOR_ADD", 16711680);
    OraFormsSetInt("WINSYS_COLOR_ADD", 16777215);
    OraFormsSetInt("WINSYS_COLOR_ADD", 16776960);
    OraFormsSetString("FONT_NAME", "Dialog");
    OraFormsSetInt("FONT_SIZE", 900);
    OraFormsSetByte("FONT_STYLE", 0);
    OraFormsSetPoint("INITIAL_SCALE_INFO", 8, 20);
    OraFormsSetBoolean("WINSYS_REQUIREDVA_LIST", false);
    OraFormsSetString("DEFAULT_LOCAL_TZ", "Europe/Berlin");
    OraFormsSetCharacter("DRAWN_CANVASUSAGE", 65);
    OraFormsConnect( "server module=c:\\orant\\forms90\\EDITCOMBO.fmx usesdi=yes userid= sso_userid=");
  end TMain;
Parent topic: Properties Functions
Related reference
OraFormsConnect Function
OraFormsOnMessageGet Function


OraFormsSetInt Function

Action

Sets an integer property that must be sent with the next request.

Include file

OraForms.bdh

Syntax

OraFormsSetInt(  in sProperty : string,
                                                                    in sValue 				:  number,
                                                                    in nFlag  				:  number optional );
Parameter | Description
sProperty | The property name.
sValue | The property value.
nFlag

The type of function that will send the property

Possible values:

  • ORA_SET_TYPE_NORMAL (default)

  • ORA_SET_TYPE_MESSAGEGET, which is currently only used for the OraFormsOnMessageGet function.

Example

dcltrans
  transaction TMain
    OraFormsSetInt("INITIAL_VERSION", 90290);
    OraFormsSetPoint("INITIAL_RESOLUTION", 96, 96);
    OraFormsSetPoint("INITIAL_DISP_SIZE", 1024, 768);
    OraFormsSetInt("INITIAL_COLOR_DEPTH", 256);
    OraFormsSetInt("WINSYS_COLOR_ADD", 0);
    OraFormsSetInt("WINSYS_COLOR_ADD", 255);
    OraFormsSetInt("WINSYS_COLOR_ADD", 65535);
    OraFormsSetInt("WINSYS_COLOR_ADD", 4210752);
    OraFormsSetInt("WINSYS_COLOR_ADD", 8421504);
    OraFormsSetInt("WINSYS_COLOR_ADD", 65280);
    OraFormsSetInt("WINSYS_COLOR_ADD", 12632256);
    OraFormsSetInt("WINSYS_COLOR_ADD", 16711935);
    OraFormsSetInt("WINSYS_COLOR_ADD", 16762880);
    OraFormsSetInt("WINSYS_COLOR_ADD", 16756655);
    OraFormsSetInt("WINSYS_COLOR_ADD", 16711680);
    OraFormsSetInt("WINSYS_COLOR_ADD", 16777215);
    OraFormsSetInt("WINSYS_COLOR_ADD", 16776960);
    OraFormsSetString("FONT_NAME", "Dialog");
    OraFormsSetInt("FONT_SIZE", 900);
    OraFormsSetByte("FONT_STYLE", 0);
    OraFormsSetPoint("INITIAL_SCALE_INFO", 8, 20);
    OraFormsSetBoolean("WINSYS_REQUIREDVA_LIST", false);
    OraFormsSetString("DEFAULT_LOCAL_TZ", "Europe/Berlin");
    OraFormsConnect( "server module=c:\\orant\\forms90\\EDITCOMBO.fmx usesdi=yes userid= sso_userid=");
end TMain;
Parent topic: Properties Functions


OraFormsSetPoint Function

Action

Sets a point property that must be sent with the next request.

Include file

OraForms.bdh

Syntax

OraFormsSetPoint( in sProperty : string,
                  in nX        : number,
                  in nY        : number,
                  in nFlag     : number optional );
Parameter | Description
sProperty | The property name.
nX | x part of the point property.
nY | y part of the point property.
nFlag

The type of function that will send the property Possible values:

  • ORA_SET_TYPE_NORMAL (default)

  • ORA_SET_TYPE_MESSAGEGET, which is currently only used for the OraFormsOnMessageGet function.

Example

dcltrans
  transaction TMain
    OraFormsSetInt("INITIAL_VERSION", 90290);
    OraFormsSetPoint("INITIAL_RESOLUTION", 96, 96);
    OraFormsSetPoint("INITIAL_DISP_SIZE", 1024, 768);
    OraFormsSetInt("INITIAL_COLOR_DEPTH", 256);
    OraFormsSetInt("WINSYS_COLOR_ADD", 0);
    OraFormsSetInt("WINSYS_COLOR_ADD", 255);
    OraFormsSetInt("WINSYS_COLOR_ADD", 65535);
    OraFormsSetInt("WINSYS_COLOR_ADD", 4210752);
    OraFormsSetInt("WINSYS_COLOR_ADD", 8421504);
    OraFormsSetInt("WINSYS_COLOR_ADD", 65280);
    OraFormsSetInt("WINSYS_COLOR_ADD", 12632256);
    OraFormsSetInt("WINSYS_COLOR_ADD", 16711935);
    OraFormsSetInt("WINSYS_COLOR_ADD", 16762880);
    OraFormsSetInt("WINSYS_COLOR_ADD", 16756655);
    OraFormsSetInt("WINSYS_COLOR_ADD", 16711680);
    OraFormsSetInt("WINSYS_COLOR_ADD", 16777215);
    OraFormsSetInt("WINSYS_COLOR_ADD", 16776960);
    OraFormsSetString("FONT_NAME", "Dialog");
    OraFormsSetInt("FONT_SIZE", 900);
    OraFormsSetByte("FONT_STYLE", 0);
    OraFormsSetPoint("INITIAL_SCALE_INFO", 8, 20);
    OraFormsSetBoolean("WINSYS_REQUIREDVA_LIST", false);
    OraFormsSetString("DEFAULT_LOCAL_TZ", "Europe/Berlin");
    OraFormsConnect( "server module=c:\\orant\\forms90\\EDITCOMBO.fmx usesdi=yes userid= sso_userid=");
end TMain;
Parent topic: Properties Functions
Related reference
OraFormsConnect Function
OraFormsOnMessageGet Function


OraFormsSetRectangle Function

Action

Sets a rectangle property that must be sent with the next request.

Include file

OraForms.bdh

Syntax

OraFormsSetRectangle( in sProperty : string,
                      in nX0       : number,
                      in nY0       : number,
                      in nX1       : number,
                      in nY1       : number,
                      in nFlag     : number optional );
Parameter | Description
sProperty | The property name.
nX0 | The x part of the first coordinates.
nY0 | The y part of the first coordinates.
nX1 | The x part of the second coordinates.
nY1 | The y part of the second coordinates.
nFlag

The type of function that will send the property Possible values:

  • ORA_SET_TYPE_NORMAL (default)

  • ORA_SET_TYPE_MESSAGEGET, which is currently only used for the OraFormsOnMessageGet function.

Example

dcltrans
   transaction TMain
    OraFormsSetInt("INITIAL_VERSION", 90290);
    OraFormsSetPoint("INITIAL_RESOLUTION", 96, 96);
    OraFormsSetPoint("INITIAL_DISP_SIZE", 1024, 768);
    OraFormsSetInt("INITIAL_COLOR_DEPTH", 256);
    OraFormsSetInt("WINSYS_COLOR_ADD", 0);
    OraFormsSetInt("WINSYS_COLOR_ADD", 255);
    OraFormsSetInt("WINSYS_COLOR_ADD", 65535);
    OraFormsSetInt("WINSYS_COLOR_ADD", 4210752);
    OraFormsSetInt("WINSYS_COLOR_ADD", 8421504);
    OraFormsSetInt("WINSYS_COLOR_ADD", 65280);
    OraFormsSetInt("WINSYS_COLOR_ADD", 12632256);
    OraFormsSetInt("WINSYS_COLOR_ADD", 16711935);
    OraFormsSetInt("WINSYS_COLOR_ADD", 16762880);
    OraFormsSetInt("WINSYS_COLOR_ADD", 16756655);
    OraFormsSetInt("WINSYS_COLOR_ADD", 16711680);
    OraFormsSetInt("WINSYS_COLOR_ADD", 16777215);
    OraFormsSetInt("WINSYS_COLOR_ADD", 16776960);
    OraFormsSetString("FONT_NAME", "Dialog");
    OraFormsSetInt("FONT_SIZE", 900);
    OraFormsSetByte("FONT_STYLE", 0);
    OraFormsSetPoint("INITIAL_SCALE_INFO", 8, 20);
    OraFormsSetBoolean("WINSYS_REQUIREDVA_LIST", false);
    OraFormsSetString("DEFAULT_LOCAL_TZ", "Europe/Berlin");
    OraFormsSetRectangle("INIITAL_SCREENSIZE", 0, 0, 1024, 768);
    OraFormsConnect( "server module=c:\\orant\\forms90\\EDITCOMBO.fmx usesdi=yes userid= sso_userid=");
  end TMain;
Parent topic: Properties Functions
Related reference
OraFormsConnect Function
OraFormsOnMessageGet Function


OraFormsSetString Function

Action

Sets a string property that must be sent with the next request.

Include file

OraForms.bdh

Syntax

OraFormsSetString( in sProperty : string,
                   in sValue    : string,
                   in nFlag     : number optional );
Parameter | Description
sProperty | The property name.
sValue | The property value.
nFlag

The type of function that will send the property Possible values:

  • ORA_SET_TYPE_NORMAL (default)

  • ORA_SET_TYPE_MESSAGEGET, which is currently only used for the OraFormsOnMessageGet function.

Example

dcltrans
  transaction TMain
  begin
    OraFormsSetInt("INITIAL_VERSION", 90290);
    OraFormsSetPoint("INITIAL_RESOLUTION", 96, 96);
    OraFormsSetPoint("INITIAL_DISP_SIZE", 1024, 768);
    OraFormsSetInt("INITIAL_COLOR_DEPTH", 256);
    OraFormsSetInt("WINSYS_COLOR_ADD", 0);
    OraFormsSetInt("WINSYS_COLOR_ADD", 255);
    OraFormsSetInt("WINSYS_COLOR_ADD", 65535);
    OraFormsSetInt("WINSYS_COLOR_ADD", 4210752);
    OraFormsSetInt("WINSYS_COLOR_ADD", 8421504);
    OraFormsSetInt("WINSYS_COLOR_ADD", 65280);
    OraFormsSetInt("WINSYS_COLOR_ADD", 12632256);
    OraFormsSetInt("WINSYS_COLOR_ADD", 16711935);
    OraFormsSetInt("WINSYS_COLOR_ADD", 16762880);
    OraFormsSetInt("WINSYS_COLOR_ADD", 16756655);
    OraFormsSetInt("WINSYS_COLOR_ADD", 16711680);
    OraFormsSetInt("WINSYS_COLOR_ADD", 16777215);
    OraFormsSetInt("WINSYS_COLOR_ADD", 16776960);
    OraFormsSetString("FONT_NAME", "Dialog");
    OraFormsSetInt("FONT_SIZE", 900);
    OraFormsSetByte("FONT_STYLE", 0);
    OraFormsSetPoint("INITIAL_SCALE_INFO", 8, 20);
    OraFormsSetBoolean("WINSYS_REQUIREDVA_LIST", false);
    OraFormsSetString("DEFAULT_LOCAL_TZ", "Europe/Berlin");
    OraFormsConnect( "server module=c:\\orant\\forms90\\EDITCOMBO.fmx usesdi=yes userid= sso_userid=");
  end TMain;
Parent topic: Properties Functions
Related reference
OraFormsConnect Function
OraFormsOnMessageGet Function


OraFormsSetStringArray Function

Action

Sets an array of string properties that must be sent with the next request.

Include file

OraForms.bdh

Syntax

OraFormsSetStringArray( in sProperty : string,
                        in strArray  : array of string,
                        in nLen      : number,
                        in nFlag     : number optional );
Parameter | Description
sProperty | The property name.
strArray | The property value.
nLen | The length of the array.
nFlag

The type of function that will send the property Possible values:

  • ORA_SET_TYPE_NORMAL (default)

  • ORA_SET_TYPE_MESSAGEGET, which is currently only used for the OraFormsOnMessageGet function.

Example

dcltrans
  transaction TMain
  var
    nArray : array of string init "1", "2", "3", "4", "5";
  begin
    OraFormsSetInt("INITIAL_VERSION", 90290);
    OraFormsSetPoint("INITIAL_RESOLUTION", 96, 96);
    OraFormsSetPoint("INITIAL_DISP_SIZE", 1024, 768);
    OraFormsSetInt("INITIAL_COLOR_DEPTH", 256);
    OraFormsSetInt("WINSYS_COLOR_ADD", 0);
    OraFormsSetInt("WINSYS_COLOR_ADD", 255);
    OraFormsSetInt("WINSYS_COLOR_ADD", 65535);
    OraFormsSetInt("WINSYS_COLOR_ADD", 4210752);
    OraFormsSetInt("WINSYS_COLOR_ADD", 8421504);
    OraFormsSetInt("WINSYS_COLOR_ADD", 65280);
    OraFormsSetInt("WINSYS_COLOR_ADD", 12632256);
    OraFormsSetInt("WINSYS_COLOR_ADD", 16711935);
    OraFormsSetInt("WINSYS_COLOR_ADD", 16762880);
    OraFormsSetInt("WINSYS_COLOR_ADD", 16756655);
    OraFormsSetInt("WINSYS_COLOR_ADD", 16711680);
    OraFormsSetInt("WINSYS_COLOR_ADD", 16777215);
    OraFormsSetInt("WINSYS_COLOR_ADD", 16776960);
    OraFormsSetString("FONT_NAME", "Dialog");
    OraFormsSetInt("FONT_SIZE", 900);
    OraFormsSetByte("FONT_STYLE", 0);
    OraFormsSetPoint("INITIAL_SCALE_INFO", 8, 20);
    OraFormsSetBoolean("WINSYS_REQUIREDVA_LIST", false);
    OraFormsSetString("DEFAULT_LOCAL_TZ", "Europe/Berlin");
    OraFormsSetStringArray("KEYBINDING", nArray, 5);
    OraFormsConnect( "server module=c:\\orant\\forms90\\EDITCOMBO.fmx usesdi=yes userid= sso_userid=");
  end TMain;
Parent topic: Properties Functions
Related reference
OraFormsConnect Function
OraFormsOnMessageGet Function


Parsing Functions

  • OraFormsGetChildren Function
    Returns a handle that can be used to iterate over the children of a specified control.
  • OraFormsGetNextChild Function
    Positions the pointer to the next child of an iterator created with OraFormsGetChildren.
  • OraFormsGetNrOfResponseBoxValues Function
    Returns the number of entries in a response dialog.
  • OraFormsGetResponseBoxValue Function
    Returns the value of a response box at a specified index.
  • OraFormsParseCheckValue Function
    Returns the check state of a check box.
  • OraFormsParseChoiceBoxProperty Function
    Returns a choice box’s property.
  • OraFormsParseInfoBoxProperty Function
    Returns an info dialog’s property.
  • OraFormsParseListEntries Function
    Returns the number of elements in a list item, combo box, or pop-up list item.
  • OraFormsParseListEntry Function
    Returns the value of a combo box, list item, or pop-up list item at a specified index.
  • OraFormsParseListIndex Function
    Returns the index of the selected item in a combo box, pop-up list box, or list box.
  • OraFormsParseListValue Function
    Returns the selected value of a combo box, list box, or pop-up list box.
  • OraFormsParseRadioValue Function
    Returns the check state of the radio button.
  • OraFormsParseResponseBoxProperty Function
    Returns a response dialog’s property.
  • OraFormsParseSelectedTreeItem Function
    Returns the value of the selected tree node.
  • OraFormsParseTextValue Functions
    Returns the value of a text field or text area control.
Parent topic: Oracle Forms Functions Reference


OraFormsGetChildren Function

Action

OraFormsGetChildren returns a handle that can be used to iterate over the children of a specified control. Use any property retrieval functions to access the control’s properties.

Include file

OraForms.bdh

Syntax

OraFormsGetChildren( in sName : string ) : number;

Return value

  • A value other than 0 on success

  • 0 if the control is not found or does not have children

Parameter | Description
sName | The control’s unique name.

Example

dcltrans
  transaction TMain
  var
    sValue     : string;
    nIterator  : number;
    nHandlerId : number;
 begin
    OraFormsSetConnectMode(ORA_SOCKET_CONNECTION);
    // Connect - with connection properties
    OraFormsSetInt("INITIAL_VERSION", 608);
    OraFormsSetPoint("INITIAL_RESOLUTION", 96, 96);
    OraFormsSetPoint("INITIAL_DISP_SIZE", 1024, 768);
    OraFormsSetInt("INITIAL_COLOR_DEPTH", 256);
    OraFormsSetString("FONT_NAME", "Dialog");
    OraFormsSetPoint("INITIAL_SCALE_INFO", 8, 18);
    OraFormsSetBoolean("WINSYS_REQUIREDVA_LIST", false);
    OraFormsConnect("server module=Person3.fmx userid= useSDI=yes record=names");
    OraFormsSetWindow("Logon");
    OraFormsLogon("user", "password", "orcl_server");
    // ---
    // New window activated: WINDOW1
    OraFormsSetWindow("WINDOW1");
    nIterator := OraFormsGetChildren("WINDOW1");
    if nIterator <> 0 then
      while OraFormsGetNextChild(nIterator, nHandlerId) do
        sValue := OraFormsGetPropString(string(nHandlerId),
        ORA_PID_TITLE);
        Print(sValue);
      end;
      OraFormsFree(nIterator);
    end;
end TMain;
Parent topic: Parsing Functions


OraFormsGetNextChild Function

Action

OraFormsGetNextChild positions the pointer to the next child of an iterator created with OraFormsGetChildren.

Include file

OraForms.bdh

Syntax

OraFormsGetNextChild( in  nIterator  : number,
    out nHandlerId : number ) : boolean;

Return value

  • true if the iterator is set to the next position

  • false otherwise

Parameter | Description
nIterator | The iterator handle
nHandlerId | This parameter is assigned the handler ID of the next control.

Example

dcltrans
  transaction TMain
  var
    sValue     : string;
    nIterator  : number;
    nHandlerId : number;
 begin
    OraFormsSetConnectMode(ORA_SOCKET_CONNECTION);
    // Connect - with connection properties
    OraFormsSetInt("INITIAL_VERSION", 608);
    OraFormsSetPoint("INITIAL_RESOLUTION", 96, 96);
    OraFormsSetPoint("INITIAL_DISP_SIZE", 1024, 768);
    OraFormsSetInt("INITIAL_COLOR_DEPTH", 256);
    OraFormsSetString("FONT_NAME", "Dialog");
    OraFormsSetPoint("INITIAL_SCALE_INFO", 8, 18);
    OraFormsSetBoolean("WINSYS_REQUIREDVA_LIST", false);
    OraFormsConnect("server module=Person3.fmx userid= useSDI=yes record=names");
    OraFormsSetWindow("Logon");
    OraFormsLogon("user", "password", "orcl_server");
    // ---
    // New window activated: WINDOW1
    OraFormsSetWindow("WINDOW1");
    nIterator := OraFormsGetChildren("WINDOW1");
    if nIterator <> 0 then
      while OraFormsGetNextChild(nIterator, nHandlerId) do
        sValue := OraFormsGetPropString(string(nHandlerId), ORA_PID_TITLE);
        Print(sValue);
      end;
      OraFormsFree(nIterator);
    end;
end TMain;
Parent topic: Parsing Functions


OraFormsGetNrOfResponseBoxValues Function

Action

OraFormsGetNrOfResponseBoxValues returns the number of entries in a response dialog.

Include file

OraForms.bdh

Syntax

OraFormsGetNrOfResponseBoxValues( in sName : string ) : number;

Return value

  • The number of entries on success.

  • -1 otherwise

Parameter | Description
sName | The control's unique name.to a .NET Object

Example

dcltrans
  transaction TMain
  var
    sValue : string;
  begin
    OraFormsSetConnectMode(ORA_SOCKET_CONNECTION);
    // Connect - with connection properties
    OraFormsSetInt("INITIAL_VERSION", 608);
    OraFormsSetPoint("INITIAL_RESOLUTION", 96, 96);
    OraFormsSetPoint("INITIAL_DISP_SIZE", 1024, 768);
    OraFormsSetInt("INITIAL_COLOR_DEPTH", 256);
    OraFormsSetString("FONT_NAME", "Dialog");
    OraFormsSetPoint("INITIAL_SCALE_INFO", 8, 18);
    OraFormsSetBoolean("WINSYS_REQUIREDVA_LIST", false);
    OraFormsConnect("server module=Person3.fmx userid= useSDI=yes record=names");
    OraFormsSetWindow("Logon");
    OraFormsLogon("user", "password", "orcl_server");
    // ---
    // New window activated: WINDOW1
    OraFormsSetWindow("WINDOW1");
    OraFormsGetNrOfResponseBoxValues("ADB Account");
  end TMain;
Parent topic: Parsing Functions


OraFormsGetResponseBoxValue Function

Action

OraFormsGetResponseBoxValue returns the value of a response box at a specified index.

Include file

OraForms.bdh

Syntax

OraFormsGetResponseBoxValue( in sName  : string,
                             in nIndex : number): string;

Return value

  • The value on success.

  • NULL otherwise

Parameter | Description
sName | The control's unique name.
nIndex | The 0-based index of the value to be returned.

Example

dcltrans
  transaction TMain
  var
    sValue : string;
  begin
    OraFormsSetConnectMode(ORA_SOCKET_CONNECTION);
    // Connect - with connection properties
    OraFormsSetInt("INITIAL_VERSION", 608);
    OraFormsSetPoint("INITIAL_RESOLUTION", 96, 96);
    OraFormsSetPoint("INITIAL_DISP_SIZE", 1024, 768);
    OraFormsSetInt("INITIAL_COLOR_DEPTH", 256);
    OraFormsSetString("FONT_NAME", "Dialog");
    OraFormsSetPoint("INITIAL_SCALE_INFO", 8, 18);
    OraFormsSetBoolean("WINSYS_REQUIREDVA_LIST", false);
    OraFormsConnect("server module=Person3.fmx userid= useSDI=yes record=names");
    OraFormsSetWindow("Logon");
    OraFormsLogon("user", "password", "orcl_server");
    // ---
    // New window activated: WINDOW1
    OraFormsSetWindow("WINDOW1");
    OraFormsGetResponseBoxValue("ADB Account", 0);
  end TMain;
Parent topic: Parsing Functions


OraFormsParseCheckValue Function

Action

Returns the check state of a check box.

Include file

OraForms.bdh

Syntax

OraFormsParseCheckValue ( in sName : string) : boolean;

Return value

  • true if the checkbox is checked
  • false otherwise
Parameter | Description
sName | The checkbox control's unique name.

Example

transaction TMain
var
  bValue :  boolean;
begin
  OraFormsSetConnectMode(ORA_SOCKET_CONNECTION);
  // Connect - with connection properties OraFormsSetInt( "INITIAL_VERSION", 608);
  OraFormsSetPoint( "INITIAL_RESOLUTION", 96,  96);
  OraFormsSetPoint( "INITIAL_DISP_SIZE", 1024,  768);
  OraFormsSetInt( "INITIAL_COLOR_DEPTH", 256);
  OraFormsSetString( "FONT_NAME" , "Dialog" );
  OraFormsSetPoint( "INITIAL_SCALE_INFO", 8,  18);
  OraFormsSetBoolean( "WINSYS_REQUIREDVA_LIST",  false);
  OraFormsConnect( "server module=Person3.fmx userid= useSDI=yes record=names");
  // New window activated: Logon
  OraFormsSetWindow( "Logon");
  OraFormsLogon( "user",  "password",  "orcl_server");
  // --- // New window activated: WINDOW1
  OraFormsSetWindow( "WINDOW1");
  OraFormsMenuItem( "WINDOW1",  "Query::Execute Query"); bValue :=
  OraFormsParseCheckValue( "PERSON_HAS_REGISTERED_0");
  OraFormsMenuItem( "WINDOW1",  "Action::Exit");
end  TMain;
Parent topic: Parsing Functions
Related concepts
Verifying Functions


OraFormsParseChoiceBoxProperty Function

Action

OraFormsParseChoiceBoxProperty returns a choice box’s property.

Include file

OraForms.bdh

Syntax

OraFormsParseChoiceBoxProperty( in sName : string,
    in nProp : number ) : string;

Return value

  • The value of the property on success.

  • NULL otherwise

Parameter | Description
sName | The control's unique name.
nProp

Can be one of these constants:

  • ORA_CHOICEBOX_MESSAGE

  • ORA_CHOICEBOX_TITLE

  • ORA_CHOICEBOX_ICON

Example

dcltrans
  transaction TMain
  var
    sValue   : string;
  begin
    OraFormsSetConnectMode(ORA_SOCKET_CONNECTION);
    // Connect - with connection properties
    OraFormsSetInt("INITIAL_VERSION", 608);
    OraFormsSetPoint("INITIAL_RESOLUTION", 96, 96);
    OraFormsSetPoint("INITIAL_DISP_SIZE", 1024, 768);
    OraFormsSetInt("INITIAL_COLOR_DEPTH", 256);
    OraFormsSetString("FONT_NAME", "Dialog");
    OraFormsSetPoint("INITIAL_SCALE_INFO", 8, 18);
    OraFormsSetBoolean("WINSYS_REQUIREDVA_LIST", false);
    OraFormsConnect("server module=Person3.fmx userid= useSDI=yes record=names");
    OraFormsSetWindow("Logon");
    OraFormsLogon("user", "password", "orcl_server");
    // ---
    // New window activated: WINDOW1
    OraFormsSetWindow("WINDOW1");
    OraFormsParseChoiceBoxProperty("ADB Account", ORA_CHOICEBOX_MESSAGE);
  end TMain;
Parent topic: Parsing Functions


OraFormsParseInfoBoxProperty Function

Action

OraFormsParseInfoBoxProperty returns an info dialog’s property.

Include file

OraForms.bdh

Syntax

OraFormsParseInfoBoxProperty( in sName : string,
                              in nProp : number ) : string;

Return value

  • The value of the property on success.

  • NULL otherwise

Parameter | Description
sName | The control's unique name.
nProp

Can be one of these constants:

  • ORA_INFOBOX_MESSAGE

  • ORA_INFOBOX_TITLE

  • ORA_INFOBOX_ICON

Example

dcltrans
  transaction TMain
  var
    sValue   : string;
  begin
    OraFormsSetConnectMode(ORA_SOCKET_CONNECTION);
    // Connect - with connection properties
    OraFormsSetInt("INITIAL_VERSION", 608);
    OraFormsSetPoint("INITIAL_RESOLUTION", 96, 96);
    OraFormsSetPoint("INITIAL_DISP_SIZE", 1024, 768);
    OraFormsSetInt("INITIAL_COLOR_DEPTH", 256);
    OraFormsSetString("FONT_NAME", "Dialog");
    OraFormsSetPoint("INITIAL_SCALE_INFO", 8, 18);
    OraFormsSetBoolean("WINSYS_REQUIREDVA_LIST", false);
    OraFormsConnect("server module=Person3.fmx userid= useSDI=yes record=names");
    OraFormsSetWindow("Logon");
    OraFormsLogon("user", "password", "orcl_server");
    // ---
    // New window activated: WINDOW1
    OraFormsSetWindow("WINDOW1");
    OraFormsParseInfoBoxProperty("ADB Account", ORA_INFOBOX_TITLE);
  end TMain;
Parent topic: Parsing Functions


OraFormsParseListEntries Function

Action

Returns the number of elements in a list item, combo box, or pop-up list item.

Include file

OraForms.bdh

Syntax

OraFormsParseListEntries ( in sName : string ) :number;

Return value

  • The number of items of success
  • -1 otherwise
Parameter | Description
sName | The control's unique name

Example

transaction TMain
var
  nValue :  number;
begin
  OraFormsSetConnectMode(ORA_SOCKET_CONNECTION);
  // Connect - with connection properties
  OraFormsSetInt( "INITIAL_VERSION", 608);
  OraFormsSetPoint( "INITIAL_RESOLUTION", 96,  96);
  OraFormsSetPoint( "INITIAL_DISP_SIZE", 1024,  768);
  OraFormsSetInt( "INITIAL_COLOR_DEPTH", 256);
  OraFormsSetString( "FONT_NAME" , "Dialog" );
  OraFormsSetPoint( "INITIAL_SCALE_INFO", 8,  18);
  OraFormsSetBoolean( "WINSYS_REQUIREDVA_LIST",  false);
  OraFormsConnect( "server module=Person3.fmx userid= useSDI=yes record=names");
  // New window activated: Logon
  OraFormsSetWindow( "Logon");
  OraFormsLogon( "user",  "password",  "orcl_server");
  // ---
  // New window activated: WINDOW1
  OraFormsSetWindow( "WINDOW1");
  OraFormsMenuItem( "WINDOW1",  "Query::Execute Query");
  nValue :=  OraFormsParseListEntries( "PERSON_JOBS_0");
  OraFormsMenuItem( "WINDOW1",  "Action::Exit");
end  TMain;
Parent topic: Parsing Functions


OraFormsParseListEntry Function

Action

Returns the value of a combo box, list item, or pop-up list item at a specified index.

Include file

OraForms.bdh

Syntax

OraFormsParseListEntry( in sName : string,
                        in nPos  : number ) : string;

Return value

  • The string representation at the specified position on success

  • NULL otherwise

Parameter | Description
sName | The control’s unique name.
nPos | The position of the entry. The first element is at position 0.

Example

transaction TMain
var
 sValue : string;  nElems : number;
begin
    OraFormsSetConnectMode(ORA_SOCKET_CONNECTION);

    // Connect - with connection properties
    OraFormsSetInt("INITIAL_VERSION", 608);
    OraFormsSetPoint("INITIAL_RESOLUTION", 96, 96);
    OraFormsSetPoint("INITIAL_DISP_SIZE", 1024, 768);
    OraFormsSetInt("INITIAL_COLOR_DEPTH", 256);
    OraFormsSetString("FONT_NAME", "Dialog");
    OraFormsSetPoint("INITIAL_SCALE_INFO", 8, 18);
    OraFormsSetBoolean("WINSYS_REQUIREDVA_LIST", false);
    OraFormsConnect("server module=Person3.fmx userid= useSDI=yes record=names");

    // New window activated: Logon
    OraFormsSetWindow("Logon");
    OraFormsLogon("user", "password", "orcl_server");

    // ---
    // New window activated: WINDOW1
    OraFormsSetWindow("WINDOW1");
    OraFormsMenuItem("WINDOW1", "Query::Execute Query");
    nElems := OraFormsParseListEntries("PERSON_JOBS_0");
    sValue := OraFormsParseListEntry("PERSON_JOBS_0", 0);
    OraFormsMenuItem("WINDOW1", "Action::Exit");
  end TMain;
Parent topic: Parsing Functions
Related concepts
Verifying Functions


OraFormsParseListIndex Function

Action

Returns the index of the selected item in a combo box, pop-up list box, or list box.

Include file

OraForms.bdh

Syntax

OraFormsParseListIndex( in sName : string) : number;

Return value

  • The index on success
  • -1 otherwise
Parameter | Description
sName | The control's unique name.

Example

transaction TMain
  var
    nValue :  number;
  begin
    OraFormsSetConnectMode(ORA_SOCKET_CONNECTION);
    // Connect - with connection properties
    OraFormsSetInt( "INITIAL_VERSION", 608);
    OraFormsSetPoint( "INITIAL_RESOLUTION", 96,  96);
    OraFormsSetPoint( "INITIAL_DISP_SIZE", 1024,  768);
    OraFormsSetInt( "INITIAL_COLOR_DEPTH", 256);
    OraFormsSetString( "FONT_NAME" , "Dialog" );
    OraFormsSetPoint( "INITIAL_SCALE_INFO", 8,  18);
    OraFormsSetBoolean( "WINSYS_REQUIREDVA_LIST",  false);
    OraFormsConnect( "server module=Person3.fmx userid= useSDI=yes record=names");
    // New window activated: Logon
    OraFormsSetWindow( "Logon");
    OraFormsLogon( "user",  "password",  "orcl_server");
    // ---
    // New window activated: WINDOW1
    OraFormsSetWindow( "WINDOW1");
    OraFormsMenuItem( "WINDOW1",  "Query::Execute Query"); nValue :=
    OraFormsParseListIndex( "PERSON_SECONDNAME_0");
    OraFormsMenuItem( "WINDOW1",  "Action::Exit");
  end TMain;
Parent topic: Parsing Functions


OraFormsParseListValue Function

Action

Returns the selected value of a combo box, list box, or pop-up list box.

Include file

OraForms.bdh

Syntax

OraFormsParseListValue( in sName : string) : string;

Return value

  • The value of the select item on success
  • NULL otherwise
Parameter | Description
sName | The control's unique name.

Example

transaction TMain
  var
    sValue :  string;
  begin
    OraFormsSetConnectMode(ORA_SOCKET_CONNECTION);
    // Connect - with connection properties
    OraFormsSetInt( "INITIAL_VERSION", 608);
    OraFormsSetPoint( "INITIAL_RESOLUTION", 96,  96);
    OraFormsSetPoint( "INITIAL_DISP_SIZE", 1024,  768);
    OraFormsSetInt( "INITIAL_COLOR_DEPTH", 256);
    OraFormsSetString( "FONT_NAME" , "Dialog" );
    OraFormsSetPoint( "INITIAL_SCALE_INFO", 8,  18);
    OraFormsSetBoolean( "WINSYS_REQUIREDVA_LIST",  false);
    OraFormsConnect( "server module=Person3.fmx userid= useSDI=yes record=names");
    // New window activated: Logon
    OraFormsSetWindow( "Logon");
    OraFormsLogon( "user",  "password",  "orcl_server");
    // ---
    // New window activated: WINDOW1
    OraFormsSetWindow( "WINDOW1");
    OraFormsMenuItem( "WINDOW1",  "Query::Execute Query"); sValue :=
    OraFormsParseListValue( "PERSON_JOB_0");
    OraFormsMenuItem( "WINDOW1",  "Action::Exit");
  end TMain;
Parent topic: Parsing Functions
Related concepts
Verifying Functions


OraFormsParseRadioValue Function

Action

Returns the check state of the radio button.

Include file

OraForms.bdh

Syntax

OraFormsParseRadioValue( in sName : string ) : boolean;

Return value

  • true If the radio button is selected
  • false otherwise
Parameter | Description
sName | The control's unique name.

Example

transaction TMain
  var
    bValue :  boolean;
  begin
    OraFormsSetConnectMode(ORA_SOCKET_CONNECTION);
    // Connect - with connection properties
    OraFormsSetInt( "INITIAL_VERSION", 608);
    OraFormsSetPoint( "INITIAL_RESOLUTION", 96,  96);
    OraFormsSetPoint( "INITIAL_DISP_SIZE", 1024,  768);
    OraFormsSetInt( "INITIAL_COLOR_DEPTH", 256);
    OraFormsSetString( "FONT_NAME" , "Dialog" );
    OraFormsSetPoint( "INITIAL_SCALE_INFO", 8,  18);
    OraFormsSetBoolean( "WINSYS_REQUIREDVA_LIST",  false);
    OraFormsConnect( "server module=Person3.fmx userid= useSDI=yes record=names");
    // New window activated: Logon
    OraFormsSetWindow( "Logon");
    OraFormsLogon( "user",  "password",  "orcl_server");
    // ---
    // New window activated: WINDOW1
    OraFormsSetWindow( "WINDOW1");
    OraFormsMenuItem( "WINDOW1",  "Query::Execute Query"); bValue :=
    OraFormsParseRadioValue( "PERSON_RADIO_0");
    OraFormsMenuItem( "WINDOW1",  "Action::Exit");
  end TMain;
Parent topic: Parsing Functions


OraFormsParseResponseBoxProperty Function

Action

OraFormsParseResponseBoxProperty returns a response dialog’s property.

Include file

OraForms.bdh

Syntax

OraFormsParseResponseBoxProperty( in sName : string,
                                  in nProp : number ) : string;

Return value

  • The value of the property on success

  • NULL otherwise

Parameter | Description
sName | The control's unique name.
nProp

Can be one of these constants:

  • ORA_RESPBOX_TITLE

  • ORA_RESPBOX_HEADER

  • ORA_RESPBOX_OKLABEL

Example

dcltrans
  transaction TMain
  var
    sValue   : string;
  begin
    OraFormsSetConnectMode(ORA_SOCKET_CONNECTION);
    // Connect - with connection properties
    OraFormsSetInt("INITIAL_VERSION", 608);
    OraFormsSetPoint("INITIAL_RESOLUTION", 96, 96);
    OraFormsSetPoint("INITIAL_DISP_SIZE", 1024, 768);
    OraFormsSetInt("INITIAL_COLOR_DEPTH", 256);
    OraFormsSetString("FONT_NAME", "Dialog");
    OraFormsSetPoint("INITIAL_SCALE_INFO", 8, 18);
    OraFormsSetBoolean("WINSYS_REQUIREDVA_LIST", false);
    OraFormsConnect("server module=Person3.fmx userid= useSDI=yes record=names");
    OraFormsSetWindow("Logon");
    OraFormsLogon("user", "password", "orcl_server");
    // ---
    // New window activated: WINDOW1
    OraFormsSetWindow("WINDOW1");
    OraFormsParseResponseBoxProperty("ADB Account", ORA_RESPBOX_TITLE);
  end TMain;
Parent topic: Parsing Functions


OraFormsParseSelectedTreeItem Function

Action

Returns the value of the selected tree node.

Include file

OraForms.bdh

Syntax

OraFormsParseSelectedTreeItem( in sName : string ) : string;

Return value

  • The string representation of the selected tree node.

  • NULL otherwise

Parameter | Description
sName | The tree control’s unique name.

Example

transaction TMain
  var
     sValue : string;
  begin
    OraFormsSetConnectMode(ORA_SOCKET_CONNECTION);

    // Connect - with connection properties
    OraFormsSetInt("INITIAL_VERSION", 608);
    OraFormsSetPoint("INITIAL_RESOLUTION", 96, 96);
    OraFormsSetPoint("INITIAL_DISP_SIZE", 1024, 768);
    OraFormsSetInt("INITIAL_COLOR_DEPTH", 256);
    OraFormsSetString("FONT_NAME", "Dialog");
    OraFormsSetPoint("INITIAL_SCALE_INFO", 8, 18);
    OraFormsSetBoolean("WINSYS_REQUIREDVA_LIST", false);
    OraFormsConnect("server module=Person3.fmx userid= useSDI=yes record=names");

    // New window activated: Logon
    OraFormsSetWindow("Logon");
    OraFormsLogon("user", "password", "orcl_server");

    // ---
    // New window activated: WINDOW1
    OraFormsSetWindow("WINDOW1");
    OraFormsMenuItem("WINDOW1", "Query::Execute Query");
    sValue := OraFormsParseSelectedTreeItem("TREE_CONTROL");
    if StrIsNull(sValue) then
    Print("sValue is null");
  end;
    OraFormsMenuItem("WINDOW1",
    "Action::Exit");
  end TMain;
Parent topic: Parsing Functions
Related concepts
Verifying Functions


OraFormsParseTextValue Functions

Action

Returns the value of a text field or text area control.

Include file

OraForms.bdh

Syntax

OraFormsParseTextValue( in sName : string) : string;

Return value

  • Returns the value as a string on success.
  • NULL otherwise
Parameter | Description
sName | The control's unique name.

Example

transaction TMain
var
  sValue :  string;
begin
  OraFormsSetConnectMode(ORA_SOCKET_CONNECTION);
  // Connect - with connection properties
  OraFormsSetInt( "INITIAL_VERSION", 608);
  OraFormsSetPoint( "INITIAL_RESOLUTION", 96,  96);
  OraFormsSetPoint( "INITIAL_DISP_SIZE", 1024,  768);
  OraFormsSetInt( "INITIAL_COLOR_DEPTH", 256);
  OraFormsSetString( "FONT_NAME" , "Dialog" );
  OraFormsSetPoint( "INITIAL_SCALE_INFO", 8,  18);
  OraFormsSetBoolean( "WINSYS_REQUIREDVA_LIST",  false);
  OraFormsConnect( "server module=Person3.fmx
  userid= useSDI=yes record=names");
  // New window activated: Logon
  OraFormsSetWindow( "Logon");
  OraFormsLogon( "user",  "password",  "orcl_server");
  // ---
  // New window activated: WINDOW1
  OraFormsSetWindow( "WINDOW1");
  OraFormsMenuItem( "WINDOW1",  "Query::Execute Query");

  sValue := OraFormsParseTextValue( "PERSON_SECONDNAME_0");
  OraFormsMenuItem( "WINDOW1",  "Action::Exit");
end TMain
Parent topic: Parsing Functions
Related concepts
Verifying Functions


Verifying Functions

There are a number of verification functions that allow you to verify control values and certain control properties. These functions allow you to verify if a certain control has a specific value or if a certain property of a control has a specific value. You can define severities that result in warnings and errors during test runs when verifications are not successful.

TrueLog Explorer

TrueLog Explorer assists you with wizards that add verification functions to your scripts. Simply select a control that you require, right-click on the grid row that displays the current value of the control and select Verify Element Value from the context menu.

Refer to the Oracle Forms Tutorial for detailed information.

  • OraFormsVerifyCheckValue Function
    Verifies whether a check box is checked or unchecked.
  • OraFormsVerifyChoiceBoxProperty Function
    Verifies a choice box property.
  • OraFormsVerifyFlexCellData Function
    Verifies the field of a flex window.
  • OraFormsVerifyFlexCellDataByIndex Function
    Verifies the field of a flex window.
  • OraFormsVerifyFlexCellPropBoolean Function
    Verifies a Boolean cell property.
  • OraFormsVerifyFlexCellPropBooleanByIndex Function
    Verifies a Boolean cell property.
  • OraFormsVerifyFlexCellPropInt Function
    Verifies a cell’s property.
  • OraFormsVerifyFlexCellPropIntByIndex Function
    Verifies an integer cell property within a flex window cell.
  • OraFormsVerifyFlexCellPropString Function
    Verifies a string property within a flex window cell.
  • OraFormsVerifyFlexCellPropStringByIndex Function
    Verifies a string property within a flex window cell.
  • OraFormsVerifyFlexPropBoolean Function
    Verifies Boolean properties within flex windows.
  • OraFormsVerifyFlexPropString Function
    Verifies a flex window’s string property.
  • OraFormsVerifyInfoBoxProperty Function
    Verifies a property within an Info dialog.
  • OraFormsVerifyListEntries Function
    Verifies the number of list entries in a combo box, list box, or pop-up list.
  • OraFormsVerifyListIndex Function
    Verifies the selected item in a list control.
  • OraFormsVerifyListValue Function
    Verifies the selected list value of a combo box, list box, or pop-up list.
  • OraFormsVerifyPropByte Function
    Verifies a byte property.
  • OraFormsVerifyPropByteArray Function
    Verifies all elements in a byte array.
  • OraFormsVerifyPropInt Function
    Verifies an integer property for a specified control.
  • OraFormsVerifyPropNull Function
    Verifies if a property value is NULL.
  • OraFormsVerifyPropPoint Function
    Verifies a point property.
  • OraFormsVerifyPropRectangle Function
    Verifies a rectangle property.
  • OraFormsVerifyPropString Function
    Verifies the properties value.
  • OraFormsVerifyPropStringArray Function
    Verifies all strings in an array.
  • OraFormsVerifyRadioValue Function
    Verifies the value of a radio button.
  • OraFormsVerifySelectedTreeItem Function
    Verifies the selected tree node of a tree control with a provided value.
  • OraFormsVerifyTextValue Functions
    Verifies a text field or text area.
Parent topic: Oracle Forms Functions Reference


OraFormsVerifyCheckValue Function

Action

Verifies whether a check box is checked or unchecked.

Include file

OraForms.bdh

Syntax

OraFormsVerifyCheckValue( in sName     : string,
                          in bVerify   : boolean,
                          in nOptions  : number optional,
                          in nSeverity : number optional := SEVERITY_ERROR ) : boolean;

Return value

  • true if successful
  • false otherwise
Parameter | Description
sName | The control's unique name.
bVerify | Value to compare with the parsed value.
nOptions Two options are recognized by this function:
  • ORA_VERIFY_EQUAL (default)
  • ORA_VERIFY_NOT_EQUAL
nSeverity Optional: Severity of the error that is raised if the verification fails. Can be one of the following values:
  • SEVERITY_SUCCESS: Success; no error (numerical value: 0)
  • SEVERITY_INFORMATIONAL: Informational; no error (numerical value: 1)
  • SEVERITY_WARNING: Warning; no error (numerical value: 2)
  • SEVERITY_ERROR: (Default) Error; simulation continues (numerical value: 3)
  • SEVERITY_TRANS_EXIT: Error; the active transaction is aborted (numerical value: 4)
  • SEVERITY_PROCESS_EXIT: Error; the simulation is aborted (numerical value: 5)

Example

transaction TMain
var
  sValue :  string;
begin
  OraFormsSetConnectMode(ORA_SOCKET_CONNECTION);
  // Connect - with connection properties
  OraFormsSetInt( "INITIAL_VERSION", 608);
  OraFormsSetPoint( "INITIAL_RESOLUTION",  96,  96);
  OraFormsSetPoint( "INITIAL_DISP_SIZE", 1024,  768);
  OraFormsSetInt( "INITIAL_COLOR_DEPTH", 256);
  OraFormsSetString( "FONT_NAME" , "Dialog" );
  OraFormsSetPoint( "INITIAL_SCALE_INFO",  8,  18);
  OraFormsSetBoolean( "WINSYS_REQUIREDVA_LIST",  false);
  OraFormsConnect( "server module=Person3.fmx userid= useSDI=yes record=names");
  OraFormsSetWindow( "Logon");
  OraFormsLogon( "user",  "password",  "orcl_server");
  // ---
  // New window activated: WINDOW1
  OraFormsSetWindow( "WINDOW1");
  OraFormsMenuItem( "WINDOW1",  "Query::Execute Query");
  OraFormsCheckboxSet( "CHECKBOX_01", true);
  OraFormsVerifyCheckValue( "CHECKBOX_01",  true, ORA_VERIFY_EQUAL, SEVERITY_WARNING);
  OraFormsMenuItem( "WINDOW1",  "Action::Exit");
end TMain;
Parent topic: Verifying Functions


OraFormsVerifyChoiceBoxProperty Function

Action

OraFormsVerifyChoiceBoxProperty verifies a choice box property.

Include file

OraForms.bdh

Syntax

OraFormsVerifyChoiceBoxProperty( in sName     : string,
                                 in nProp     : number,
                                 in sValue    : string,
                                 in nOptions  : number,
                                 in nSeverity : number := SEVERITY_ERROR ) : boolean;

Return value

  • true if successful

  • false otherwise

Parameter | Description
sName | The control's unique name.
nProp

Can be one of these constants:

  • ORA_CHOICEBOX_MESSAGE

  • ORA_CHOICEBOX_TITLE

  • ORA_CHOICEBOX_ICON

sValue | The value to be verified.
nOptions

Can be one of these flags or a combination:

  • ORA_VERIFY_EQUAL

  • ORA_VERIFY_NOT_EQUAL

  • ORA_VERIFY_CASE_SENSITIVE

  • ORA_VERIFY_IGNORE_WHITESPACES

nSeverity Optional: Severity of the error that is raised if the verification fails. Can be one of the following values:
  • SEVERITY_SUCCESS: Success; no error (numerical value: 0)
  • SEVERITY_INFORMATIONAL: Informational; no error (numerical value: 1)
  • SEVERITY_WARNING: Warning; no error (numerical value: 2)
  • SEVERITY_ERROR: (Default) Error; simulation continues (numerical value: 3)
  • SEVERITY_TRANS_EXIT: Error; the active transaction is aborted (numerical value: 4)
  • SEVERITY_PROCESS_EXIT: Error; the simulation is aborted (numerical value: 5)

Example

dcltrans
  transaction TMain
  var
    sValue   : string;
  begin
    OraFormsSetConnectMode(ORA_SOCKET_CONNECTION);
    // Connect - with connection properties
    OraFormsSetInt("INITIAL_VERSION", 608);
    OraFormsSetPoint("INITIAL_RESOLUTION", 96, 96);
    OraFormsSetPoint("INITIAL_DISP_SIZE", 1024, 768);
    OraFormsSetInt("INITIAL_COLOR_DEPTH", 256);
    OraFormsSetString("FONT_NAME", "Dialog");
    OraFormsSetPoint("INITIAL_SCALE_INFO", 8, 18);
    OraFormsSetBoolean("WINSYS_REQUIREDVA_LIST", false);
    OraFormsConnect("server module=Person3.fmx userid= useSDI=yes record=names");
    OraFormsSetWindow("Logon");
    OraFormsLogon("user", "password", "orcl_server");
    // ---
    // New window activated: WINDOW1
    OraFormsSetWindow("WINDOW1");
    OraFormsVerifyChoiceBoxProperty("ADB Account", ORA_CHOICEBOX_ICON, "value", ORA_VERIFY_EQUAL, SEVERITY_ERROR);
  end TMain;
Parent topic: Verifying Functions


OraFormsVerifyFlexCellData Function

Action

OraFormsVerifyFlexCellData verifies the field of a flex window.

Include file

OraForms.bdh

Syntax

OraFormsVerifyFlexCellData( in sName     : string,
                            in sRow      : string,
                            in sCol      : string,
                            in sValue    : string,
                            in nOptions  : number,
                            in nSeverity : number := SEVERITY_ERROR ) : boolean;

Return value

  • true if successful

  • false otherwise

Parameter | Description
sName | The control's unique name.
sRow | The field’s row.
sCol | The field’s column.
sValue | The string to be verified.
nOptions

Can be one of these flags or a combination:

  • ORA_VERIFY_EQUAL

  • ORA_VERIFY_NOT_EQUAL

  • ORA_VERIFY_CASE_SENSITIVE

  • ORA_VERIFY_IGNORE_WHITESPACES

nSeverity Optional: Severity of the error that is raised if the verification fails. Can be one of the following values:
  • SEVERITY_SUCCESS: Success; no error (numerical value: 0)
  • SEVERITY_INFORMATIONAL: Informational; no error (numerical value: 1)
  • SEVERITY_WARNING: Warning; no error (numerical value: 2)
  • SEVERITY_ERROR: (Default) Error; simulation continues (numerical value: 3)
  • SEVERITY_TRANS_EXIT: Error; the active transaction is aborted (numerical value: 4)
  • SEVERITY_PROCESS_EXIT: Error; the simulation is aborted (numerical value: 5)

Example

dcltrans
  transaction TMain
  var
    sValue   : string;
  begin
    OraFormsSetConnectMode(ORA_SOCKET_CONNECTION);
    // Connect - with connection properties
    OraFormsSetInt("INITIAL_VERSION", 608);
    OraFormsSetPoint("INITIAL_RESOLUTION", 96, 96);
    OraFormsSetPoint("INITIAL_DISP_SIZE", 1024, 768);
    OraFormsSetInt("INITIAL_COLOR_DEPTH", 256);
    OraFormsSetString("FONT_NAME", "Dialog");
    OraFormsSetPoint("INITIAL_SCALE_INFO", 8, 18);
    OraFormsSetBoolean("WINSYS_REQUIREDVA_LIST", false);
    OraFormsConnect("server module=Person3.fmx userid= useSDI=yes record=names");
    OraFormsSetWindow("Logon");
    OraFormsLogon("user", "password", "orcl_server");
    // ---
    // New window activated: WINDOW1
    OraFormsSetWindow("WINDOW1");
    OraFormsVerifyFlexCellData("ADB Account", "Transfer", "Low", "value", ORA_VERIFY_EQUAL, SEVERITY_ERROR);
  end TMain;
Parent topic: Verifying Functions


OraFormsVerifyFlexCellDataByIndex Function

Action

OraFormsVerifyFlexCellDataByIndex verifies the field of a flex window.

Include file

OraForms.bdh

Syntax

OraFormsVerifyFlexCellDataByIndex( in sName     : string,
                                   in nRow      : number,
                                   in nCol      : number,
                                   in sValue    : string,
                                   in nOptions  : number,
                                   in nSeverity : number := SEVERITY_ERROR ) : boolean;

Return value

  • true if successful

  • false otherwise

Parameter | Description
sName | The control's unique name.
nRow | The field’s row.
nCol | The field’s column.
sValue | The string to be verified.
nOptions Can be one of these flags or a combination:

  • ORA_VERIFY_EQUAL

  • ORA_VERIFY_NOT_EQUAL

  • ORA_VERIFY_CASE_SENSITIVE

  • ORA_VERIFY_IGNORE_WHITESPACES

nSeverity Optional: Severity of the error that is raised if the verification fails. Can be one of the following values:
  • SEVERITY_SUCCESS: Success; no error (numerical value: 0)
  • SEVERITY_INFORMATIONAL: Informational; no error (numerical value: 1)
  • SEVERITY_WARNING: Warning; no error (numerical value: 2)
  • SEVERITY_ERROR: (Default) Error; simulation continues (numerical value: 3)
  • SEVERITY_TRANS_EXIT: Error; the active transaction is aborted (numerical value: 4)
  • SEVERITY_PROCESS_EXIT: Error; the simulation is aborted (numerical value: 5)

Example

dcltrans
  transaction TMain
  var
    sValue   : string;
  begin
    OraFormsSetConnectMode(ORA_SOCKET_CONNECTION);
    // Connect - with connection properties
    OraFormsSetInt("INITIAL_VERSION", 608);
    OraFormsSetPoint("INITIAL_RESOLUTION", 96, 96);
    OraFormsSetPoint("INITIAL_DISP_SIZE", 1024, 768);
    OraFormsSetInt("INITIAL_COLOR_DEPTH", 256);
    OraFormsSetString("FONT_NAME", "Dialog");
    OraFormsSetPoint("INITIAL_SCALE_INFO", 8, 18);
    OraFormsSetBoolean("WINSYS_REQUIREDVA_LIST", false);
    OraFormsConnect("server module=Person3.fmx userid= useSDI=yes record=names");
    OraFormsSetWindow("Logon");
    OraFormsLogon("user", "password", "orcl_server");
    // ---
    // New window activated: WINDOW1
    OraFormsSetWindow("WINDOW1");
    OraFormsVerifyFlexCellDataByIndex("ADB Account", 0, 0, "value", ORA_VERIFY_EQUAL, SEVERITY_ERROR);
  end TMain;
Parent topic: Verifying Functions


OraFormsVerifyFlexCellPropBoolean Function

Action

OraFormsVerifyFlexCellPropBoolean verifies a Boolean cell property.

Include file

OraForms.bdh

Syntax

OraFormsVerifyFlexCellPropBoolean( in sName     : string,
                                   in sRow      : string,
                                   in sCol      : string,
                                   in nProp     : number,
                                   in bValue    : boolean,
                                   in nOptions  : number,
                                   in nSeverity : number := SEVERITY_ERROR ) : boolean;

Return value

  • true if successful

  • false otherwise

Parameter | Description
sName | The control's unique name.
sRow | The field’s row.
sCol | The field’s column.
nProp

Can be one of these constants:

  • ORA_FLEX_CELL_IS_QUERYABLE

  • ORA_FLEX_CELL_IS_FOCUSNOTIFY

  • ORA_FLEX_CELL_IS_REQUIRED

  • ORA_FLEX_CELL_IS_UPDATEABLE

  • ORA_FLEX_CELL_IS_FLEXFIELD

  • ORA_FLEX_CELL_IS_UPPERCASE

  • ORA_FLEX_CELL_IS_NUMERIC

  • ORA_FLEX_CELL_IS_VALID

  • ORA_FLEX_CELL_IS_ENABLED

bValue | The value to be verified.
nOptions

Can be one of these flags:

  • ORA_VERIFY_EQUAL

  • ORA_VERIFY_NOT_EQUAL

nSeverity Optional: Severity of the error that is raised if the verification fails. Can be one of the following values:
  • SEVERITY_SUCCESS: Success; no error (numerical value: 0)
  • SEVERITY_INFORMATIONAL: Informational; no error (numerical value: 1)
  • SEVERITY_WARNING: Warning; no error (numerical value: 2)
  • SEVERITY_ERROR: (Default) Error; simulation continues (numerical value: 3)
  • SEVERITY_TRANS_EXIT: Error; the active transaction is aborted (numerical value: 4)
  • SEVERITY_PROCESS_EXIT: Error; the simulation is aborted (numerical value: 5)

Example

dcltrans
  transaction TMain
  var
    sValue   : string;
  begin
    OraFormsSetConnectMode(ORA_SOCKET_CONNECTION);
    // Connect - with connection properties
    OraFormsSetInt("INITIAL_VERSION", 608);
    OraFormsSetPoint("INITIAL_RESOLUTION", 96, 96);
    OraFormsSetPoint("INITIAL_DISP_SIZE", 1024, 768);
    OraFormsSetInt("INITIAL_COLOR_DEPTH", 256);
    OraFormsSetString("FONT_NAME", "Dialog");
    OraFormsSetPoint("INITIAL_SCALE_INFO", 8, 18);
    OraFormsSetBoolean("WINSYS_REQUIREDVA_LIST", false);
    OraFormsConnect("server module=Person3.fmx userid= useSDI=yes record=names");
    OraFormsSetWindow("Logon");
    OraFormsLogon("user", "password", "orcl_server");
    // ---
    // New window activated: WINDOW1
    OraFormsSetWindow("WINDOW1");
    OraFormsVerifyFlexCellPropBoolean("ADB Account", "Transfer", "Low", ORA_FLEX_CELL_IS_ENABLED, true, ORA_VERIFY_EQUAL, SEVERITY_ERROR);
  end TMain;
Parent topic: Verifying Functions


OraFormsVerifyFlexCellPropBooleanByIndex Function

Action

OraFormsVerifyFlexCellPropBooleanByIndex verifies a Boolean cell property.

Include file

OraForms.bdh

Syntax

OraFormsVerifyFlexCellPropBooleanByIndex( in sName     : string,
                                          in nRow      : number,
                                          in nCol      : number,
                                          in nProp     : number,
                                          in bValue    : boolean,
                                          in nOptions  : number,
                                          in nSeverity : number := SEVERITY_ERROR ) : boolean;

Return value

  • true if successful

  • false otherwise

Parameter | Description
sName | The control's unique name.
nRow | The field’s row.
nCol | The field’s column.
nProp

Can be one of these constants:

  • ORA_FLEX_CELL_IS_QUERYABLE

  • ORA_FLEX_CELL_IS_FOCUSNOTIFY

  • ORA_FLEX_CELL_IS_REQUIRED

  • ORA_FLEX_CELL_IS_UPDATEABLE

  • ORA_FLEX_CELL_IS_FLEXFIELD

  • ORA_FLEX_CELL_IS_UPPERCASE

  • ORA_FLEX_CELL_IS_NUMERIC

  • ORA_FLEX_CELL_IS_VALID

  • ORA_FLEX_CELL_IS_ENABLED

bValue | The value to be verified.
nOptions

Can be one of these flags:

  • ORA_VERIFY_EQUAL

  • ORA_VERIFY_NOT_EQUAL

nSeverity Optional: Severity of the error that is raised if the verification fails. Can be one of the following values:
  • SEVERITY_SUCCESS: Success; no error (numerical value: 0)
  • SEVERITY_INFORMATIONAL: Informational; no error (numerical value: 1)
  • SEVERITY_WARNING: Warning; no error (numerical value: 2)
  • SEVERITY_ERROR: (Default) Error; simulation continues (numerical value: 3)
  • SEVERITY_TRANS_EXIT: Error; the active transaction is aborted (numerical value: 4)
  • SEVERITY_PROCESS_EXIT: Error; the simulation is aborted (numerical value: 5)

Example

dcltrans
  transaction TMain
  var
    sValue   : string;
  begin
    OraFormsSetConnectMode(ORA_SOCKET_CONNECTION);
    // Connect - with connection properties
    OraFormsSetInt("INITIAL_VERSION", 608);
    OraFormsSetPoint("INITIAL_RESOLUTION", 96, 96);
    OraFormsSetPoint("INITIAL_DISP_SIZE", 1024, 768);
    OraFormsSetInt("INITIAL_COLOR_DEPTH", 256);
    OraFormsSetString("FONT_NAME", "Dialog");
    OraFormsSetPoint("INITIAL_SCALE_INFO", 8, 18);
    OraFormsSetBoolean("WINSYS_REQUIREDVA_LIST", false);
    OraFormsConnect("server module=Person3.fmx userid= useSDI=yes record=names");
    OraFormsSetWindow("Logon");
    OraFormsLogon("user", "password", "orcl_server");
    // ---
    // New window activated: WINDOW1
    OraFormsSetWindow("WINDOW1");
    OraFormsVerifyFlexCellPropBooleanByIndex("ADB Account", 0, 0, ORA_FLEX_CELL_IS_ENABLED, true, ORA_VERIFY_EQUAL, SEVERITY_ERROR);
  end TMain;
Parent topic: Verifying Functions


OraFormsVerifyFlexCellPropInt Function

Action

OraFormsVerifyFlexCellPropInt verifies a cell’s property.

Include file

OraForms.bdh

Syntax

OraFormsVerifyFlexCellPropInt( in sName     : string,
                               in sRow      : string,
                               in sCol      : string,
                               in nProp     : number,
                               in nValue    : number,
                               in nOptions  : number,
                               in nSeverity : number := SEVERITY_ERROR ) : boolean;

Return value

  • true if successful

  • false otherwise

Parameter | Description
sName | The control's unique name.
sRow | The field’s row.
sCol | The field’s column.
nProp

Can be one of these constants:

  • ORA_FLEX_CELL_MAX_LEN

  • ORA_FLEX_CELL_LEN

  • ORA_FLEX_CELL_DESCR_LEN

nValue | The value to be verified.
nOptions

Can be one of these flags:

  • ORA_VERIFY_EQUAL

  • ORA_VERIFY_NOT_EQUAL

  • ORA_VERIFY_GREATER

  • ORA_VERIFY_GREATEREQUAL

  • ORA_VERIFY_SMALLER

  • ORA_VERIFY_SMALLEREQUAL

nSeverity Optional: Severity of the error that is raised if the verification fails. Can be one of the following values:
  • SEVERITY_SUCCESS: Success; no error (numerical value: 0)
  • SEVERITY_INFORMATIONAL: Informational; no error (numerical value: 1)
  • SEVERITY_WARNING: Warning; no error (numerical value: 2)
  • SEVERITY_ERROR: (Default) Error; simulation continues (numerical value: 3)
  • SEVERITY_TRANS_EXIT: Error; the active transaction is aborted (numerical value: 4)
  • SEVERITY_PROCESS_EXIT: Error; the simulation is aborted (numerical value: 5)

Example

dcltrans
  transaction TMain
  var
    sValue   : string;
  begin
    OraFormsSetConnectMode(ORA_SOCKET_CONNECTION);
    // Connect - with connection properties
    OraFormsSetInt("INITIAL_VERSION", 608);
    OraFormsSetPoint("INITIAL_RESOLUTION", 96, 96);
    OraFormsSetPoint("INITIAL_DISP_SIZE", 1024, 768);
    OraFormsSetInt("INITIAL_COLOR_DEPTH", 256);
    OraFormsSetString("FONT_NAME", "Dialog");
    OraFormsSetPoint("INITIAL_SCALE_INFO", 8, 18);
    OraFormsSetBoolean("WINSYS_REQUIREDVA_LIST", false);
    OraFormsConnect("server module=Person3.fmx userid= useSDI=yes record=names");
    OraFormsSetWindow("Logon");
    OraFormsLogon("user", "password", "orcl_server");
    // ---
    // New window activated: WINDOW1
    OraFormsSetWindow("WINDOW1");
    OraFormsVerifyFlexCellPropInt("ADB Account", "Transfer", "Low", ORA_FLEX_CELL_LEN, 5, ORA_VERIFY_EQUAL, SEVERITY_ERROR);
  end TMain;
Parent topic: Verifying Functions


OraFormsVerifyFlexCellPropIntByIndex Function

Action

OraFormsVerifyFlexCellPropIntByIndex verifies an integer cell property within a flex window cell.

Include file

OraForms.bdh

Syntax

OraFormsVerifyFlexCellPropIntByIndex( in sName     : string,
                                      in nRow      : number,
                                      in nCol      : number,
                                      in nProp     : number,
                                      in nValue    : number,
                                      in nOptions  : number,
                                      in nSeverity : number := SEVERITY_ERROR ) : boolean;

Return value

  • true if successful

  • false otherwise

Parameter | Description
sName | The control's unique name.
nRow | The field’s row.
nCol | The field’s column.
nProp Can be one of these constants:

  • ORA_FLEX_CELL_MAX_LEN

  • ORA_FLEX_CELL_LEN

  • ORA_FLEX_CELL_DESCR_LEN

nValue | The value to be verified.
nOptions Can be one of these flags:

  • ORA_VERIFY_EQUAL

  • ORA_VERIFY_NOT_EQUAL

  • ORA_VERIFY_GREATER

  • ORA_VERIFY_GREATEREQUAL

  • ORA_VERIFY_SMALLER

  • ORA_VERIFY_SMALLEREQUAL

nSeverity Optional: Severity of the error that is raised if the verification fails. Can be one of the following values:
  • SEVERITY_SUCCESS: Success; no error (numerical value: 0)
  • SEVERITY_INFORMATIONAL: Informational; no error (numerical value: 1)
  • SEVERITY_WARNING: Warning; no error (numerical value: 2)
  • SEVERITY_ERROR: (Default) Error; simulation continues (numerical value: 3)
  • SEVERITY_TRANS_EXIT: Error; the active transaction is aborted (numerical value: 4)
  • SEVERITY_PROCESS_EXIT: Error; the simulation is aborted (numerical value: 5)

Example

dcltrans
  transaction TMain
  var
    sValue   : string;
  begin
    OraFormsSetConnectMode(ORA_SOCKET_CONNECTION);
    // Connect - with connection properties
    OraFormsSetInt("INITIAL_VERSION", 608);
    OraFormsSetPoint("INITIAL_RESOLUTION", 96, 96);
    OraFormsSetPoint("INITIAL_DISP_SIZE", 1024, 768);
    OraFormsSetInt("INITIAL_COLOR_DEPTH", 256);
    OraFormsSetString("FONT_NAME", "Dialog");
    OraFormsSetPoint("INITIAL_SCALE_INFO", 8, 18);
    OraFormsSetBoolean("WINSYS_REQUIREDVA_LIST", false);
    OraFormsConnect("server module=Person3.fmx userid= useSDI=yes record=names");
    OraFormsSetWindow("Logon");
    OraFormsLogon("user", "password", "orcl_server");
    // ---
    // New window activated: WINDOW1
    OraFormsSetWindow("WINDOW1");
    OraFormsVerifyFlexCellPropIntByIndex("ADB Account", 0, 0, ORA_FLEX_CELL_LEN, 5, ORA_VERIFY_EQUAL, SEVERITY_ERROR);
  end TMain;
Parent topic: Verifying Functions


OraFormsVerifyFlexCellPropString Function

Action

OraFormsVerifyFlexCellPropString verifies a string property within a flex window cell.

Include file

OraForms.bdh

Syntax

OraFormsVerifyFlexCellPropString( in sName     : string,
                                  in sRow      : string,
                                  in sCol      : string,
                                  in nProp     : number,
                                  in sValue    : string,
                                  in nOptions  : number,
                                  in nSeverity : number := SEVERITY_ERROR ) : boolean;

Return value

  • true if successful

  • false otherwise

Parameter | Description
sName | The control's unique name.
sRow | The field’s row.
sCol | The field’s column.
nProp

Can be one of these constants:

  • ORA_FLEX_CELL_VALUE

  • ORA_FLEX_CELL_DESCRIPTION

sValue | The value to be verified.
nOptions

Can be one of these flags:

  • ORA_VERIFY_EQUAL

  • ORA_VERIFY_NOT_EQUAL

  • ORA_VERIFY_CASE_SENSITIVE

  • ORA_VERIFY_IGNORE_WHITESPACES

nSeverity Optional: Severity of the error that is raised if the verification fails. Can be one of the following values:
  • SEVERITY_SUCCESS: Success; no error (numerical value: 0)
  • SEVERITY_INFORMATIONAL: Informational; no error (numerical value: 1)
  • SEVERITY_WARNING: Warning; no error (numerical value: 2)
  • SEVERITY_ERROR: (Default) Error; simulation continues (numerical value: 3)
  • SEVERITY_TRANS_EXIT: Error; the active transaction is aborted (numerical value: 4)
  • SEVERITY_PROCESS_EXIT: Error; the simulation is aborted (numerical value: 5)

Example

dcltrans
  transaction TMain
  var
    sValue   : string;
  begin
    OraFormsSetConnectMode(ORA_SOCKET_CONNECTION);
    // Connect - with connection properties
    OraFormsSetInt("INITIAL_VERSION", 608);
    OraFormsSetPoint("INITIAL_RESOLUTION", 96, 96);
    OraFormsSetPoint("INITIAL_DISP_SIZE", 1024, 768);
    OraFormsSetInt("INITIAL_COLOR_DEPTH", 256);
    OraFormsSetString("FONT_NAME", "Dialog");
    OraFormsSetPoint("INITIAL_SCALE_INFO", 8, 18);
    OraFormsSetBoolean("WINSYS_REQUIREDVA_LIST", false);
    OraFormsConnect("server module=Person3.fmx userid= useSDI=yes record=names");
    OraFormsSetWindow("Logon");
    OraFormsLogon("user", "password", "orcl_server");
    // ---
    // New window activated: WINDOW1
    OraFormsSetWindow("WINDOW1");
    OraFormsVerifyFlexCellPropString("ADB Account", "Transfer", "Low", ORA_FLEX_CELL_VALUE, "value", ORA_VERIFY_EQUAL, SEVERITY_ERROR);
  end TMain;
Parent topic: Verifying Functions


OraFormsVerifyFlexCellPropStringByIndex Function

Action

OraFormsVerifyFlexCellPropStringByIndex verifies a string property within a flex window cell.

Include file

OraForms.bdh

Syntax

OraFormsVerifyFlexCellPropStringByIndex(  in sName     : string,
                                          in nRow      : number,
                                          in nCol      : number,
                                          in nProp     : number,
                                          in sValue    : string,
                                          in nOptions  : number,
                                          in nSeverity : number := SEVERITY_ERROR ) : boolean;

Return value

  • true if successful

  • false otherwise

Parameter | Description
sName | The control's unique name.
nRow | The field’s row.
nCol | The field’s column.
nProp

Can be one of these constants:

  • ORA_FLEX_CELL_VALUE

  • ORA_FLEX_CELL_DESCRIPTION

sValue | The value to be verified.
nOptions

Can be one of these flags:

  • ORA_VERIFY_EQUAL

  • ORA_VERIFY_NOT_EQUAL

  • ORA_VERIFY_CASE_SENSITIVE

  • ORA_VERIFY_IGNORE_WHITESPACES

nSeverity Optional: Severity of the error that is raised if the verification fails. Can be one of the following values:
  • SEVERITY_SUCCESS: Success; no error (numerical value: 0)
  • SEVERITY_INFORMATIONAL: Informational; no error (numerical value: 1)
  • SEVERITY_WARNING: Warning; no error (numerical value: 2)
  • SEVERITY_ERROR: (Default) Error; simulation continues (numerical value: 3)
  • SEVERITY_TRANS_EXIT: Error; the active transaction is aborted (numerical value: 4)
  • SEVERITY_PROCESS_EXIT: Error; the simulation is aborted (numerical value: 5)

Example

dcltrans
  transaction TMain
  var
    sValue   : string;
  begin
    OraFormsSetConnectMode(ORA_SOCKET_CONNECTION);
    // Connect - with connection properties
    OraFormsSetInt("INITIAL_VERSION", 608);
    OraFormsSetPoint("INITIAL_RESOLUTION", 96, 96);
    OraFormsSetPoint("INITIAL_DISP_SIZE", 1024, 768);
    OraFormsSetInt("INITIAL_COLOR_DEPTH", 256);
    OraFormsSetString("FONT_NAME", "Dialog");
    OraFormsSetPoint("INITIAL_SCALE_INFO", 8, 18);
    OraFormsSetBoolean("WINSYS_REQUIREDVA_LIST", false);
    OraFormsConnect("server module=Person3.fmx userid= useSDI=yes record=names");
    OraFormsSetWindow("Logon");
    OraFormsLogon("user", "password", "orcl_server");
    // ---
    // New window activated: WINDOW1
    OraFormsSetWindow("WINDOW1");
    OraFormsVerifyFlexCellPropStringByIndex("ADB Account", 0, 0, ORA_FLEX_CELL_VALUE, "value", ORA_VERIFY_EQUAL, SEVERITY_ERROR);
  end TMain;
Parent topic: Verifying Functions


OraFormsVerifyFlexPropBoolean Function

Action

OraFormsVerifyFlexPropBoolean verifies Boolean properties within flex windows.

Include file

OraForms.bdh

Syntax

OraFormsVerifyFlexPropBoolean( in sName     : string,
                               in nProp     : number,
                               in bValue    : boolean,
                               in nOptions  : number,
                               in nSeverity : number ) : boolean;

Return value

  • true if successful

  • false otherwise

Parameter | Description
sName | The control's unique name.
nProp

Can be one of these constants:

  • ORA ORA_FLEX_WND_IS_AUTOPIK

  • ORA_FLEX_WND_IS_AUTOSKIP

  • ORA_FLEX_WND_IS_COMBO_AVAILABLE

  • ORA_FLEX_WND_IS_READONLY

bValue | The value to be verified.
nOptions

Can be one of these flags:

  • ORA_VERIFY_EQUAL

  • ORA_VERIFY_NOT_EQUAL

nSeverity
Severity of the error that is raised if the verification fails. Can be one of the following values:
  • SEVERITY_SUCCESS: Success; no error (numerical value: 0)
  • SEVERITY_INFORMATIONAL: Informational; no error (numerical value: 1)
  • SEVERITY_WARNING: Warning; no error (numerical value: 2)
  • SEVERITY_ERROR: Error; simulation continues (numerical value: 3)
  • SEVERITY_TRANS_EXIT: Error; the active transaction is aborted (numerical value: 4)
  • SEVERITY_PROCESS_EXIT: Error; the simulation is aborted (numerical value: 5)

Example

dcltrans
  transaction TMain
  var
    sValue   : string;
  begin
    OraFormsSetConnectMode(ORA_SOCKET_CONNECTION);
    // Connect - with connection properties
    OraFormsSetInt("INITIAL_VERSION", 608);
    OraFormsSetPoint("INITIAL_RESOLUTION", 96, 96);
    OraFormsSetPoint("INITIAL_DISP_SIZE", 1024, 768);
    OraFormsSetInt("INITIAL_COLOR_DEPTH", 256);
    OraFormsSetString("FONT_NAME", "Dialog");
    OraFormsSetPoint("INITIAL_SCALE_INFO", 8, 18);
    OraFormsSetBoolean("WINSYS_REQUIREDVA_LIST", false);
    OraFormsConnect("server module=Person3.fmx userid= useSDI=yes record=names");
    OraFormsSetWindow("Logon");
    OraFormsLogon("user", "password", "orcl_server");
    // ---
    // New window activated: WINDOW1
    OraFormsSetWindow("WINDOW1");
    OraFormsVerifyFlexPropBoolean("ADB Account", ORA_FLEX_WND_IS_READONLY, true, ORA_VERIFY_EQUAL, SEVERITY_ERROR);
  end TMain;
Parent topic: Verifying Functions


OraFormsVerifyFlexPropString Function

Action

OraFormsVerifyFlexPropString verifies a flex window’s string property.

Include file

OraForms.bdh

Syntax

OraFormsVerifyFlexPropString( in sName     : string,
                              in nProp     : number,
                              in sValue    : string,
                              in nOptions  : number,
                              in nSeverity : number ) : boolean;

Return value

  • true if successful

  • false otherwise

Parameter | Description
sName | The control's unique name.
nProp

Can be one of these constants:

  • ORA_FLEX_WND_LABEL

  • ORA_FLEX_WND_PROTOCOL

sValue | The value to be verified.
nOptions

Can be one of these flags:

  • ORA_VERIFY_EQUAL

  • ORA_VERIFY_NOT_EQUAL

  • ORA_VERIFY_CASE_SENSITIVE

  • ORA_VERIFY_IGNORE_WHITESPACES

nSeverity
Severity of the error that is raised if the verification fails. Can be one of the following values:
  • SEVERITY_SUCCESS: Success; no error (numerical value: 0)
  • SEVERITY_INFORMATIONAL: Informational; no error (numerical value: 1)
  • SEVERITY_WARNING: Warning; no error (numerical value: 2)
  • SEVERITY_ERROR: Error; simulation continues (numerical value: 3)
  • SEVERITY_TRANS_EXIT: Error; the active transaction is aborted (numerical value: 4)
  • SEVERITY_PROCESS_EXIT: Error; the simulation is aborted (numerical value: 5)

Example

dcltrans
  transaction TMain
  var
    sValue   : string;
  begin
    OraFormsSetConnectMode(ORA_SOCKET_CONNECTION);
    // Connect - with connection properties
    OraFormsSetInt("INITIAL_VERSION", 608);
    OraFormsSetPoint("INITIAL_RESOLUTION", 96, 96);
    OraFormsSetPoint("INITIAL_DISP_SIZE", 1024, 768);
    OraFormsSetInt("INITIAL_COLOR_DEPTH", 256);
    OraFormsSetString("FONT_NAME", "Dialog");
    OraFormsSetPoint("INITIAL_SCALE_INFO", 8, 18);
    OraFormsSetBoolean("WINSYS_REQUIREDVA_LIST", false);
    OraFormsConnect("server module=Person3.fmx userid= useSDI=yes record=names");
    OraFormsSetWindow("Logon");
    OraFormsLogon("user", "password", "orcl_server");
    // ---
    // New window activated: WINDOW1
    OraFormsSetWindow("WINDOW1");
    OraFormsVerifyFlexPropString("ADB Account", ORA_FLEX_WND_PROTOCOL, "value", ORA_VERIFY_EQUAL, SEVERITY_ERROR);
  end TMain;
Parent topic: Verifying Functions


OraFormsVerifyInfoBoxProperty Function

Action

OraFormsVerifyInfoBoxProperty verifies a property within an Info dialog.

Include file

OraForms.bdh

Syntax

OraFormsVerifyInfoBoxProperty( in sName     : string,
                               in nProp     : number,
                               in sValue    : string,
                               in nOptions  : number,
                               in nSeverity : number := SEVERITY_ERROR ) : boolean;

Return value

  • true if successful

  • false otherwise

Parameter | Description
sName | The control's unique name.
nProp

Can be one of these constants:

  • ORA_INFOBOX_MESSAGE

  • ORA_INFOBOX_TITLE

  • ORA_INFOBOX_ICON

sValue | The value to be verified.
nOptions

Can be one of these flags:

  • ORA_VERIFY_EQUAL (default)

  • ORA_VERIFY_NOT_EQUAL

  • ORA_VERIFY_CASE_SENSITIVE

  • ORA_VERIFY_IGNORE_WHITESPACES

nSeverity
Severity of the error that is raised if the verification fails. Can be one of the following values:
  • SEVERITY_SUCCESS: Success; no error (numerical value: 0)
  • SEVERITY_INFORMATIONAL: Informational; no error (numerical value: 1)
  • SEVERITY_WARNING: Warning; no error (numerical value: 2)
  • SEVERITY_ERROR: Error; simulation continues (numerical value: 3)
  • SEVERITY_TRANS_EXIT: Error; the active transaction is aborted (numerical value: 4)
  • SEVERITY_PROCESS_EXIT: Error; the simulation is aborted (numerical value: 5)

Example

dcltrans
  transaction TMain
  var
    sValue   : string;
  begin
    OraFormsSetConnectMode(ORA_SOCKET_CONNECTION);
    // Connect - with connection properties
    OraFormsSetInt("INITIAL_VERSION", 608);
    OraFormsSetPoint("INITIAL_RESOLUTION", 96, 96);
    OraFormsSetPoint("INITIAL_DISP_SIZE", 1024, 768);
    OraFormsSetInt("INITIAL_COLOR_DEPTH", 256);
    OraFormsSetString("FONT_NAME", "Dialog");
    OraFormsSetPoint("INITIAL_SCALE_INFO", 8, 18);
    OraFormsSetBoolean("WINSYS_REQUIREDVA_LIST", false);
    OraFormsConnect("server module=Person3.fmx userid= useSDI=yes record=names");
    OraFormsSetWindow("Logon");
    OraFormsLogon("user", "password", "orcl_server");
    // ---
    // New window activated: WINDOW1
    OraFormsSetWindow("WINDOW1");
    OraFormsVerifyInfoBoxProperty("ADB Account", ORA_INFOBOX_MESSAGE, "value", ORA_VERIFY_EQUAL, SEVERITY_ERROR);
  end TMain;
Parent topic: Verifying Functions


OraFormsVerifyListEntries Function

Action

Verifies the number of list entries in a combo box, list box, or pop-up list.

Include file

OraForms.bdh

Syntax

OraFormsVerifyListEntries( in sName     : string,
                           in nVerify   : number,
                           in nOptions  : number optional,
                           in nSeverity : number optional := SEVERITY_ERROR ) : boolean;

Return value

  • true if successful
  • false otherwise
Parameter | Description
sName | The control's unique name.nSeverity.
nVerify | The value to be verified with the number of list entries.
nOptions

Can be one of these flags:

  • ORA_VERIFY_EQUAL (default)
  • ORA_VERIFY_NOT_EQUAL
  • ORA_VERIFY_GREATER
  • ORA_VERIFY_GREATEREQUAL
  • ORA_VERIFY_SMALLER
  • ORA_VERIFY_SMALLEREQUAL
nSeverity Optional: Severity of the error that is raised if the verification fails. Can be one of the following values:
  • SEVERITY_SUCCESS: Success; no error (numerical value: 0)
  • SEVERITY_INFORMATIONAL: Informational; no error (numerical value: 1)
  • SEVERITY_WARNING: Warning; no error (numerical value: 2)
  • SEVERITY_ERROR: (Default) Error; simulation continues (numerical value: 3)
  • SEVERITY_TRANS_EXIT: Error; the active transaction is aborted (numerical value: 4)
  • SEVERITY_PROCESS_EXIT: Error; the simulation is aborted (numerical value: 5)

Example

transaction TMain
var
  sValue :  string;
begin
  OraFormsSetConnectMode(ORA_SOCKET_CONNECTION);
  // Connect - with connection properties
  OraFormsSetInt( "INITIAL_VERSION", 608);
  OraFormsSetPoint( "INITIAL_RESOLUTION", 96,  96);
  OraFormsSetPoint( "INITIAL_DISP_SIZE", 1024,  768);
  OraFormsSetInt( "INITIAL_COLOR_DEPTH", 256);
  OraFormsSetString( "FONT_NAME" , "Dialog" );
  OraFormsSetPoint( "INITIAL_SCALE_INFO", 8,  18);
  OraFormsSetBoolean( "WINSYS_REQUIREDVA_LIST",  false);
  OraFormsConnect( "server module=Person3.fmx userid= useSDI=yes record=names");
  OraFormsSetWindow( "Logon");
  OraFormsLogon( "user",  "password",  "orcl_server");
  // ---
  // New window activated: WINDOW1
  OraFormsSetWindow( "WINDOW1");
  OraFormsMenuItem( "WINDOW1",  "Query::Execute Query");
  OraFormsListSelect( "LISTBOX_01",  "An Option",  2);
  OraFormsVerifyListEntries( "LISTBOX_01",  5, ORA_VERIFY_EQUAL, SEVERITY_WARNING);
  OraFormsMenuItem( "WINDOW1",  "Action::Exit");
end TMain;
Parent topic: Verifying Functions


OraFormsVerifyListIndex Function

Action

Verifies the selected item in a list control.

Include file

OraForms.bdh

Syntax

OraFormsVerifyListIndex( in sName     : string,
                         in nVerify   : number,
                         in nOptions  : number optional,
                         in nSeverity : number optional := SEVERITY_ERROR ) :  boolean;

Return value

  • true if successful
  • false otherwise
Parameter | Description
sName | The control's unique name.
nVerify | The index to be verified with the selected item's index.
nOptions

Can be one of these flags:

  • ORA_VERIFY_EQUAL (default)
  • ORA_VERIFY_NOT_EQUAL
  • ORA_VERIFY_GREATER
  • ORA_VERIFY_GREATEREQUAL
  • ORA_VERIFY_SMALLER
  • ORA_VERIFY_SMALLEREQUAL
nSeverity Optional: Severity of the error that is raised if the verification fails. Can be one of the following values:
  • SEVERITY_SUCCESS: Success; no error (numerical value: 0)
  • SEVERITY_INFORMATIONAL: Informational; no error (numerical value: 1)
  • SEVERITY_WARNING: Warning; no error (numerical value: 2)
  • SEVERITY_ERROR: (Default) Error; simulation continues (numerical value: 3)
  • SEVERITY_TRANS_EXIT: Error; the active transaction is aborted (numerical value: 4)
  • SEVERITY_PROCESS_EXIT: Error; the simulation is aborted (numerical value: 5)

Example

transaction TMain
var
  sValue :  string;
begin
  OraFormsSetConnectMode(ORA_SOCKET_CONNECTION);
  // Connect - with connection properties
  OraFormsSetInt( "INITIAL_VERSION", 608);
  OraFormsSetPoint( "INITIAL_RESOLUTION", 96,  96);
  OraFormsSetPoint( "INITIAL_DISP_SIZE", 1024,  768);
  OraFormsSetInt( "INITIAL_COLOR_DEPTH", 256);
  OraFormsSetString( "FONT_NAME" , "Dialog" );
  OraFormsSetPoint( "INITIAL_SCALE_INFO", 8,  18);
  OraFormsSetBoolean( "WINSYS_REQUIREDVA_LIST",  false);
  OraFormsConnect( "server module=Person3.fmx userid= useSDI=yes record=names");
  OraFormsSetWindow( "Logon");
  OraFormsLogon( "user",  "password",  "orcl_server");
  // ---
  // New window activated: WINDOW1 OraFormsSetWindow( "WINDOW1");
  OraFormsMenuItem( "WINDOW1",  "Query::Execute Query");
  OraFormsListSelect( "LISTBOX_01",  "An Option",  2);
  OraFormsVerifyListIndex("LISTBOX_01",
  2, ORA_VERIFY_EQUAL, SEVERITY_WARNING);
  OraFormsMenuItem( "WINDOW1",  "Action::Exit");
end TMain;
Parent topic: Verifying Functions


OraFormsVerifyListValue Function

Action

Verifies the selected list value of a combo box, list box, or pop-up list.

Include file

OraForms.bdh

Syntax

OraFormsVerifyListValue(  in sName     :  string,
                          in sVerify   :  string,
                          in nOptions  :  number optional,
                          in nSeverity :  number optional := SEVERITY_ERROR ) : boolean;

Return value

  • true if successful
  • false otherwise
Parameter | Description
sName | The control's unique name.
sVerify | The value to verify the selected item in the list against.
nOptions

Can be one of these flags or a combination:

  • ORA_VERIFY_EQUAL (default)
  • ORA_VERIFY_NOT_EQUAL
  • ORA_VERIFY_CASE_SENSITIVE
  • ORA_VERIFY_IGNORE_WHITESPACES
nSeverity Optional: Severity of the error that is raised if the verification fails. Can be one of the following values:
  • SEVERITY_SUCCESS: Success; no error (numerical value: 0)
  • SEVERITY_INFORMATIONAL: Informational; no error (numerical value: 1)
  • SEVERITY_WARNING: Warning; no error (numerical value: 2)
  • SEVERITY_ERROR: (Default) Error; simulation continues (numerical value: 3)
  • SEVERITY_TRANS_EXIT: Error; the active transaction is aborted (numerical value: 4)
  • SEVERITY_PROCESS_EXIT: Error; the simulation is aborted (numerical value: 5)

Example

transaction TMain
var
  sValue :  string;
begin
  OraFormsSetConnectMode(ORA_SOCKET_CONNECTION);
  // Connect - with connection properties
  OraFormsSetInt( "INITIAL_VERSION", 608);
  OraFormsSetPoint( "INITIAL_RESOLUTION", 96,  96);
  OraFormsSetPoint( "INITIAL_DISP_SIZE", 1024,  768);
  OraFormsSetInt( "INITIAL_COLOR_DEPTH", 256);
  OraFormsSetString( "FONT_NAME" , "Dialog" );
  OraFormsSetPoint( "INITIAL_SCALE_INFO", 8,  18);
  OraFormsSetBoolean( "WINSYS_REQUIREDVA_LIST",  false);
  OraFormsConnect( "server module=Person3.fmx userid= useSDI=yes record=names");
  OraFormsSetWindow( "Logon");
  OraFormsLogon( "user",  "password",  "orcl_server");
  // ---
  // New window activated: WINDOW1
  OraFormsSetWindow( "WINDOW1");
  OraFormsMenuItem( "WINDOW1",  "Query::Execute Query");
  OraFormsListSelect( "LISTBOX_01",  "An Option",  2);
  OraFormsVerifyListValue( "LISTBOX_01",  "An Option", ORA_VERIFY_EQUAL, SEVERITY_WARNING);
  OraFormsMenuItem( "WINDOW1",  "Action::Exit");
end TMain;
Parent topic: Verifying Functions


OraFormsVerifyPropByte Function

Action

Verifies a byte property.

Include file

OraForms.bdh

Syntax

OraFormsVerifyPropByte( in sName     : string,
                        in nPropId   : number,
                        in nVerify   : number,
                        in nSeverity : number optional := SEVERITY_ERROR ) : boolean;

Return value

  • true if successful
  • false otherwise
Parameter | Description
sName | The control's unique name.
nPropId | The property ID.
nVerify | Number to verify the parsed property against.
nSeverity Optional: Severity of the error that is raised if the verification fails. Can be one of the following values:
  • SEVERITY_SUCCESS: Success; no error (numerical value: 0)
  • SEVERITY_INFORMATIONAL: Informational; no error (numerical value: 1)
  • SEVERITY_WARNING: Warning; no error (numerical value: 2)
  • SEVERITY_ERROR: (Default) Error; simulation continues (numerical value: 3)
  • SEVERITY_TRANS_EXIT: Error; the active transaction is aborted (numerical value: 4)
  • SEVERITY_PROCESS_EXIT: Error; the simulation is aborted (numerical value: 5)

Example

transaction TMain
var
  sValue :  string;
begin
  OraFormsSetConnectMode(ORA_SOCKET_CONNECTION);
  // Connect - with connection properties
  OraFormsSetInt( "INITIAL_VERSION", 608);
  OraFormsSetPoint( "INITIAL_RESOLUTION", 96,  96);
  OraFormsSetPoint( "INITIAL_DISP_SIZE", 1024,  768);
  OraFormsSetInt( "INITIAL_COLOR_DEPTH", 256);
  OraFormsSetString( "FONT_NAME" , "Dialog" );
  OraFormsSetPoint( "INITIAL_SCALE_INFO", 8,  18);
  OraFormsSetBoolean( "WINSYS_REQUIREDVA_LIST",  false);
  OraFormsConnect( "server module=Person3.fmx userid= useSDI=yes record=names");
  OraFormsSetWindow( "Logon");
  OraFormsLogon( "user",  "password",  "orcl_server");
  // ---
  // New window activated: WINDOW1
  OraFormsSetWindow( "WINDOW1");
  OraFormsMenuItem( "WINDOW1",  "Query::Execute Query");
  OraFormsVerifyPropByte( "1", ORA_PID_FONT_STYLE,  0, SEVERITY_WARNING);
  OraFormsMenuItem( "WINDOW1",  "Action::Exit");
end TMain;
Parent topic: Verifying Functions


OraFormsVerifyPropByteArray Function

Action

Verifies all elements in a byte array. The Oracle Forms type byte array is mainly used for transferring images from the server to the client.

Include file

OraForms.bdh

Syntax

OraFormsVerifyPropByteArray( in sName     : string,
                             in nPropId   : number,
                             in vArray    : array of byte,
                             in nLen      : number,
                             in nSeverity : number optional := SEVERITY_ERROR ) : boolean;

Return value

  • true is successful
  • false otherwise
Parameter | Description
sName | The control's unique name.
nPropId | The property ID.
vArray | The array to verify the parsed property value against.
nLen | Length of the array.
nSeverity Optional: Severity of the error that is raised if the verification fails. Can be one of the following values:
  • SEVERITY_SUCCESS: Success; no error (numerical value: 0)
  • SEVERITY_INFORMATIONAL: Informational; no error (numerical value: 1)
  • SEVERITY_WARNING: Warning; no error (numerical value: 2)
  • SEVERITY_ERROR: (Default) Error; simulation continues (numerical value: 3)
  • SEVERITY_TRANS_EXIT: Error; the active transaction is aborted (numerical value: 4)
  • SEVERITY_PROCESS_EXIT: Error; the simulation is aborted (numerical value: 5)
Parent topic: Verifying Functions


OraFormsVerifyPropInt Function

Action

Verifies an integer property for a specified control.

Include file

OraForms.bdh

Syntax

 OraFormsVerifyPropInt( in sName     : string,
                        in nPropId   : number,
                        in nVerify   : number,
                        in nSeverity : number optional := SEVERITY_ERROR ) : boolean;

Return value

  • true if successful
  • false otherwise
Parameter | Description
sName | The control's unique name.
nPropId | The property ID.
nVerify | The value to verify the parsed property against.
nSeverity Optional: Severity of the error that is raised if the verification fails. Can be one of the following values:
  • SEVERITY_SUCCESS: Success; no error (numerical value: 0)
  • SEVERITY_INFORMATIONAL: Informational; no error (numerical value: 1)
  • SEVERITY_WARNING: Warning; no error (numerical value: 2)
  • SEVERITY_ERROR: (Default) Error; simulation continues (numerical value: 3)
  • SEVERITY_TRANS_EXIT: Error; the active transaction is aborted (numerical value: 4)
  • SEVERITY_PROCESS_EXIT: Error; the simulation is aborted (numerical value: 5)

Example

transaction TMain
var
  sValue :  string;
begin
  OraFormsSetConnectMode(ORA_SOCKET_CONNECTION);
  // Connect - with connection properties
  OraFormsSetInt( "INITIAL_VERSION", 608);
  OraFormsSetPoint( "INITIAL_RESOLUTION", 96,  96);
  OraFormsSetPoint( "INITIAL_DISP_SIZE", 1024,  768);
  OraFormsSetInt( "INITIAL_COLOR_DEPTH", 256);
  OraFormsSetString( "FONT_NAME" , "Dialog" );
  OraFormsSetPoint( "INITIAL_SCALE_INFO", 8,  18);
  OraFormsSetBoolean( "WINSYS_REQUIREDVA_LIST",  false);
  OraFormsConnect( "server module=Person3.fmx userid= useSDI=yes record=names");
  OraFormsSetWindow( "Logon");
  OraFormsLogon( "user",  "password",  "orcl_server");
  // ---
  // New window activated: WINDOW1
  OraFormsSetWindow( "WINDOW1");
  OraFormsMenuItem( "WINDOW1",  "Query::Execute Query");

  OraFormsVerifyPropInt( "1", ORA_PID_FONT_SIZE,  900, SEVERITY_WARNING);
  OraFormsMenuItem( "WINDOW1",  "Action::Exit");
end TMain;
Parent topic: Verifying Functions


OraFormsVerifyPropNull Function

Action

Verifies if a property value is NULL.

Include file

OraForms.bdh

OraForms.bdh Syntax

OraFormsVerifyPropNull( in sName         : string,
                        in nPropId       : number,
                        in bShouldBeNull : boolean,
                        in nSeverity     : number optional := SEVERITY_ERROR ) : boolean;

Return value

  • true if successful
  • false otherwise
Parameter | Description
sName | The control's unique name.
nPropId | The property ID.
bShouldBeNull | Set to "true" when the property should be verified with NULL.
nSeverity Optional: Severity of the error that is raised if the verification fails. Can be one of the following values:
  • SEVERITY_SUCCESS: Success; no error (numerical value: 0)
  • SEVERITY_INFORMATIONAL: Informational; no error (numerical value: 1)
  • SEVERITY_WARNING: Warning; no error (numerical value: 2)
  • SEVERITY_ERROR: (Default) Error; simulation continues (numerical value: 3)
  • SEVERITY_TRANS_EXIT: Error; the active transaction is aborted (numerical value: 4)
  • SEVERITY_PROCESS_EXIT: Error; the simulation is aborted (numerical value: 5)

Example

transaction TMain
var
  sValue :  string;
begin
  OraFormsSetConnectMode(ORA_SOCKET_CONNECTION);
  // Connect - with connection properties
  OraFormsSetInt( "INITIAL_VERSION", 608);
  OraFormsSetPoint( "INITIAL_RESOLUTION", 96,  96);
  OraFormsSetPoint( "INITIAL_DISP_SIZE", 1024,  768);
  OraFormsSetInt( "INITIAL_COLOR_DEPTH", 256);
  OraFormsSetString( "FONT_NAME" , "Dialog" );
  OraFormsSetPoint( "INITIAL_SCALE_INFO", 8,  18);
  OraFormsSetBoolean( "WINSYS_REQUIREDVA_LIST",  false);
  OraFormsConnect( "server module=Person3.fmx userid= useSDI=yes record=names");
  OraFormsSetWindow( "Logon");
  OraFormsLogon( "user",  "password",  "orcl_server");
  // ---
  // New window activated: WINDOW1
  OraFormsSetWindow( "WINDOW1");
  OraFormsMenuItem( "WINDOW1",  "Query::Execute Query");
  OraFormsVerifyPropNull( "PERSON_SECONDNAME_0", ORA_PID_VALUE,  true, SEVERITY_WARNING);
  OraFormsMenuItem( "WINDOW1",  "Action::Exit");
end TMain;
Parent topic: Verifying Functions


OraFormsVerifyPropPoint Function

Action

Verifies a point property.

Include file

OraForms.bdh

Syntax

OraFormsVerifyPropPoint(  in sName     :  string,
                          in nPropId   :  number,
                          in nX        :  number,
                          in nY        :  number,
                          in nSeverity :  number optional := SEVERITY_ERROR ) : boolean;

Return value

  • true if successful
  • false otherwise
Parameter | Description
sName | The control's unique name.
nPropId | The property ID.
nX | x part of the point property.
nY | y part of the point property.
nSeverity Optional: Severity of the error that is raised if the verification fails. Can be one of the following values:
  • SEVERITY_SUCCESS: Success; no error (numerical value: 0)
  • SEVERITY_INFORMATIONAL: Informational; no error (numerical value: 1)
  • SEVERITY_WARNING: Warning; no error (numerical value: 2)
  • SEVERITY_ERROR: (Default) Error; simulation continues (numerical value: 3)
  • SEVERITY_TRANS_EXIT: Error; the active transaction is aborted (numerical value: 4)
  • SEVERITY_PROCESS_EXIT: Error; the simulation is aborted (numerical value: 5)

Example

transaction TMain
var
  sValue :  string;
begin
  OraFormsSetConnectMode(ORA_SOCKET_CONNECTION);
  // Connect - with connection properties
  OraFormsSetInt( "INITIAL_VERSION",  608);
  OraFormsSetPoint( "INITIAL_RESOLUTION",  96,  96);
  OraFormsSetPoint( "INITIAL_DISP_SIZE", 1024,  768);
  OraFormsSetInt( "INITIAL_COLOR_DEPTH", 256);
  OraFormsSetString( "FONT_NAME" , "Dialog" );
  OraFormsSetPoint( "INITIAL_SCALE_INFO", 8,  18);
  OraFormsSetBoolean( "WINSYS_REQUIREDVA_LIST",  false);
  OraFormsConnect( "server module=Person3.fmx userid= useSDI=yes record=names");
  OraFormsSetWindow( "Logon");
  OraFormsLogon( "user",  "password",  "orcl_server");
  // ---
  // New window activated: WINDOW1
  OraFormsSetWindow( "WINDOW1");
  OraFormsMenuItem( "WINDOW1",  "Query::Execute Query");
  OraFormsVerifyPropPoint( "WINDOW1", ORA_PID_OUTERSIZE,  720,  463, SEVERITY_WARNING);
  OraFormsMenuItem( "WINDOW1",  "Action::Exit");
end TMain;
Parent topic: Verifying Functions


OraFormsVerifyPropRectangle Function

Action

Verifies a rectangle property.

Include file

OraForms.bdh

Syntax

OraFormsVerifyPropRectangle( in sName     : string,
                             in nPropId   : number,
                             in nX0       : number,
                             in nY0       : number,
                             in nX1       : number,
                             in nY1       : number,
                             in nSeverity : number optional := SEVERITY_ERROR ) : boolean;

Return value

  • true if successful
  • false otherwise
Parameter | Description
sName | The control's unique name.
nPropId | The property ID.
nX0 | x part of the first coordinates.
nY0 | y part of the first coordinates.
nX1 | x part of the second coordinates.
nY1 | y part of the second coordinates.
nSeverity Optional: Severity of the error that is raised if the verification fails. Can be one of the following values:
  • SEVERITY_SUCCESS: Success; no error (numerical value: 0)
  • SEVERITY_INFORMATIONAL: Informational; no error (numerical value: 1)
  • SEVERITY_WARNING: Warning; no error (numerical value: 2)
  • SEVERITY_ERROR: (Default) Error; simulation continues (numerical value: 3)
  • SEVERITY_TRANS_EXIT: Error; the active transaction is aborted (numerical value: 4)
  • SEVERITY_PROCESS_EXIT: Error; the simulation is aborted (numerical value: 5)
Parent topic: Verifying Functions


OraFormsVerifyPropString Function

Action

Verifies the properties value.

Include file

OraForms.bdh

Syntax

OraFormsVerifyPropString( in sName     : string,
                          in nPropId   : number,
                          in sVerify   : string,
                          in nSeverity : number optional := SEVERITY_ERROR ) : boolean;

Return value

  • true if the verification succeeded
  • false otherwise
Parameter | Description
sName | The control's unique name.
nPropId | The property to be verified.
sVerify | String to verify the parsed property against.
nSeverity Optional: Severity of the error that is raised if the verification fails. Can be one of the following values:
  • SEVERITY_SUCCESS: Success; no error (numerical value: 0)
  • SEVERITY_INFORMATIONAL: Informational; no error (numerical value: 1)
  • SEVERITY_WARNING: Warning; no error (numerical value: 2)
  • SEVERITY_ERROR: (Default) Error; simulation continues (numerical value: 3)
  • SEVERITY_TRANS_EXIT: Error; the active transaction is aborted (numerical value: 4)
  • SEVERITY_PROCESS_EXIT: Error; the simulation is aborted (numerical value: 5)

Example

transaction TMain
var
  sValue :  string;
begin
  OraFormsSetConnectMode(ORA_SOCKET_CONNECTION);
  // Connect - with connection properties
  OraFormsSetInt( "INITIAL_VERSION", 608);
  OraFormsSetPoint( "INITIAL_RESOLUTION", 96,  96);
  OraFormsSetPoint( "INITIAL_DISP_SIZE", 1024,  768);
  OraFormsSetInt( "INITIAL_COLOR_DEPTH", 256);
  OraFormsSetString( "FONT_NAME" , "Dialog" );
  OraFormsSetPoint( "INITIAL_SCALE_INFO", 8,  18);
  OraFormsSetBoolean( "WINSYS_REQUIREDVA_LIST",  false);
  OraFormsConnect( "server module=Person3.fmx userid= useSDI=yes record=names");
  OraFormsSetWindow( "Logon");
  OraFormsLogon( "user",  "password",  "orcl_server");
  // ---
  // New window activated: WINDOW1
  OraFormsSetWindow( "WINDOW1");
  OraFormsMenuItem( "WINDOW1",  "Query::Execute Query");
  OraFormsVerifyPropString( "PERSON_SECONDNAME_0", ORA_PID_VALUE,  "Roydman", SEVERITY_WARNING);
  OraFormsMenuItem( "WINDOW1",  "Action::Exit");
end TMain;
Parent topic: Verifying Functions


OraFormsVerifyPropStringArray Function

Action

Verifies all strings in an array.

Include file

OraForms.bdh

Syntax

OraFormsVerifyPropStringArray( in sName     : string,
                               in nPropId   : number,
                               in vArray    : array of string,
                               in nLen      : number,
                               in nSeverity : number optional := SEVERITY_ERROR ) : boolean;

Return value

  • true if the verification was successful
  • false otherwise
Parameter | Description
sName | The control's unique name.
nPropId | The property ID.
vArray | An array of strings to be verified.
nLen | The length of the array.
nSeverity Optional: Severity of the error that is raised if the verification fails. Can be one of the following values:
  • SEVERITY_SUCCESS: Success; no error (numerical value: 0)
  • SEVERITY_INFORMATIONAL: Informational; no error (numerical value: 1)
  • SEVERITY_WARNING: Warning; no error (numerical value: 2)
  • SEVERITY_ERROR: (Default) Error; simulation continues (numerical value: 3)
  • SEVERITY_TRANS_EXIT: Error; the active transaction is aborted (numerical value: 4)
  • SEVERITY_PROCESS_EXIT: Error; the simulation is aborted (numerical value: 5)
Parent topic: Verifying Functions


OraFormsVerifyRadioValue Function

Action

Verifies the value of a radio button.

Include file

OraForms.bdh

Syntax

OraFormsVerifyRadioValue( in sName     : string,
                          in bVerify   : boolean,
                          in nOptions  : number optional,
                          in nSeverity : number optional := SEVERITY_ERROR ) : boolean;

Return value

  • true if successful
  • false otherwise
Parameter | Description
sName | The control's unique name.
bVerify | The value to verify the control's current value against.
nOptions

Can be one of these flags:

  • ORA_VERIFY_EQUAL (default)
  • ORA_VERIFY_NOT_EQUAL
nSeverity Optional: Severity of the error that is raised if the verification fails. Can be one of the following values:
  • SEVERITY_SUCCESS: Success; no error (numerical value: 0)
  • SEVERITY_INFORMATIONAL: Informational; no error (numerical value: 1)
  • SEVERITY_WARNING: Warning; no error (numerical value: 2)
  • SEVERITY_ERROR: (Default) Error; simulation continues (numerical value: 3)
  • SEVERITY_TRANS_EXIT: Error; the active transaction is aborted (numerical value: 4)
  • SEVERITY_PROCESS_EXIT: Error; the simulation is aborted (numerical value: 5)

Example

transaction TMain
var
  sValue :  string;
begin
  OraFormsSetConnectMode(ORA_SOCKET_CONNECTION);
  // Connect - with connection properties
  OraFormsSetInt( "INITIAL_VERSION", 608);
  OraFormsSetPoint( "INITIAL_RESOLUTION", 96,  96);
  OraFormsSetPoint( "INITIAL_DISP_SIZE", 1024,  768);
  OraFormsSetInt( "INITIAL_COLOR_DEPTH", 256);
  OraFormsSetString( "FONT_NAME" , "Dialog" );
  OraFormsSetPoint( "INITIAL_SCALE_INFO", 8,  18);
  OraFormsSetBoolean( "WINSYS_REQUIREDVA_LIST",  false);
  OraFormsConnect( "server module=Person3.fmx userid= useSDI=yes record=names");
  OraFormsSetWindow( "Logon");
  OraFormsLogon( "user",  "password",  "orcl_server");
  // ---
  // New window activated: WINDOW1
  OraFormsSetWindow( "WINDOW1");
  OraFormsMenuItem( "WINDOW1",  "Query::Execute Query");
  OraFormsRadioSet( "RADIO_1",  true);
  OraFormsVerifyRadioValue( "RADIO_1",  true, ORA_VERIFY_EQUAL, SEVERITY_WARNING);
  OraFormsMenuItem( "WINDOW1",  "Action::Exit");
end TMain;
Parent topic: Verifying Functions


OraFormsVerifySelectedTreeItem Function

Action

Verifies the selected tree node of a tree control with a provided value.

Include file

OraForms.bdh

Syntax

OraFormsVerifySelectedTreeItem( in sName     : string,
                                in sItem     : string,
                                in nOptions  : number optional,
                                in nSeverity : number optional := SEVERITY_ERROR ) : boolean;

Return value

  • true if successful
  • false otherwise
Parameter | Description
sName | The control's unique name.
sItem | The value to compare the selected value against.
nOptions Can be one of these flags:
  • ORA_VERIFY_EQUAL (default)
  • ORA_VERIFY_NOT_EQUAL
nSeverity Optional: Severity of the error that is raised if the verification fails. Can be one of the following values:
  • SEVERITY_SUCCESS: Success; no error (numerical value: 0)
  • SEVERITY_INFORMATIONAL: Informational; no error (numerical value: 1)
  • SEVERITY_WARNING: Warning; no error (numerical value: 2)
  • SEVERITY_ERROR: (Default) Error; simulation continues (numerical value: 3)
  • SEVERITY_TRANS_EXIT: Error; the active transaction is aborted (numerical value: 4)
  • SEVERITY_PROCESS_EXIT: Error; the simulation is aborted (numerical value: 5)

Example

transaction TMain
var
  sValue :  string;
begin
  OraFormsSetConnectMode(ORA_SOCKET_CONNECTION);
  // Connect - with connection properties
  OraFormsSetInt( "INITIAL_VERSION", 608);
  OraFormsSetPoint( "INITIAL_RESOLUTION", 96,  96);
  OraFormsSetPoint( "INITIAL_DISP_SIZE", 1024,  768);
  OraFormsSetInt( "INITIAL_COLOR_DEPTH", 256);
  OraFormsSetString( "FONT_NAME" , "Dialog" );
  OraFormsSetPoint( "INITIAL_SCALE_INFO", 8,  18);
  OraFormsSetBoolean( "WINSYS_REQUIREDVA_LIST",  false);
  OraFormsConnect( "server module=Person3.fmx userid= useSDI=yes record=names");
  OraFormsSetWindow( "Logon");
  OraFormsLogon( "user",  "password",  "orcl_server");
  // ---
  // New window activated: WINDOW1
  OraFormsSetWindow( "WINDOW1");
  OraFormsMenuItem( "WINDOW1",  "Query::Execute Query");
  OraFormsVerifySelectedTreeItem( "TREE_01",  "Node 1", ORA_VERIFY_EQUAL, SEVERITY_WARNING);
  OraFormsMenuItem( "WINDOW1",  "Action::Exit");
end TMain;
Parent topic: Verifying Functions


OraFormsVerifyTextValue Functions

Action

Verifies a text field or text area.

Include file

OraForms.bdh

Syntax

OraFormsVerifyTextValue( in sName     : string,
                         in sVerify   : string,
                         in nOptions  : number optional,
                         in nSeverity : number optional := SEVERITY_ERROR ) : boolean;

Return value

  • true if successful
  • false otherwise
Parameter | Description
sName | The control's unique name.
sVerify | The string to compare the control's value against.
nOptions Can be one of these flags or a combination
  • ORA_VERIFY_EQUAL (default)
  • ORA_VERIFY_NOT_EQUAL
  • ORA_VERIFY_CASE_SENSITIVE (default)
  • ORA_VERIFY_IGNORE_WHITESPACES
nSeverity Optional: Severity of the error that is raised if the verification fails. Can be one of the following values:
  • SEVERITY_SUCCESS: Success; no error (numerical value: 0)
  • SEVERITY_INFORMATIONAL: Informational; no error (numerical value: 1)
  • SEVERITY_WARNING: Warning; no error (numerical value: 2)
  • SEVERITY_ERROR: (Default) Error; simulation continues (numerical value: 3)
  • SEVERITY_TRANS_EXIT: Error; the active transaction is aborted (numerical value: 4)
  • SEVERITY_PROCESS_EXIT: Error; the simulation is aborted (numerical value: 5)

Example

transaction TMain
var
  sValue :  string;
begin
  OraFormsSetConnectMode(ORA_SOCKET_CONNECTION);
  // Connect - with connection properties
  OraFormsSetInt( "INITIAL_VERSION", 608);
  OraFormsSetPoint( "INITIAL_RESOLUTION", 96,  96);
  OraFormsSetPoint( "INITIAL_DISP_SIZE", 1024,  768);
  OraFormsSetInt( "INITIAL_COLOR_DEPTH", 256);
  OraFormsSetString( "FONT_NAME" , "Dialog" );
  OraFormsSetPoint( "INITIAL_SCALE_INFO", 8,  18);
  OraFormsSetBoolean( "WINSYS_REQUIREDVA_LIST",  false);
  OraFormsConnect( "server module=Person3.fmx userid= useSDI=yes record=names");
  OraFormsSetWindow( "Logon");
  OraFormsLogon( "user",  "password",  "orcl_server");
  // ---
  // New window activated: WINDOW1
  OraFormsSetWindow( "WINDOW1");
  OraFormsMenuItem( "WINDOW1",  "Query::Execute Query");
  OraFormsListSelect( "LISTBOX_01",  "An Option",  2);
  OraFormsVerifyTextValue( "TEXT_01",  "Sample", ORA_VERIFY_EQUAL | ORA_VERIFY_CASE_SENSITIVE, SEVERITY_WARNING);
  OraFormsMenuItem( "WINDOW1",  "Action::Exit");
end TMain;
Parent topic: Verifying Functions


Synchronization Functions

  • OraFormsWaitForTimer Function
    Synchronizes script execution with the expiration of a timer.
  • OraFormsWaitForWindow Function
    Synchronizes script execution by waiting for a window to appear.
Parent topic: Oracle Forms Functions Reference


OraFormsWaitForTimer Function

Action

OraFormsWaitForTimer synchronizes script execution with the expiration of a timer. The script waits within this function until the timer expires.

Include file

OraForms.bdh

Syntax

OraFormsWaitForTimer( in sName : string ) : boolean;

Return value

  • true if successful

  • false otherwise

Parameter | Description
sName | The timer’s unique name.

Example

dcltrans
  transaction TMain
  var
    sValue   : string;
  begin
    OraFormsSetConnectMode(ORA_SOCKET_CONNECTION);
    // Connect - with connection properties
    OraFormsSetInt("INITIAL_VERSION", 608);
    OraFormsSetPoint("INITIAL_RESOLUTION", 96, 96);
    OraFormsSetPoint("INITIAL_DISP_SIZE", 1024, 768);
    OraFormsSetInt("INITIAL_COLOR_DEPTH", 256);
    OraFormsSetString("FONT_NAME", "Dialog");
    OraFormsSetPoint("INITIAL_SCALE_INFO", 8, 18);
    OraFormsSetBoolean("WINSYS_REQUIREDVA_LIST", false);
    OraFormsConnect("server
    module=Person3.fmx userid= useSDI=yes record=names");
    OraFormsSetWindow("Logon");
    OraFormsLogon("user",
"password", "orcl_server");
    // ---
    // New window activated: WINDOW1
    OraFormsSetWindow("WINDOW1");
    OraFormsWaitForTimer("ADB Account");
  end TMain;

Parent topic: Synchronization Functions


OraFormsWaitForWindow Function

Action

OraFormsWaitForWindow synchronizes script execution by waiting for a window to appear. The script waits within this function until the window appears or until the wait function times out.

Include file

OraForms.bdh

Syntax

OraFormsWaitForWindow( in sName    : string;
                       in fTimeout : float optional ) : boolean;

Return value

  • true if successful

  • false otherwise

Parameter | Description
sName | The window’s unique name.
fTimeout | A timeout specifying how long to wait for the window. (optional) If the value is omitted, the default timeout value is used.

Example

dcltrans
  transaction TMain
  var
    sValue   : string;
  begin
    OraFormsSetConnectMode(ORA_SOCKET_CONNECTION);
    // Connect - with connection properties
    OraFormsSetInt("INITIAL_VERSION", 608);
    OraFormsSetPoint("INITIAL_RESOLUTION", 96, 96);
    OraFormsSetPoint("INITIAL_DISP_SIZE", 1024, 768);
    OraFormsSetInt("INITIAL_COLOR_DEPTH", 256);
    OraFormsSetString("FONT_NAME", "Dialog");
    OraFormsSetPoint("INITIAL_SCALE_INFO", 8, 18);
    OraFormsSetBoolean("WINSYS_REQUIREDVA_LIST", false);
    OraFormsConnect("server module=Person3.fmx userid= useSDI=yes record=names");
    OraFormsSetWindow("Logon");
    OraFormsLogon("user", "password", "orcl_server");
    // ---
    // New window activated: WINDOW1
    OraFormsSetWindow("WINDOW1");
    OraFormsWaitForWindow("ADB Account");
  end TMain;
Parent topic: Synchronization Functions


TUXEDO Functions Reference

A number of functions are provided to handle TUXEDO function calls from within Silk Performer. While most of them are identical to the original TUXEDO ATMI functions, some additional functions serve to handle several buffer types within BDL.

  • Native TUXEDO ATMI Functions
    The following Silk Performer functions are identical to the TUXEDO ATMI functions of the same name without the Tux_ prefix.
  • Native TUXEDO FML Functions
    The following Silk Performer functions are identical to the TUXEDO FML functions of the same name without the Tux_ prefix.
  • TuxAuthInit Function
    Manages joining a TUXEDO System application.
  • TUXEDO Data Structures Overview
    Provides an overview of TUXEDO data structures that are supported by Silk Performer.
  • Buffer Handling Functions
    Lists BDL functions for initializing, allocating, and writing typed buffers.
  • Buffer Manipulating Functions
    Lists BDL functions for manipulating predefined buffer types.
Parent topic: Application Server Functions


Native TUXEDO ATMI Functions

The following Silk Performer functions are identical to the TUXEDO ATMI functions of the same name without the Tux_ prefix.

Include file

TUXEDO.bdh

Function | Description
Tux_gettperrno | Retrieves the error code when a TUXEDO System function call returns a failure value.
Tux_tpstrerror | Retrieves the text of an error message when a TUXEDO System function call returns a failure value.
Tux_gettpurcode | Retrieves the user return code after a TUXEDO System function call.
Tux_tpbegin | Defines the begin of a transaction. In the TUXEDO System, a transaction is used to define a single logical unit of work.
Tux_tpcancel | Cancels a call descriptor returned by the Tux_tpacall function.
Tux_tpscmt | Sets the characteristic which affects the way the Tux_tpcommit function behaves with respect to returning control to its caller.
Tux_tpabort | Signifies the abnormal end of a transaction. When this function call returns, all changes made to resources during the transaction are undone.
Tux_tpcommit | Signifies the end of a transaction, using a two-phase commit protocol to coordinate participants. This function can be called only by the initiator of a transaction.
Tux_tpgetrply | Returns a reply from a previously sent request. By default, this function waits until the reply matching call descriptor arrives or a timeout occurs.
Tux_tpsuspend | Suspends the transaction active in the caller's process. A transaction begun with the Tux_tpbegin function may be suspended with the Tux_tpsuspend function.
Tux_tpresume | Resumes work on behalf of a previously suspended transaction. Once the caller resumes work on a transaction, it must either suspend it or complete it at a later time.
Tux_tpgetlev | Returns to the caller the current transaction level.
Tux_tx_begin | Places the calling thread of control in transaction mode. The calling thread must first ensure that its linked resource managers have been opened before it can start transactions
Tux_tx_close | Closes a set of resource managers in a portable manner. It invokes a transaction manager to read resource-manager-specific information in a transaction-manager-specific manner and pass this information to the resource managers linked to the caller.
Tux_tx_commit | Commits the work of the transaction active in the caller's thread of control.
Tux_tx_info | Returns global transaction information. In addition, this function returns a value indicating whether the caller is currently in transaction mode.
Tux_tx_open | Opens a set of resource managers in a portable manner. It invokes a transaction manager to read resource-manager-specific information in a transaction-manager-specific manner and pass this information to the resource managers linked to the caller.
Tux_tx_rollback | Rolls back the work of the transaction active in the caller's thread of control.
Tux_tx_set_commit_return | Sets the characteristic which affects the way the Tux_tx_commit function behaves with respect to returning control to its caller.
Tux_tx_set_transaction_control | Sets the characteristic which determines whether the Tux_tx_commit and the Tux_tx_rollback function start a new transaction before returning to their caller.
Tux_tx_set_transaction_timeout | Sets the characteristic which specifies the time period in which the transaction must complete before becoming susceptible to transaction timeout.
Tux_tpcall | Sends a request and synchronously awaits its reply. A call to this function is the same as calling the Tux_tpacall function immediately followed by the Tux_tpgetrply function.
Tux_tpacall | Sends a request message to a specified service. The request is sent out at the priority defined unless overridden by a previous call to the Tux_tpsprio function.
Tux_tpalloc | Returns a pointer to a buffer of a specified type. The TUXEDO System provides a variety of typed buffers, and applications are free to add their own buffer types.
Tux_tprealloc | Changes the size of a buffer to a specified number of bytes and returns a pointer to the new buffer.
Tux_tpfree | Releases a buffer previously obtained by either the Tux_tpalloc function or the Tux_tprealloc function.
Tux_tpinit | Allows a client to join a TUXEDO System application. Before a client can use any of the TUXEDO System communication or transaction routines, it must first join a TUXEDO System application.
Tux_tpterm | Removes a client from a TUXEDO System application. If the client is in transaction mode, then the transaction is rolled back.
Tux_tpconnect | Allows a program to set up a half-duplex connection to a conversational service. The name must be one of the conversational service names posted by a conversational server.
Tux_tpdiscon | Tears down a specified connection immediately.
Tux_tpsend | Sends data across an open connection to another program. The caller must have control of the connection.
Tux_tprecv | Receives data sent across an open connection from another program.
Tux_tpenqueue | Stores a message on a specified queue in a queue space. A queue space is a collection of queues, one of which must be the specified queue.
Tux_tpdequeue | Dequeues a message for processing from a specified queue in a queue space.
Tux_tpnotify | Allows a client or server to send an unsolicited message to an individual client
Tux_tpbroadcast | Allows a client or server to send unsolicited messages to registered clients within the system.
Tux_tpsubscribe | Subscribes the caller to a specified event or a set of events. Subscriptions are maintained by the TUXEDO System Event Broker, and are used to notify subscribers when events are posted.
Tux_tpunsubscribe | Removes an event subscription or a set of event subscriptions from the TUXEDO System Event Broker's list of active subscriptions.
Tux_tpchkauth | Checks if authentication is required by the application configuration.
Tux_tpsprio | Sets the priority for the next request sent or forwarded. The priority set affects only the next request sent.
Tux_tpgprio | Returns the priority for the last request sent or received.
Tux_tpconvert | Converts the string representation of interface structures to or from the binary representation.
Tux_tptypes | Returns the type and subtype of a specified buffer.
Tux_tuxgetenv | Searches the environment list for a specified string and, if the string is present, returns a pointer to the value in the current environment.
Tux_tuxputenv | Sets the value of a specified environment variable by altering an existing variable or creating a new one.
Tux_tuxreadenv | Reads a file containing environment variables and adds them to the environment, independent of platform.

Refer to the TUXEDO Reference Manual for detailed information, including syntax, parameter and return value descriptions for each function.

Parent topic: TUXEDO Functions Reference


Native TUXEDO FML Functions

The following Silk Performer functions are identical to the TUXEDO FML functions of the same name without the Tux_ prefix.

Include file

FML.bdh

Function | Description
Tux_GetFerror | Produces a message on the standard error output, describing the last error encountered during a call to a system or library function.
Tux_Fldid | Provides a run-time translation of a field-name to its field identifier and returns a field identifier corresponding to its field name parameter.
Tux_Fname | Provides a run-time translation of a field identifier to its field name and returns a pointer to a character string containing the name corresponding to its argument.
Tux_Ftype | Returns a pointer to a string containing the name of the type of a field.
Tux_Fldtype | Returns the field type contained in a field identifier.
Tux_Fldno | Returns the field number contained in a field identifier.
Tux_Flen | Finds the value of a specified field occurrence in a buffer and returns its length.
Tux_Fielded | Tests whether a specified buffer is fielded.
Tux_Fneeded | Determines the space that must be allocated for a number of fields and bytes of value space.
Tux_Finit | Initializes a fielded buffer statically.
Tux_Falloc | Dynamically allocates space for a fielded buffer and calls the Tux_Finitfunction to initialize it.
Tux_Ffree | Recovers space allocated to a fielded buffer.
Tux_Fsizeof | Returns the size of a fielded buffer in bytes.
Tux_Fused | Returns the amount of used space in a fielded buffer in bytes, including both user data and the header.
Tux_Funused | Returns the amount of space currently unused in a buffer. Space is unused if it contains neither user data nor overhead data such as the header and index.
Tux_Frealloc | Re-allocates space to enlarge a fielded buffer.
Tux_Fmove | Copies data from a fielded buffer to any type of buffer.
Tux_Fcpy | Copies the contents of one fielded buffer to another fielded buffer.
Tux_Fadd | Adds a specified field value to the given buffer.
Tux_Fadds | Handles the case of conversion from a user string field type to a specified field type and add it to the fielded buffer.
Tux_Fappend | Adds a specified field value to the end of the given buffer.
Tux_Fchg | Changes the value of a field in a buffer.
Tux_Fchgs | Handles the case of conversion from a user string field type.
Tux_Fcmp | Compares the field identifiers and then the field values of two FML buffers.
Tux_Fdelall | Deletes all occurrences of the specified field in the buffer.
Tux_Fdelete | Deletes all occurrences of all fields listed in an array of field identifiers.
Tux_Fdel | Deletes a specified field occurrence from a buffer.
Tux_Ffindlast | Finds the last occurrence of a field in a buffer.
Tux_Ffind | Finds the value of a specified field occurrence in a buffer.
Tux_Ffindocc | Looks at occurrences of a specified field in a buffer and returns the occurrence number of the first field occurrence that matches the user specified field value.
Tux_Fget | Retrieves a field from a fielded buffer when the value is to be modified.
Tux_Fgets | Retrieves a field occurrence from the fielded buffer first converting the value to a user string field type.
Tux_Fgetsa | Gets a specified field from a buffer, allocates space, converts the field to the type specified by the user and returns a pointer to its location.
Tux_Fgetalloc | Acquires space for a field, then finds and makes a copy of a buffer field.
Tux_Fgetlast | Retrieves both the value and occurrence number of the last occurrence of a field.
Tux_Fnext | Finds the next field in a buffer after a specified field occurrence.
Tux_Fnum | Returns the number of fields contained in a specified buffer.
Tux_Foccur | Determines the number of occurrences of a field.
Tux_Fpres | Detects if a given occurrence of a specified field exists in a buffer.
Tux_Fvall | Works like the Tux_Ffind function for long and short values, but returns the actual value of the field as a long rather than a pointer to the value.
Tux_Fvals | Works like the Tux_Ffind function for string values but guarantees that a value is returned.
Tux_Fconcat | Adds fields from a source buffer to the fields that already exist in a destination buffer.
Tux_Fjoin | Joins two fielded buffers based on matching field id/occurrence.
Tux_Fojoin | Works like the Tux_Fjoin function, but it keeps fields from the destination buffer that have no corresponding field id/occurrence in the source buffer.
Tux_Fproj | Updates a buffer so as to keep only the desired fields.
Tux_Fprojcpy | Works like the Tux_Fproj function, but the projection is done into a destination buffer instead of in-place.
Tux_Fupdate | Updates a destination buffer with the field values in a source buffer.
Tux_Fvftos | Transfers data from a fielded buffer to a common data structure.
Tux_Fvstof | Transfers data from a common data structure to a fielded buffer.
Tux_Fvsinit | Initializes all members in a common data structure to the NULL values specified in a view description.
Tux_Fvopt | Allows users to specify buffer-to-structure mapping options at run time.
Tux_Fvnull | Determines if an occurrence of a structure element is null.
Tux_Fvselinit | Initializes an individual element of a common data structure to its appropriate NULL value.
Tux_Fvrefresh | Clears and re-initializes the internal cache of view structure mappings.
Tux_CFadd | Acts like the Tux_Fadd function, but first converts the value from the user-specified type to the type for which a field is added to the fielded buffer.
Tux_CFchg | Acts like the Tux_Fchg function, but first converts the value from the user-specified type to the type for which the field is changed in the fielded buffer.
Tux_CFfind | Finds a specified field in a buffer, converts it and returns a pointer to the converted value.
Tux_CFindocc | Acts like the Tux_Ffindocc function, but first converts the value from the user-specified type to a specified type.
Tux_CFget | Works like the Tux_Fget function. The main difference is that it copies a converted value to a user supplied buffer.
Tux_CFgetalloc | Gets a specified field from a buffer, allocates space, converts the field to the type specified by the user and returns a pointer to its location.
Tux_Ftypcvt | Converts a value from one field type to another.
Tux_Fstrerror | Retrieves the text of an error message.
Tux_Fidxused | Indicates the current amount of space used by a buffer's index.
Tux_Funindex | Discards a fielded buffer's index.
Tux_Findex | Serves to index a fielded buffer.
Tux_Frstrindex | Serves to re-index an unindexed buffer.
Tux_Fboolev | Checks whether a fielded buffer matches a number of specified conditions.
Tux_Fvboolev | Checks whether a fielded buffer matches a number of specified conditions.
Tux_Ffloatev | Returns the value of a specified arithmetic expression, represented by a tree.
Tux_Fboolco | Compiles a Boolean expression and returns a pointer to the evaluation tree.
Tux_Fvboolco | Compiles a Boolean expression and returns a pointer to the evaluation tree.
Tux_Fnmid_unload | Unloads the files used by the field tables loaded by the Tux_Fldid function.
Tux_Fidnm_unload | Recovers space allocated by the Tux_Fname function for field identifier to field name mapping tables.
Tux_Fchksum | Calculates a checksum for extra-reliable I/O and stores it in a fielded buffer.

Refer to the TUXEDO Reference Manual for detailed information, including syntax, parameter and return value descriptions for each function.

Parent topic: TUXEDO Functions Reference


TuxAuthInit Function

Action

Manages joining a TUXEDO System application. Before a client is able to use any of the TUXEDO System communication or transaction routines, it must first join a TUXEDO System application. This function joins the client to a TUXEDO System application. In addition, this function is used to provide application authentication (if required). After this function successfully completes, the client can initiate service requests and define transactions.

To join a TUXEDO System application, use this function rather than the native Tux_tpinit function.

Include file

TUXEDO.bdh

Syntax

TuxAuthInit( in sUserName   : string optional,
             in sClientName : string optional,
             in sPassword   : string optional,
             in sGroupName  : string optional,
             in nFlags      : number optional,
             in nDataSize   : number optional,
             in sData       : string optional ): boolean;

Return value

  • true if successful

  • false otherwise

Parameter | Description
sUserName | User name (optional). This parameter represents the name of the caller commonly entered in logon dialogs
sClientName | Client name (optional). The semantics of this parameter are application-specific
sPassword | Application password in unencrypted format (optional). This parameter is used for validation against the application password
sGroupName | Group name (optional). This parameter is used to associate the client with a resource manager group name
nFlags

Indicates the client-specific notification mechanism (optional). Any of the following flags is valid:

  • TPU_MASK. Unsolicited notification

  • TPU_SIG. Select unsolicited notification by signals

  • TPU_DIP. Select unsolicited notification by dip-in

  • TPU_IGN. Ignore unsolicited notification
nDataSize | Size of the application-specific data passed to the function (optional)
sData | Application-specific data that is forwarded to an application-defined authentication service (optional)

Example

dcltrans
  transaction TInit
  begin
    // set environment variables
    Tux_tuxputenv("TUXDIR=c:\\tuxedo");
    Tux_tuxputenv("WSNADDR=//server3:3000");
    // join TUXEDO System application    TuxAuthInit("user", "*", "pass", "", 2, 4, "pass");
    Tux_tuxputenv("FLDTBLDIR=C:\\TUXEDO\\apps\\bankapp");
  end TInit;

Sample scripts

bankappn.bdf

Parent topic: TUXEDO Functions Reference


TUXEDO Data Structures Overview

Silk Performer supports the following data structures, each of which has to be defined as a string of the corresponding length and is accessed through a number of type-dependent Set and Get functions:

  • Queue control data structure

  • Event control data structure

  • TPINFO data structure

  • TXINFO data structure

Example

dcltrans
  transaction TInit
  const
    USERNAME   := "user";    // client user name
    CLIENTNAME := "*";       // application client name
    PASSWORD   := "pass";    // application password
    GROUPNAME  := "group";   // client group name
  var
    tpinfo: string(TPINFO_SIZE);
  begin
    // set TPINFO data structure elements
    SetString(tpinfo, TPINFO_USRNAME, USERNAME, Strlen(USERNAME));
    SetString(tpinfo, TPINFO_CLTNAME, CLIENTNAME, Strlen(CLIENTNAME));
    SetString(tpinfo, TPINFO_PASSWD, PASSWORD, Strlen(PASSWORD));
    SetString(tpinfo, TPINFO_GRPNAME, GROUPNAME, Strlen(GROUPNAME));
    SetLong(tpinfo, TPINFO_FLAGS, TPNOFLAGS);
    SetLong(tpinfo, TPINFO_DATALEN, 0);

    // join TUXEDO System application
    Tux_tpinit(tpinfo);
  end TInit;
  • Queue Control Data Structure
  • Event Control Data Structure
  • TPINFO Data Structure
  • TXINFO Data Structure
Parent topic: TUXEDO Functions Reference


Queue Control Data Structure

Declaration

vartpqctl: string(TPQCTL_SIZE);
Offset | Type | Description
TPQCTL_FLAGS | number | Indicates which of the values are set.
TPQCTL_DEQ_TIME | number | Absolute/relative time for dequeuing.
TPQCTL_PRIORITY | number | Enqueue priority.
TPQCTL_DIAGNOSTIC | number | Indicates reason for failure.
TPQCTL_MSGID | string(32) | Id of message before which to queue.
TPQCTL_CORRID | string(32) | Correlation id used to identify message.
TPQCTL_REPLYQUEUE | string(16) | Queue name for reply message.
TPQCTL_FAILUREQUEUE | string(16) | Queue name for failure message.
TPQCTL_CLTID1 | number | Client identifier for originating client.
TPQCTL_CLTID2 | number |
TPQCTL_CLTID3 | number |
TPQCTL_CLTID4 | number |
TPQCTL_URCODE | number | Application user-return code.
TPQCTL_APPKEY | number | Application authentication client key.
Parent topic: TUXEDO Data Structures Overview
Related reference
Event Control Data Structure
TPINFO Data Structure
TXINFO Data Structure


Event Control Data Structure

Declaration

varevctl: string(TPEVCTL_SIZE);
Offset | Type | Description
TPEVCTL_FLAGS | number | Indicates which of the values are set.
TPEVCTL_NAME1 | string(32) |
TPEVCTL_NAME2 | string(32) |
TPEVCTL_QCTL | TPQCTL | Queue control data structure.
Parent topic: TUXEDO Data Structures Overview
Related reference
Queue Control Data Structure
TPINFO Data Structure
TXINFO Data Structure


TPINFO Data Structure

Declaration

var
tpinfo: string(TPINFO_SIZE);
Offset | Type | Description
TPINFO_USRNAME | string(32) | Client user name.
TPINFO_CLTNAME | string(32) | Application client name.
TPINFO_PASSWD | string(32) | Application password.
TPINFO_GRPNAME | string(32) | Client group name.
TPINFO_FLAGS | number | Initialization flags.
TPINFO_DATALEN | number | Length of application-specific data.
TPINFO_DATA | string | Application-specific data.
Parent topic: TUXEDO Data Structures Overview
Related reference
Event Control Data Structure
Queue Control Data Structure
TXINFO Data Structure


TXINFO Data Structure

Declaration

var
txinfo: string(TXINFO_SIZE);
Offset | Type
TXINFO_XID_FORMATID | number
TXINFO_XID_GTRID_LENGTH | number
TXINFO_XID_BQUAL_LENGTH | number
TXINFO_XID_DATA | string(128)
TXINFO_COMMIT_RETURN | number
TXINFO_TRANSACTION_CONTROL | number
TXINFO_TRANSACTION_TIMEOUT | number
TXINFO_TRANSACTION_STATE | number
Parent topic: TUXEDO Data Structures Overview
Related reference
Event Control Data Structure
Queue Control Data Structure
TPINFO Data Structure


Buffer Handling Functions

  • TuxGetBuffer Function
    Allocates a typed buffer. Depending on the buffer type, a subtype has to be specified.
  • TuxInitBuffer Function
  • TuxWriteBuffer Function
    Writes the content of a typed buffer to the output file.
Parent topic: TUXEDO Functions Reference


TuxGetBuffer Function

Action

Allocates a typed buffer. Depending on the buffer type, a subtype has to be specified. The TUXEDO System provides a variety of typed buffers, and applications are free to add their own buffer types. Silk Performer's buffer handling and manipulating functions automatically detect any of the buffer types listed below and handles them appropriately. Custom buffer types are handled like binary buffers (CARRAY).

STRING, FML, FML32, VIEW, VIEW32, CARRAY

Include file

TUXEDO.bdh

Syntax

TuxGetBuffer( inout hBuffer  : number,
              in    sType    : string,
              in    sSubType : string optional,
              in    nSize    : number optional): boolean;

Return value

  • true if successful

  • false otherwise

Parameter | Description
hBuffer | Variable receiving the handle to the typed buffer
sType

Buffer type. Predefined typed buffers are:

  • "STRING". String buffer.

  • "FML". Fielded buffer. Buffer containing any number of arrays of various data types.

  • "FML32". 32-bit fielded buffer.

  • "VIEW". View. Buffer containing any number of fields, each of which may hold a different data type.

  • "CARRAY". Binary data buffer.
sSubType | Buffer subtype identifying a set of characteristics (optional).
nSize

Buffer size (optional). Default buffer size is 1024 bytes for fielded buffers, and 512 bytes for any other buffer types.

Note: The default buffer size values also represent the minimum size, allocating smaller buffers is impossible.

Example

const
  ID_ELEM1 := 16;
  ID_ELEM2 := 32;

dcltrans
  transaction TMain
  var
    hBuffer, olen: number;
  begin
    Tux_tpbegin(30, 0);

    // allocate buffer
    TuxGetBuffer(hBuffer, "FML", NULL, 1024);

    // store two integer values in buffer
    TuxSetInt(hBuffer, ID_ELEM1, 640);
    TuxSetInt(hBuffer, ID_ELEM2, 480);

    // create database table of the appropriate size
    Tux_tpcall("CREATETABLE", hBuffer, 0, hBuffer, olen, TPNOFLAGS);
    Tux_tpcommit(0);
  end TMain;

Sample scripts

bankappn.bdf

Parent topic: Buffer Handling Functions
Related reference
TuxInitBuffer Function
TuxWriteBuffer Function
TuxSetString Function
TuxSetInt Function
TuxSetFloat Function
TuxSetCArray Function
TuxGetCArray Function
TuxGetFloat Function
TuxGetInt Function
TuxGetString Function


TuxInitBuffer Function

Action

Initializes an allocated typed buffer. This function can be used to clear the content of any allocated typed buffer.

Include file

TUXEDO.bdh

Syntax

TuxInitBuffer(in hBuffer: number): boolean;

Return value

  • true if successful.

  • false otherwise.

Parameter | Description
hBuffer | Typed buffer to initialize.

Example

dcltrans
  transaction TMain
  var
    hBuffer: number;
  begin
    // allocate buffer
    TuxGetBuffer(hBuffer, "FML", NULL, 1024);

    // store dummy values in buffer
    TuxSetInt(hBuffer, 16, 832);
    TuxSetInt(hBuffer, 32, 173);

    // clear buffer for later reuse
    TuxInitBuffer(hBuffer);
  end TMain;
Parent topic: Buffer Handling Functions
Related reference
TuxGetBuffer Function
TuxWriteBuffer Function


TuxWriteBuffer Function

Action

Writes the content of a typed buffer to the output file.

Include file

TUXEDO.bdh

Syntax

TuxWriteBuffer(in hBuffer : number,
               in sText   : string optional): boolean;

Return value

  • true if successful.

  • false otherwise.

Parameter | Description
hBuffer | Typed buffer that will be written to the output file.
sText | Additional text written to the output file (optional)

Example

dcltrans
  transaction TMain
  var
    hBuffer: number;
  begin
    // allocate buffer
    TuxGetBuffer(hBuffer,"FML", NULL, 1024);

    // store dummy values in fielded buffer
    TuxSetInt(hBuffer, 16, 832);
    TuxSetInt(hBuffer, 32, 173);

    // write buffer to output file
    TuxWriteBuffer(hBuffer, "buffer content");
  end TMain;
Parent topic: Buffer Handling Functions
Related reference
TuxGetBuffer Function
TuxInitBuffer Function


Buffer Manipulating Functions

  • TuxFML2View Function
    Copies the content of a fielded buffer (FML, FML32) to a view buffer.
  • TuxView2FML Function
    Copies to content of a view buffer to a fielded buffer (FML, FML32).
  • TuxSetFloat Function
    Sets the value of a specified floating-point field within a typed buffer.
  • TuxGetFloat Function
    Retrieves the value of a specified floating-point field within a typed buffer.
  • TuxSetString Function
    Sets the content of a specified string field within a typed buffer.
  • TuxGetString Function
    Retrieves the content of a specified string field within a typed buffer.
  • TuxSetCArray Function
    Sets the content of a specified binary data field within a typed buffer.
  • TuxGetCArray Function
    Retrieves the content of a specified binary data field within a typed buffer.
  • TuxSetInt Function
    Sets the value of a specified integer field within a typed buffer.
  • TuxGetInt Function
    Retrieves the value of a specified integer field within a typed buffer.
Parent topic: TUXEDO Functions Reference


TuxFML2View Function

Action

Copies the content of a fielded buffer (FML, FML32) to a view buffer.

Include file

TUXEDO.bdh

Syntax

TuxFML2View( in hFML  : number,
             in hView : number ): boolean;

Return value

  • true if successful

  • false otherwise

Parameter | Description
hFML | Fielded buffer containing the data
hView | View buffer receiving the data

Example

const
  ID_ELEM1 := 16;
  ID_ELEM2 := 32;

dcltrans
  transaction TMain
  var
    hFML, hView: number;
  begin

    // allocate buffers
    TuxGetBuffer(hFML, "FML", NULL, 1024);
    TuxGetBuffer(hView, "VIEW", "MyView", 1024);

    // store dummy values in fielded buffer
    TuxSetInt(hFML, ID_ELEM1, 832);
    TuxSetInt(hFML, ID_ELEM2, 173);

    // convert fielded buffer to view buffer
    TuxFML2View(hFML, hView);
  end TMain;
Parent topic: Buffer Manipulating Functions
Related reference
TuxView2FML Function


TuxView2FML Function

Action

Copies to content of a view buffer to a fielded buffer (FML, FML32).

Include file

TUXEDO.bdh

Syntax

TuxView2FML(in hFML  : number,
            in hView : number): boolean;

Return value

  • true if successful.

  • false otherwise.

Parameter | Description
hFML | Fielded buffer receiving the data
hView | View buffer containing the data

Example

const
  ID_ELEM1 := 16;
  ID_ELEM2 := 32;

dcltrans
    transaction TMain
  var
    hFML, hView: number;
  begin
    // allocate buffer
    TuxGetBuffer(hFML, "FML", NULL, 1024);
    TuxGetBuffer(hView, "VIEW", "MyView", 1024);

    // store dummy values in view buffer
    TuxSetInt(hView, ID_ELEM1, 832);
    TuxSetInt(hView, ID_ELEM2, 173);

    // convert view buffer to fielded buffer
    TuxView2FML(hFML, hView);
  end TMain;
Parent topic: Buffer Manipulating Functions
Related reference
TuxFML2View Function


TuxSetFloat Function

Action

Sets the value of a specified floating-point field within a typed buffer. This function can be used to manipulate any of the following predefined buffer types:

FML, FML32

Include file

TUXEDO.bdh

Syntax

TuxSetFloat(in hBuffer  : number,
            in nFieldId : number,
            in fValue   : float,
            in nIndex   : number optional): boolean;

Return value

  • true if successful

  • false otherwise

Parameter | Description
hBuffer | Typed buffer allocated with TuxGetBuffer or Tux_tpalloc.
nFieldId | Identifier specifying a field of the typed buffer.
fValue | Floating-point value to copy to the typed buffer.
nIndex | Array index (optional). This parameter has to be passed to the function if the field identifier specifies an array.

Example

const
  ID_NUMBERS :=  8;
  ID_PRODUCT := 16;

dcltrans
  transaction TMain
  var
  hBuffer, olen : number;
  fResult       : float;

  begin
  Tux_tpbegin(30, 0);

    // allocate buffer
    TuxGetBuffer(hBuffer, "FML", NULL, 1024);

    // store two floating-point values in buffer
    TuxSetFloat(hBuffer, ID_NUMBERS, 807.33, 1);
    TuxSetFloat(hBuffer, ID_NUMBERS, 23.09, 2);

    // multiply floating-point values
    Tux_tpcall("MULTIPLY", hBuffer, 0, hBuffer, olen, TPNOFLAGS);

    // retrieve product
    fResult := TuxGetFloat(hBuffer, ID_PRODUCT);
    Tux_tpcommit(0);
  end TMain;
Parent topic: Buffer Manipulating Functions
Related reference
TuxSetString Function
TuxSetInt Function
TuxSetCArray Function
TuxGetBuffer Function
TuxGetFloat Function


TuxGetFloat Function

Action

Retrieves the value of a specified floating-point field within a typed buffer. This function can be used to manipulate any of the following predefined buffer types:

FML, FML32

Include file

TUXEDO.bdh

Syntax

TuxGetFloat(in hBuffer  : number,
            in nFieldId : number,
            in nIndex   : number optional): float;

Return value

Floating-point value retrieved from the typed buffer.

Parameter | Description
hBuffer | Typed buffer allocated with TuxGetBuffer or Tux_tpalloc.
nFieldId | Identifier specifying a field of the typed buffer
nIndex | Array index (optional). This parameter has to be passed to the function if the field identifier specifies an array.

Example

const
  ID_NUMBERS :=  8;
  ID_PRODUCT := 16;

dcltrans
  transaction TMain
  var
    hBuffer, olen : number;
    fResult       : float;
  begin
    Tux_tpbegin(30, 0);

    // allocate buffer
    TuxGetBuffer(hBuffer, "FML", NULL, 1024);

    // store two floating-point values in buffer
    TuxSetFloat(hBuffer, ID_NUMBERS, 807.33, 1);
    TuxSetFloat(hBuffer, ID_NUMBERS, 23.09, 2);

    // multiply floating-point values
    Tux_tpcall("MULTIPLY", hBuffer, 0, hBuffer, olen, TPNOFLAGS);

    // retrieve product
    fResult := TuxGetFloat(hBuffer, ID_PRODUCT);
    Tux_tpcommit(0);
  end TMain;

Sample scripts

bankappn.bdf

Parent topic: Buffer Manipulating Functions
Related reference
TuxGetCArray Function
TuxGetInt Function
TuxGetString Function
TuxGetBuffer Function
TuxSetFloat Function


TuxSetString Function

Action

Sets the content of a specified string field within a typed buffer. This function can be used to manipulate any of the following predefined buffer types:

FML, FML32, STRING

Include file

TUXEDO.bdh

Syntax

TuxSetString(in hBuffer  : number,
             in nFieldId : number,
             in sString  : string,
             in nIndex   : number optional): boolean;

Return value

  • true if successful.

  • false otherwise.

Parameter | Description
hBuffer | Typed buffer allocated with TuxGetBuffer or Tux_tpalloc.
nFieldId | Identifier specifying a field of the typed buffer.
sString | String to copy to the typed buffer.
nIndex | Array index (optional). This parameter has to be passed to the function if the field identifier specifies a string array.

Example

const
  ID_STRINGS      :=  8;
  ID_CONCATENATED := 16;

dcltrans
  transaction TMain
  var
    hBuffer, olen : number;
    sString       : string;

  begin
    Tux_tpbegin(30, 0);

    // allocate buffer
    TuxGetBuffer(hBuffer, "FML", NULL, 1024);

    // store two strings in buffer
    TuxSetString(hBuffer, ID_STRINGS, "Hello", 1);
    TuxSetString(hBuffer, ID_STRINGS, " world!", 2);

    // concatenate strings
    Tux_tpcall("CONCAT", hBuffer, 0, hBuffer, olen, TPNOFLAGS);

    // retrieve concatenated string
    TuxGetString(hBuffer, ID_CONCATENATED, sString, sizeof(sString));
    Tux_tpcommit(0);
  end TMain;

Sample scripts

bankappn.bdf

Parent topic: Buffer Manipulating Functions
Related reference
TuxSetInt Function
TuxSetFloat Function
TuxSetCArray Function
TuxGetBuffer Function
TuxGetString Function


TuxGetString Function

Action

Retrieves the content of a specified string field within a typed buffer. This function can be used to manipulate any of the following predefined buffer types:

FML, FML32, STRING

Include file

TUXEDO.bdh

Syntax

TuxGetString( in  hBuffer     : number,
              in  nFieldId    : number,
              out sString     : string,
              in  nStringSize : number optional,
              in  nIndex      : number optional ): boolean;

Return value

  • true if successful.

  • false otherwise.

Parameter | Description
hBuffer | Typed buffer allocated with TuxGetBuffer or Tux_tpalloc
nFieldId | Identifier specifying a field of the typed buffer.
sString | Variable receiving the string retrieved from the typed buffer.
nStringSize | Length of the variable receiving the string (optional).
nIndex | Array index (optional). This parameter has to be passed to the function if the field identifier specifies a string array.

Example

const
  ID_STRINGS      :=  8;
  ID_CONCATENATED := 16;

dcltrans
  transaction TMain
  var
    hBuffer, olen : number;
    sString       : string;
  begin
    Tux_tpbegin(30, 0);

    // allocate buffer
    TuxGetBuffer(hBuffer, "FML", NULL, 1024);

    // store two strings in buffer
    TuxSetString(hBuffer, ID_STRINGS, "Hello", 1);
    TuxSetString(hBuffer, ID_STRINGS, " world!", 2);

    // concatenate string
    Tux_tpcall("CONCAT", hBuffer, 0, hBuffer, olen, TPNOFLAGS);

    // retrieve concatenated string
    TuxGetString(hBuffer, ID_CONCATENATED, sString);
    Tux_tpcommit(0);
  end TMain;

Sample scripts

bankappn.bdf

Parent topic: Buffer Manipulating Functions
Related reference
TuxSetString Function
TuxGetCArray Function
TuxGetFloat Function
TuxGetInt Function
TuxGetBuffer Function


TuxSetCArray Function

Action

Sets the content of a specified binary data field within a typed buffer. This function can be used to manipulate any of the following predefined buffer types:

FML, FML32, CARRAY

Include file

TUXEDO.bdh

Syntax

TuxSetCArray( in hBuffer   : number,
              in nFieldId  : number,
              in sValue    : string,
              in nValueLen : number optional,
              in nIndex    : number optional ): boolean;

Return value

  • true if successful.

  • false otherwise.

Parameter | Description
hBuffer | Typed buffer allocated with TuxGetBuffer or Tux_tpalloc.
nFieldId | Identifier specifying a field of the typed buffer.
sValue | Binary data to copy to the typed buffer.
nValueLen | Size of the binary data copied to the typed buffer (optional).
nIndex | Array index (optional). This parameter has to be passed to the function if the field identifier specifies an array.

Example

const
  ID_DATA := 8;  ID_RESULT := 16;
dcltrans  transaction TMain
  var
    hBuffer, olen : number;
    sResult       : string;
    sString       : string;
  begin
    Tux_tpbegin(30, 0);

    // allocate buffer
    TuxGetBuffer(hBuffer, "FML", NULL, 1024);

    // store data and password in buffer
    TuxSetCArray(hBuffer, ID_DATA, "\h54396e31009f", 6, 1);
    TuxSetCArray(hBuffer, ID_DATA, "\h4034f83ad930", 6, 2);

    // encrypt data
    Tux_tpcall("XOR", hBuffer, 0, hBuffer, olen, TPNOFLAGS);

    // retrieve encrypted data
    TuxGetCArray(hBuffer, ID_RESULT, sString);
    Tux_tpcommit(0);
  end TMain;
Parent topic: Buffer Manipulating Functions
Related reference
TuxGetCArray Function
TuxSetString Function
TuxSetInt Function
TuxSetFloat Function
TuxGetBuffer Function


TuxGetCArray Function

Action

Retrieves the content of a specified binary data field within a typed buffer. This function can be used to manipulate any of the following predefined buffer types:

FML, FML32, CARRAY

Include file

TUXEDO.bdh

Syntax

TuxGetCArray( in  hBuffer     : number,
              in  nFieldId    : number,
              out sBinary     : string,
              in  nBinarySize : number optional,
              in  nIndex      : number optional ): boolean;

Return value

  • true if successful.

  • false otherwise.

Parameter | Description
hBuffer | Typed buffer allocated with TuxGetBuffer or Tux_tpalloc.
nFieldId | Identifier specifying a field of the typed buffer.
sBinary | Buffer receiving the binary data retrieved from the typed buffer.
nBinarySize | Size of the buffer receiving the binary data (optional).
nIndex | Array index (optional). This parameter has to be passed to the function if the field identifier specifies an array.

Example

const
  ID_DATA   :=  8;
  ID_RESULT := 16;

dcltrans
  transaction TMain
  var
    hBuffer, olen : number;
    sResult       : string;
    sString       : string;
  begin
    Tux_tpbegin(30, 0);

    // allocate buffer
    TuxGetBuffer(hBuffer, "FML", NULL, 1024);

    // store data and password in buffer
    TuxSetCArray(hBuffer, ID_DATA, "\h54396e31009f", 6, 1);
    TuxSetCArray(hBuffer, ID_DATA, "\h4034f83ad930", 6, 2);

    // encrypt data
    Tux_tpcall("XOR", hBuffer, 0, hBuffer, olen, TPNOFLAGS);

    // retrieve encrypted data
    TuxGetCArray(hBuffer, ID_RESULT, sString);
    Tux_tpcommit(0);
  end TMain;
Parent topic: Buffer Manipulating Functions
Related reference
TuxSetCArray Function
TuxGetFloat Function
TuxGetInt Function
TuxGetString Function
TuxGetBuffer Function


TuxSetInt Function

Action

Sets the value of a specified integer field within a typed buffer. This function can be used to manipulate any of the following predefined buffer types:

FML, FML32

Include file

TUXEDO.bdh

Syntax

TuxSetInt(in hBuffer  : number,
          in nFieldId : number,
          in nValue   : number,
          in nIndex   : number optional): boolean;

Return value

  • true if successful

  • false otherwise

Parameter | Description
hBuffer | Typed buffer allocated with TuxGetBuffer or Tux_tpalloc.
nFieldId | Identifier specifying a field of the typed buffer.
nValue | Integer value to copy to the typed buffer.
nIndex | Array index (optional). This parameter has to be passed to the function if the field identifier specifies an integer array.

Example

const
  ID_NUMBERS :=  8;
  ID_SUM     := 16;

dcltrans
  transaction TMain
  var
    hBuffer, olen, nSum: number;
  begin
    Tux_tpbegin(30, 0);

    // allocate buffer
    TuxGetBuffer(hBuffer, "FML", NULL, 1024);

    // store two values in buffer
    TuxSetInt(hBuffer, ID_NUMBERS, 8, 1);
    TuxSetInt(hBuffer, ID_NUMBERS, 4, 2);

    // calculate the sum of both values
    Tux_tpcall("SUM", hBuffer, 0, hBuffer, olen, TPNOFLAGS);

    // retrieve result
    nSum := TuxGetInt(hBuffer, ID_SUM);
    Tux_tpcommit(0);
  end TMain;

Sample scripts

bankappn.bdf

Parent topic: Buffer Manipulating Functions
Related reference
TuxGetInt Function
TuxSetString Function
TuxSetFloat Function
TuxSetCArray Function
TuxGetBuffer Function


TuxGetInt Function

Action

Retrieves the value of a specified integer field within a typed buffer. This function can be used to manipulate any of the following predefined buffer types:

FML, FML32

Include file

TUXEDO.bdh

Syntax

TuxGetInt(in hBuffer  : number,
          in nFieldId : number
          in nIndex   : number optional): number;

Return value

Integer value retrieved from the typed buffer.

Parameter | Description
hBuffer | Typed buffer allocated with TuxGetBuffer or Tux_tpalloc.
nFieldId | Identifier specifying a field of the typed buffer
nIndex | Array index (optional). This parameter has to be passed to the function if the field identifier specifies an integer array

Example

const
  ID_NUMBERS :=  8;
  ID_SUM     := 16;

dcltrans
  transaction TMain
  var
    hBuffer, olen, nResult: number;
  begin
    Tux_tpbegin(30, 0);

    // allocate buffer
    TuxGetBuffer(hBuffer, "FML", NULL, 1024);

    // store two integer value in buffer
    TuxSetInt(hBuffer, ID_NUMBERS, 8, 1);
    TuxSetInt(hBuffer, ID_NUMBERS, 4, 2);

    // calculate sum
    Tux_tpcall("SUM", hBuffer, 0, hBuffer, olen, TPNOFLAGS);

    // retrieve result
    nResult := TuxGetInt(hBuffer, ID_SUM);
    Tux_tpcommit(0);
  end TMain;

Sample scripts

bankappn.bdf

Parent topic: Buffer Manipulating Functions
Related reference
TuxSetInt Function
TuxGetCArray Function
TuxGetFloat Function
TuxGetString Function
TuxGetBuffer Function


Jacada Functions Reference

A number of functions are provided to handle Jacada function calls from within Silk Performer. These functions are one-to-one wrappers of Jacada's own load testing API. Please refer to Jacada documentation for detailed information.

Parent topic: Application Server Functions


Browser-Driven Web Load Testing Functions

Silk Performer provides the following functions for browser-driven Web load testing:

  • BrowserActivateWindow Function
    Activates the window (tab) inside the web browser so that all following locator-based API calls work on the window.
  • BrowserBack Function
    Equivalent to clicking the browser Back button.
  • BrowserButtonSelect Function
    Clicks a DOM button.
  • BrowserCheckBoxSelect Function
    Sets the state of a check box.
  • BrowserClick Function
    Clicks a DOM element with a specified mouse button.
  • BrowserCloseWindow Function
    Closes the window (tab) that is currently active in the web browser, or a window specified by a handle.
  • BrowserCreateWindow Function
    Opens a new window (or a new tab in the browser) programmatically.
  • BrowserDeleteCertificate Function
  • BrowserDlgDownload Function
    Creates a file download command in the dialog command storage.
  • BrowserDlgDownloadCancel Function
    Creates a file download cancel command in the dialog command storage.
  • BrowserDlgSetButton Function
    Stores a button press command in the dialog command storage.
  • BrowserDlgSetText Function
    Stores a text command in the dialog command storage.
  • BrowserDlgStop Function
    Clears the content of the dialog command storage and closes any open pop-up dialog boxes.
  • BrowserDlgVerifyDownloadSize Function
    Adds a download command to the dialog command storage that checks the size of the downloaded file.
  • BrowserDoubleClick Function
    Double-clicks a DOM element.
  • BrowserExecuteJavaScript Function
    Executes JavaScript code based on the currently loaded HTML content.
  • BrowserFileDownload Function
    Reads a file from a certain location and stores it to the local file system.
  • BrowserFind Function
    Finds a DOM element using a given locator.
  • BrowserFindAll Function
    Finds all DOM elements for a given locator.
  • BrowserFormSubmit Function
    Submits a DOM form.
  • BrowserForward Function
    Equivalent to clicking the Web browser Forward button.
  • BrowserGetActiveWindow Function
    Returns the handle of the active browser window (tab).
  • BrowserGetIEMode Function
    Returns the current IE mode.
  • BrowserGetOption Function
    Gets a BrowserEngine option.
  • BrowserGetProperty Function
    Reads the value of the specified DOM element's property.
  • BrowserGetProxy
    Retrieves the current proxy host name and port number either for all protocols or for a specific protocol.
  • BrowserGetProxyAutoConfigFile
    Retrieves the location of a PAC (Proxy Auto-Configuration) file.
  • BrowserGetProxyBypass
    Retrieves the names of hosts that are not to be accessed through a proxy.
  • BrowserGetScrollPos Function
    Returns the current scrollbar position of the active window.
  • BrowserGetStandardHost Function
    Gets the replacement name for the predefined host name standardhost.
  • BrowserGetText Function
    Retrieves the text of a DOM element.
  • BrowserGetUrl Function
    Retrieves the current URL from the browser.
  • BrowserHighlight Function
    Highlights an object by changing background and foreground colors.
  • BrowserIgnoreServerError Function
    Modifies the error severity of a specified server error for the subsequent browser-driven function call.
  • BrowserImportCertificate Function
    Imports the client certificate from a file into the certificate store of the operating system for later use by Internet Explorer.
  • BrowserLinkSelect Function
    Clicks a DOM link.
  • BrowserListBoxMultiSelect Function
    Selects multiple items in a DOM list box.
  • BrowserListBoxSelect Function
    Selects an item in a DOM listbox.
  • BrowserMouseMove Function
    Sends a DOM mouse-move event to the specified DOM element.
  • BrowserNativeClick Function
    Clicks a DOM element with a specified position and mouse button.
  • BrowserNativeDoubleClick Function
    Double-clicks a DOM element with a specified position and mouse button.
  • BrowserNativeMouseMove Function
    Sends a mouse-move event to the specified DOM element with a specified position.
  • BrowserNavigate Function
    Navigates to a specified URL.
  • BrowserPause Function
    Enables step-by-step mode so the execution of a Try Script run is paused before the next API call is executed.
  • BrowserRadioButtonSelect Function
    Selects a radio button.
  • BrowserReload Function
    Equivalent to clicking the Web browser Reload button.
  • BrowserReplayCompatibility Function
    Sets the replay compatibility by defining how locators are generated.
  • BrowserReset Function
    Resets the browser state (cookies, cache and history).
  • BrowserSetAuthentication Function
    Sets username and password for a subsequent authentication attempt.
  • BrowserSetBrowserType Function
    Sets the browser type to be used for the simulation.
  • BrowserSetCertificate Function
    Sets a client certificate of a given name for authentication and encryption purposes.
  • BrowserSetDomainSuppress Function
    Suppresses content in a Web page which is hosted on another domain, for example popup ads or requests submitted by social networking sites.
  • BrowserSetIEMode Function
    Sets the IE compatibility mode for the browser-driven Web load testing feature.
  • BrowserSetOption Function
    Sets a BrowserEngine option.
  • BrowserSetPassword Function
    Sets the password of a text field or text area element.
  • BrowserSetProperty Function
    Changes the property values of DOM elements.
  • BrowserSetProxy
    Sets the proxy host name and port for a specific protocol.
  • BrowserSetProxyAutoConfigFile
    Specifies the location of a PAC (Proxy Auto-Configuration) file.
  • BrowserSetProxyBypass
    Sets the names of hosts that are not be accessed through a proxy.
  • BrowserSetReplayBehavior Function (deprecated)
    Sets the replay behavior by defining how locators are generated.
  • BrowserSetScrollPos Function
    Scrolls to the specified position inside the active window.
  • BrowserSetStandardHost Function
    Sets the replacement name for the predefined host name "standardhost".
  • BrowserSetText Function
    Sets the text of a text field or text area element.
  • BrowserScreenshot Function
    Takes a screenshot during replay and stores it in the TrueLog.
  • BrowserStart Function
    Starts the browser and resets the virtual user.
  • BrowserStop Function
    Closes the browser.
  • BrowserStore Function
    Stores a handle to a DOM element for reuse.
  • BrowserTtiIncludeElement Function
    Marks an element as relevant for measuring the Time to Interact.
  • BrowserTypeKeys Function
    Replays keystrokes as if they were entered directly using the keyboard.
  • BrowserUnhighlight Function
    Unhighlights an object.
  • BrowserVerifyProperty Function
    Verifies that a property of a DOM element has a specified value.
  • BrowserVerifyText Function
    Checks if a DOM element has a specified caption.
  • BrowserWaitForDisappear Function
    Waits until the respective DOM element is invisible or detached from the document.
  • BrowserWaitForNewWindow Function
    Waits until a new browser window (tab) is created and returns the handle of this window (tab).
  • BrowserWaitForProperty Function
    Waits until the respective property has the specified value.
  • GetInternetExplorerInfo Function
    Returns the major and minor version and the build number of the installed Internet Explorer.
Parent topic: Benchmark Description Language (BDL) Reference


BrowserActivateWindow Function

Action

Activates the window (tab) inside the web browser so that all following locator-based API calls work on the window.

Include file

BrowserAPI.bdh

Syntax

BrowserActivateWindow( uHandle : in number ): boolean;

Parameter | Description
uHandle | The handle returned by a previous BrowserGetActiveWindow call.

Return value

  • true if successful

  • false otherwise

Example

benchmark SilkPerformerRecorder

use "Kernel.bdh"
use "BrowserAPI.bdh"

dcluser
  user
    VUser
  transactions
    TInit           : begin;
    TMain           : 1;

var

dclrand

dcltrans
  transaction TInit
  begin
  end TInit;

  transaction TMain
  var
    wnd1   : number;
    wnd2   : number;
    check1 : number;
  begin
    BrowserStart(BROWSER_MODE_DEFAULT, 800, 600);
    BrowserNavigate("http://demo.borland.com/TestSite/multiplewindows/multipleWindows.html");
    wnd1 := BrowserGetActiveWindow("mainWindow");
    BrowserLinkSelect("//A[@name='window1']",  "Select, BODY (#1)");
    wnd2 := BrowserGetActiveWindow("first window");
    BrowserActivateWindow(wnd1);
    BrowserLinkSelect("//A[@name='window2']",  "Select, BODY (#1)");

    BrowserCloseWindow(wnd2); // close second window (tab)
    BrowserCloseWindow();     // close active window (tab)
  end TMain;
Parent topic: Browser-Driven Web Load Testing Functions
Related reference
BrowserCloseWindow Function
BrowserGetActiveWindow Function


BrowserBack Function

Action

Equivalent to clicking the browser Back button.

Include file

BrowserAPI.bdh

Syntax

BrowserBack(): boolean;

Return value

  • true if successful

  • false otherwise

Example

benchmark SilkPerformerRecorder

use "Kernel.bdh"
use "BrowserAPI.bdh"

dcluser
  user
    VUser
  transactions
    TInit           : begin;
    TMain           : 1;

var

dclrand

dcltrans
  transaction TInit
  begin
  end TInit;

  transaction TMain
  begin
    BrowserStart(BROWSER_MODE_DEFAULT, 800, 600);
    BrowserNavigate("http://demo.borland.com/");
    BrowserClick("//A[@textContents='Demo Application']");

    BrowserBack();  // go one step back in your browser's history

    BrowserForward(); // go one step forward in your browser's history
  end TMain;
Parent topic: Browser-Driven Web Load Testing Functions
Related reference
BrowserForward Function
BrowserReload Function


BrowserButtonSelect Function

Action

Clicks a DOM button.

Note: This function performs the same action as BrowserClick.

Include file

BrowserAPI.bdh

Syntax

BrowserButtonSelect( uTestObject : in union,
                     sTimer      : in string optional ): boolean;
Parameter | Description
uTestObject | Either a locator that identifies the button or a handle to a previously found button. Throws an error if an invalid handle is used or if the locator can not be resolved.
sTimer | Optional: Name of the timer used for page measurements. If this parameter is omitted, no measurements are performed.

Return value

  • true if successful

  • false otherwise

Example

benchmark SilkPerformerRecorder

use "Kernel.bdh"
use "BrowserAPI.bdh"

dcluser
  user
    VUser
  transactions
    TInit           : begin;
    TMain           : 1;

var

dclrand

dcltrans
  transaction TInit
  begin
  end TInit;

  transaction TMain
  begin
    BrowserStart(BROWSER_MODE_DEFAULT, 800, 600);
    BrowserNavigate("http://demo.borland.com/gmopost/");

    BrowserButtonSelect("//INPUT[@name='bSubmit']");  // select (click) the "Enter GMO OnLine" button
  end TMain;
Parent topic: Browser-Driven Web Load Testing Functions
Related reference
BrowserClick Function


BrowserCheckBoxSelect Function

Action

Sets the state of a check box.

Include file

BrowserAPI.bdh

Syntax

BrowserCheckBoxSelect( uTestObject : in union,
                       nState      : in number,
                       sTimer      : in string optional ): boolean;
Parameter | Description
uTestObject | Either a locator that identifies the check box or a handle to a previously found check box. Throws an error if an invalid handle is used or if the locator can not be resolved.
nState | Use CHECKBOX_CHECKED to check the check box or CHECKBOX_UNCHECKED to uncheck the checkbox. Other values will raise an error.
sTimer | Optional: Name of the timer used for page measurements. If this parameter is omitted, no measurements are performed.

Return value

  • true if successful

  • false otherwise

Example

benchmark SilkPerformerRecorder

use "Kernel.bdh"
use "BrowserAPI.bdh"

dcluser
  user
    VUser
  transactions
    TInit           : begin;
    TMain           : 1;

var

dclrand

dcltrans
  transaction TInit
  begin
  end TInit;

  transaction TMain
  begin
    BrowserStart(BROWSER_MODE_DEFAULT, 800, 600);
    BrowserNavigate("http://demo.borland.com/TestSite/gwt/Showcase.html#CwCheckBox");

    // check Monday
    BrowserCheckBoxSelect("//SPAN[@hideFocus='0']/INPUT[@hideFocus='0']", CHECKBOX_CHECKED);
    // uncheck Monday
    BrowserCheckBoxSelect("//SPAN[@hideFocus='0'][1]/INPUT[@hideFocus='0']", CHECKBOX_UNCHECKED);
    // check Tuesday
    BrowserCheckBoxSelect("//SPAN[@hideFocus='0'][2]/INPUT[@hideFocus='0']", CHECKBOX_CHECKED);

    BrowserStop();
  end TMain;
Parent topic: Browser-Driven Web Load Testing Functions


BrowserClick Function

Action

Clicks a DOM element with a specified mouse button. A left-button click executes the default actions of the clicked element type.

Include file

BrowserAPI.bdh

Syntax

BrowserClick( uTestObject : in union,
              nButton     : in number optional,
              sTimer      : in string optional ): boolean;
Parameter | Description
uTestObject | Either a locator that identifies the DOM element or a handle to a previously found DOM element. Throws an error if an invalid handle is used or if the locator cannot be resolved.
nButton | Optional: The mouse button with which the DOM element is to be clicked. Specify BUTTON_LEFT to use the left mouse button (default), or BUTTON_RIGHT to use the right mouse button. You can combine mouse buttons with modifier keys using an OR operator. Specify MODIFIER_SHIFT, MODIFIER_ALT, or MODIFIER_CTRL for the respective modifier key. For example: BUTTON LEFT | MODIFIER_CTRL
sTimer | Optional: Name of the timer used for page measurements. If this parameter is omitted, no measurements are performed.

Return value

  • true if successful

  • false otherwise

Example

benchmark SilkPerformerRecorder

use "Kernel.bdh"
use "BrowserAPI.bdh"
use "WebAPI.bdh"

dcluser
  user
    BDLTUser
  transactions
    TInit           : begin;
    TMain(BROWSER_MODE_DISPLAY_VISIBLE) : 1;

  var
    gDemoSite:string;

dclrand

dcltrans
  transaction TInit
  begin
    gDemoSite := "http://demo.borland.com/InsuranceWebExtJS/";
  end TInit;

  transaction TMain(mode:number)
  var
    sQuote,sExpected : string;
  begin
    BrowserStart(BROWSER_MODE_DISPLAY_VISIBLE | BROWSER_MODE_USERBEHAVIOR_FIRST_TIME);
    BrowserNavigate(gDemoSite, "Navigate to Demo Site");
    if BrowserFind(HANDLE_DESKTOP , "//LABEL[@textContents='John Smith']", false, 0, true) = HANDLE_INVALID then
      BrowserClick("//INPUT[@id='login-form:email']", BUTTON_Left);
      BrowserSetText("//INPUT[@id='login-form:email']", "john.smith@gmail.com");
      BrowserClick("//INPUT[@id='login-form:password']", BUTTON_Left);
      BrowserSetText("//INPUT[@id='login-form:password']", "john");
      BrowserButtonSelect("//INPUT[@id='login-form:login']", "BrowserButtonSelect (#1)");
    end;
    BrowserListBoxSelect("//SELECT[@id='quick-link:jump-menu']", "Auto Quote", "BrowserListBoxSelect (#1)");
    BrowserRadioButtonSelect("//INPUT[@id='autoquote:vehicle:0']");
    BrowserClick("//INPUT[@id='autoquote:zipcode']", BUTTON_Left);
    BrowserSetText("//INPUT[@id='autoquote:zipcode']", "555");
    BrowserClick("//INPUT[@id='autoquote:e-mail']", BUTTON_Left);
    BrowserSetText("//INPUT[@id='autoquote:e-mail']", "john.smith@gmail.com");
    BrowserButtonSelect("//INPUT[@id='autoquote:next']", "BrowserButtonSelect (#2)");
    BrowserRadioButtonSelect("//INPUT[@id='autoquote:gender:0']");
    BrowserRadioButtonSelect("//INPUT[@id='autoquote:type:0']");
    BrowserButtonSelect("//INPUT[@id='autoquote:next']", "BrowserButtonSelect (#3)");
    BrowserClick("//IMG[@hideFocus='0'][2]", BUTTON_Left, "BrowserClick (#3)");
    BrowserClick("//DIV[@textContents='Chrysler']", BUTTON_Left, "BrowserClick (#4)");
    BrowserClick("//IMG[@hideFocus='0'][3]", BUTTON_Left, "BrowserClick (#5)");
    BrowserClick("//DIV[@textContents='Aspen']", BUTTON_Left);
    BrowserRadioButtonSelect("//INPUT[@id='autoquote:finInfo:0']");
    BrowserButtonSelect("//INPUT[@id='autoquote:next']", "BrowserButtonSelect (#4)");
    BrowserLinkSelect("//A[@textContents='Home']", "Select, A, textContents=Home (#1)");
    BrowserButtonSelect("//INPUT[@id='logout-form:logout']",
      "Select, INPUT, href=http://demo.borland.com/InsuranceWebExtJS/index.jsf (#1)");
  end TMain;
Parent topic: Browser-Driven Web Load Testing Functions
Related concepts
Native Replay
Related reference
BrowserNativeClick Function
BrowserDoubleClick Function
BrowserNativeDoubleClick Function
BrowserSetText Function
BrowserTypeKeys Function
BrowserSetPassword Function
BrowserMouseMove Function
BrowserNativeMouseMove Function


BrowserCloseWindow Function

Action

Closes the window (tab) that is currently active in the web browser, or a window specified by a handle.

Note: The first window opened (the main window) cannot be closed.

Include file

BrowserAPI.bdh

Syntax

BrowserCloseWindow( uHandle : in number optional ): boolean;

Parameter | Description
uHandle | Optional: The handle returned by a previous BrowserGetActiveWindow call. If not specified, the active window is closed.

Return value

  • true if successful

  • false otherwise

Example

benchmark SilkPerformerRecorder

use "Kernel.bdh"
use "BrowserAPI.bdh"

dcluser
  user
    VUser
  transactions
    TInit           : begin;
    TMain           : 1;

var

dclrand

dcltrans
  transaction TInit
  begin
  end TInit;

  transaction TMain
  var
    wnd1   : number;
    wnd2   : number;
    check1 : number;
  begin
    BrowserStart(BROWSER_MODE_DEFAULT, 800, 600);
    BrowserNavigate("http://demo.borland.com/TestSite/multiplewindows/multipleWindows.html");
    wnd1 := BrowserGetActiveWindow("mainWindow");
    BrowserLinkSelect("//A[@name='window1']",  "Select, BODY (#1)");
    wnd2 := BrowserGetActiveWindow("first window");
    BrowserActivateWindow(wnd1);
    BrowserLinkSelect("//A[@name='window2']",  "Select, BODY (#1)");

    BrowserCloseWindow(wnd2); // close second window (tab)
    BrowserCloseWindow();     // close active window (tab)
  end TMain;
Parent topic: Browser-Driven Web Load Testing Functions
Related reference
BrowserActivateWindow Function
BrowserGetActiveWindow Function


BrowserCreateWindow Function

Action

Opens a new window (or a new tab in the browser) programmatically. Usually a BrowserNavigate has to be executed afterwards.

Include file

BrowserAPI.bdh

Syntax

BrowserCreateWindow(): boolean;

Return value

  • true if successful

  • false otherwise

Example

benchmark SilkPerformerRecorder

use "Kernel.bdh"
use "BrowserAPI.bdh"

dcluser
  user
    VUser
  transactions
    TInit           : begin;
    TMain           : 1;

var

dclrand

dcltrans
  transaction TInit
  begin
  end TInit;

  transaction TMain
  begin
    BrowserStart(BROWSER_MODE_DEFAULT, 800, 600);
    BrowserCreateWindow(); // create new window (tab)
    BrowserNavigate("http://demo.borland.com/");  // navigate to demo.borland.com
  end TMain;
Parent topic: Browser-Driven Web Load Testing Functions


BrowserDeleteCertificate Function

Action

Deletes the client certificate from the operating system's certificate store. This function is similar to manually deleting a certificate.

The certificate APIs work with Microsoft Windows 7 or later, Microsoft Windows Server 2008 R2 or later, and Internet Explorer 8 or later.

Note: This function only works with Internet Explorer.

Include file

BrowserAPI.bdh

Syntax

BrowserDeleteCertificate( sCertificatename : in string,
                          sCertstore       : in string optional ): boolean;

Parameter | Description
sCertificatename | The certificate to be deleted.
sCertstore | Optional: The certificate store name. When this parameter is not specified certificates are deleted from the My store, available on the certificate tab's Personal tab.

Return Value

  • true if successful

  • false otherwise

Example

Note: The following example does not work out-of-the-box, as you first need to set up a certificate in order to execute actions on it.
benchmark SilkPerformerRecorder

use "Kernel.bdh"
use "BrowserAPI.bdh"

dcluser
  user
    VUser
  transactions
    TInit           : begin;
    TMain           : 1;

var

dclrand

dcltrans
  transaction TInit
  begin
  end TInit;

  transaction TMain
  begin
    BrowserStart(BROWSER_MODE_DEFAULT, 800, 600);

    // delete the certificate from the default certificate store
    BrowserDeleteCertificate("John Smith");
  end TMain;
Parent topic: Browser-Driven Web Load Testing Functions
Related reference
BrowserImportCertificate Function
BrowserSetCertificate Function


BrowserDlgDownload Function

Action

Creates a file download command in the dialog command storage. BrowserDlgDownload provides enhanced file download functionality and replaces the BrowserFileDownload function when recording new scripts. The actual file download is triggered by a subsequent call like BrowserClick.

BrowserDlgStop is required to synchronize and end the file download procedure. The default timeout is 20 seconds, which can be customized by using BrowserSetOption with the BROWSER_OPT_FILEDOWNLOAD_BEGIN_TIMEOUT option. If the download starts within the defined timeout, the execution of the script is blocked within BrowserDlgStop until the download has finished. If the download does not start within the specified time, the API call fails and returns an error.

Whether and how the file is copied from the browser cache to the local disk depends on the type of executed test run and/or on the BROWSER_OPT_FILEDOWNLOAD_SAVEFILE option defined in the BrowserSetOption call that needs to be scripted before the BrowserDlgDownload call. If the BROWSER_OPT_FILEDOWNLOAD_SAVEFILE option is not specified, all downloaded files are copied from the browser cache to the results directory for Try Script runs, and for load test runs and find baseline runs no files are copied to the results directory. It is recommended not to copy any files to the results directory for load test runs, as this could result in huge amounts of data being saved on the local disk, and this data will also need to be copied from the agent machines to the controller.

Note: This function only works with Internet Explorer.

Include file

BrowserAPI.bdh

Syntax

BrowserDlgDownload( sFileName : in string ): boolean;
Parameter | Description
sFilename | The name of the file which shall be downloaded to the local disk. For recording, files are stored in the current project folder. For replay, files are stored in the project's results folder. The results folders are called RecentTryScriptRun for Try Script runs, the specified load test folder name for load tests, and RecentBaseLineTest for find baseline runs.

Return value

  • true if successful

  • false otherwise

Example

benchmark SilkPerformerRecorder

use "Kernel.bdh"
use "BrowserAPI.bdh"

dcluser
  user
    VUser
  transactions
    TMain           : 1;

dcltrans
  transaction TMain
  var
    wnd1 : number;
  begin
    BrowserStart(BROWSER_MODE_DEFAULT, 800, 600);
    BrowserNavigate("http://demo.borland.com/TestSite/common_main.asp#Download",
      "Navigate_http://demo.borland.com/TestSite/common_main.asp#Download (#1)");
    wnd1 := BrowserGetActiveWindow("wnd1");
    BrowserSetOption(BROWSER_OPT_FILEDOWNLOAD_SAVEFILE, FILEDOWNLOAD_SAVEFILE_SAVELAST);
    BrowserDlgDownload("SmallFile.exe");
    BrowserClick("//A[@textContents='Small File']", BUTTON_Left, "Click, A, textContents=Small File (#1)");
    BrowserDlgStop();
  end TMain;
Parent topic: Browser-Driven Web Load Testing Functions
Related reference
BrowserFileDownload Function
BrowserSetOption Function
BrowserDlgStop Function
BrowserDlgDownloadCancel Function


BrowserDlgDownloadCancel Function

Action

Creates a file download cancel command in the dialog command storage. If a file download is triggered by one of the following API calls, for example BrowserClick, the download is canceled and no data is downloaded. The behavior of BrowserDlgDownloadCancel is similar to BrowserDlgDownload, but cancels the download instead of performing it.

Note: This function only works with Internet Explorer.

Include file

BrowserAPI.bdh

Syntax

BrowserDlgDownloadCancel(): boolean;

Return value

  • true if successful

  • false otherwise

Example

benchmark SilkPerformerRecorder

use "Kernel.bdh"
use "BrowserAPI.bdh"

dcluser
  user
    VUser
  transactions
    TMain           : 1;

dcltrans
  transaction TMain
  var
    wnd1 : number;
  begin
    BrowserStart(BROWSER_MODE_DEFAULT, 800, 600);
    BrowserNavigate("http://demo.borland.com/TestSite/common_main.asp#Download",
      "Navigate_http://demo.borland.com/TestSite/common_main.asp#Download (#1)");
    wnd1 := BrowserGetActiveWindow("wnd1");
    BrowserDlgDownloadCancel();
    BrowserClick("//A[@textContents='Small File']", BUTTON_Left, "Click, A, textContents=Small File (#1)");
    BrowserDlgStop();
  end TMain;
Parent topic: Browser-Driven Web Load Testing Functions
Related reference
BrowserDlgDownload Function
BrowserSetOption Function
BrowserDlgStop Function


BrowserDlgSetButton Function

Action

Stores a button press command in the dialog command storage. If a dialog pops up during replay, this button press command is used for the specified dialog. Usually only the recorded API calls shall be used for replaying, because the captions and sequence numbers are detected during recording.

Include file

BrowserAPI.bdh

Syntax

BrowserDlgSetButton( sDialog : in string,
                     sButton : in string ): boolean;
Parameter | Description
sDialog | The caption of the dialog with a sequence number.
sButton | The name of the button.

Return value

  • true if successful

  • false otherwise

Example

benchmark SilkPerformerRecorder

use "Kernel.bdh"
use "BrowserAPI.bdh"

dcluser
  user
    VUser
  transactions
    TInit           : begin;
    TMain           : 1;

var

dclrand

dcltrans
  transaction TInit
  begin
  end TInit;

  transaction TMain
  begin
    BrowserStart(BROWSER_MODE_DEFAULT, 800, 600);
    BrowserNavigate("http://demo.borland.com/TestSite/common_main.asp#Popup");

    // store the text "John Smith" to be inserted into a pop-up dialog's textbox
    BrowserDlgSetText("Explorer User Prompt #1", 0, "John Smith");
    // store the button press for the first popup
    BrowserDlgSetButton("Explorer User Prompt #1", "OK");
    // store the button press for the second popup
    BrowserDlgSetButton("Message from webpage #2", "OK");
    // click on prompt-button to start popping up dialogs
    BrowserClick("//INPUT[@value='Prompt']", BUTTON_Left);
    // clear the dialog command storage
    BrowserDlgStop();
  end TMain;
Parent topic: Browser-Driven Web Load Testing Functions
Related reference
BrowserDlgSetText Function
BrowserDlgStop Function


BrowserDlgSetText Function

Action

Stores a text command in the dialog command storage. If a dialog pops up during replay, the text is the user input for the specified text input field. Usually only the recorded API calls shall be used for replaying, because the captions and sequence numbers are detected during recording.

Include file

BrowserAPI.bdh

Syntax

BrowserDlgSetText( sDialog   : in string,
                   uPosition : in number,
                   sText     : in string ): boolean;
Parameter | Description
sDialog | The caption of the dialog with a sequence number.
uPosition | The text field position inside the dialog.
sText | The string which shall be used as user input.

Return value

  • true if successful

  • false otherwise

Example

benchmark SilkPerformerRecorder

use "Kernel.bdh"
use "BrowserAPI.bdh"

dcluser
  user
    VUser
  transactions
    TInit           : begin;
    TMain           : 1;

var

dclrand

dcltrans
  transaction TInit
  begin
  end TInit;

  transaction TMain
  begin
    BrowserStart(BROWSER_MODE_DEFAULT, 800, 600);
    BrowserNavigate("http://demo.borland.com/TestSite/common_main.asp#Popup");

    // store the text "John Smith" to be inserted into a pop-up dialog's textbox
    BrowserDlgSetText("Explorer User Prompt #1", 0, "John Smith");
    // store the button press for the first popup
    BrowserDlgSetButton("Explorer User Prompt #1", "OK");
    // store the button press for the second popup
    BrowserDlgSetButton("Message from webpage #2", "OK");
    // click on prompt-button to start popping up dialogs
    BrowserClick("//INPUT[@value='Prompt']", BUTTON_Left);
    // clear the dialog command storage
    BrowserDlgStop();
  end TMain;
Parent topic: Browser-Driven Web Load Testing Functions
Related reference
BrowserDlgSetButton Function
BrowserDlgStop Function


BrowserDlgStop Function

Action

Clears the content of the dialog command storage and closes any open pop-up dialog boxes. This is necessary for clearing unused dialog commands. This should be done immediately after an API call evokes the opening of a dialog.

BrowserDlgStop is also required for synchronization of file downloads and should not be manually removed from a script. It is used to synchronize and end the file download procedure. If a file download command was initiated by BrowserDlgDownload or BrowserDlgCancel and triggered by a call such as BrowserClick, the execution of BrowserDlgStop waits until the download starts. The default timeout is 20 seconds, which can be customized by using BrowserSetOption with the BROWSER_OPT_FILEDOWNLOAD_BEGIN_TIMEOUT option. If the download starts within the defined timeout, the execution of the script is blocked within BrowserDlgStop until the download has finished. If the download does not start within the specified time, the API call fails and returns an error.

Whether and how the file is copied from the browser cache to the local disk depends on the type of executed test run and/or on the BROWSER_OPT_FILEDOWNLOAD_SAVEFILE option defined in the BrowserSetOption call that needs to be scripted before the BrowserDlgDownload call. If the BROWSER_OPT_FILEDOWNLOAD_SAVEFILE option is not specified, all downloaded files are copied from the browser cache to the results directory for Try Script runs, and for load test runs and find baseline runs no files are copied to the results directory. It is recommended not to copy any files to the results directory for load test runs, as this could result in huge amounts of data being saved on the local disk, and this data will also need to be copied from the agent machines to the controller.

Include file

BrowserAPI.bdh

Syntax

BrowserDlgStop(): boolean;

Return value

  • true if successful

  • false otherwise

Example

benchmark SilkPerformerRecorder

use "Kernel.bdh"
use "BrowserAPI.bdh"

dcluser
  user
    VUser
  transactions
    TMain           : 1;

dcltrans
  transaction TMain
  var
    wnd1 : number;
  begin
    BrowserStart(BROWSER_MODE_DEFAULT, 800, 600);
    BrowserNavigate("http://demo.borland.com/TestSite/common_main.asp#Download",
      "Navigate_http://demo.borland.com/TestSite/common_main.asp#Download (#1)");
    wnd1 := BrowserGetActiveWindow("wnd1");
    BrowserDlgDownload("SmallFile.exe");
    BrowserClick("//A[@textContents='Small File']", BUTTON_Left, "Click, A, textContents=Small File (#1)");
    BrowserDlgStop();
  end TMain;
Parent topic: Browser-Driven Web Load Testing Functions
Related reference
BrowserDlgSetButton Function
BrowserDlgSetText Function
BrowserDlgDownload Function
BrowserSetOption Function
BrowserDlgDownloadCancel Function


BrowserDlgVerifyDownloadSize Function

Action

Adds a download command to the dialog command storage that checks the size of the downloaded file. The file to be downloaded must be declared beforehand with the BrowserDlgVerifyDownloadSize function. The function must be called before the download starts. Multiple verifications can be applied to a single download command to ensure that the resulting file size lies in between certain bounds. During recording, you can add a BrowserDlgVerifyDownloadSize function by checking the Verify size of download checkbox in the save file dialog.

Note: This function only works with Internet Explorer.

Include file

BrowserAPI.bdh

Syntax

BrowserDlgVerifyDownloadSize( in uExpectedSize : number,
                              in nOptions      : number optional := VERIFY_SIZE_EQUAL,
                              in nSeverity     : number optional := SEVERITY_ERROR      ): boolean;

Return value

  • true if successful

  • false otherwise

Parameter | Description
uExpectedSize | The file size used for the verification
nOptions Describes how the actual size is compared to the expected size:
  • VERIFY_SIZE_EQUAL
  • VERIFY_SIZE_LARGER_THAN
  • VERIFY_SIZE_SMALLER_THAN

If this parameter is omitted, a check for equality is performed.

nSeverity Optional: Severity of the error that is raised if the verification fails. Can be one of the following values:
  • SEVERITY_SUCCESS: Success; no error (numerical value: 0)
  • SEVERITY_INFORMATIONAL: Informational; no error (numerical value: 1)
  • SEVERITY_WARNING: Warning; no error (numerical value: 2)
  • SEVERITY_ERROR: (Default) Error; simulation continues (numerical value: 3)
  • SEVERITY_TRANS_EXIT: Error; the active transaction is aborted (numerical value: 4)
  • SEVERITY_PROCESS_EXIT: Error; the simulation is aborted (numerical value: 5)

Example

benchmark SilkPerformerRecorder

use "Kernel.bdh"
use "BrowserAPI.bdh"

dcluser
  user
    VUser
  transactions
    TMain           : 1;

dcltrans
  transaction TMain
  var
    wnd1 : number;
  begin
    BrowserStart(BROWSER_MODE_DEFAULT, 800, 600);
    BrowserNavigate("http://demo.borland.com/TestSite/common_main.asp#Download",
      "Navigate_http://demo.borland.com/TestSite/common_main.asp#Download (#1)");
    wnd1 := BrowserGetActiveWindow("wnd1");
    BrowserSetOption(BROWSER_OPT_FILEDOWNLOAD_SAVEFILE, FILEDOWNLOAD_SAVEFILE_SAVELAST);
    BrowserDlgDownload("SmallFile.exe");
    BrowserDlgVerifyDownloadSize(200, VERIFY_SIZE_LARGER_THAN | VERIFY_SIZE_EQUAL); // actual file must contain 200 Bytes or more
    BrowserClick("//A[@textContents='Small File']", BUTTON_Left, "Click, A, textContents=Small File (#1)");
    BrowserDlgStop();
  end TMain;
Parent topic: Browser-Driven Web Load Testing Functions


BrowserDoubleClick Function

Action

Double-clicks a DOM element.

Include file

BrowserAPI.bdh

Syntax

BrowserDoubleClick( uTestObject : in union,
                    nButton     : in number optional,
                    sTimer      : in string optional ): boolean;
Parameter | Description
uTestObject | Either a locator that identifies the DOM element or a handle to a previously found DOM element. Throws an error if an invalid handle is used or if the locator can not be resolved.
nButton | Optional: Specify BUTTON_LEFT to use the left mouse button (default), or BUTTON_RIGHT to use the right mouse button. You can combine mouse buttons with modifier keys using an OR operator. Specify MODIFIER_SHIFT, MODIFIER_ALT, or MODIFIER_CTRL for the respective modifier key. For example: BUTTON LEFT | MODIFIER_CTRL
sTimer | Optional: Name of the timer used for page measurements. If this parameter is omitted, no measurements are performed.

Return value

  • true if successful

  • false otherwise

Example

benchmark SilkPerformerRecorder

use "Kernel.bdh"
use "BrowserAPI.bdh"

dcluser
  user
    VUser
  transactions
    TInit           : begin;
    TMain           : 1;

var

dclrand

dcltrans
  transaction TInit
  begin
  end TInit;

  transaction TMain
  var
    wnd1 : number;
  begin
    BrowserStart(BROWSER_MODE_DEFAULT, 1230, 564);
    BrowserNavigate("http://demo.borland.com/InsuranceWebExtJS/", "Navigate to demo site (#1)");
    wnd1 := BrowserGetActiveWindow("wnd1");
    BrowserListBoxSelect("//SELECT[@id='quick-link:jump-menu']", "Agent Lookup",
      "ListBoxSelect, SELECT, name=quick-link:jump-menu (#1)");
    BrowserClick("//INPUT[@id='show-all:search-all']", BUTTON_Left, "Click, INPUT, name=show-all:search-all (#1)");
    BrowserDoubleClick("//DIV[@textContents='Walker']", BUTTON_Left, "DoubleClick, DIV, textContents=Walker (#1)");
    BrowserClick("//DIV[@unselectable='on'][30]/DIV[@hideFocus='0']", BUTTON_Left);
    BrowserClick("//A[@textContents='Home'][2]", BUTTON_Left, "Click, A, textContents=Home (#1)");
  end TMain;
Parent topic: Browser-Driven Web Load Testing Functions
Related concepts
Native Replay
Related reference
BrowserClick Function
BrowserNativeClick Function
BrowserNativeDoubleClick Function
BrowserSetText Function
BrowserTypeKeys Function
BrowserSetPassword Function
BrowserMouseMove Function
BrowserNativeMouseMove Function


BrowserExecuteJavaScript Function

Action

Executes JavaScript code based on the currently loaded HTML content.

Include file

BrowserAPI.bdh

Syntax

BrowserExecuteJavaScript( sScript     : in string
                          sResult     : out string optional
                          uTestObject : in union optional ): boolean;
Parameter | Description
sScript | The JavaScript code.
sResult | Optional: Variable receiving the result of the JavaScript execution, converted to a string.
uTestObject | The XPath locator or the handle to the DOM element. This element can be accessed as currentElement from within the script. Note: Return values are not supported when uTestObject is specified. In this case, NULL must be supplied as value for sResult.

Return value

  • true if successful

  • false otherwise

Example

benchmark SilkPerformerRecorder

use "Kernel.bdh"
use "BrowserAPI.bdh"

dcluser
  user
    VUser
  transactions
    TJavascript  : 1;

dcltrans
  transaction TJavascript
  var
    sScript  : string;
    sVersion : string;
    sObjectAsJSON : string;
    sResult : string;
  begin
    BrowserStart(BROWSER_MODE_DEFAULT, 800, 600);
    // define JavaScript to execute
    sScript := "window.open('http://demo.borland.com/gmoajax')";
    // execute the script (which opens a new window and navigates to demo.borland.com)
    BrowserExecuteJavaScript(sScript);

    // Check, if page is using "Modernizr"
    BrowserExecuteJavaScript("if (window.Modernizr) { window.Modernizr._version; }", sVersion);
    if (Strlen(sVersion) > 0) then
      Print("Page is using Modernizr, version " + sVersion);
    else
      Print("Page is not using Modernizr");
    end;

    // Acces object, stringifying it first
    BrowserExecuteJavaScript("JSON.stringify(window.Modernizr)", sObjectAsJSON);
    Print(sObjectAsJSON); // yields, e.g.: {"touch":false,"cssanimations":true,"csstransitions":true,"_version" ... }

    // run javascript for specific locator
    // return value can be retrieved via helper variable
    BrowserNavigate("http://demo.borland.com/gmoajax/");
    BrowserExecuteJavascript("document.body.sResult=currentElement.currentStyle.borderBottomColor", NULL, "//img[@id='logoIMG']");
    BrowserGetProperty("//body", "sResult", sResult);
    Print(sResult);      // yields, e.g.: hsl(120, 33%, 43%)
  end TJavascript;
Parent topic: Browser-Driven Web Load Testing Functions


BrowserFileDownload Function

Action

Reads a file from a certain location and stores it to the local file system. This call can only be scripted manually. The recorded function is the improved BrowserDlgDownload function.

Include file

BrowserAPI.bdh

Syntax

BrowserFileDownload( sUrl      : in string,
                     sFilename : in string optional,
                     sTimer    : in string optional,
                     nFilesize : out number optional ): boolean;
Parameter | Description
sUrl | The location of the file to be downloaded.
sFilename | Optional: The name of the file (optionally including path) which shall be created on the local disk. If no path is specified, the file is stored in the current project folder.
sTimer | Optional: The name of the timer used for page measurements. If this parameter is omitted, no measurements are performed.
nFilesize | Optional: The size of the file.

Return value

  • true if successful

  • false otherwise

Example

benchmark SilkPerformerRecorder

use "Kernel.bdh"
use "BrowserAPI.bdh"

dcluser
  user
    VUser
  transactions
    TInit           : begin;
    TMain           : 1;

var

dclrand

dcltrans
  transaction TInit
  begin
  end TInit;

  transaction TMain
  var
    javaScript : string;
  begin
    BrowserStart(BROWSER_MODE_DEFAULT, 800, 600);
    // start download of a file from the demo.borland.com site
    BrowserFileDownload("http://demo.borland.com/TestSite/temp/SmallFile.exe", "SmallFile.exe",
      "FileDownload SmallFile.exe (#1)");
  end TMain;
Parent topic: Browser-Driven Web Load Testing Functions
Related reference
BrowserDlgDownload Function


BrowserFind Function

Action

Finds a DOM element using a given locator.

Include file

BrowserAPI.bdh

Syntax

BrowserFind( nHandle        : in number,
             sLocator       : in string,
             bStoreHandle   : in boolean optional,
             nTimeout       : in union optional,
             bSuppressError : in boolean optional ): number;
Parameter | Description
nHandle | The handle where the search should be started. Use HANDLE_DESKTOP to search the complete DOM hierarchy.
sLocator | An XPath expression that describes the DOM element.
bStoreHandle | Optional: The browser engine can internally store the found handle for later use. You can use HANDLE_STORED to refer to the internally stored element in other function calls. If not specified, the default value FALSE is used and the handle will not be stored.
nTimeout | Optional: The wait timeout in milliseconds. If not specified, the default timeout specified in the profile settings or set by BrowserSetOption(BROWSER_OPT_WAIT_TIMEOUT) will be used. When the timeout is reached, an error is thrown, unless bSuppressError is TRUE. Use the data type number for this parameter. The data type float is not allowed.
bSuppressError | Optional: If set to TRUE, suppresses throwing the error if no element can be found. Default is FALSE.

Return value

The handle to the DOM element. HANDLE_INVALID if the element could not be found.

Example

benchmark SilkPerformerRecorder

use "Kernel.bdh"
use "BrowserAPI.bdh"

dcluser
  user
    VUser
  transactions
    TInit           : begin;
    TMain           : 1;

var

dclrand

dcltrans
  transaction TInit
  begin
  end TInit;

  transaction TMain
  var
    liHandle : number;
    liText : string;
  begin
    BrowserStart(BROWSER_MODE_DEFAULT, 800, 600);
    BrowserNavigate("http://demo.borland.com");

    // find the first list item (LI) tag on this page and store it into a variable (liHandle)
    liHandle := BrowserFind(HANDLE_DESKTOP, "//LI");
    // Alternative: find the first list item (LI) tag on this page and store it internally (HANDLE_STORED)
    BrowserFind(HANDLE_DESKTOP, "//LI", true);
    // get the text of the list item and print it
    BrowserGetText(liHandle, liText);
    print(liText);
    //Alternative: get the text of the list item and print it
    BrowserGetText(HANDLE_STORED, liText);
    print(liText);
  end TMain;
Parent topic: Browser-Driven Web Load Testing Functions
Related reference
BrowserSetOption Function
BrowserStore Function


BrowserFindAll Function

Action

Finds all DOM elements for a given locator.

Include file

BrowserAPI.bdh

Syntax

BrowserFindAll( in nHandle          : number,
                in sLocatorToSearch : string,
                out lHandles        : list,
                in nTimeout         : union optional ): boolean;
Parameter | Description
nHandle | The handle where the search should be started. Use HANDLE_DESKTOP to search the complete DOM hierarchy.
sLocatorToSearch | An XPath expression that describes the DOM elements.
lHandles | A list of handles in which the matching DOM elements will be returned.
nTimeout | Optional: The wait timeout in milliseconds. If not specified, the default timeout specified in the profile settings or set by BrowserSetOption(BROWSER_OPT_WAIT_TIMEOUT) will be used. Use the data type number for this parameter. The data type float is not allowed.

Return value

  • true if one or more DOM elements were found for the given locator
  • false otherwise

Example

benchmark SilkPerformerRecorder

use "Kernel.bdh"
use "BrowserAPI.bdh"

dcluser
  user
    VUser
  transactions
    TInit           : begin;
    TMain           : 1;

var

dclrand

dcltrans
  transaction TInit
  begin
  end TInit;

  transaction TMain
  var
    lList: list of number;
    nHandle: number;
    sText  : string;
  begin
    BrowserStart(BROWSER_MODE_DEFAULT, 800, 600);
    BrowserNavigate("http://demo.borland.com");

    // Find all list item (LI) tags on this page.
    BrowserFindAll(HANDLE_DESKTOP, "//LI", lList);
    // Print the result list of matching DOM elements.
    ListPrint(lList);
    // Get text of first item in result list and print it.
    ListGetAt(lList, 1, nHandle);
    BrowserGetText(nHandle, sText);
    print(sText);
  end TMain;
Parent topic: Browser-Driven Web Load Testing Functions


BrowserFormSubmit Function

Action

Submits a DOM form.

Include file

BrowserAPI.bdh

Syntax

BrowserFormSubmit( uTestObject : in union,
                   sTimer      : in string optional ): boolean;
Parameter | Description
uTestObject | Either a locator that identifies the DOM form or a handle to a previously found DOM form. Throws an error if an invalid handle is used or if the locator can not be resolved.
sTimer | Optional: Name of the timer used for page measurements. If this parameter is omitted, no measurements are performed.

Return value

  • true if successful

  • false otherwise

Example

benchmark SilkPerformerRecorder

use "Kernel.bdh"
use "BrowserAPI.bdh"

dcluser
  user
    VUser
  transactions
    TInit           : begin;
    TMain           : 1;

var

dclrand

dcltrans
  transaction TInit
  begin
  end TInit;

  transaction TMain
  begin
    BrowserStart(BROWSER_MODE_DEFAULT, 800, 600);
    BrowserNavigate("http://demo.borland.com/TestSite/common_main.asp#Common Forms");
    BrowserSetText("//INPUT[@value='value1']", "John Smith");

    // submit the form by pressing <RETURN> in the solely input element of the form
    BrowserFormSubmit("//FORM[@method='get'][2]", "Submit, FORM, action=data2html.asp?Intermediate (#2)");
  end TMain;
Parent topic: Browser-Driven Web Load Testing Functions


BrowserForward Function

Action

Equivalent to clicking the Web browser Forward button.

Include file

BrowserAPI.bdh

Syntax

BrowserForward(): boolean;

Return value

  • true if successful

  • false otherwise

Example

benchmark SilkPerformerRecorder

use "Kernel.bdh"
use "BrowserAPI.bdh"

dcluser
  user
    VUser
  transactions
    TInit           : begin;
    TMain           : 1;

var

dclrand

dcltrans
  transaction TInit
  begin
  end TInit;

  transaction TMain
  begin
    BrowserStart(BROWSER_MODE_DEFAULT, 800, 600);
    BrowserNavigate("http://demo.borland.com/");
    BrowserClick("//A[@textContents='Demo Application']");

    BrowserBack();  // go one step back in your browser's history
    BrowserForward(); // go one step forward in your browser's history
  end TMain;
Parent topic: Browser-Driven Web Load Testing Functions
Related reference
BrowserBack Function
BrowserReload Function


BrowserGetActiveWindow Function

Action

Returns the handle of the active browser window (tab).

Include file

BrowserAPI.bdh

Syntax

BrowserGetActiveWindow( sWindowName : string optional ): number;

Parameter | Description
sWindowName | Optional: This window name is used in TrueLogs and the Browser Application. Whenever the window handle returned by BrowserWaitForNewWindow is passed to another window function, such as BrowserActivateWindow or BrowserCloseWindow, this window name is used for textual identification of the window.

Return value

  • The value of the window handle.

Example

benchmark SilkPerformerRecorder

use "Kernel.bdh"
use "BrowserAPI.bdh"

dcluser
  user
    VUser
  transactions
    TMain           : 1;

dcltrans

  transaction TMain
  var
    mainWindow : number;
    newWindow  : number;
    check      : number;
   begin
    BrowserStart(BROWSER_MODE_DEFAULT, 800, 600);
    BrowserNavigate("http://demo.borland.com/TestSite/multiplewindows/multipleWindows.html");

    mainWindow := BrowserGetActiveWindow("main window");
    BrowserLinkSelect("//A[@name='window1']",  "Select, BODY (#1)");

    newWindow := BrowserWaitForNewWindow("new window");

    BrowserActivateWindow(mainWindow);
    check := BrowserGetActiveWindow();

    if (check <> mainWindow) then
      RepMessage("Window handles are different", SEVERITY_ERROR);
    end;
  end TMain;
Parent topic: Browser-Driven Web Load Testing Functions
Related reference
BrowserActivateWindow Function
BrowserCloseWindow Function


BrowserGetIEMode Function

Action

Returns the current IE mode, which is set in the registry for the browser-driven Web load testing feature.

Include file

BrowserAPI.bdh

Syntax

BrowserGetIEMode(): number;

Return value

Returns the value of the IE mode which is set in the registry:
  • 0: BROWSER_IE_DEFAULT
  • 7000: BROWSER_IE7_MODE
  • 8000: BROWSER_IE8_MODE
  • 8888: BROWSER_IE8_REGARDLESS_OF_DOCTYPE
  • 9000: BROWSER_IE9_MODE
  • 9999: BROWSER_IE9_REGARDLESS_OF_DOCTYPE
  • 10000: BROWSER_IE10_MODE
  • 10001: BROWSER_IE10_REGARDLESS_OF_DOCTYPE
  • 11000: BROWSER_IE11_MODE
  • 11001: BROWSER_IE11_REGARDLESS_OF_DOCTYPE

Example

benchmark SilkPerformerRecorder

use "Kernel.bdh"
use "BrowserAPI.bdh"

dcluser
  user
    VUser
  transactions
    TInit           : begin;
    TMain           : 1;

var

dclrand

dcltrans
  transaction TInit
  begin
  end TInit;

  transaction TMain
  var
    ieMode : number;
  begin
    BrowserStart(BROWSER_MODE_DEFAULT, 800, 600);

    // retrieve the IE mode and store it into a variable (ieMode)
    ieMode:= BrowserGetIEMode();
    // print out the ieMode
    print(string(ieMode));
  end TMain;
Parent topic: Browser-Driven Web Load Testing Functions
Related reference
BrowserSetIEMode Function


BrowserGetOption Function

Action

Gets a BrowserEngine option.

Include file

BrowserAPI.bdh

Syntax

BrowserGetOption( sOption : in string,
                  vValue  : inout union ): boolean;
Parameter | Description
sOption The BrowserEngine option to be read. Can be one of the following values:

  • BROWSER_OPT_WAIT_TIMEOUT - A timeout in milliseconds. Silk Performer waits to resolve an element until it is found or the timeout is reached. The default timeout is 5000 ms.

  • BROWSER_OPT_SYNC_TIMEOUT - A timeout in milliseconds after which the synchronization aborts. Synchronization normally waits until the browser is in an idle state. If this state is not achieved, synchronization aborts after the defined timeout. The default timeout is 300000 ms.

  • BROWSER_OPT_SYNC_MODE - The synchronization mode:

    • SYNC_MODE_AJAX - The AJAX mode synchronization waits for the browser to be in a kind of idle state, which is especially useful for AJAX applications or pages that contain AJAX components. Using the AJAX mode eliminates the need to manually script synchronization functions, which eases the script creation process dramatically. This automatic synchronization is also the basis for a successful record and replay approach.
    • SYNC_MODE_HTML - Using the HTML mode ensures that all HTML documents are in an interactive state. With this mode, you can test simple Web pages.
vValue | A variable that takes the value.

Return value

  • true if successful

  • false otherwise

Example

benchmark SilkPerformerRecorder

use "Kernel.bdh"
use "BrowserAPI.bdh"

dcluser
  user
    VUser
  transactions
    TInit           : begin;
    TMain           : 1;

var

dclrand

dcltrans
  transaction TInit
  begin
  end TInit;

  transaction TMain
  var
    nWaitTimeout : number;
  begin
    BrowserStart(BROWSER_MODE_DEFAULT, 800, 600);

    // get the wait timeout and print it
    BrowserGetOption(BROWSER_OPT_WAIT_TIMEOUT, nWaitTimeout);
    print(string(nWaitTimeout));
    // set the wait timeout to a new value
    BrowserSetOption(BROWSER_OPT_WAIT_TIMEOUT, 6000);
    // revert it back to the old setting
    BrowserSetOption(BROWSER_OPT_WAIT_TIMEOUT, nWaitTimeout);
  end TMain;
Parent topic: Browser-Driven Web Load Testing Functions


BrowserGetProperty Function

Action

Reads the value of the specified DOM element's property.

Include file

BrowserAPI.bdh

Syntax

BrowserGetProperty( uTestObject       : in union,
                    sDomPropertyName  : in string,
                    vDomPropertyValue : inout union ): boolean;
Parameter | Description
uTestObject | The XPath locator or the handle to the DOM element.
sDomPropertyName | The DOM property name.
vDomPropertyValue | The value of the property.

Return value

  • true if successful

  • false otherwise

Example

benchmark SilkPerformerRecorder

use "Kernel.bdh"
use "BrowserAPI.bdh"

dcluser
  user
    VUser
  transactions
    TInit           : begin;
    TMain           : 1;

var

dclrand

dcltrans
  transaction TInit
  begin
  end TInit;

  transaction TMain
  var
    propertyValue : boolean;
  begin
    BrowserStart(BROWSER_MODE_DEFAULT, 800, 600);
    BrowserNavigate("http://demo.borland.com/TestSite/gwt/Showcase.html#CwCheckBox");

    // check Monday
    BrowserSetProperty("//SPAN[@hideFocus='0']/INPUT[@hideFocus='0']", "checked", true);
    // get the value of the checked property and print it
    BrowserGetProperty("//SPAN[@hideFocus='0']/INPUT[@hideFocus='0']","checked", propertyValue);
    print(string(propertyValue));

    // uncheck Monday
    BrowserSetProperty("//SPAN[@hideFocus='0']/INPUT[@hideFocus='0']", "checked", false);
    // get the value of the checked property and print it
    BrowserGetProperty("//SPAN[@hideFocus='0']/INPUT[@hideFocus='0']","checked", propertyValue);
    print(string(propertyValue));
  end TMain;
Parent topic: Browser-Driven Web Load Testing Functions
Related reference
BrowserSetProperty Function
BrowserVerifyProperty Function


BrowserGetProxy

Action

Retrieves the current proxy host name and port number either for all protocols or for a specific protocol.
Note: This function only works with Internet Explorer.

Include file

BrowserAPI

Syntax

BrowserGetProxy( out sProxy     : string,
                 in  nProxyType : number optional ): boolean;
Parameter | Description
sProxy | A string buffer that receives the proxies.
nProxyType Proxy type. Can be one of the following types:
  • BROWSER_PROXY_HTTP
  • BROWSER_PROXY_FTP
  • BROWSER_PROXY_HTTPS
  • BROWSER_PROXY_SOCKS

Return value

  • true if successful

  • false otherwise

Example

transaction TMain
var
  sProxy: string;
begin
  BrowserStart(BROWSER_MODE_DEFAULT, 800, 600);
  BrowserSetProxy(BROWSER_PROXY_HTTP, "proxy.mydomain.com", 8080);
  BrowserNavigate("www.mycompany.com");
  BrowserGetProxy(sProxy, BROWSER_PROXY_HTTP);
end TMain;
Parent topic: Browser-Driven Web Load Testing Functions
Related reference
BrowserGetProxyAutoConfigFile
BrowserGetProxyBypass
BrowserSetProxy
BrowserSetProxyAutoConfigFile
BrowserSetProxyBypass


BrowserGetProxyAutoConfigFile

Action

Retrieves the location of a PAC (Proxy Auto-Configuration) file.
Note: This function only works with Internet Explorer.

Include file

BrowserAPI

Syntax

BrowserGetProxyAutoConfigFile( out sConfigUrl : string ): boolean;
Parameter | Description
sConfigUrl | A string buffer that receives the location of the PAC file.

Return value

  • true if successful

  • false otherwise

Example

transaction TMain
var
  sConfigUrl: string;
begin
  BrowserStart(BROWSER_MODE_DEFAULT, 800, 600);
  BrowserSetProxyAutoConfigFile("http://proxy.mydomain.com/proxy.pac");
  BrowserNavigate("www.mycompany.com");
  BrowserGetProxyAutoConfigFile(sConfigUrl);
end TMain;
Parent topic: Browser-Driven Web Load Testing Functions
Related reference
BrowserGetProxy
BrowserGetProxyBypass
BrowserSetProxy
BrowserSetProxyAutoConfigFile
BrowserSetProxyBypass


BrowserGetProxyBypass

Action

Retrieves the names of hosts that are not to be accessed through a proxy.
Note: This function only works with Internet Explorer.

Include file

BrowserAPI

Syntax

BrowserGetProxyBypass( out sBypassList : string ): boolean;
Parameter | Description
sBypassList | String variable that receives the list of hosts that have been set to not be accessed through a proxy.

Return value

  • true if successful

  • false otherwise

Example

transaction TMain
var
  sBypassList: string;
begin
  BrowserStart(BROWSER_MODE_DEFAULT, 800, 600);
  BrowserSetProxy(BROWSER_PROXY_HTTP, "proxy.mydomain.com", 8080);
  BrowserSetProxyBypass(false, "www.mycompany.com");
  BrowserNavigate("www.mycompany.com");
  BrowserGetProxyBypass(sBypassList);
end TMain;
Parent topic: Browser-Driven Web Load Testing Functions
Related reference
BrowserGetProxy
BrowserGetProxyAutoConfigFile
BrowserSetProxy
BrowserSetProxyAutoConfigFile
BrowserSetProxyBypass


BrowserGetScrollPos Function

Action

Returns the current scrollbar position of the active window. In case there are no vertical or horizontal scrollbars, the values are set to zero.

Note: This function only works with Internet Explorer.

Include file

BrowserAPI.bdh

Syntax

BrowserGetScrollPos( nTop  : out number,
                     nLeft : out number ): boolean;
Parameter | Description
nTop | The current vertical position of the scrollbar.
nLeft | The current horizontal position of the scrollbar.

Return value

  • true if successful

  • false otherwise

Example

benchmark SilkPerformerRecorder

use "Kernel.bdh"
use "BrowserAPI.bdh"

dcluser
  user
    VUser
  transactions
    TInit           : begin;
    TMain           : 1;

var

dclrand

dcltrans
  transaction TInit
  begin
  end TInit;

  transaction TMain
  var
    top  : number;
    left : number;
  begin
    BrowserStart(BROWSER_MODE_DEFAULT, 800, 600);
    BrowserNavigate("http://demo.borland.com/TestSite/htmlparser/forms.asp");

    // scroll one whole page down (e.g. 600 pixels)
    BrowserSetScrollPos(600,0,BROWSER_RELATIVE_SCROLLING);
    // get the actual scroll position
    BrowserGetScrollPos(top, left);
    // print top, left coordinates
    print(string(top));
    print(string(left));
  end TMain;
Parent topic: Browser-Driven Web Load Testing Functions
Related reference
BrowserSetScrollPos Function


BrowserGetStandardHost Function

Action

Gets the replacement name for the predefined host name "standardhost" set by the BrowserSetStandardHost function, or initially defined in the active profile settings (Settings > Active Profile > Internet > Hosts > Standardhost).

Include file

BrowserAPI.bdh

Syntax

BrowserGetStandardHost( sHost   : out string,
                        nMaxLen : in number optional,
                        nPort   : out number optional ): boolean;
Parameter | Description
sHost | String buffer receiving the current name of the standardhost.
nMaxLen | Optional: The maximum length of the receive buffer sHost.
nPort | Optional: Variable receiving the current port number of the standardhost.

Return value

  • true if successful

  • false otherwise

Example

benchmark SilkPerformerRecorder

use "Kernel.bdh"
use "BrowserAPI.bdh"

dcluser
  user
    VUser
  transactions
    TInit           : begin;
    TMain           : 1;

var

dclrand

dcltrans
  transaction TInit
  begin
  end TInit;

  transaction TMain
  var
    sHost : string;
    nPort : number;
  begin
    BrowserStart(BROWSER_MODE_DEFAULT, 800, 600);

    // get the standard host name & port and print them
    BrowserGetStandardHost(sHost, STRING_COMPLETE, nPort);
    print("Standardhost: '"+sHost+"'");
    print("Port: '"+string(nPort)+"'");
    // set the standard host name to demo.borland.com and port to 80
    BrowserSetStandardHost("demo.borland.com",80);
    // Navigate to demo.borland.com on port 80
    BrowserNavigate("http://standardhost");
    // set the standard host name to www.google.com and port to 80
    BrowserSetStandardHost("www.google.com");
    // Navigate to www.google.com
    BrowserNavigate("http://standardhost");

    // revert to previous state
    BrowserSetStandardHost(sHost, nPort);
  end TMain;
Parent topic: Browser-Driven Web Load Testing Functions
Related reference
BrowserSetStandardHost Function


BrowserGetText Function

Action

Retrieves the text of any DOM element, like list boxes, radio buttons, and so on.

Include file

BrowserAPI.bdh

Syntax

BrowserGetText( uTestObject : in union,
                sText       : out string ): boolean;
Parameter | Description
uTestObject | The XPath locator or the handle of the DOM element.
sText | The text output parameter.

Return value

  • true if successful

  • false otherwise

Example

benchmark SilkPerformerRecorder

use "Kernel.bdh"
use "BrowserAPI.bdh"

dcluser
  user
    VUser
  transactions
    TInit           : begin;
    TMain           : 1;

var

dclrand

dcltrans
  transaction TInit
  begin
  end TInit;

  transaction TMain
  var
    liHandle : number;
    liText : string;
  begin
    BrowserStart(BROWSER_MODE_DEFAULT, 800, 600);
    BrowserNavigate("http://demo.borland.com");

    // find the first list item (LI) tag on this page and store it into a variable (liHandle)
    liHandle := BrowserFind(HANDLE_DESKTOP, "//LI");
    // Alternative: find the first list item (LI) tag on this page and store it internally (HANDLE_STORED)
    BrowserFind(HANDLE_DESKTOP, "//LI", true);
    // get the text of the list item and print it
    BrowserGetText(liHandle, liText);
    print(liText);
    //Alternative: Get the text of the list item and print it
    BrowserGetText(HANDLE_STORED, liText);
    print(liText);
  end TMain;
Parent topic: Browser-Driven Web Load Testing Functions


BrowserGetUrl Function

Action

Retrieves the current URL from the browser.

Include file

BrowserAPI.bdh

Syntax

BrowserGetUrl( sUrl : out string ): boolean;
Parameter | Description
sUrl | The URL output parameter.

Return value

  • true if successful

  • false otherwise

Example

benchmark SilkPerformerRecorder

use "Kernel.bdh"
use "BrowserAPI.bdh"

dcluser
  user
    VUser
  transactions
    TInit           : begin;
    TMain           : 1;

var

dclrand

dcltrans
  transaction TInit
  begin
  end TInit;

  transaction TMain
  var
    url : string;
  begin
    BrowserStart(BROWSER_MODE_DEFAULT, 800, 600);
    BrowserNavigate("http://demo.borland.com/");

    // get the url of the current browser-window and print it
    BrowserGetUrl(url);
    print(url);
  end TMain;
Parent topic: Browser-Driven Web Load Testing Functions


BrowserHighlight Function

Action

This function can be used to highlight an object by changing its background and foreground color.

Note: All valid HTML color-name formats are supported by this function (for example, both Red and #ff0000 are supported).

Include file

BrowserAPI.bdh

Syntax

BrowserHighlight( uTestObject : in union,
                  sForeground : in string,
                  sBackground : in string ): boolean;
Parameter | Description
uTestObject | The XPath locator or the handle to the DOM element.
sForeground | The foreground color that should be used to highlight the object, for example Red or #ff0000.
sBackground | The background color that should be used to highlight the object, for example Red or #ff0000.

Return value

  • true if successful

  • false otherwise

Example

benchmark SilkPerformerRecorder

use "Kernel.bdh"
use "BrowserAPI.bdh"

dcluser
  user
    VUser
  transactions
    TInit           : begin;
    TMain           : 1;

var

dclrand

dcltrans
  transaction TInit
  begin
  end TInit;

  transaction TMain
  var
    liHandle : number;
  begin
    BrowserStart(BROWSER_MODE_DEFAULT, 800, 600);
    BrowserNavigate("http://demo.borland.com");
    liHandle := BrowserFind(HANDLE_DESKTOP, "//LI");

    // highlight the first list item with a yellow background, wait 5 seconds and then undo the highlighting
    BrowserHighlight(liHandle, "black", "yellow");
    Wait(5.0);
    BrowserUnhighlight(liHandle);
  end TMain;
Parent topic: Browser-Driven Web Load Testing Functions
Related reference
BrowserUnhighlight Function


BrowserIgnoreServerError Function

Action

Modifies the error severity of a specified server error for the subsequent browser-driven function call. This can be done for a specified amount of server errors or for all. Only errors causing Internet Explorer's web browser control to display an error page due to an error in navigation are handled.

Note: This function only works with Internet Explorer.

Include file

BrowserAPI.bdh

Syntax

BrowserIgnoreServerError( in nStatusCode : number,
                          in nSeverity   : number optional := SEVERITY_SUCCESS,
                          in nCount      : number optional );

Return value

  • none

Parameter | Description
nStatusCode | Server status code to ignore or change the severity for (e.g. 404).
nSeverity Optional: Severity of the error that is raised if the verification fails. Can be one of the following values:
  • SEVERITY_SUCCESS: (Default) Success; no error (numerical value: 0)
  • SEVERITY_INFORMATIONAL: Informational; no error (numerical value: 1)
  • SEVERITY_WARNING: Warning; no error (numerical value: 2)
  • SEVERITY_ERROR: Error; simulation continues (numerical value: 3)
  • SEVERITY_TRANS_EXIT: Error; the active transaction is aborted (numerical value: 4)
  • SEVERITY_PROCESS_EXIT: Error; the simulation is aborted (numerical value: 5)
nCount | The specified error can occur nCount times before an error with the default severity is raised. If this parameter is omitted the specified severity is valid for all server responses

Example

benchmark SilkPerformerRecorder

use "BrowserAPI.bdh"

dcluser
  user
    VUser
  transactions
    TMain : 1;

dcltrans

  transaction TMain
  begin
    BrowserStart(BROWSER_MODE_DEFAULT, 800, 600);
    BrowserIgnoreServerError(404, SEVERITY_WARNING, 1);
    BrowserNavigate("http://demo.borland.com")

  end TMain;
Parent topic: Browser-Driven Web Load Testing Functions


BrowserImportCertificate Function

Action

Imports the client certificate from a file into the certificate store of the operating system for later use by Internet Explorer. This function is similar to manually importing certificate files. Note that certificates are shared resources in the operating system. In other words, all Internet Explorer instances access the same certificate store.

The certificate APIs work with Microsoft Windows 7 or later, Microsoft Windows Server 2008 R2 or later, and Internet Explorer 8 or later.

Note: This function only works with Internet Explorer.

Include file

BrowserAPI.bdh

Syntax

BrowserImportCertificate( sFilename        : in  string,
                          sPassword        : in  string,
                          sCertificatename : out string optional,
                          sCertstore       : in  string optional ): boolean;
Parameter | Description
sFilename | The file containing the certificate (PFX or P12).
sPassword | The password for decrypting the contents of the file.
sCertificatename | Optional: The name of the client certificate.
sCertstore | Optional: The certificate store name. When this parameter is not specified certificates are imported into the My store, available on the certificate tab's Personal tab.

Return Value

  • true if successful

  • false otherwise

Example

Note: The following example does not work out-of-the-box, as you first need to set up a certificate in order to execute actions on it.
benchmark SilkPerformerRecorder

use "Kernel.bdh"
use "BrowserAPI.bdh"

dcluser
  user
    VUser
  transactions
    TInit           : begin;
    TMain           : 1;

var

dclrand

dcltrans
  transaction TInit
  begin
  end TInit;

  transaction TMain
  var
    sCertificate : string;
  begin
    BrowserStart(BROWSER_MODE_DEFAULT, 800, 600);

    // import a certificate into the default certificate store
    BrowserImportCertificate("C:\Users\johns\Desktop\BDLT\johns.pfx","password", sCertificate);
    // select the newly imported certificate
    BrowserSetCertificate("John Smith");
    // navigate to the secure site
    BrowserNavigate("https://testsite/clientcert/servervar.asp");
  end TMain;
Parent topic: Browser-Driven Web Load Testing Functions
Related reference
BrowserDeleteCertificate Function
BrowserSetCertificate Function


BrowserLinkSelect Function

Action

Clicks a DOM link. A DOM link represents all DOM elements that were specified using the <A> tag.

Note: This function performs the same action as BrowserClick.

Include file

BrowserAPI.bdh

Syntax

BrowserLinkSelect( uTestObject : in union,
                   sTimer      : in string optional ): boolean;
Parameter | Description
uTestObject | The XPath locator or the handle to the Link.
sTimer | Optional: Name of the timer used for page measurements. If this parameter is omitted, no measurements are performed.

Return value

  • true if successful

  • false otherwise

Example

benchmark SilkPerformerRecorder

use "Kernel.bdh"
use "BrowserAPI.bdh"

dcluser
  user
    VUser
  transactions
    TInit           : begin;
    TMain           : 1;

var

dclrand

dcltrans
  transaction TInit
  begin
  end TInit;

  transaction TMain
  var
    wnd1   : number;
    wnd2   : number;
    check1 : number;
  begin
    BrowserStart(BROWSER_MODE_DEFAULT, 800, 600);
    BrowserNavigate("http://demo.borland.com/TestSite/multiplewindows/multipleWindows.html");
    wnd1 := BrowserGetActiveWindow("mainWindow");
    BrowserLinkSelect("//A[@name='window1']",  "Select, BODY (#1)");
    wnd2 := BrowserGetActiveWindow("first window");
    BrowserActivateWindow(wnd1);
    BrowserLinkSelect("//A[@name='window2']",  "Select, BODY (#1)");

    BrowserCloseWindow(wnd2); // close second window (tab)
    BrowserCloseWindow();     // close active window (tab)
  end TMain;
Parent topic: Browser-Driven Web Load Testing Functions
Related reference
BrowserClick Function


BrowserListBoxMultiSelect Function

Action

Selects multiple items in a DOM list box. A DomListBox represents all DOM elements that are specified using the <select> tag.

Include file

BrowserAPI.bdh

Syntax

BrowserListBoxMultiSelect( uTestObject      : in union,
                           sItemIdentifiers : in string,
                           sTimer           : in string optional ): boolean;
Parameter | Description
uTestObject | The XPath locator or the handle to the list box.
sItemIdentifiers | A comma-separated list of item identifiers. The items can be identified by their name or by their zero-based index. Names can also be combined with an index (for example, you could use blue[2] to identify the second item that has the value of blue).
sTimer | Optional: Name of the timer used for page measurements. If this parameter is omitted, no measurements are performed.

Return value

  • true if successful

  • false otherwise

Example

benchmark SilkPerformerRecorder

use "Kernel.bdh"
use "BrowserAPI.bdh"

dcluser
  user
    VUser
  transactions
    TInit           : begin;
    TMain           : 1;

var

dclrand

dcltrans
  transaction TInit
  begin
  end TInit;

  transaction TMain
  begin
    BrowserStart(BROWSER_MODE_DEFAULT, 800, 600);
    BrowserNavigate("http://demo.borland.com/TestSite/gwt/Showcase.html#CwListBox");

    // select the first three items
    BrowserListBoxMultiSelect("//SELECT[@multiple='-1']", "compact, sedan, coupe");
    // alternatively you can select items based on their zero-based index (select fourth and fifth item)
    BrowserListBoxMultiSelect("//SELECT[@multiple='-1']", "[3], [4]");
  end TMain;
Parent topic: Browser-Driven Web Load Testing Functions
Related reference
BrowserListBoxSelect Function


BrowserListBoxSelect Function

Action

Selects an item in a DOM listbox. A DomListBox represents all DOM elements that are specified using the <select> tag.

Include file

BrowserAPI.bdh

Syntax

BrowserListBoxSelect( uTestObject : in union,
                      vItem       : in union,
                      sTimer      : in string optional ): boolean;
Parameter | Description
uTestObject | The XPath locator or the handle to the Listbox.
vItem | The identifier of the list item to select. Items can be identified by their name or by their zero-based index. Names can also be combined with an index (for example, you could use blue[2] to identify the second item that has the value of blue).
sTimer | Optional: Name of the timer used for page measurements. If this parameter is omitted, no measurements are performed.

Return value

  • true if successful

  • false otherwise

Example

benchmark SilkPerformerRecorder

use "Kernel.bdh"
use "BrowserAPI.bdh"

dcluser
  user
    VUser
  transactions
    TInit           : begin;
    TMain           : 1;

var

dclrand

dcltrans
  transaction TInit
  begin
  end TInit;

  transaction TMain
  begin
    BrowserStart(BROWSER_MODE_DEFAULT, 800, 600);
    BrowserNavigate("http://demo.borland.com/TestSite/gwt/Showcase.html#CwListBox");

    // select the first item in the listbox
    BrowserListBoxSelect("//SELECT[@multiple='-1']", "compact");
    // alternatively you can select items by their index (zero-based)
    BrowserListBoxSelect("//SELECT[@multiple='-1']", 1);    // select the second item
  end TMain;
Parent topic: Browser-Driven Web Load Testing Functions
Related reference
BrowserListBoxMultiSelect Function


BrowserMouseMove Function

Action

Sends a DOM mouse-move event to the specified DOM Element.

Include file

BrowserAPI.bdh

Syntax

BrowserMouseMove( uTestObject : in union,
                  sTimer      : in string optional ): boolean;
Parameter | Description
uTestObject | The XPath locator or the handle to the DOM element.
sTimer | Optional: Name of the timer used for page measurements. If this parameter is omitted, no measurements are performed.

Return value

  • true if successful

  • false otherwise

Example

benchmark SilkPerformerRecorder

use "Kernel.bdh"
use "BrowserAPI.bdh"

dcluser
  user
    VUser
  transactions
    TInit           : begin;
    TMain           : 1;

var

dclrand

dcltrans
  transaction TInit
  begin
  end TInit;

  transaction TMain
  var
    liHandle : number;
  begin
    BrowserStart(BROWSER_MODE_DEFAULT, 800, 600);
    BrowserNavigate("http://demo.borland.com");
    liHandle := BrowserFind(HANDLE_DESKTOP, "//LI");

    // move the mouse to the first list item on the page
    BrowserMouseMove(liHandle);
    // Alternatively you can use the native function
    // which also allows you to specify a relative margin
    BrowserNativeMouseMove(liHandle, 5, 5);
  end TMain;
Parent topic: Browser-Driven Web Load Testing Functions
Related concepts
Native Replay
Related reference
BrowserClick Function
BrowserNativeClick Function
BrowserDoubleClick Function
BrowserNativeDoubleClick Function
BrowserSetText Function
BrowserTypeKeys Function
BrowserSetPassword Function
BrowserNativeMouseMove Function


BrowserNativeClick Function

Action

Clicks a DOM element with a specified position and mouse button. A left-button click executes the default actions of the clicked element type.

Include file

BrowserAPI.bdh

Syntax

BrowserNativeClick( uTestObject : in union,
                    nX          : in number optional,
                    nY          : in number optional,
                    nButton     : in number optional,
                    sTimer      : in string optional ): boolean;
Parameter | Description
uTestObject | Either a locator that identifies the DOM element or a handle to a previously found DOM element. Throws an error if an invalid handle is used or if the locator can not be resolved.
nX | Optional: X position relative to the top left corner of the DOM element. Defaults to the middle of the DOM element. If the middle of the DOM element cannot be clicked, which can be the case when another element is placed in front of it, a different position will be used. If no such position can be found, a legacy click function will be used instead.
nY | Optional: Y position relative to the top left corner of the DOM element. Defaults to the middle of the DOM element. If the middle of the DOM element cannot be clicked, which can be the case when another element is placed in front of it, a different position will be used. If no such position can be found, a legacy click function will be used instead.
nButton | Optional: BUTTON_LEFT to use the left mouse button (default), BUTTON_RIGHT to use the right mouse button. You can combine mouse buttons with modifier keys using an OR operator. Specify MODIFIER_SHIFT, MODIFIER_ALT, or MODIFIER_CTRL for the respective modifier key. For example: BUTTON LEFT | MODIFIER_CTRL
sTimer | Optional: Name of the timer used for page measurements. If this parameter is omitted, no measurements are performed.

Return value

  • true if successful

  • false otherwise

Example

benchmark SilkPerformerRecorder

use "Kernel.bdh"
use "BrowserAPI.bdh"

dcluser
  user
    VUser
  transactions
    TInit           : begin;
    TMain           : 1;

var

dclrand

dcltrans
  transaction TInit
  begin
  end TInit;

  transaction TMain
  begin
    BrowserStart(BROWSER_MODE_DEFAULT, 800, 600);
    BrowserNavigate("http://demo.borland.com/TestSite/gwt/Showcase.html#CwBasicButton");

    // store the button press action to perform when if the dialog with the given name pops up during replay
    BrowserDlgSetButton("Message from webpage #1", "OK");
    // click the button to make the dialog pop up
    BrowserNativeClick("//BUTTON[@textContents='Normal Button']", 5, 5, BUTTON_Left);
    // clear the dialog command storage
    BrowserDlgStop();
  end TMain;
Parent topic: Browser-Driven Web Load Testing Functions
Related concepts
Native Replay
Related reference
BrowserClick Function
BrowserDoubleClick Function
BrowserNativeDoubleClick Function
BrowserSetText Function
BrowserTypeKeys Function
BrowserSetPassword Function
BrowserMouseMove Function
BrowserNativeMouseMove Function


BrowserNativeDoubleClick Function

Action

Double clicks a DOM element with a specified position and mouse button.

The BrowserNativeDoubleClick function uses Windows API level events to simulate the mouse events. Another difference to the BrowserDoubleClick function is that you can specify a mouse position relative to the top left corner of the DOM element which is specified by the uTestObject parameter.

Include file

BrowserAPI.bdh

Syntax

BrowserNativeDoubleClick( uTestObject : in union,
                          nX          : in number optional,
                          nY          : in number optional,
                          nButton     : in number optional,
                          sTimer      : in string optional ): boolean;
Parameter | Description
uTestObject | Either a locator that identifies the DOM element or a handle to a previously found DOM element. Throws an error if an invalid handle is used or if the locator cannot be resolved.
nX | Optional: X position relative to the top left corner of the DOM element. Defaults to the middle of the DOM element. If the middle of the DOM element cannot be clicked, which can be the case when another element is placed in front of it, a different position will be used. If no such position can be found, a legacy click function will be used instead.
nY | Optional: Y position relative to the top left corner of the DOM element. Defaults to the middle of the DOM element. If the middle of the DOM element cannot be clicked, which can be the case when another element is placed in front of it, a different position will be used. If no such position can be found, a legacy click function will be used instead.
nButton | Optional: BUTTON_LEFT to use the left mouse button (default), BUTTON_RIGHT to use the right mouse button. You can combine mouse buttons with modifier keys using an OR operator. Specify MODIFIER_SHIFT, MODIFIER_ALT, or MODIFIER_CTRL for the respective modifier key. For example: BUTTON LEFT | MODIFIER_CTRL
sTimer | Optional: Name of the timer used for page measurements. If this parameter is omitted, no measurements are performed.

Return value

  • true if successful

  • false otherwise

Example

benchmark SilkPerformerRecorder

use "Kernel.bdh"
use "BrowserAPI.bdh"

dcluser
  user
    VUser
  transactions
    TInit           : begin;
    TMain           : 1;

var

dclrand

dcltrans
  transaction TInit
  begin
  end TInit;

  transaction TMain
  var
    wnd1 : number;
  begin
    BrowserStart(BROWSER_MODE_DEFAULT, 1230, 564);
    BrowserNavigate("http://demo.borland.com/InsuranceWebExtJS/", "Navigate to demo site (#1)");
    wnd1 := BrowserGetActiveWindow("wnd1");
    BrowserListBoxSelect("//SELECT[@id='quick-link:jump-menu']", "Agent Lookup",
      "ListBoxSelect, SELECT, name=quick-link:jump-menu (#1)");
    BrowserClick("//INPUT[@id='show-all:search-all']", BUTTON_Left, "Click, INPUT, name=show-all:search-all (#1)");
    BrowserNativeDoubleClick("//DIV[@textContents='Walker']", 10, 20, BUTTON_Left, "DoubleClick, DIV, textContents=Walker (#1)");
    BrowserClick("//DIV[@unselectable='on'][30]/DIV[@hideFocus='0']", BUTTON_Left);
    BrowserClick("//A[@textContents='Home'][2]", BUTTON_Left, "Click, A, textContents=Home (#1)");
  end TMain;
Parent topic: Browser-Driven Web Load Testing Functions
Related concepts
Native Replay
Related reference
BrowserClick Function
BrowserNativeClick Function
BrowserDoubleClick Function
BrowserSetText Function
BrowserTypeKeys Function
BrowserSetPassword Function
BrowserMouseMove Function
BrowserNativeMouseMove Function


BrowserNativeMouseMove Function

Action

Sends a mouse-move event to the specified DOM element with a specified position.

The BrowserNativeMouseMove function uses the Windows API level events to simulate the mouse events instead of Java script events. Another difference to the BrowserMouseMove function is that you can specify a mouse position relative to the top left corner of the DOM element which is specified by the uTestObject parameter.

Include file

BrowserAPI.bdh

Syntax

BrowserNativeMouseMove( uTestObject : in union,
                        nX          : in number optional,
                        nY          : in number optional,
                        sTimer      : in string optional ): boolean;
Parameter | Description
uTestObject | The XPath locator or the handle to the DOM element.
nX | Optional: X position relative to the top left corner of the DOM element. Defaults to the middle of the DOM element.
nY | Optional: Y position relative to the top left corner of the DOM element. Defaults to the middle of the DOM element.
sTimer | Optional: Name of the timer used for page measurements. If this parameter is omitted, no measurements are performed.

Return value

  • true if successful

  • false otherwise

Example

benchmark SilkPerformerRecorder

use "Kernel.bdh"
use "BrowserAPI.bdh"

dcluser
  user
    VUser
  transactions
    TInit           : begin;
    TMain           : 1;

var

dclrand

dcltrans
  transaction TInit
  begin
  end TInit;

  transaction TMain
  var
    liHandle : number;
  begin
    BrowserStart(BROWSER_MODE_DEFAULT, 800, 600);
    BrowserNavigate("http://demo.borland.com");
    liHandle := BrowserFind(HANDLE_DESKTOP, "//LI");

    // move the mouse to the first list item on the page
    BrowserMouseMove(liHandle);
    // Alternatively you can use the native function
    // which also allows you to specify a relative margin
    BrowserNativeMouseMove(liHandle, 5, 5);
  end TMain;
Parent topic: Browser-Driven Web Load Testing Functions
Related concepts
Native Replay
Related reference
BrowserClick Function
BrowserNativeClick Function
BrowserDoubleClick Function
BrowserNativeDoubleClick Function
BrowserSetText Function
BrowserTypeKeys Function
BrowserSetPassword Function
BrowserMouseMove Function


BrowserNavigate Function

Action

Navigates to a specified URL.

Include file

BrowserAPI.bdh

Syntax

BrowserNavigate( sUrl   : in string,
                 sTimer : in string optional ): boolean;
Parameter | Description
sUrl | The destination URL.
sTimer | Optional: Name of the timer used for page measurements. If this parameter is omitted, no measurements are performed.

Return value

  • true if successful

  • false otherwise

Example

benchmark SilkPerformerRecorder

use "Kernel.bdh"
use "BrowserAPI.bdh"

dcluser
  user
    VUser
  transactions
    TInit           : begin;
    TMain           : 1;

var

dclrand

dcltrans
  transaction TInit
  begin
  end TInit;

  transaction TMain
  begin
    BrowserStart(BROWSER_MODE_DISPLAY_VISIBLE, 800, 600);
    BrowserNavigate("http://demo.borland.com/"); // navigate to demo.borland.com
  end TMain;
Parent topic: Browser-Driven Web Load Testing Functions
Related reference
BrowserSetStandardHost Function


BrowserPause Function

Action

This API call only works in Try Script mode with the Visible client option enabled for Internet Explorer (Browser Application). This function enables step-by-step mode so the execution of a Try Script run is paused before the next API call is executed.

Include file

BrowserAPI.bdh

Syntax

BrowserPause( );

Example

benchmark SilkPerformerRecorder

use "Kernel.bdh"
use "BrowserAPI.bdh"
use "WebAPI.bdh"

dcluser
  user
    BDLTUser
  transactions
    TInit           : begin;
    TMain(BROWSER_MODE_DISPLAY_VISIBLE) : 1;

  var
    gDemoSite:string;

dclrand

dcltrans
  transaction TInit
  begin
    gDemoSite := "http://demo.borland.com/InsuranceWebExtJS/";
  end TInit;

  transaction TMain(mode:number)
  var
    sQuote,sExpected : string;
  begin
    BrowserStart(BROWSER_MODE_DISPLAY_VISIBLE | BROWSER_MODE_USERBEHAVIOR_FIRST_TIME);
    BrowserNavigate(gDemoSite, "Navigate to Demo Site");
    if BrowserFind(HANDLE_DESKTOP , "//LABEL[@textContents='John Smith']", false, 0, true) = HANDLE_INVALID then
      BrowserClick("//INPUT[@id='login-form:email']", BUTTON_Left);
      BrowserSetText("//INPUT[@id='login-form:email']", "john.smith@gmail.com");
      BrowserClick("//INPUT[@id='login-form:password']", BUTTON_Left);
      BrowserSetText("//INPUT[@id='login-form:password']", "john");
      BrowserButtonSelect("//INPUT[@id='login-form:login']", "BrowserButtonSelect (#1)");
    BrowserClick("//IMG[@hideFocus='0'][2]", BUTTON_Left, "BrowserClick (#3)");
     BrowserPause();
    BrowserClick("//DIV[@textContents='Chrysler']", BUTTON_Left, "BrowserClick (#4)");
    BrowserClick("//IMG[@hideFocus='0'][3]", BUTTON_Left, "BrowserClick (#5)");
    BrowserClick("//DIV[@textContents='Aspen']", BUTTON_Left);
    BrowserRadioButtonSelect("//INPUT[@id='autoquote:finInfo:0']");
    BrowserButtonSelect("//INPUT[@id='autoquote:next']", "BrowserButtonSelect (#4)");
    BrowserLinkSelect("//A[@textContents='Home']", "Select, A, textContents=Home (#1)");
    BrowserButtonSelect("//INPUT[@id='logout-form:logout']",
      "Select, INPUT, href=http://demo.borland.com/InsuranceWebExtJS/index.jsf (#1)");
  end TMain;
Parent topic: Browser-Driven Web Load Testing Functions


BrowserRadioButtonSelect Function

Action

This function applies to <INPUT TYPE="RADIO"> HTML elements. It selects the radio button identified by the locator or handle respectively.

Include file

BrowserAPI.bdh

Syntax

BrowserRadioButtonSelect( uTestObject : in union,
                          sTimer      : in string optional ): boolean;
Parameter | Description
uTestObject | The XPath locator or the handle to the DOM element.
sTimer | Optional: Name of the timer used for page measurements. If this parameter is omitted, no measurements are performed.

Return value

  • true if successful

  • false otherwise

Example

benchmark SilkPerformerRecorder

use "Kernel.bdh"
use "BrowserAPI.bdh"

dcluser
  user
    VUser
  transactions
    TInit           : begin;
    TMain           : 1;

var

dclrand

dcltrans
  transaction TInit
  begin
  end TInit;

  transaction TMain
   begin
    BrowserStart(BROWSER_MODE_DEFAULT, 800, 600);
    BrowserNavigate("http://demo.borland.com/TestSite/gwt/Showcase.html#CwRadioButton");

    // check the first radio button
    BrowserRadioButtonSelect("//INPUT[@name='color'][1]");
    // chek the fourth radio button
    BrowserRadioButtonSelect("//INPUT[@name='color'][4]");
  end TMain;
Parent topic: Browser-Driven Web Load Testing Functions


BrowserReload Function

Action

Equivalent to clicking the Web browser Reload button.

Include file

BrowserAPI.bdh

Syntax

BrowserReload( bBypassCache : in boolean ): boolean;
Parameter | Description
bBypassCache | If true, the cache is not used for reload and resources are reloaded even if they are cached.

Return value

  • true if successful

  • false otherwise

Example

benchmark SilkPerformerRecorder

use "Kernel.bdh"
use "BrowserAPI.bdh"

dcluser
  user
    VUser
  transactions
    TInit           : begin;
    TMain           : 1;

var

dclrand

dcltrans
  transaction TInit
  begin
  end TInit;

  transaction TMain
  begin
    // start the browser in visible mode with a width of 800 and a height of 600 pixels
    BrowserStart(BROWSER_MODE_DISPLAY_VISIBLE, 800, 600);
    // navigate to demo.borland.com
    BrowserNavigate("http://demo.borland.com/");
    // reload the page
    BrowserReload(true);
  end TMain;
Parent topic: Browser-Driven Web Load Testing Functions
Related reference
BrowserBack Function
BrowserForward Function


BrowserReplayCompatibility Function

Action

Sets the replay compatibility by defining how locators are generated. During recording, Silk Performer automatically scripts this function to avoid compatibility issues. You can also manually add this function to your script to ensure flawless replay of older scripts with newer versions of Silk Performer. The replay compatibility can also be set in the Profile settings. If this function is omitted or removed from the script, the value configured in the Profile settings will be used.

Include file

BrowserAPI.bdh

Syntax

BrowserReplayCompatibility( in sCompatibility : string ): boolean;
Parameter Description
sCompatibility The replay compatibility option. Can be one of the following values:
  • SP_19_0: for Silk Performer 19.0 and newer
  • SP_15_5: for Silk Performer from version 15.5 to version 18.5
  • SP_10_0: for Silk Performer from version 10.0 to version 15.0
  • SP_9_5: for Silk Performer 9.5

Return value

  • true if successful

  • false otherwise

Example

benchmark SilkPerformerRecorder

use "BrowserAPI.bdh"

dcluser
  user
    VUser
  transactions
    TMain : 1;

dcltrans

  transaction TMain
  begin
    BrowserStart(BROWSER_MODE_DEFAULT, 800, 600);
    BrowserReplayCompatibility(SP_19_0);
    BrowserNavigate("http://demo.borland.com ")

  end TMain;
Parent topic: Browser-Driven Web Load Testing Functions


BrowserReset Function

Action

Resets the browser state (cookies, cache and history).

Note: BrowserStart also resets the browser state.

Include file

BrowserAPI.bdh

Syntax

BrowserReset( nMode : in number optional ): boolean;
Parameter Description
nMode Optional: Configures virtual user behaviour and browser visibility. The following constants may be used:
  • BROWSER_MODE_DEFAULT: Uses the profile settings.
  • BROWSER_MODE_DISPLAY_VISIBLE: Shows the browser window of each virtual user.
  • BROWSER_MODE_DISPLAY_INVISIBLE (default): Runs the browsers of the virtual users in hidden mode (does not apply for Try Script runs).
  • BROWSER_MODE_USERBEHAVIOR_DISABLE: Disables resetting the browser at end of transaction.
  • BROWSER_MODE_USERBEHAVIOR_FIRST_TIME: Clears virtual user browser state. Overrides the profile settings.
  • BROWSER_MODE_USERBEHAVIOR_REVISITING: Resets the non-persistent session, but does not delete the persistent cookies, cache, and history. Overrides the profile settings.

Return value

  • true if successful

  • false otherwise

Example

benchmark SilkPerformerRecorder

use "Kernel.bdh"
use "BrowserAPI.bdh"

dcluser
  user
    VUser
  transactions
    TInit           : begin;
    TMain           : 1;

var

dclrand

dcltrans
  transaction TInit
  begin
  end TInit;

  transaction TMain
  var
    sHost : string;
    nPort : number;
  begin
    BrowserStart(BROWSER_MODE_USERBEHAVIOR_REVISITING, 800, 600);

    // get the standard host name & port and print them
    BrowserGetStandardHost(sHost, STRING_COMPLETE, nPort);
    print("Standardhost: '"+sHost+"'");
    print("Port: '"+string(nPort)+"'");
    // set the standard host name to demo.borland.com and port to 80
    BrowserSetStandardHost("demo.borland.com",80);
    // navigate to demo.borland.com on port 80
    BrowserNavigate("http://standardhost");
    // set the standard host name to www.google.com and port to 80
    BrowserSetStandardHost("www.google.com");
    // reset the browser state
    BrowserReset(BROWSER_MODE_USERBEHAVIOR_FIRST_TIME);
    // navigate to www.google.com
    BrowserNavigate("http://standardhost");

    // revert to previous state
    BrowserSetStandardHost(sHost, nPort);
  end TMain;
Parent topic: Browser-Driven Web Load Testing Functions
Related reference
BrowserStart Function
BrowserStop Function


BrowserSetAuthentication Function

Action

Sets username and password for a subsequent authentication attempt. Usually the username and password must be typed into an authentication dialog for authentication purposes. This function stores both strings temporarily so that they can be used for authentication with the following API call. The password string is never visible in the replay pane of the browser application nor shown by TrueLog Explorer.

Note: This function only works with Internet Explorer.

Include file

BrowserAPI.bdh

Syntax

BrowserSetAuthentication( sUsername : in string,
                          sPassword : in string ): boolean;
Parameter | Description
sUsername | The username for a subsequent authentication attempt.
sPassword | The password for a subsequent authentication attempt.

Return value

  • true if successful

  • false otherwise

Example:

benchmark SilkPerformerRecorder

use "Kernel.bdh"
use "BrowserAPI.bdh"

dcluser
  user
    VUser
  transactions
    TInit           : begin;
    TMain           : 1;

var

dclrand

dcltrans
  transaction TInit
  begin
  end TInit;

  transaction TMain
  begin
    BrowserStart(BROWSER_MODE_DEFAULT, 800, 600);

    // set the authentication for the secure site
    BrowserSetAuthentication("BasicAuthUser", "BasicAuthPass");
    // navigate to the secure site
    BrowserNavigate("http://demo.borland.com/TestSite/secure_sub1/secure_authrequ.asp?LOGON_USER=BasicAuthUser");
  end TMain;
Parent topic: Browser-Driven Web Load Testing Functions


BrowserSetBrowserType Function

Action

Sets the browser type to be used for the simulation. Make sure that BrowserSetBrowserType is executed before BrowserStart.
Note: BrowserSetBrowserType also overrules the browser defined in the Try Script dialog.

Include file

BrowserAPI.bdh

Syntax

BrowserSetBrowserType( in nBrowserType : number): boolean;
Parameter Description
nBrowserType The following constants can be used:
  • BROWSER_BROWSERTYPE_EMBEDDED_IE: Replays using Internet Explorer.
  • BROWSER_BROWSERTYPE_FIREFOX: Replays using the installed Mozilla Firefox browser.
  • BROWSER_BROWSERTYPE_CHROME: Replays using the installed Google Chrome browser.

Return value

  • true if successful
  • false otherwise

Example

benchmark SilkPerformerRecorder

use "Kernel.bdh"
use "BrowserAPI.bdh"

dcluser
  user
    VUser
  transactions
    TInit           : begin;
    TMain           : 1;

var

dclrand

dcltrans
  transaction TInit
  begin
  end TInit;

  transaction TMain
  begin
    BrowserSetBrowserType(BROWSER_BROWSERTYPE_CHROME);
    BrowserStart(BROWSER_MODE_DEFAULT, 800, 600);
  end TMain;
Parent topic: Browser-Driven Web Load Testing Functions


BrowserSetCertificate Function

Action

Sets a client certificate of a given name for authentication and encryption purposes. Usually the certificate to be used must be selected via a selection dialog box. This function stores the certificate temporarily in the Silk Performer runtime so that it can be used by the following API call without user interaction.

The certificate APIs work with Microsoft Windows 7 or later, Microsoft Windows Server 2008 R2 or later, and Internet Explorer 8 or later.

Note: Review the following Microsoft support article for more details: http://support.microsoft.com/KB/308087. In particular, note that the Internet Explorer option Check for server certificate revocation must be disabled.
Note: This function only works with Internet Explorer.

Include file

BrowserAPI.bdh

Syntax

BrowserSetCertificate( sCertificatename : in string,
                       sCertstore       : in string optional ): boolean;
Parameter | Description
sCertificatename | The certificate to be used.
sCertstore | Optional: The certificate store name. When this parameter is not specified certificates are loaded from the My store, available on the certificate tab's Personal tab.

Return Value

  • true if successful

  • false otherwise

Example

Note: The following example does not work out-of-the-box, as you first need to set up a certificate in order to execute actions on it.
benchmark SilkPerformerRecorder

use "Kernel.bdh"
use "BrowserAPI.bdh"

dcluser
  user
    VUser
  transactions
    TInit           : begin;
    TMain           : 1;

var

dclrand

dcltrans
  transaction TInit
  begin
  end TInit;

  transaction TMain
  begin
    BrowserStart(BROWSER_MODE_DEFAULT, 800, 600);

    // set the authentication for the secure site
    BrowserSetCertificate("John Smith");
    // navigate to the secure site
    BrowserNavigate("https://testsite/clientcert/servervar.asp");
  end TMain;
Parent topic: Browser-Driven Web Load Testing Functions
Related reference
BrowserDeleteCertificate Function
BrowserImportCertificate Function


BrowserSetDomainSuppress Function

Action

Suppresses content in a Web page which is hosted on another domain, for example popup ads or traffic to social networking sites. Connections to the suppressed domains will not be established so that the requests are not performed. Whenever a connection is suppressed, an informational line is scripted to the VU output pane. To reset the list of suppressed domains call BrowserSetDomainSuppress with an empty string as parameter value.

Note: This function only works with Internet Explorer.

Include file

BrowserAPI.bdh

Syntax

BrowserSetDomainSuppress( in sDomains : string,
                          in bExclude : boolean optional );
Parameter | Description
sDomains | List of domains to be suppressed. Substrings of domains are also suppressed (for example, "us.com" will also suppress "microfocus.com"). Specify an empty string to lift the restrictions. Allowed separators are blank spaces, commas, and semicolons.
bExclude | Optional: If true, all domains except the domains in sDomains will be suppressed. Default is false.

Example

dcltrans
  transaction TMain
  begin
    BrowserSetDomainSuppress("addthis.com");
    BrowserNavigate("www.mycompany.com");
  end TMain;
Parent topic: Browser-Driven Web Load Testing Functions


BrowserSetIEMode Function

Action

Sets the IE compatibility mode for the browser-driven Web load testing feature. This API call has to be called before the BrowserStart function when browser applications are starting. Because this is a global setting, all running instances are affected when started depending on the current value.
Note: This function only works if Compatibility View is disabled in Internet Explorer. To disable Compatibility View in Internet Explorer 9, choose Tools > Compatibility View settings and uncheck the Display intranet sites in Compatibility View check box.

Include file

BrowserAPI.bdh

Syntax

BrowserSetIEMode( nMode : in number ): boolean;
Parameter Description
nMode The IE mode used for the browser-driven Web load testing feature. The following values may be used:
  • BROWSER_IE_DEFAULT := 0;
  • BROWSER_IE7_MODE := 7000;
  • BROWSER_IE8_MODE := 8000;
  • BROWSER_IE8_REGARDLESS_OF_DOCTYPE := 8888;
  • BROWSER_IE9_MODE := 9000;
  • BROWSER_IE9_REGARDLESS_OF_DOCTYPE := 9999;
  • BROWSER_IE10_MODE := 10000;
  • BROWSER_IE10_REGARDLESS_OF_DOCTYPE := 10001;
  • BROWSER_IE11_MODE := 11000;
  • BROWSER_IE11_REGARDLESS_OF_DOCTYPE := 11001;

Return value

  • true if successful

  • false otherwise

Example

benchmark SilkPerformerRecorder

use "Kernel.bdh"
use "BrowserAPI.bdh"

dcluser
  user
    VUser
  transactions
    TInit           : begin;
    TMain           : 1;

var

dclrand

dcltrans
  transaction TInit
  begin
  end TInit;

  transaction TMain
  var
    ieMode : number;
  begin
    BrowserSetIEMode(BROWSER_IE7_MODE);
    BrowserStart(BROWSER_MODE_DEFAULT, 800, 600);

    // retrieve the IE mode and store it into a variable (ieMode)
    ieMode:= BrowserGetIEMode();
    // print out the ieMode
    print(string(ieMode));
  end TMain;
Parent topic: Browser-Driven Web Load Testing Functions
Related concepts
Browser-Driven Load Testing Overview
Related reference
BrowserGetIEMode Function


BrowserSetOption Function

Action

Sets a BrowserEngine option.

Include file

BrowserAPI.bdh

Syntax

BrowserSetOption( sOption : in string,
                  vValue  : in union ): boolean;
Parameter | Description
sOption The BrowserEngine option. Can be one of the following values:
  • BROWSER_OPT_WAIT_TIMEOUT: Defines a timeout in milliseconds. Silk Performer waits to resolve an element until it is found or the timeout is reached. The default timeout is 5000 ms.
  • BROWSER_OPT_SYNC_TIMEOUT: Defines a timeout in milliseconds after which the synchronization aborts. Synchronization normally waits until the browser is in an idle state. If this state is not achieved, synchronization aborts after the defined timeout. The default timeout is 300000 ms.
  • BROWSER_OPT_SYNC_MODE: Defines the synchronization mode:
    • SYNC_MODE_AJAX: The AJAX mode synchronization waits for the browser to be in a kind of idle state, which is especially useful for AJAX applications or pages that contain AJAX components. Using the AJAX mode eliminates the need to manually script synchronization functions, which eases the script creation process dramatically. This automatic synchronization is also the basis for a successful record and replay approach.
    • SYNC_MODE_HTML: Using the HTML mode ensures that all HTML documents are in an interactive state. With this mode, you can test simple Web pages.
  • BROWSER_OPT_FILEDOWNLOAD_SAVEFILE: Defines if downloaded files, triggered by BrowserDlgDownload, should be saved from the Internet Explorer cache to the results directory:
    • FILEDOWNLOAD_SAVEFILE_SAVENONE: Files are not copied from the cache to the results directory.
    • FILEDOWNLOAD_SAVEFILE_SAVELAST: Files are copied from the cache to the results directory. If a version of the file already exists it gets replaced, so only the last downloaded file is saved in the results directory.
    • FILEDOWNLOAD_SAVEFILE_SAVEALL: All downloaded files are copied from the cache to the results directory. A timestamp is added to the filename so that all filenames are unique.
    If the BROWSER_OPT_FILEDOWNLOAD_SAVEFILE option is not specified, all downloaded files are copied from the browser cache to the results directory for Try Script runs, and for load test runs and find baseline runs no files are copied to the results directory. It is recommended not to copy any files to the results directory for load test runs, as this could result in huge amounts of data being saved on the local disk, and this data will also need to be copied from the agent machines to the controller.
  • BROWSER_OPT_FILEDOWNLOAD_BEGIN_TIMEOUT: Defines a timeout in milliseconds. The BrowserDlgStop call waits for a download to begin until this timeout is reached before returning an error. If this value is not specified, the default value of 20 seconds is applied.
  • BROWSER_OPT_LEGACY_INPUT_MODE: Set this parameter to true to turn off the automatic native replay. This state is also referred to as the legacy input mode. The legacy input mode is turned on by default for all project profiles created using Silk Performer 9.0 or earlier.
vValue | The new value for the selected option. See sOption description for details.

Return value

  • true if successful

  • false otherwise

Example

benchmark SilkPerformerRecorder

use "Kernel.bdh"
use "BrowserAPI.bdh"

dcluser
  user
    VUser
  transactions
    TInit           : begin;
    TMain           : 1;

var

dclrand

dcltrans
  transaction TInit
  begin
  end TInit;

  transaction TMain
  var
    nWaitTimeout : number;
  begin
    BrowserStart(BROWSER_MODE_DEFAULT, 800, 600);

    // get the wait timeout and print it
    BrowserGetOption(BROWSER_OPT_WAIT_TIMEOUT, nWaitTimeout);
    print(string(nWaitTimeout));
    // set the wait timeout to a new value
    BrowserSetOption(BROWSER_OPT_WAIT_TIMEOUT, 6000);
    // revert it back to the old setting
    BrowserSetOption(BROWSER_OPT_WAIT_TIMEOUT, nWaitTimeout);
  end TMain;
Parent topic: Browser-Driven Web Load Testing Functions
Related reference
BrowserDlgDownload Function
BrowserDlgStop Function
BrowserDlgDownloadCancel Function


BrowserSetPassword Function

Action

Sets the password of a text field or text area element. This function is equivalent to the BrowserSetText function except that the password string is never visible in the replay pane of the browser application or shown by TrueLog Explorer.

Include file

BrowserAPI.bdh

Syntax

BrowserSetPassword( uTestObject           : in union,
                    sPassword             : in string,
                    bForceLegacyInputMode : in boolean optional ): boolean;
Parameter | Description
uTestObject | The XPath locator or the handle to the DOM element.
sPassword | The password to be set.
bForceLegacyInputMode | Optional: Replays the BrowserSetPassword function in legacy input mode even if Legacy input mode is disabled or BrowserSetOption(BROWSER_OPT_LEGACY_INPUT_MODE, true) is scripted (JavaScript events instead of Windows API-level events). Default is FALSE.

Return value

  • true if successful

  • false otherwise

Example

benchmark SilkPerformerRecorder

use "Kernel.bdh"
use "BrowserAPI.bdh"

dcluser
  user
    VUser
  transactions
    TInit           : begin;
    TMain           : 1;

var

dclrand

dcltrans
  transaction TInit
  begin
  end TInit;

  transaction TMain
  begin
    BrowserStart(BROWSER_MODE_DEFAULT, 800, 600);

    // navigate to the login site
    BrowserNavigate("http://demo.borland.com/TestSite/LoginForm.html");
    // set the authentication for the secure site
    BrowserSetText("//INPUT[@name='user']", "BasicAuthUser");
    BrowserSetPassword("//INPUT[@name='pwd']", Decrypt3DES("Ax7/X9sk1kIfHlbAZ434Pq4="));
    // submit the form
    BrowserClick("//INPUT[@value='Submit Query']", BUTTON_Left);
  end TMain;
Parent topic: Browser-Driven Web Load Testing Functions
Related concepts
Native Replay
Related reference
BrowserClick Function
BrowserNativeClick Function
BrowserDoubleClick Function
BrowserNativeDoubleClick Function
BrowserSetText Function
BrowserTypeKeys Function
BrowserMouseMove Function
BrowserNativeMouseMove Function


BrowserSetProperty Function

Action

Changes the property values of the respective DOM element.

Include file

BrowserAPI.bdh

Syntax

BrowserSetProperty( uTestObject       : in union,
                    sDomPropertyName  : in string,
                    vDomPropertyValue : in union ): boolean;
Parameter | Description
uTestObject | The XPath locator or the handle to the DOM element.
sDomPropertyName | The DOM property name.
vDomPropertyValue | The value of the property.

Return value

  • true if successful

  • false otherwise

Example

benchmark SilkPerformerRecorder

use "Kernel.bdh"
use "BrowserAPI.bdh"

dcluser
  user
    VUser
  transactions
    TInit           : begin;
    TMain           : 1;

var

dclrand

dcltrans
  transaction TInit
  begin
  end TInit;

  transaction TMain
  var
    propertyValue : boolean;
  begin
    BrowserStart(BROWSER_MODE_DEFAULT, 800, 600);
    BrowserNavigate("http://demo.borland.com/TestSite/gwt/Showcase.html#CwCheckBox");

    // check Monday
    BrowserSetProperty("//SPAN[@hideFocus='0']/INPUT[@hideFocus='0']", "checked", true);
    // get the value of the checked property and print it
    BrowserGetProperty("//SPAN[@hideFocus='0']/INPUT[@hideFocus='0']","checked", propertyValue);
    print(string(propertyValue));

    // uncheck Monday
    BrowserSetProperty("//SPAN[@hideFocus='0']/INPUT[@hideFocus='0']", "checked", false);
    // get the value of the checked property and print it
    BrowserGetProperty("//SPAN[@hideFocus='0']/INPUT[@hideFocus='0']","checked", propertyValue);
    print(string(propertyValue));
  end TMain;
Parent topic: Browser-Driven Web Load Testing Functions
Related reference
BrowserGetProperty Function
BrowserVerifyProperty Function


BrowserSetProxy

Action

Sets the proxy host name and port for a specific protocol.
Note: This function only works with Internet Explorer.

Include file

BrowserAPI

Syntax

BrowserSetProxy( in nProxyType : number,
                 in sHost      : string,
                 in nPort      : number ): boolean;
Parameter | Description
nProxyType Proxy type. Can be one of the following types:
  • BROWSER_PROXY_HTTP
  • BROWSER_PROXY_FTP
  • BROWSER_PROXY_HTTPS
  • BROWSER_PROXY_SOCKS
sHost | Host name of the proxy server. Specify an empty string ("") to establish a direct connection for the specific protocol.
nPort | Port that the proxy server listens to.

Return value

  • true if successful

  • false otherwise

Example

transaction TMain
begin
  BrowserStart(BROWSER_MODE_DEFAULT, 800, 600);
  BrowserSetProxy(BROWSER_PROXY_HTTP, "proxy.mydomain.com", 8080);
  BrowserNavigate("www.mycompany.com");
end TMain;
Parent topic: Browser-Driven Web Load Testing Functions
Related reference
BrowserGetProxy
BrowserGetProxyAutoConfigFile
BrowserGetProxyBypass
BrowserSetProxyAutoConfigFile
BrowserSetProxyBypass


BrowserSetProxyAutoConfigFile

Action

Specifies the location of a PAC (Proxy Auto-Configuration) file.
Note: This function only works with Internet Explorer.

Include file

BrowserAPI

Syntax

BrowserSetProxyAutoConfigFile( in sConfigUrl : string ): boolean;
Parameter | Description
sConfigUrl | Specifies the location of the PAC file. This may be a Web URL like http://localhost:81/proxy.pac or it may be a file location like file://K:/temp/proxy.pac. Specify an empty string ("") to reset this setting.

Return value

  • true if successful

  • false otherwise

Example

transaction TMain
begin
  BrowserStart(BROWSER_MODE_DEFAULT, 800, 600);
  BrowserSetProxyAutoConfigFile("http://proxy.mydomain.com/proxy.pac");
  BrowserNavigate("www.mycompany.com");
end TMain;
Parent topic: Browser-Driven Web Load Testing Functions
Related reference
BrowserGetProxy
BrowserGetProxyAutoConfigFile
BrowserGetProxyBypass
BrowserSetProxy
BrowserSetProxyBypass


BrowserSetProxyBypass

Action

Sets the names of hosts that are not be accessed through a proxy.
Note: This function only works with Internet Explorer.

Include file

BrowserAPI

Syntax

BrowserSetProxyBypass( in bBypassLocal : boolean,
                       in sBypassList  : string optional ): boolean;
Parameter | Description
bBypassLocal | If this parameter is set to true, the browser-driven functions bypass proxies to hosts that do not contain a period in their names.
sBypassList | Optional: List of host names or IP addresses, or both, that should not be routed through the proxy. The host names are separated by semicolons (;). The list can contain wildcards. Specify an empty string ("") to clear the list.

Return value

  • true if successful

  • false otherwise

Example

transaction TMain
begin
  BrowserStart(BROWSER_MODE_DEFAULT, 800, 600);
  BrowserSetProxy(BROWSER_PROXY_HTTP, "proxy.mydomain.com", 8080);
  BrowserSetProxyBypass(false, "www.mycompany.com");
  BrowserNavigate("www.mycompany.com");
end TMain;
Parent topic: Browser-Driven Web Load Testing Functions
Related reference
BrowserGetProxy
BrowserGetProxyAutoConfigFile
BrowserGetProxyBypass
BrowserSetProxy
BrowserSetProxyAutoConfigFile


BrowserSetReplayBehavior Function (deprecated)

Action

This function has been deprecated. If you use it in a script, the function BrowserReplayCompatibility will be called instead.

Parent topic: Browser-Driven Web Load Testing Functions
Related reference
BrowserReplayCompatibility Function


BrowserSetScrollPos Function

Action

Scrolls to the specified position inside the active window. In case there are no vertical or horizontal scrollbars, no scrolling will be done. When using the value BROWSER_NO_SCROLL the parameter is ignored.

Note: This function only works with Internet Explorer.

Include file

BrowserAPI.bdh

Syntax

BrowserSetScrollPos( nTop               : in number,
                     nLeft              : in number,
                     nRelativeScrolling : in number optional ): boolean;
Parameter | Description
nTop | The vertical position of the scrollbar. If nRelativeScrolling is set to BROWSER_RELATIVE_SCROLLING this is the offset that is added. Set this parameter to BROWSER_NO_SCROLL if you only want to scroll horizontally.
nLeft | The horizontal position of the scrollbar. If nRelativeScrolling is set to BROWSER_RELATIVE_SCROLLING this is the offset that is added. Set this parameter to BROWSER_NO_SCROLL if you only want to scroll vertically.
nRelativeScrolling | Optional: If this value is set to BROWSER_RELATIVE_SCROLLING, the values of nTop and nLeft are interpreted as offsets.

Return value

  • true if successful
  • false otherwise

Example

benchmark SilkPerformerRecorder

use "Kernel.bdh"
use "BrowserAPI.bdh"

dcluser
  user
    VUser
  transactions
    TInit           : begin;
    TMain           : 1;

var

dclrand

dcltrans
  transaction TInit
  begin
  end TInit;

  transaction TMain
  var
    top  : number;
    left : number;
  begin
    BrowserStart(BROWSER_MODE_DEFAULT, 800, 600);
    BrowserNavigate("http://demo.borland.com/TestSite/htmlparser/forms.asp");

    // scroll one whole page down (e.g. 600 pixels)
    BrowserSetScrollPos(600,0,BROWSER_RELATIVE_SCROLLING);
    // get the actual scroll position
    BrowserGetScrollPos(top, left);
    // print top, left coordinates
    print(string(top));
    print(string(left));
  end TMain;
Parent topic: Browser-Driven Web Load Testing Functions
Related reference
BrowserGetScrollPos Function


BrowserSetStandardHost Function

Action

Sets the replacement name for the predefined host name "standardhost". This replacement is only used for the BrowserNavigate function and is not used for Web functions. If not specified, the default setting is taken from the active profile settings (Settings > Active Profile > Internet > Hosts > Standardhost).

Include file

BrowserAPI.bdh

Syntax

BrowserSetStandardHost( sHost : in string,
                        nPort : in number optional ): boolean;
Parameter | Description
sHost | Replacement name for the predefined host name "standardhost".
nPort | Optional: Port number appended to the replacement name.

Return value

  • true if successful

  • false otherwise

Example

benchmark SilkPerformerRecorder

use "Kernel.bdh"
use "BrowserAPI.bdh"

dcluser
  user
    VUser
  transactions
    TInit           : begin;
    TMain           : 1;

var

dclrand

dcltrans
  transaction TInit
  begin
  end TInit;

  transaction TMain
  var
    sHost : string;
    nPort : number;
  begin
    BrowserStart(BROWSER_MODE_DEFAULT, 800, 600);

    // get the standard host name & port and print them
    BrowserGetStandardHost(sHost, STRING_COMPLETE, nPort);
    print("Standardhost: '"+sHost+"'");
    print("Port: '"+string(nPort)+"'");
    // set the standard host name to demo.borland.com and port to 80
    BrowserSetStandardHost("demo.borland.com",80);
    // Navigate to demo.borland.com on port 80
    BrowserNavigate("http://standardhost");
    // set the standard host name to www.google.com and port to 80
    BrowserSetStandardHost("www.google.com");
    // Navigate to www.google.com
    BrowserNavigate("http://standardhost");

    // revert to previous state
    BrowserSetStandardHost(sHost, nPort);
  end TMain;
Parent topic: Browser-Driven Web Load Testing Functions
Related reference
BrowserGetStandardHost Function
BrowserNavigate Function


BrowserSetText Function

Action

This function can be used to set the text of a text field or text area element. The BrowserSetText function applies to the HTML elements <input type='text'> and <textarea>.

Include file

BrowserAPI.bdh

Syntax

BrowserSetText( uTestObject           : in union,
                sText                 : in string
                bForceLegacyInputMode : in boolean optional ): boolean;
Parameter | Description
uTestObject | The XPath locator or the handle to the DOM element.
sText | The text to be set.
bForceLegacyInputMode | Optional: Replays the BrowserSetText function in legacy input mode even if Legacy input mode is disabled or BrowserSetOption(BROWSER_OPT_LEGACY_INPUT_MODE, true) is scripted (JavaScript events instead of Windows API-level events). Default is FALSE.

Return value

  • true if successful

  • false otherwise

Example

benchmark SilkPerformerRecorder

use "Kernel.bdh"
use "BrowserAPI.bdh"

dcluser
  user
    VUser
  transactions
    TInit           : begin;
    TMain           : 1;

var

dclrand

dcltrans
  transaction TInit
  begin
  end TInit;

  transaction TMain
  begin
    BrowserStart(BROWSER_MODE_DEFAULT, 800, 600);

    // navigate to the login site
    BrowserNavigate("http://demo.borland.com/TestSite/LoginForm.html");
    // set the authentication for the secure site
    BrowserSetText("//INPUT[@name='user']", "BasicAuthUser");
    BrowserSetPassword("//INPUT[@name='pwd']", Decrypt3DES("Ax7/X9sk1kIfHlbAZ434Pq4="));
    // submit the form
    BrowserClick("//INPUT[@value='Submit Query']", BUTTON_Left);
  end TMain;
Parent topic: Browser-Driven Web Load Testing Functions
Related concepts
Native Replay
Related reference
BrowserClick Function
BrowserNativeClick Function
BrowserDoubleClick Function
BrowserNativeDoubleClick Function
BrowserTypeKeys Function
BrowserSetPassword Function
BrowserMouseMove Function
BrowserNativeMouseMove Function


BrowserScreenshot Function

Action

Takes a screenshot during replay and stores it in the TrueLog.

Include file

BrowserAPI.bdh

Syntax

BrowserScreenshot();

Return value

  • true if successful

  • false otherwise

Example

benchmark SilkPerformerRecorder

use "BrowserAPI.bdh"

dcluser
  user
    VUser
  transactions
    TMain : 1;

dcltrans

  transaction TMain
  begin
    BrowserStart(BROWSER_MODE_DEFAULT, 800, 600);
    if not BrowserNavigate("http://demo.borland.com/invalidtarget.html") then
      BrowserScreenshot();
    end;

  end TMain;
Parent topic: Browser-Driven Web Load Testing Functions


BrowserStart Function

Action

BrowserStart is used to start the browser and also to manage virtual user behavior. There are two types of VUsers: Revisiting users and first time users. For first time users, the browser state (cookies, cache, and history) is cleared on each call to BrowserStart. Revisiting users reuse persistent session information.

Note: BrowserReset also resets the browser state.

Include file

BrowserAPI.bdh

Syntax

BrowserStart( nMode : in number optional,
              nHRes : in number optional,
              nVRes : in number optional,
              nXPos : in union optional,
              nYPos : in union optional ): boolean;
Parameter | Description
nMode Optional: Configures virtual user behavior and browser visibility. The following constants may be used:
  • BROWSER_MODE_DEFAULT: Uses the profile settings.
  • BROWSER_MODE_DISPLAY_VISIBLE: Shows the browser window of each virtual user.
  • BROWSER_MODE_DISPLAY_INVISIBLE (default): Runs the browsers of the virtual users in hidden mode (does not apply for Try Script runs).
  • BROWSER_MODE_USERBEHAVIOR_DISABLE: Disables resetting the browser at end of transaction.
  • BROWSER_MODE_USERBEHAVIOR_FIRST_TIME: Clears virtual user browser state. Overrides the profile settings.
  • BROWSER_MODE_USERBEHAVIOR_REVISITING: Resets the non-persistent session, but does not delete the persistent cookies, cache, and history. Overrides the profile settings.
nHRes | Optional: The width of the browser window. If this parameter is not specified, the system defaults are used.
nVRes | Optional: The height of the browser window. If this parameter is not specified, the system defaults are used.
nXPos | Optional: The X-position of the browser on the screen. If this parameter is not specified, the system defaults are used.
nYPos | Optional: The Y-position of the browser on the screen. If this parameter is not specified, the system defaults are used.

Return value

  • true if successful

  • false otherwise

Example

benchmark SilkPerformerRecorder

use "Kernel.bdh"
use "BrowserAPI.bdh"

dcluser
  user
    VUser
  transactions
    TInit           : begin;
    TMain           : 1;

var

dclrand

dcltrans
  transaction TInit
  begin
  end TInit;

  transaction TMain
  var
    options : number;
   begin
    // you can set multiple mode options by logically disjunctioning them.
    options := BROWSER_MODE_DISPLAY_VISIBLE | BROWSER_MODE_USERBEHAVIOR_FIRST_TIME;

    // start the browser with given options and a width of 480 and a height of 320 pixels
    BrowserStart(options, 480, 320);
  end TMain;
Parent topic: Browser-Driven Web Load Testing Functions
Related reference
BrowserReset Function
BrowserStop Function


BrowserStop Function

Action

This function is used to close the browser of a virtual user.

Note: If you only want to restart the browser, consider using BrowserReset or BrowserStart.

Include file

BrowserAPI.bdh

Syntax

BrowserStop(): boolean;

Return value

  • true if successful

  • false otherwise

Example

benchmark SilkPerformerRecorder

use "Kernel.bdh"
use "BrowserAPI.bdh"

dcluser
  user
    VUser
  transactions
    TInit           : begin;
    TMain           : 1;

var

dclrand

dcltrans
  transaction TInit
  begin
  end TInit;

  transaction TMain
  begin
    BrowserStart(BROWSER_MODE_DEFAULT, 800, 600);
    BrowserNavigate("http://demo.borland.com/TestSite/gwt/Showcase.html#CwCheckBox");

    // check Monday
    BrowserCheckBoxSelect("//SPAN[@hideFocus='0']/INPUT[@hideFocus='0']", CHECKBOX_CHECKED);
    // uncheck Monday
    BrowserCheckBoxSelect("//SPAN[@hideFocus='0'][1]/INPUT[@hideFocus='0']", CHECKBOX_UNCHECKED);
    // check Tuesday
    BrowserCheckBoxSelect("//SPAN[@hideFocus='0'][2]/INPUT[@hideFocus='0']", CHECKBOX_CHECKED);

    BrowserStop();
  end TMain;
Parent topic: Browser-Driven Web Load Testing Functions
Related reference
BrowserReset Function
BrowserStart Function


BrowserStore Function

Action

This function can be used to store a handle for reuse. A handle can be obtained by the BrowserFind function. The HANDLE_STORED constant refers to the last handle stored. Alternatively, you can store the handle by passing true to the BrowserFind function for the store parameter.

Include file

BrowserAPI.bdh

Syntax

BrowserStore( nHandle : in number );
Parameter | Description
nHandle | The handle that should be stored.

Return value

  • none

Example

benchmark SilkPerformerRecorder

use "Kernel.bdh"
use "BrowserAPI.bdh"

dcluser
  user
    VUser
  transactions
    TInit           : begin;
    TMain           : 1;

var

dclrand

dcltrans
  transaction TInit
  begin
  end TInit;

  transaction TMain
  var
    liHandle : number;
    liText : string;
  begin
    BrowserStart(BROWSER_MODE_DEFAULT, 800, 600);
    BrowserNavigate("http://demo.borland.com");

    // find the first list item (LI) tag on this page and store it into a variable (liHandle)
    liHandle := BrowserFind(HANDLE_DESKTOP, "//LI");
    // store the handle into the internal handle variable (HANDLE_STORED)
    BrowserStore(liHandle);
    // get the text of the list item and print it
    BrowserGetText(liHandle, liText);
    print(liText);
    //get the text of item represented by the internally stored handle and print it
    BrowserGetText(HANDLE_STORED, liText);
    print(liText);
  end TMain;
Parent topic: Browser-Driven Web Load Testing Functions
Related reference
BrowserFind Function


BrowserTtiIncludeElement Function

Action

Marks an element as relevant for measuring the Time to Interact. A subsequent API call such as BrowserNavigate or BrowserClick starts the actual measurement. You can define any number of TTI elements. The browser waits until all specified TTI elements are found. The slowest element determines the Time to Interact; this value is stored in the results. Furthermore, if TrueLog creation is enabled, additional information about each TTI element is presented in the Truelog file.

Include file

BrowserAPI.bdh

Syntax

BrowserTtiIncludeElement( uTestObject : in union );

Parameter | Description
uTestObject | The XPath locator or the handle to the DOM element.

Return value

  • none

Example

benchmark SilkPerformerRecorder

use "BrowserAPI.bdh"

dcluser
  user
    VUser
  transactions
    TMain           : 1;

dcltrans
  // When navigating to the test site (see 'BrowserNavigate' function below), a download link is created after a few seconds.
  // We can interact with the page only after this download link has appeared.
  // Therefore we define this download link as a TTI element.
  transaction TMain
  begin
    BrowserStart(BROWSER_MODE_DEFAULT, 800, 600);
    BrowserReplayCompatibility(SP_15_5);

    // Mark the download link as TTI element:
    BrowserTtiIncludeElement("//a[@textContents='DOWNLOAD PDF NOW']");
    // Navigate with TTI measurement enabled.
    // The following call will be blocked until the download link appears.
    BrowserNavigate("http://demo.borland.com/testsite/download_appear.html", "Measure_Time_To_Interact");

    // Navigate without TTI measurement.
    // This navigation will finish almost immediately.
    BrowserNavigate("http://demo.borland.com/testsite/download_appear.html", "Measure_Navigation");
  end TMain;
Parent topic: Browser-Driven Web Load Testing Functions
Related concepts
Time to Interact
Related tasks
Including Elements in the TTI


BrowserTypeKeys Function

Action

This function replays keystrokes as if they were entered directly using the keyboard.

BrowserTypeKeys is synchronized as a whole. If you want to synchronize single keystrokes, you have to use single function calls per keystroke.

The BrowserTypeKeys function uses the Windows API level events to simulate the keystrokes instead of Java script events.

To simulate a modifier key (like SHIFT, CTRL or ALT) pressed and held down while pressing another key, use the following syntax: BrowserTypeKeys("//INPUT[@id='gwt-debug-cwBasicText-textbox']","<LEFT_CTRL+a>"). This will simulate a pressed and held down CTRL key and a pressed a key.

Include file

BrowserAPI.bdh

Syntax

BrowserTypeKeys( uTestObject : in union,
                 sKeyChain   : in string,
                 sTimer      : in string optional,
                 uDelay      : in number optional ): boolean;
Parameter | Description
uTestObject | The XPath locator or the handle to the DOM element.
sKeyChain | The key strokes to be issued. For all characters that have a visual representation, that representation can be used to issue the keystrokes. All other keys are referred to as named keys. Named keys can be replayed by using the name of the key within <> as in the example below.
sTimer | Optional: Name of the timer used for page measurements. If this parameter is omitted, no measurements are performed.
uDelay | Optional: Delay (in milliseconds) between the separate key strokes. If omitted, there is no delay.

Return value

  • true if successful

  • false otherwise

Example

benchmark SilkPerformerRecorder

use "Kernel.bdh"
use "BrowserAPI.bdh"

dcluser
  user
    VUser
  transactions
    TInit           : begin;
    TMain           : 1;

var

dclrand

dcltrans
  transaction TInit
  begin
  end TInit;

  transaction TMain
  begin
    BrowserStart(BROWSER_MODE_DEFAULT, 800, 600);
    BrowserNavigate("http://demo.borland.com/TestSite/gwt/Showcase.html#CwBasicText");

    // set the text to 'Hello!'
    BrowserTypeKeys("//INPUT[@id='gwt-debug-cwBasicText-textbox']", "Hello!!<BACKSPACE><ENTER>");
  end TMain;
  • Named Keys
    Lists the named keys that can be recorded and scripted using the BrowserTypeKeys function.
Parent topic: Browser-Driven Web Load Testing Functions
Related concepts
Native Replay
Related reference
BrowserClick Function
BrowserNativeClick Function
BrowserDoubleClick Function
BrowserNativeDoubleClick Function
BrowserSetText Function
BrowserSetPassword Function
BrowserMouseMove Function
BrowserNativeMouseMove Function


Named Keys

This table lists the named keys that can be recorded and scripted using the BrowserTypeKeys function. In the table below, each named key is associated with a virtual key code:

Named Key | Key Code | Named Key | Key Code
ACCEPT | 0x1E | NEXT_TRACK | 0xB0
APPLICATION_KEY | 0x5D | NONCONVERT | 0x1D
ATTN | 0xF6 | NUMLOCK | 0x90
BACKSPACE | 0x08 | NUMPAD_0 | 0x60
BROWSER_BACK | 0xA6 | NUMPAD_1 | 0x61
BROWSER_FAVORITES | 0xAB | NUMPAD_2 | 0x62
BROWSER_FORWARD | 0xA7 | NUMPAD_3 | 0x63
BROWSER_HOME | 0xAC | NUMPAD_4 | 0x64
BROWSER_REFRESH | 0xA8 | NUMPAD_5 | 0x65
BROWSER_SEARCH | 0xAA | NUMPAD_6 | 0x66
BROWSER_STOP | 0xA9 | NUMPAD_7 | 0x67
CAPSLOCK | 0x14 | NUMPAD_8 | 0x68
CLEAR | 0x0C | NUMPAD_9 | 0x69
CONVERT | 0x1C | NUMPAD_ADD | 0x6B
CR_SEL | 0xF7 | NUMPAD_DECIMAL | 0x6E
DELETE | 0x2E | NUMPAD_DELETE | 0x2E
DOWN | 0x28 | NUMPAD_DIVIDE | 0x6F
END | 0x23 | NUMPAD_DOWN | 0x28
ENTER | 0x0D | NUMPAD_END | 0x23
ER_EOF | 0xF9 | NUMPAD_ENTER | 0x0D
ESC | 0x1B | NUMPAD_HOME | 0x24
EX_SEL | 0xF8 | NUMPAD_INSERT | 0x2D
EXECUTE | 0x2B | NUMPAD_LEFT | 0x25
F1 | 0x70 | NUMPAD_PAGE_DOWN | 0x22
F10 | 0x79 | NUMPAD_PAGE_UP | 0x21
F11 | 0x7A | NUMPAD_RIGHT | 0x27
F12 | 0x7B | NUMPAD_SUBTRACT | 0x6D
F13 | 0x7C | NUMPAD_TIMES | 0x6A
F14 | 0x7D | NUMPAD_UP | 0x26
F15 | 0x7E | PA1 | 0xFD
F16 | 0x7F | PAGE_DOWN | 0x22
F17 | 0x80 | PAGE_UP | 0x21
F18 | 0x81 | PAUSE | 0x13
F19 | 0x82 | PLAY | 0xFA
F2 | 0x71 | PLAY_PAUSE_MEDIA | 0xB3
F20 | 0x83 | PREVIOUS_TRACK | 0xB1
F21 | 0x84 | PRINT | 0x2A
F22 | 0x85 | PRINT_SCREEN | 0x2C
F23 | 0x86 | PROCESS | 0xE5
F24 | 0x87 | RIGHT | 0x27
F3 | 0x72 | RIGHT_ALT | 0xA5
F4 | 0x73 | RIGHT_CTRL | 0xA3
F5 | 0x74 | RIGHT_SHIFT | 0xA1
F6 | 0x75 | RIGHT_WIN_KEY | 0x5C
F7 | 0x76 | SCROLL_LOCK | 0x91
F8 | 0x77 | SELECT | 0x29
F9 | 0x78 | SELECT_MEDIA | 0xB5
FINAL | 0x18 | SEPARATOR | 0x6C
HANJA | 0x19 | SLEEP | 0x5F
HELP | 0x2F | START_APPLICATION1 | 0xB6
HOME | 0x24 | START_APPLICATION2 | 0xB7
INSERT | 0x2D | START_MAIL | 0xB4
JUNJA | 0x17 | STOP_MEDIA | 0xB2
KANA | 0x15 | TAB | 0x09
LEFT | 0x25 | UP | 0x26
LEFT_ALT | 0xA4 | VOLUME_DOWN | 0xAE
LEFT_CTRL | 0xA2 | VOLUME_MUTE | 0xAD
LEFT_SHIFT | 0xA0 | VOLUME_UP | 0xAF
LEFT_WIN_KEY | 0x5B | ZOOM | 0xFB
MODE_CHANGE | 0x1F |  |
Parent topic: BrowserTypeKeys Function


BrowserUnhighlight Function

Action

This function is the counterpart to the BrowserHighlight function. When a DOM element has been highlighted by calling the BrowserHighlight function it can be unhighlighted by calling the BrowserUnhighlight function.

Include file

BrowserAPI.bdh

Syntax

BrowserUnhighlight( uTestObject : in union ): boolean;
Parameter | Description
uTestObject | The XPath locator or the handle to the DOM element.

Return value

  • true if successful

  • false otherwise

Example

benchmark SilkPerformerRecorder

use "Kernel.bdh"
use "BrowserAPI.bdh"

dcluser
  user
    VUser
  transactions
    TInit           : begin;
    TMain           : 1;

var

dclrand

dcltrans
  transaction TInit
  begin
  end TInit;

  transaction TMain
  var
    liHandle : number;
  begin
    BrowserStart(BROWSER_MODE_DEFAULT, 800, 600);
    BrowserNavigate("http://demo.borland.com");
    liHandle := BrowserFind(HANDLE_DESKTOP, "//LI");

    // highlight the first list item with a yellow background, wait 5 seconds and then undo the highlighting
    BrowserHighlight(liHandle, "black", "yellow");
    Wait(5.0);
    BrowserUnhighlight(liHandle);
  end TMain;
Parent topic: Browser-Driven Web Load Testing Functions
Related reference
BrowserHighlight Function


BrowserVerifyProperty Function

Action

This function verifies that a property of a DOM element has a specified value. The logic of this function works as follows:

  1. Locates the object referred to in the locator string. If the object cannot be found, processing ends and an error with SEVERITY_ERROR is raised, regardless of the defined severity.
  2. Gets the list of properties for the object.
  3. Verifies that property x has value y.
  4. If the verification fails, an error with the defined severity is raised.
Note: Do not attempt to verify an attribute that is contained in the locator string.

Include file

BrowserAPI.bdh

Syntax

BrowserVerifyProperty( uTestObject       : in union,
                       sDomPropertyName  : in string,
                       vDomPropertyValue : in union,
                       nOptions          : in number optional,
                       nSeverity         : in number optional := SEVERITY_ERROR ): boolean;
Parameter | Description
uTestObject | The XPath locator or the handle to the DOM element.
sDomPropertyName | The name of the property of the DOM element.
vDomPropertyValue | The value of the property to be verified.
nOptions Optional: Flagmask to configure the verification. Can be one of the following values:
  • Default: VERIFY_EQUAL
  • VERIFY_NOT_EQUAL
  • VERIFY_STARTS_WITH
  • VERIFY_ENDS_WITH
  • VERIFY_CONTAINS
  • VERIFY_CASE_SENSITIVE (available additionally to the above options)
  • VERIFY_IGNORE_WHITESPACE (available additionally to the above options)
nSeverity Optional: Severity of the error that is raised if the verification fails. Can be one of the following values:
  • SEVERITY_SUCCESS: Success; no error (numerical value: 0)
  • SEVERITY_INFORMATIONAL: Informational; no error (numerical value: 1)
  • SEVERITY_WARNING: Warning; no error (numerical value: 2)
  • SEVERITY_ERROR: (Default) Error; simulation continues (numerical value: 3)
  • SEVERITY_TRANS_EXIT: Error; the active transaction is aborted (numerical value: 4)
  • SEVERITY_PROCESS_EXIT: Error; the simulation is aborted (numerical value: 5)

Return value

  • true if successful

  • false otherwise

Example

benchmark SilkPerformerRecorder

use "Kernel.bdh"
use "BrowserAPI.bdh"

dcluser
  user
    VUser
  transactions
    TInit           : begin;
    TMain           : 1;

var

dclrand

dcltrans
  transaction TInit
  begin
  end TInit;

  transaction TMain
  var
    propertyValue : boolean;
  begin
    BrowserStart(BROWSER_MODE_DEFAULT, 800, 600);
    BrowserNavigate("http://demo.borland.com/TestSite/gwt/Showcase.html#CwCheckBox");
    // check Monday
    BrowserCheckBoxSelect("//SPAN[@hideFocus='0']/INPUT[@hideFocus='0']", CHECKBOX_CHECKED);
    // get the value of the checked property and print it
    BrowserGetProperty("//SPAN[@hideFocus='0']/INPUT[@hideFocus='0']", "checked", propertyValue);
    print(string(propertyValue));

    //verify that the property value is true
    BrowserVerifyProperty("//SPAN[@hideFocus='0']/INPUT[@hideFocus='0']", "checked",
      true, VERIFY_EQUAL | VERIFY_CASE_SENSITIVE, SEVERITY_INFORMATIONAL);
  end TMain;
Parent topic: Browser-Driven Web Load Testing Functions
Related reference
BrowserGetProperty Function
BrowserSetProperty Function


BrowserVerifyText Function

Action

Verifies that a DOM element has a specified caption. The logic of this function works as follows:

  1. Locates the object referred to in the locator string. If the object cannot be found, processing ends and an error with SEVERITY_ERROR is raised, regardless of the defined severity.
  2. Gets the value of the property textContents.
  3. Verifies that the value of property textContents has the specified value.
  4. If the verification fails, an error with the defined severity is raised.
Note: Do not call BrowserVerifyText() with a locator that contains the property textContents.

Include file

BrowserAPI.bdh

Syntax

BrowserVerifyText( uTestObject : in union,
                   sText       : in string,
                   nOptions    : in number optional,
                   nSeverity   : in number optional := SEVERITY_ERROR );
Parameter | Description
uTestObject | The XPath locator or the handle to the DOM element.
sText | The caption that the element is expected to have.
nOptions Optional: Flagmask to configure the verification. Can be one of the following values:
  • Default: VERIFY_EQUAL
  • VERIFY_NOT_EQUAL
  • VERIFY_STARTS_WITH
  • VERIFY_ENDS_WITH
  • VERIFY_CONTAINS
  • VERIFY_CASE_SENSITIVE (available additionally to the above options)
  • VERIFY_IGNORE_WHITESPACE (available additionally to the above options)
nSeverity Optional: Severity of the error that is raised if the verification fails. Can be one of the following values:
  • SEVERITY_SUCCESS: Success; no error (numerical value: 0)
  • SEVERITY_INFORMATIONAL: Informational; no error (numerical value: 1)
  • SEVERITY_WARNING: Warning; no error (numerical value: 2)
  • SEVERITY_ERROR: (Default) Error; simulation continues (numerical value: 3)
  • SEVERITY_TRANS_EXIT: Error; the active transaction is aborted (numerical value: 4)
  • SEVERITY_PROCESS_EXIT: Error; the simulation is aborted (numerical value: 5)

Example

benchmark SilkPerformerRecorder

use "Kernel.bdh"
use "BrowserAPI.bdh"

dcluser
  user
    VUser
  transactions
    TInit           : begin;
    TMain           : 1;

var

dclrand

dcltrans
  transaction TInit
  begin
  end TInit;

  transaction TMain
  begin
    BrowserStart(BROWSER_MODE_DEFAULT, 800, 600);
    BrowserNavigate("http://demo.borland.com/TestSite/gwt/Showcase.html#CwBasicText");
    // set the text to 'Hello World!'
    BrowserTypeKeys("//INPUT[@id='gwt-debug-cwBasicText-textbox']", "Hello World!");

    //verify if the textfield has the expected text - case sensitive and ignoring whitespaces.
    //If the verification fails, an error will be raised
    BrowserVerifyText("//INPUT[@id='gwt-debug-cwBasicText-textbox']", "Hello World!",
      VERIFY_CASE_SENSITIVE | VERIFY_IGNORE_WHITESPACE, SEVERITY_ERROR);
  end TMain;
Parent topic: Browser-Driven Web Load Testing Functions


BrowserWaitForDisappear Function

Action

This function is useful for custom synchronization. It can be used to wait until a certain DOM element becomes invisible or is detached from the document.

Note: Automatic synchronization is also available. When automatic synchronization is turned on, replay functions wait until the browser has completed loading (including asynchronous remote calls and Javascript processing).

Include file

BrowserAPI.bdh

Syntax

BrowserWaitForDisappear( uTestObject : in union,
                         nTimeout    : in union optional ): boolean;
Parameter | Description
uTestObject | The XPath locator or the handle to the DOM element.
nTimeout | Optional: The wait timeout in milliseconds. If not specified, the default timeout specified in the profile settings or set by BrowserSetOption(BROWSER_OPT_WAIT_TIMEOUT) will be used. When the timeout is reached, an error is thrown. Use the data type number for this parameter. The data type float is not allowed.

Return value

  • true if successful

  • false otherwise

Example

benchmark SilkPerformerRecorder

use "Kernel.bdh"
use "BrowserAPI.bdh"

dcluser
  user
    VUser
  transactions
    TInit           : begin;
    TMain           : 1;

var

dclrand

dcltrans
  transaction TInit
  begin
  end TInit;

  transaction TMain
  begin
    BrowserStart(BROWSER_MODE_DEFAULT | BROWSER_MODE_USERBEHAVIOR_FIRST_TIME, 800, 600);

    // wait for DOM element to disappear (should disappear after 2.5 seconds)
    BrowserNavigate("http://demo.borland.com/TestSite/JavaScriptDisappear.html");

    BrowserWaitForDisappear("//SPAN[@id='ToHide']", 1000);
  end TMain;
Parent topic: Browser-Driven Web Load Testing Functions
Related reference
BrowserSetOption Function


BrowserWaitForNewWindow Function

Action

Waits until a new browser window (tab) is created and returns the handle of this window (tab). The timeout value for retrieving a handle is defined in the Profile settings in the Object resolve timeout field. To define a custom timeout value, use the nTimeout parameter.

Include file

BrowserAPI.bdh

Syntax

BrowserWaitForNewWindow( in sWindowName : string optional,
                         in nTimeout    : union optional ): number;

Parameter | Description
sWindowName | Optional: This window name is used in TrueLogs and the Browser Application. Whenever the window handle returned by BrowserWaitForNewWindow is passed to another window function, such as BrowserActivateWindow or BrowserCloseWindow, this window name is used for textual identification of the window.
nTimeout | Optional: The wait timeout in milliseconds. If not specified, the default timeout specified in the profile settings or set by BrowserSetOption(BROWSER_OPT_WAIT_TIMEOUT) will be used. When the timeout is reached, an error is thrown. Use the data type number for this parameter. The data type float is not allowed.

Return value

  • The value of the window handle.

Example

benchmark SilkPerformerRecorder

use "Kernel.bdh"
use "BrowserAPI.bdh"

dcluser
  user
    VUser
  transactions
    TMain           : 1;

dcltrans

  transaction TMain
  var
    mainWindow : number;
    newWindow  : number;
    check      : number;
   begin
    BrowserStart(BROWSER_MODE_DEFAULT, 800, 600);
    BrowserNavigate("http://demo.borland.com/TestSite/multiplewindows/multipleWindows.html");

    mainWindow := BrowserGetActiveWindow("main window");
    BrowserLinkSelect("//A[@name='window1']",  "Select, BODY (#1)");

    newWindow := BrowserWaitForNewWindow("new window");

    BrowserActivateWindow(mainWindow);
    check := BrowserGetActiveWindow();

    if (check <> mainWindow) then
      RepMessage("Window handles are different", SEVERITY_ERROR);
    end;
  end TMain;
Parent topic: Browser-Driven Web Load Testing Functions


BrowserWaitForProperty Function

Action

This function is useful for custom synchronization. It can be used to wait until a property has a certain value. As soon as the property has the specified value, the function returns. When the timeout is reached, an error is thrown.

Note: Automatic synchronization is also available. When automatic synchronization is turned on, replay functions wait until the browser has completed loading (including asynchronous remote calls and JavaScript processing).

Include file

BrowserAPI.bdh

Syntax

BrowserWaitForProperty( uTestObject       : in union,
                        sDomPropertyName  : in string,
                        vDomPropertyValue : in union,
                        nTimeout          : in union optional ): boolean;
Parameter | Description
uTestObject | The XPath locator or the handle to the DOM element.
sDomPropertyName | The DOM property name.
vDomPropertyValue | The value to be waited for.
nTimeout | Optional: The wait timeout in milliseconds. If not specified, the default timeout specified in the profile settings or set by BrowserSetOption(BROWSER_OPT_WAIT_TIMEOUT) will be used. When the timeout is reached, an error is thrown. Use the data type number for this parameter. The data type float is not allowed.

Return value

  • true if successful

  • false otherwise

Example

benchmark SilkPerformerRecorder

use "Kernel.bdh"
use "BrowserAPI.bdh"

dcluser
  user
    VUser
  transactions
    TInit           : begin;
    TMain           : 1;

var

dclrand

dcltrans
  transaction TInit
  begin
  end TInit;

  transaction TMain
  begin
    BrowserStart(BROWSER_MODE_DEFAULT, 800, 600);

    // wait for dom element to alter checked state (should be checked after 2.5 seconds)
    BrowserNavigate("http://demo.borland.com/TestSite/JavaScriptDisappear.html");

    BrowserWaitForProperty("//INPUT[@id='ToChange']", "checked", true);
  end TMain;
Parent topic: Browser-Driven Web Load Testing Functions
Related reference
BrowserSetOption Function


Database (DBMS) Functions

Silk Performer allows you to create load testing scripts for your database server at three different levels. You can combine scripting methods in a single script.

  • High-level Interface
    Describes the high-level database access interface. This interface is used to allow simple data base scripts, which can be generated manually (e.g. read value from table, update element, etc.).
  • Medium-level Interface
    Describes the characteristics and functions for accessing DBMSs via ODBC. This interface is used by the old ODBC Recorder. The interface is obsolete now and is just included to ensure backward compatibility.
  • Native-level Interface
    Enables you to use native interface API functions. This interface is used by the Recorder. It is the most powerful interface.
  • ODBC Functions Overview
    Lists the scripting functions used to load test database applications using the ODBC interface.
  • Oracle API Functions Overview
    Lists the Oracle API functions.
  • Oracle 8 API Functions Overview
    Lists the Oracle 8 API functions.
  • Binding Setting Functions
    Lists the binding setting functions.
  • Result Set Functions Overview
    Use the result set functions to get generalized access to the result sets of different database APIs.
Parent topic: Benchmark Description Language (BDL) Reference


High-level Interface

The Silk Performer scripting language is easy to read and provides a high-level database access interface. The following example shows the TSelling transaction of a stock inventory management system using the high-level interface.

use "DBAPI.bdh"

dclrand
  rAno: RndUniN(1..2000);

var
  ano, stock: number;

dcltrans
  transaction TSelling
  var
    i: number;
  begin
    for i := 1 to RndUniN(4..7) do
      ano := rAno;
      c1: SelArticle();
      c2: UpdStock();
    end;
  end TSelling;

dclsql
  SelArticle:  SELECT a_name, a_cat, a_price, a_stock
  INTO *, *, *, :stock FROM article
  WHERE a_no = :ano;
  UpdStock:
  UPDATE article SET a_stock = 99999
  WHERE a_no = :ano;
Parent topic: Database (DBMS) Functions
Related reference
Medium-level Interface
Native-level Interface
SQL Section


Medium-level Interface

The Silk Performer medium-level interface provides access to DBMSs via ODBC. The medium-level interface gives you more control when accessing the database than is possible with the high-level interface.

The main characteristics of the medium-level interface are:

  • DB_Api functions work with SQL commands defined in the dclsql section. See Datatype SQL.

  • Automatic binding is supported.

  • Automatic error handling is provided.

  • Cursors must be declared explicitly (in contrast to the high-level interface). See Datatype cursor.

  • Multiple connects to DBMSs are possible within a single transaction.

Example

The following example shows the TSelling transaction from above using the medium-level interface.

use "DBAPI.bdh";

dclrand
  rAno: RndUniN(1..2000);

var
  hDBC1, ano, stock : number;
  c1, c2 : cursor;

dcltrans
  transaction DBApiSelling
  var
    i      : number;
    bFirst : boolean init true;
  begin
    if bFirst then //connecting, only executed on first call
      bFirst := false;
      hDBC1 := DB_Connect("dsn=sample;uid=u1;pwd=u1");
      SQLSetConnectOption(hDBC1, SQL_AUTOCOMMIT, 0);
      DB_AllocCursor(hDBC1, c1);
      DB_AllocCursor(hDBC1, c2);
      DB_Prepare(c1, SelArticle);
      DB_Prepare(c2, UpdStock);
    end;

    for i := 1 to RndUniN(4..7) do
      ano := rAno;
      DB_Execute(c1);
      fetch c1 next 1;
      DB_Execute(c2);
    end;

    DB_Commit(hDBC1);
  end DBApiSelling;

dclsql
  SelArticle:
  SELECT a_name, a_cat, a_price, a_stock
  INTO *, *, *, :stock FROM article
  WHERE a_no = :ano;
  UpdStock:
  UPDATE article SET a_stock = 99999
  WHERE a_no = :ano;

The medium-level interface consists of the following database access functions (DB_Api functions):

  • Datatype Cursors
    Several DB_Api functions need cursors, which must be declared.
  • Datatype SQL
    The DB_Api functions DB_ExecDirect and DB_Prepare work with SQL commands defined in your dclsql section.
  • DB_AllocCursor Function
    Allocates memory for a cursor and associates the cursor with the connection specified by hDBC.
  • DB_CloseCursor Function
    Closes the cursor and discards all pending results.
  • DB_Commit Function
    Commits a transaction.
  • DB_Connect Function
    Establishes a connection to a database system and returns a handle to that system.
  • DB_Disconnect Function
    Disconnects from the database system and releases all resources.
  • DB_DropCursor Function
    Drops a cursor and deallocates the resources used by the cursor.
  • DB_ExecDirect Function
    Prepares and executes a SQL statement in one step.
  • DB_Execute Function
    Executes a prepared SQL statement.
  • DB_Prepare Function
    Prepares a SQL statement (declared in the SQL section) for execution.
  • DB_Rollback Function
    Rolls back a transaction.
  • Hstmt Function
    Retrieves the ODBC statement handle from the cursor data structure.
Parent topic: Database (DBMS) Functions
Related reference
High-level Interface
Native-level Interface
SQL Section


Datatype Cursors

Several DB_Api functions need cursors, which must be declared. You can declare cursors explicitly in the global var section of Silk Performer (cursors have global scope).

Example

var
  c1: cursor;

dcltrans
  transaction DBApiSelling
  begin
    hDBC1 := DB_Connect("dsn=sample;uid=u1;pwd=u1");
    SQLSetConnectOption(hDBC1, SQL_AUTOCOMMIT, 0);
    DB_AllocCursor(hDBC1, c1);
  end DBApiSelling;
Parent topic: Medium-level Interface


Datatype SQL

The DB_Api functions DB_ExecDirect and DB_Prepare work with SQL commands defined in your dclsql section. SQL commands you use in these DB_Api functions must be declared in a dclsql section of your script. You cannot use SQL commands in DB_Api functions that use parameters.

Example

var
 c1: cursor;

dcltrans
  transaction DBApiSelling
  begin
    ...
    DB_Prepare(c1, SelArticle);
    ...
  end DBApiSelling;

dclsql
  SelArticle:
    SELECT * FROM article
    WHERE a_stock > 5 AND a_price > 1000;
Parent topic: Medium-level Interface


DB_AllocCursor Function

Action

Allocates memory for a cursor and associates the cursor with the connection specified by hDBC.

Include file

DBAPI.bdh

Syntax

DB_AllocCursor(in hDBC: number, out cCursor: cursor): number;

Return value

SQL return code

The following values are possible:

  • SQL_SUCCESS. Function completed successfully.

  • SQL_SUCCESS_WITH_INFO. Call native ODBC function SQLError for detailed information.

  • SQL_INVALID_HANDLE. Invalid database connection handle.

  • SQL_ERROR. Call native ODBC function SQLError for detailed information.

Parameter | Description
hDBC | Valid handle to a database connection. This handle must have been returned from a previous call to DB_Connect .
cCursor | Variable receiving the allocated cursor

Example

rCode := DB_AllocCursor(hDBC, c1);

Sample scripts

DBApi01.bdf, Trans.bdf, MutexLogin.bdf

Parent topic: Medium-level Interface


DB_CloseCursor Function

Action

Closes the cursor and discards all pending results.

Include file

DBAPI.bdh

Syntax

DB_CloseCursor(in cCursor: cursor): number;

Return value

SQL return code

Parameter | Description
cCursor | Cursor to be closed

Example

rCode := DB_CloseCursor(c1);

Sample scripts

DBApi01.bdf

Parent topic: Medium-level Interface
Related reference
DB_Connect Function


DB_Commit Function

Action

Commits a transaction.

Include file

DBAPI.bdh

Syntax

DB_Commit(in hDBC: number): number;

Return value

SQL return code

Parameter | Description
hDBC | Valid handle to a database connection. This handle must have been returned from a previous call to DB_Connect.

Example

rCode := DB_Commit(hDBC);

Sample scripts

DBApi01.bdf, Trans.bdf, MutexLogin.bdf

Parent topic: Medium-level Interface


DB_Connect Function

Action

Establishes a connection to a database system and returns a handle to that system. This allows you to submit SQL statements to the database for execution.

Include file

DBAPI.bdh

Syntax

DB_Connect(in sConnectStr: string): number;

Return value

Handle to a database connection

Parameter Description
sConnectStr

A connection string identifying the database system and any additional logon information required by your driver. The connection string has the form:

"dsn=data source name;uid=user name;pwd=user password"

where data source name is the name you specified when you generated the ODBC.INI file during the installation of your ODBC driver, and user name is the User ID and password.

You can issue successive calls to DB_Connect to open simultaneous connections to different database systems, or simultaneous connections to the same database system (if supported by that database system). Use DB_Disconnect to close the connection and release the resources.

Example

// To connect to SQL Server:

hDBC := DB_Connect("dsn=qa_sql_server;uid=u1;pwd=u1");

Sample scripts

DBApi01.bdf, Trans.bdf, MutexLogin.bdf

Parent topic: Medium-level Interface
Related reference
DB_Disconnect Function


DB_Disconnect Function

Action

Disconnects from the database system and releases all resources.

Include file

DBAPI.bdh

Syntax

DB_Disconnect(inout hDBC: number): number;

Return value

SQL return code

Parameter | Description
hDBC | Valid handle to a database connection. This handle must have been returned from a previous call to DB_Connect.

Example

rCode := DB_Disconnect(hDBC);

Sample scripts

Trans.bdf, MutexLogin.bdf

Parent topic: Medium-level Interface
Related reference
DB_Connect Function


DB_DropCursor Function

Action

Drops a cursor and deallocates the resources used by the cursor.

Include file

DBAPI.bdh

Syntax

DB_DropCursor(in cCursor: cursor): number;

Return value

SQL return code

Parameter | Description
cCursor | Cursor to be dropped

Example

rCode := DB_DropCursor(c1);

Sample scripts

Trans.bdf, MutexLogin.bdf

Parent topic: Medium-level Interface


DB_ExecDirect Function

Action

Prepares and executes a SQL statement in one step. DB_ExecDirect is the fastest way to submit a SQL statement for one-time execution. Binding of program variables and random variables used in the SQL statement is done automatically.

Include file

DBAPI.bdh

Syntax

DB_ExecDirect(in cCursor: cursor, in sqlStat: sql): number;

Return value

SQL return code

Parameter | Description
cCursor | Cursor
sqlStat | SQL statement name (defined in the SQL section); the statement is executed directly

Example

dcltrans
  transaction TExecDirect
  var
    nRetCode: number;
  begin
    ...
    nRetCode := DB_ExecDirect(c1, InsSelling);
    ...
  end TExecDirect;

dclsql
  InsSelling:
    INSERT INTO sale VALUES (:gAno, "121297", 'N', :rTerm);

Sample scripts

Trans.bdf, MutexLogin.bdf

Parent topic: Medium-level Interface


DB_Execute Function

Action

Executes a prepared SQL statement.

Include file

DBAPI.bdh

Syntax

DB_Execute(in cCursor: cursor): number;

Return value

SQL return code

Parameter | Description
cCursor | Cursor holding the prepared statement

Example

rCode := DB_Execute(c1);

Sample scripts

DBApi01.bdf

Parent topic: Medium-level Interface


DB_Prepare Function

Action

Prepares a SQL statement (declared in the SQL section) for execution. Binding of program variables and random variables used in the SQL statement is done automatically.

Include file

DBAPI.bdh

Syntax

DB_Prepare( in cCursor: cursor, in sqlStat: sql ): number;

Return value

SQL return code

Parameter | Description
cCursor | Cursor for prepared SQL statement
sqlStat | SQL statement name (defined in the SQL section) to be prepared for further executing

Example

dcltrans
  transaction TPrepare
  var
    nRetCode: number;
  begin
    ...
    nRetCode := DB_Prepare(c1, InsSelling);
    ...
  end TPrepare;

dclsql
  InsSelling:
    INSERT INTO sale VALUES (:gAno, "121297", 'N', :rTerm);

Sample scripts

DBApi01.bdf

Parent topic: Medium-level Interface


DB_Rollback Function

Action

Rolls back a transaction.

Include file

DBAPI.bdh

Syntax

DB_Rollback(in hDBC: number): number;

Return value

SQL return code

Parameter | Description
hDBC | Valid handle to a database connection. This handle must have been returned from a previous call to DB_Connect.

Example

rCode := DB_Rollback(hDBC);

Sample scripts

DBApi01.bdf, Trans.bdf, MutexLogin.bdf

Parent topic: Medium-level Interface
Related reference
DB_Connect Function


Hstmt Function

Action

Retrieves the ODBC statement handle from the cursor data structure. The statement handle is used for native ODBC function calls.

Include file

DBAPI.bdh

Syntax

Hstmt(in cCursor: cursor): number;

Return value

ODBC statement handle

Parameter | Description
cCursor | Cursor

Example

var
  c1: cursor;

dcltrans
  transaction THstmt
  begin
    ...
    DB_Execute(c1);
    SQLFreeStmt(Hstmt(c1), ...);
    ...
  end THstmt;
Parent topic: Medium-level Interface


Native-level Interface

The Silk Performer native-level interface enables you to use native interface API functions (via external function calls) for any database system or transaction monitor.

Example

The following example uses Oracle's OCI as the native-level interface.

var
  hConnection : number;
  cCursor : cursor;

dcltrans
  transaction TMain
  var
    sName             : string;
    nFetched, nAge, i : number;
  begin
    OraLogon(hConnection, "user", "password", "orclnet2");
    OraOpen(cCursor, hConnection);
    // insert two persons: Jimmy and Ronald
    OraParse(cCursor, sqlInsert);
    OraBind(cCursor, ":name", SQLT_CHR, 32, 2);
    OraBind(cCursor, ":age", SQLT_INT, 0, 2);
    OraSetString(cCursor, ":name", "Jimmy", 1);
    OraSetInt(cCursor, ":age", 55, 1);
    OraSetString(cCursor, ":name", "Ronald", 2);
    OraSetInt(cCursor, ":age", 18, 2);
    OraExec(cCursor, 2);
    // select all persons
    OraParse(cCursor, sqlSelect);
    OraDefine(cCursor, 1, SQLT_CHR, 32);
    OraDefine(cCursor, 2, SQLT_INT);
    OraExec(cCursor, 1, 50, 0, 0, nFetched);

    for i := 1 to nFetched do
      sName := OraGetString(cCursor, "1", i);
      nAge := OraGetInt(cCursor, "2", i);
      write(sName, 32); write(nAge, 5); writeln;
    end;

    OraClose(cCursor);
    OraLogoff(hConnection);
  end TMain;

dclsql
  sqlInsert:
    INSERT INTO persons (name, age) VALUES (:name, :age);
  sqlSelect:
    SELECT * FROM persons;
Parent topic: Database (DBMS) Functions
Related reference
High-level Interface
Medium-level Interface


ODBC Functions Overview

ODBC, an acronym for Open Database Connectivity, is a standardized set of application programming interface functions that can be used to access data stored in both relational and non-relational database management systems.

Silk Performer provides the following scripting functions to load test database applications using the ODBC interface:

  • Memory Management Functions
  • Connection Handling Functions
  • Cursor Handling Functions
  • Value Setting Functions
  • SQL Statement Execution Functions
  • Value Retrieving Functions
  • Transaction Handling Functions
  • Error Handling Functions
Parent topic: Database (DBMS) Functions


Memory Management Functions

  • OdbcAlloc Function
    Allocates memory for a connection, environment or descriptor handle.
  • OdbcFree Function
    Releases a handle and frees all memory associated with it.
Parent topic: ODBC Functions Overview


OdbcAlloc Function

Action

Allocates memory for a connection, environment or descriptor handle.

Include file

ODBC.bdh

Syntax

OdbcAlloc( in nType    : number,
           out hHandle : number,
           in hParent  : number optional ): boolean;

Return value

  • true if successful

  • false otherwise

Parameter | Description
nType

Type of the handle to be allocated. This parameter must be one of the following:

  • SQL_HANDLE_ENV. Environment handle.

  • SQL_HANDLE_DBC. Connection handle.

  • SQL_HANDLE_DESC. Descriptor handle.
hHandle | Variable receiving the handle.
hParent

Existing handle in whose context the new handle is to be allocated.

  • To allocate a connection handle, this parameter must be an environment handle that refers to a previously allocated environment information storage buffer.

  • To allocate a descriptor handle, this parameter must be a connection handle.

  • To allocate an environment handle, omit this parameter.

Example

var
  hEnv, hDbc : number;
  cCursor : cursor;

dcltrans
  transaction TMain
  begin
    OdbcAlloc(SQL_HANDLE_ENV, hEnv);
    OdbcAlloc(SQL_HANDLE_DBC, hDbc, hEnv);
    OdbcConnect(hDbc, "DSN=database;UID=user;PWD=pass;");
    OdbcOpen(cCursor, hDbc);
    OdbcPrepare(cCursor, sqlInsert);
    OdbcBind(cCursor, ":1", SQL_C_CHAR, 32);
    OdbcBind(cCursor, ":2", SQL_C_LONG);
    OdbcSetString(cCursor, ":1", "Bob", 1);
    OdbcSetInt(cCursor, ":2", 25, 1);
    OdbcSetString(cCursor, ":1", "Marcy", 2);
    OdbcSetInt(cCursor, ":2", 33, 2);
    OdbcExecute(cCursor);
    OdbcClose(cCursor, SQL_DROP);
    OdbcCommit(hDbc);
    OdbcDisconnect(hDbc);
    OdbcFree(hDbc);
    OdbcFree(hEnv);
  end TMain;

dclsql
  sqlInsert:
    INSERT INTO persons (name, age) VALUES (?, ?);
Parent topic: Memory Management Functions
Related reference
OdbcFree Function


OdbcFree Function

Action

Releases a handle and frees all memory associated with it.

Include file

ODBC.bdh

Syntax

OdbcFree( inout hHandle : number ): boolean;

Return value

  • true if successful

  • false otherwise

Parameter | Description
hHandle | Handle to release. The handle must have been allocated with the OdbcAlloc function.

Example

var
  hEnv, hDbc : number;
  cCursor : cursor;

dcltrans
  transaction TMain
  begin
    OdbcAlloc(SQL_HANDLE_ENV, hEnv);
    OdbcAlloc(SQL_HANDLE_DBC, hDbc, hEnv);
    OdbcConnect(hDbc, "DSN=database;UID=user;PWD=pass;");
    OdbcOpen(cCursor, hDbc);
    OdbcPrepare(cCursor, sqlInsert);
    OdbcBind(cCursor, ":1", SQL_C_CHAR, 32);
    OdbcBind(cCursor, ":2", SQL_C_LONG);
    OdbcSetString(cCursor, ":1", "Bob", 1);
    OdbcSetInt(cCursor, ":2", 25, 1);
    OdbcSetString(cCursor, ":1", "Marcy", 2);
    OdbcSetInt(cCursor, ":2", 33, 2);
    OdbcExecute(cCursor);
    OdbcClose(cCursor, SQL_DROP);
    OdbcCommit(hDbc);
    OdbcDisconnect(hDbc);
    OdbcFree(hDbc);
    OdbcFree(hEnv);
  end TMain;

dclsql
  sqlInsert:
    INSERT INTO persons (name, age) VALUES (?, ?);
Parent topic: Memory Management Functions
Related reference
OdbcAlloc Function


Connection Handling Functions

  • OdbcConnect Function
    Establishes a connection to a database.
  • OdbcSetEnvAttr Function
    Modifies the current value of a specified environment attribute.
  • OdbcSetConnectAttr Function
    Modifies the current value of a specified connection attribute.
  • OdbcSetDescField Function
    Modifies the value of a specified descriptor record field.
  • OdbcDisconnect Function
    Closes a connection to a database.
Parent topic: ODBC Functions Overview


OdbcConnect Function

Action

Establishes a connection to a database. Using this function, you can establish multiple connections to either a single database or to several instances at the same time.

Include file

ODBC.bdh

Syntax

OdbcConnect( in hConnection : number,
             in sDataSource : string,
             in sUserName   : string optional,
             in sPassword   : string optional ): boolean;

Return value

  • true if successful

  • false otherwise

Parameter | Description
hConnection | Handle to a database connection.
sDataSource | Name of the data source to connect to.
sUserName | User’s authorization name (optional). When the user identifier is specified in the sDataSource parameter, this parameter may be omitted.
sPassword | Password for the specified authorization name (optional). When the password is specified in the sDataSource parameter, this parameter may be omitted.

Example

var
  hEnv, hDbc : number;
  cCursor : cursor;

dcltrans
  transaction TMain
  begin
    OdbcAlloc(SQL_HANDLE_ENV, hEnv);
    OdbcAlloc(SQL_HANDLE_DBC, hDbc, hEnv);
    OdbcConnect(hDbc, "DSN=database;UID=user;PWD=pass;");
    OdbcOpen(cCursor, hDbc);
    OdbcPrepare(cCursor, sqlInsert);
    OdbcBind(cCursor, ":1", SQL_C_CHAR, 32);
    OdbcBind(cCursor, ":2", SQL_C_LONG);
    OdbcSetString(cCursor, ":1", "Bob", 1);
    OdbcSetInt(cCursor, ":2", 25, 1);
    OdbcSetString(cCursor, ":1", "Marcy", 2);
    OdbcSetInt(cCursor, ":2", 33, 2);
    OdbcExecute(cCursor);
    OdbcClose(cCursor, SQL_DROP);
    OdbcCommit(hDbc);
    OdbcDisconnect(hDbc);
    OdbcFree(hDbc);
    OdbcFree(hEnv);
  end TMain;

dclsql
  sqlInsert:
    INSERT INTO persons (name, age) VALUES (?, ?);
Parent topic: Connection Handling Functions
Related reference
OdbcSetEnvAttr Function
OdbcSetConnectAttr Function
OdbcSetDescField Function
OdbcDisconnect Function


OdbcSetEnvAttr Function

Action

Modifies the current value of a specified environment attribute. All environment attributes persist until the environment handle is freed with the OdbcFree function.

Because more than one environment handle can be allocated simultaneously, environment attribute settings on one environment are not affected when another environment is allocated. Once an environment attribute is set, that attribute’s value affects all data source connections that exist or become allocated under the specified environment.

Include file

ODBC.bdh

Syntax

OdbcSetEnvAttr( in hEnvironment : number,
                in nAttribute   : number,
                in sValue       : string): boolean;

Return value

  • true if successful

  • false otherwise

Parameter | Description
hEnvironment | Environment handle that refers to a previously allocated environment information storage buffer.
nAttribute

Environment attribute of which the value is to be modified. This parameter must be set to one of the following values:

  • SQL_ATTR_CONNECTION_POOLING

  • SQL_ATTR_CP_MATCH

  • SQL_ATTR_ODBC_VERSION

  • SQL_ATTR_OUTPUT_NTS
sValue

New value for the environment attribute nAttribute. The following parameters are allowed:

For nAttribute SQL_ATTR_CONNECTION_POOLING:

  • SQL_CP_OFF

  • SQL_CP_ONE_PER_DRIVER

  • SQL_CP_ONE_PER_HENV

For nAttribute SQL_ATTR_CP_MATCH:

  • SQL_CP_STRICT_MATCH

  • SQL_CP_RELAXED_MATCH

For nAttribute SQL_ATTR_ODBC_VERSION:

  • SQL_OV_ODBC2

  • SQL_OV_ODBC3

For nAttribute SQL_ATTR_OUTPUT_NTS:

  • SQL_TRUE

  • SQL_FALSE

Example

var
  hEnv, hDbc: number;

dcltrans
  transaction TConnect
  begin
    OdbcAlloc(SQL_HANDLE_ENV, hEnv);
    OdbcAlloc(SQL_HANDLE_DBC, hDbc, hEnv);
    OdbcSetEnvAttr(hEnv, SQL_ATTR_CONNECTION_POOLING, SQL_CP_ONE_PER_DRIVER);
    OdbcConnect(hDbc, "DSN=database;UID=user;PWD=pass;");
  end TConnect;
Parent topic: Connection Handling Functions
Related reference
OdbcConnect Function
OdbcSetConnectAttr Function
OdbcSetDescField Function
OdbcDisconnect Function
OdbcFree Function


OdbcSetConnectAttr Function

Action

Modifies the current value of a specified connection attribute.

Include file

ODBC.bdh

Syntax

OdbcSetConnectAttr( in hDbc       : number,
                    in nAttribute : number,
                    in sValue     : string): boolean;

Return value

  • true if successful

  • false otherwise

Parameter | Description
hDbc | Handle to a database connection.
nAttribute

Connection attribute whose value is to be modified . This parameter must be set to one of the following values:

  • SQL_ATTR_AUTOCOMMIT

  • SQL_ATTR_CONNECTION_TIMEOUT

  • SQL_ATTR_CURRENT_CATALOG

  • SQL_ATTR_LOGIN_TIMEOUT

  • SQL_ATTR_METADATA_ID

  • SQL_ATTR_ODBC_CURSORS

  • SQL_ATTR_PACKET_SIZE

  • SQL_ATTR_TRACE

  • SQL_ATTR_TRACEFILE

  • SQL_ATTR_TRANSLATE_LIB

  • SQL_ATTR_TRANSLATE_OPTION

  • SQL_ATTR_TXN_ISOLATION
sValue | New value for the connection attribute.

Example

var
  hEnv, hDbc : number;

dcltrans
  transaction TLogon
  begin
    OdbcAlloc(SQL_HANDLE_ENV, hEnv);
    OdbcAlloc(SQL_HANDLE_DBC, hDbc, hEnv);
    OdbcSetConnectAttr(hDbc, SQL_ATTR_AUTOCOMMIT, SQL_AUTOCOMMIT_ON);
    OdbcConnect(hDbc, "DSN=database;UID=user;PWD=pass;");
  end TLogon;
Parent topic: Connection Handling Functions
Related reference
OdbcConnect Function
OdbcSetEnvAttr Function
OdbcSetDescField Function
OdbcDisconnect Function


OdbcSetDescField Function

Action

Modifies the value of a specified descriptor record field.

Include file

ODBC.bdh

Syntax

OdbcSetDescField( in hDescriptor : number,
                  in nRecord     : number,
                  in nIdentifier : number,
                  in sValue      : string ): boolean;

Return value

  • true if successful

  • false otherwise

Parameter | Description
hDescriptor | Descriptor handle that refers to a previously allocated descriptor information storage buffer.
nRecord | Descriptor record to modify. If any field of the descriptor header record is specified in the nIdentifier parameter, this parameter is ignored. Otherwise, this parameter should contain a number greater than or equal to 0. Descriptor records are numbered, starting at 0, with record 0 being the bookmark record.
nIdentifier

Field of the descriptor header record or descriptor parameter/column record whose value is to be modified. This parameter must be set to one of the following values:

  • SQL_DESC_AUTO_UNIQUE_VALUE

  • SQL_DESC_BASE_COLUMN_NAME

  • SQL_DESC_BASE_TABLE_NAME

  • SQL_DESC_CASE_SENSITIVE

  • SQL_DESC_CATALOG_NAME

  • SQL_DESC_CONCISE_TYPE

  • SQL_DESC_DATETIME_INTERVAL_CODE

  • SQL_DESC_DATETIME_INTERVAL_PRECISION

  • SQL_DESC_DISPLAY_SIZE

  • SQL_DESC_FIXED_PREC_SCALE

  • SQL_DESC_LABEL

  • SQL_DESC_LENGTH

  • SQL_DESC_LITERAL_PREFIX

  • SQL_DESC_LITERAL_SUFFIX

  • SQL_DESC_LOCAL_TYPE_NAME

  • SQL_DESC_NAME

  • SQL_DESC_NULLABLE

  • SQL_DESC_NUM_PREC_RADIX

  • SQL_DESC_OCTET_LENGTH

  • SQL_DESC_PARAMETER_TYPE

  • SQL_DESC_PRECISION

  • SQL_DESC_ROWVER

  • SQL_DESC_SCALE

  • SQL_DESC_SCHEMA_NAME

  • SQL_DESC_SEARCHABLE

  • SQL_DESC_TABLE_NAME

  • SQL_DESC_TYPE

  • SQL_DESC_TYPE_NAME

  • SQL_DESC_UNNAMED

  • SQL_DESC_UNSIGNED

  • SQL_DESC_UPDATABLE
sValue | New value of the descriptor record field.
Parent topic: Connection Handling Functions
Related reference
OdbcConnect Function
OdbcSetEnvAttr Function
OdbcSetConnectAttr Function
OdbcDisconnect Function


OdbcDisconnect Function

Action

Closes a connection to a database. When a program establishes multiple simultaneous active connections, separate OdbcDisconnect function calls must be performed for each active connection.

Include file

ODBC.bdh

Syntax

OdbcDisconnect( in hConnection : number ) : boolean;

Return value

  • true if successful

  • false otherwise

Parameter | Description
hConnection | Handle to a database connection.

Example

var
  hEnv, hDbc : number;
  cCursor : cursor;

dcltrans
  transaction TMain
  begin
    OdbcAlloc(SQL_HANDLE_ENV, hEnv);
    OdbcAlloc(SQL_HANDLE_DBC, hDbc, hEnv);
    OdbcConnect(hDbc, "DSN=database;UID=user;PWD=pass;");
    OdbcOpen(cCursor, hDbc);
    OdbcPrepare(cCursor, sqlInsert);
    OdbcBind(cCursor, ":1", SQL_C_CHAR, 32);
    OdbcBind(cCursor, ":2", SQL_C_LONG);
    OdbcSetString(cCursor, ":1", "Bob", 1);
    OdbcSetInt(cCursor, ":2", 25, 1);
    OdbcSetString(cCursor, ":1", "Marcy", 2);
    OdbcSetInt(cCursor, ":2", 33, 2);
    OdbcExecute(cCursor);
    OdbcClose(cCursor, SQL_DROP);
    OdbcCommit(hDbc);
    OdbcDisconnect(hDbc);
    OdbcFree(hDbc);
    OdbcFree(hEnv);
  end TMain;

dclsql
  sqlInsert:
    INSERT INTO persons (name, age) VALUES (?, ?);
Parent topic: Connection Handling Functions
Related reference
OdbcConnect Function
OdbcSetEnvAttr Function
OdbcSetConnectAttr Function
OdbcSetDescField Function


Cursor Handling Functions

  • OdbcOpen Function
    Associates a cursor with a database connection.
  • OdbcSetStmtAttr Function
    Modifies the current value of a specified SQL statement attribute.
  • OdbcGetStmtAttr Function
    Retrieves the current value of a specified SQL statement attribute.
  • OdbcSetCursorName Function
    Assigns a user-defined name to a cursor.
  • OdbcGetCursorName Function
    Retrieves the name of a cursor.
  • OdbcBind Function
    Binds a place holder in a SQL statement.
  • OdbcClose Function
    Closes a cursor.
Parent topic: ODBC Functions Overview


OdbcOpen Function

Action

Associates a cursor with a database connection. A cursor serves to maintain state information about processing a SQL statement. In a test script, multiple cursors can be used at the same time. Usually, immediately after opening a cursor, the OdbcPrepare function is called to prepare a SQL statement and associate the statement with a cursor.

Include file

ODBC.bdh

Syntax

OdbcOpen( out cCursor     : cursor,
          in  hConnection : number ): boolean;

Return value

  • true if successful

  • false otherwise

Parameter | Description
cCursor | Variable receiving the cursor associated with the database connection
hConnection | Handle to a database connection.

Example

var
  hEnv, hDbc : number;
  cCursor : cursor;

dcltrans
  transaction TMain
  begin
    OdbcAlloc(SQL_HANDLE_ENV, hEnv);
    OdbcAlloc(SQL_HANDLE_DBC, hDbc, hEnv);
    OdbcConnect(hDbc, "DSN=database;UID=user;PWD=pass;");
    OdbcOpen(cCursor, hDbc);
    OdbcPrepare(cCursor, sqlInsert);
    OdbcBind(cCursor, ":1", SQL_C_CHAR, 32);
    OdbcBind(cCursor, ":2", SQL_C_LONG);
    OdbcSetString(cCursor, ":1", "Bob", 1);
    OdbcSetInt(cCursor, ":2", 25, 1);
    OdbcSetString(cCursor, ":1", "Marcy", 2);
    OdbcSetInt(cCursor, ":2", 33, 2);
    OdbcExecute(cCursor);
    OdbcClose(cCursor, SQL_DROP);
    OdbcCommit(hDbc);
    OdbcDisconnect(hDbc);
    OdbcFree(hDbc);
    OdbcFree(hEnv);
  end TMain;

dclsql
  sqlInsert:
    INSERT INTO persons (name, age) VALUES (?, ?);
Parent topic: Cursor Handling Functions
Related reference
OdbcSetStmtAttr Function
OdbcGetStmtAttr Function
OdbcSetCursorName Function
OdbcGetCursorName Function
OdbcBind Function
OdbcClose Function
OdbcPrepare Function


OdbcSetStmtAttr Function

Action

Modifies the current value of a specified SQL statement attribute.

Include file

ODBC.bdh

Syntax

OdbcSetStmtAttr(
   in cCursor    : cursor,
   in nAttribute : number,
   in sValue     : string ) : boolean;

Return value

  • true if successful

  • false otherwise

Parameter | Description
cCursor | Cursor associated with a database connection.
nAttribute

SQL statement attribute whose value is to be modified. This parameter must be set to one of the following values:

  • SQL_ATTR_CONCURRENCY

  • SQL_ATTR_CURSOR_TYPE

  • SQL_ATTR_MAX_LENGTH

  • SQL_ATTR_MAX_ROWS

  • SQL_ATTR_NOSCAN

  • SQL_ATTR_QUERY_TIMEOUT

  • SQL_ATTR_RETRIEVE_DATA

  • SQL_ATTR_SIMULATE_CURSOR

  • SQL_ATTR_USE_BOOKMARKS
sValue | New value for the SQL statement attribute.

Example

var
  hEnv, hDbc : number;
  cCursor : cursor;

dcltrans
  transaction TMain
  begin
    OdbcAlloc(SQL_HANDLE_ENV, hEnv);
    OdbcAlloc(SQL_HANDLE_DBC, hDbc, hEnv);
    OdbcConnect(hDbc, "DSN=database;UID=user;PWD=pass;");
    OdbcOpen(cCursor, hDbc);
    OdbcSetStmtAttr(cCursor, SQL_ATTR_QUERY_TIMEOUT, 15);
    OdbcPrepare(cCursor, sqlSelect);
    OdbcExecute(cCursor);
    while OdbcFetch(cCursor) do
      write("name: " + OdbcGetString(cCursor, "1"));
      writeln(" age: " + (string)OdbcGetInt(cCursor, "2"));
    end;
    OdbcClose(cCursor, SQL_DROP);
    OdbcCommit(hDbc);
    OdbcDisconnect(hDbc);
    OdbcFree(hDbc);
    OdbcFree(hEnv);
  end TMain;

dclsql
  sqlSelect:
  SELECT * FROM persons;
Parent topic: Cursor Handling Functions
Related reference
OdbcOpen Function
OdbcGetStmtAttr Function
OdbcSetCursorName Function
OdbcGetCursorName Function
OdbcBind Function
OdbcClose Function


OdbcGetStmtAttr Function

Action

Retrieves the current value of a specified SQL statement attribute.

Include file

ODBC.bdh

Syntax

OdbcGetStmtAttr( in  cCursor    : cursor,
                 in  nAttribute : number,
                 out nValue     : number): boolean;

Return value

  • true if successful

  • false otherwise

Parameter | Description
cCursor | Cursor associated with a database connection.
nAttribute

SQL statement attribute whose value is to be retrieved. This parameter must be set to one of the following values:

  • SQL_ATTR_CONCURRENCY

  • SQL_ATTR_CURSOR_TYPE

  • SQL_ATTR_MAX_LENGTH

  • SQL_ATTR_MAX_ROWS

  • SQL_ATTR_NOSCAN

  • SQL_ATTR_QUERY_TIMEOUT

  • SQL_ATTR_RETRIEVE_DATA

  • SQL_ATTR_SIMULATE_CURSOR

  • SQL_ATTR_USE_BOOKMARKS
nValue | Variable that will receive the value of the SQL statement attribute.

Example

var
  hEnv, hDbc : number;
  cCursor    : cursor;

dcltrans
  transaction TMain
  var
    nTimeout : number;
  begin
    OdbcAlloc(SQL_HANDLE_ENV, hEnv);
    OdbcAlloc(SQL_HANDLE_DBC, hDbc, hEnv);
    OdbcConnect(hDbc, "DSN=database;UID=user;PWD=pass;");
    OdbcOpen(cCursor, hDbc);
    OdbcSetStmtAttr(cCursor, SQL_ATTR_QUERY_TIMEOUT, 15);
    OdbcGetStmtAttr(cCursor, SQL_ATTR_QUERY_TIMEOUT, nTimeout );
    OdbcPrepare(cCursor, sqlSelect);
    OdbcExecute(cCursor);

    while OdbcFetch(cCursor) do
      write("name: " + OdbcGetString(cCursor, "1"));
      writeln(" age: " + (string)OdbcGetInt(cCursor, "2"));
    end;

    OdbcClose(cCursor, SQL_DROP);
    OdbcCommit(hDbc);
    OdbcDisconnect(hDbc);
    OdbcFree(hDbc);
    OdbcFree(hEnv);
  end TMain;

dclsql
  sqlSelect:
  SELECT * FROM persons;
Parent topic: Cursor Handling Functions
Related reference
OdbcOpen Function
OdbcSetStmtAttr Function
OdbcSetCursorName Function
OdbcGetCursorName Function
OdbcBind Function
OdbcClose Function


OdbcSetCursorName Function

Action

Assigns a user-defined name to a cursor. Usually, Silk Performer generates and uses an internally generated cursor name whenever a SQL query statement is either prepared or executed directly. This function enables you to replace this internally generated cursor name with a user-defined name. This user-defined cursor name can then be used in place of the internally generated cursor name in positioned UPDATE and positioned DELETE statements.

Include file

ODBC.bdh

Syntax

OdbcSetCursorName( in cCursor : cursor,
                   in sName   : string ): boolean;

Return value

  • true if successful

  • false otherwise

Parameter | Description
cCursor | Cursor associated with a database connection.
sName | User-defined cursor name that Silk Performer uses instead of the internally generated name.

Example

var
  hEnv, hDbc : number;
  c1, c2     : cursor;

dcltrans
  transaction TMain
  begin
    OdbcAlloc(SQL_HANDLE_ENV, hEnv);
    OdbcAlloc(SQL_HANDLE_DBC, hDbc,mhEnv);
    OdbcConnect(hDbc, "DSN=database;UID=user;PWD=pass;");
    OdbcOpen(c1, hDbc);
    OdbcPrepare(c1, sqlSelect);
    OdbcSetCursorName(c1, "cursor_persons");
    OdbcExecute(c1);
    OdbcFetch(c1);
    OdbcOpen(c2, hDbc);
    OdbcPrepare(c2, sqlDelete);
    OdbcExecute(c2);
    OdbcClose(c1, SQL_DROP);
    OdbcClose(c2, SQL_DROP);
    OdbcCommit(hDbc);
    OdbcDisconnect(hDbc);
    OdbcFree(hDbc);
    OdbcFree(hEnv);
  end TMain;

dclsql
  sqlSelect:
    SELECT * FROM persons;
  sqlDelete:
    DELETE FROM persons WHERE CURRENT OF cursor_persons;
Parent topic: Cursor Handling Functions
Related reference
OdbcOpen Function
OdbcSetStmtAttr Function
OdbcGetStmtAttr Function
OdbcGetCursorName Function
OdbcBind Function
OdbcClose Function


OdbcGetCursorName Function

Action

Retrieves the name of a cursor.

Include file

ODBC.bdh

Syntax

OdbcGetCursorName( in  cCursor : cursor,
                   out sName   : string ): boolean;

Return value

  • true if successful

  • false otherwise

Parameter | Description
cCursor | Cursor associated with a database connection.
sName | String receiving the user-defined

Example

var
  hEnv, hDbc : number;
  cCursor : cursor;

dcltrans
  transaction TMain
  var
    sName: string;
  begin
    OdbcAlloc(SQL_HANDLE_ENV, hEnv);
    OdbcAlloc(SQL_HANDLE_DBC, hDbc, hEnv);
    OdbcConnect(hDbc, "DSN=database;UID=user;PWD=pass;");
    OdbcOpen(cCursor, hDbc);
    OdbcGetCursorName(cCursor, sName); writeln(sName);
    OdbcPrepare(cCursor, sqlSelect);
    OdbcExecute(cCursor);

    while OdbcFetch(cCursor) do
       write("name: " + OdbcGetString(cCursor, "1"));
       writeln(" age: " + (string)OdbcGetInt(cCursor, "2"));
    end;

    OdbcClose(cCursor, SQL_DROP);
    OdbcCommit(hDbc);
    OdbcDisconnect(hDbc);
    OdbcFree(hDbc);
    OdbcFree(hEnv);
  end TMain;

dclsql
  sqlSelect:
    SELECT * FROM persons;
Parent topic: Cursor Handling Functions
Related reference
OdbcOpen Function
OdbcSetStmtAttr Function
OdbcGetStmtAttr Function
OdbcSetCursorName Function
OdbcBind Function
OdbcClose Function


OdbcBind Function

Action

Binds a place holder in a SQL statement. The bound place holder — identified by number — is then accessible through the OdbcSet and OdbcGet functions. This function must be called after preparing the SQL statement and before calling the OdbcSet functions.

Include file

ODBC.bdh

Syntax

OdbcBind( in cCursor      : cursor,
          in sPlaceholder : string,
          in nDataType    : number optional,
          in nSize        : number optional,
          in nSqlDataType : number optional,
          in nSqlSize     : number optional,
          in nPrecision   : number optional,
          in nParamType   : number optional ): boolean;

Return value

  • true if successful

  • false otherwise

Parameter | Description
cCursor | Cursor associated with a database connection.
sPlaceholder

Location of the place holder in the SQL statement. This parameter must include the preceding colon identifying it as a place holder.

Place holders are numbered sequentially from left to right, starting with 1, as they appear in the SQL statement.
nDataType

C language data type of the place holder (optional). This parameter must be set to one of the following values:

  • SQL_C_CHAR

  • SQL_C_SHORT

  • SQL_C_SSHORT

  • SQL_C_USHORT

  • SQL_C_LONG

  • SQL_C_SLONG

  • SQL_C_ULONG

  • SQL_C_FLOAT

  • SQL_C_DOUBLE

  • SQL_C_BIT

  • SQL_C_TINYINT

  • SQL_C_STINYINT

  • SQL_C_UTINYINT

  • SQL_C_BINARY

  • SQL_C_DATE

  • SQL_C_TIME

  • SQL_C_TIMESTAMP

  • SQL_C_SBIGINT

  • SQL_C_UBIGINT

  • SQL_C_TYPE_DATE

  • SQL_C_TYPE_TIME

  • SQL_C_TYPE_TIMESTAMP

  • SQL_C_WCHAR

  • SQL_C_NUMERIC

  • SQL_C_DEFAULT (default)
nSize | Size of the C language data type in bytes (optional).
nSqlDataType

SQL data type of the place holder being bound (optional). This parameter must be set to one of the following values:

  • SQL_CHAR

  • SQL_VARCHAR

  • SQL_LONGVARCHAR

  • SQL_DECIMAL

  • SQL_NUMERIC

  • SQL_SMALLINT

  • SQL_INTEGER

  • SQL_REAL

  • SQL_FLOAT

  • SQL_DOUBLE

  • SQL_BIT

  • SQL_TINYINT

  • SQL_BIGINT

  • SQL_BINARY

  • SQL_VARBINARY

  • SQL_LONGVARBINARY

  • SQL_DATE

  • SQL_TIME

  • SQL_TIMESTAMP

  • SQL_INTERVAL_YEAR

  • SQL_INTERVAL_MONTH

  • SQL_INTERVAL_DAY

  • SQL_INTERVAL_HOUR

  • SQL_INTERVAL_MINUTE

  • SQL_INTERVAL_SECOND

  • SQL_INTERVAL_YEAR_TO_MONTH

  • SQL_INTERVAL_DAY_TO_HOUR

  • SQL_INTERVAL_DAY_TO_MINUTE

  • SQL_INTERVAL_DAY_TO_SECOND

  • SQL_INTERVAL_HOUR_TO_MINUTE

  • SQL_INTERVAL_HOUR_TO_SECOND

  • SQL_INTERVAL_MINUTE_TO_SECOND

  • SQL_TYPE_DATE

  • SQL_TYPE_TIME

  • SQL_TYPE_TIMESTAMP

  • SQL_WCHAR

  • SQL_WVARCHAR

  • SQL_WLONGVARCHAR
nSqlSize | Size of the SQL data type in bytes (optional).
nPrecision | Number of digits to the right of the decimal point (optional).
nParamType

Type of place holder being bound (optional). This parameter must be set to one of the following values:

  • SQL_PARAM_INPUT

  • SQL_PARAM_OUTPUT

  • SQL_PARAM_INPUT_OUTPUT

Example

var
  hEnv, hDbc : number;
  cCursor : cursor;

dcltrans
  transaction TMain
  begin
    OdbcAlloc(SQL_HANDLE_ENV, hEnv);
    OdbcAlloc(SQL_HANDLE_DBC, hDbc, hEnv);
    OdbcConnect(hDbc, "DSN=database;UID=user;PWD=pass;");
    OdbcOpen(cCursor, hDbc);
    OdbcPrepare(cCursor, sqlInsert);
    OdbcBind(cCursor, ":1", SQL_C_CHAR, 32);
    OdbcBind(cCursor, ":2", SQL_C_LONG);
    OdbcSetString(cCursor, ":1", "Bob", 1);
    OdbcSetInt(cCursor, ":2", 25, 1);
    OdbcSetString(cCursor, ":1", "Marcy", 2);
    OdbcSetInt(cCursor, ":2", 33, 2);
    OdbcExecute(cCursor);
    OdbcClose(cCursor, SQL_DROP);
    OdbcCommit(hDbc);
    OdbcDisconnect(hDbc);
    OdbcFree(hDbc);
    OdbcFree(hEnv);
  end  TMain;

dclsql
  sqlInsert:
    INSERT INTO persons (name, age) VALUES (?, ?);
Parent topic: Cursor Handling Functions
Related reference
OdbcOpen Function
OdbcSetStmtAttr Function
OdbcGetStmtAttr Function
OdbcSetCursorName Function
OdbcGetCursorName Function
OdbcClose Function


OdbcClose Function

Action

Closes a cursor.

Include file

ODBC.bdh

Syntax

OdbcClose( in cCursor    : cursor,
           in nOperation : number optional ): boolean;

Return value

  • true if successful

  • false otherwise

Parameter | Description
cCursor | Cursor associated with a database connection.
nOperation

Specifies which operation to perform. This parameter must be set to one of the following values:

  • SQL_CLOSE (default). Use this option to Close the cursor when the cursor is re-used later.

  • SQL_DROP. Destroys the cursor and frees all memory allocated for the cursor ( use this option (at the end of the transaction) when the cursor is not re-used anymore).

  • SQL_UNBIND. Disposes the result data columns.

  • SQL_RESET_PARAMS. Disposes the bound parameters.

Example

var
  hEnv, hDbc : number;
  cCursor : cursor;

dcltrans
  transaction TMain
  begin
    OdbcAlloc(SQL_HANDLE_ENV, hEnv);
    OdbcAlloc(SQL_HANDLE_DBC, hDbc, hEnv);
    OdbcConnect(hDbc, "DSN=database;UID=user;PWD=pass;");
    OdbcOpen(cCursor, hDbc);
    OdbcPrepare(cCursor, sqlInsert);
    OdbcBind(cCursor, ":1", SQL_C_CHAR, 32);
    OdbcBind(cCursor, ":2", SQL_C_LONG);
    OdbcSetString(cCursor, ":1", "Bob", 1);
    OdbcSetInt(cCursor, ":2", 25, 1);
    OdbcSetString(cCursor, ":1", "Marcy", 2);
    OdbcSetInt(cCursor, ":2", 33, 2);
    OdbcExecute(cCursor);
    OdbcClose(cCursor, SQL_DROP);
    OdbcCommit(hDbc);
    OdbcDisconnect(hDbc);
    OdbcFree(hDbc);
    OdbcFree(hEnv);
  end TMain;

dclsql
  sqlInsert:
    INSERT INTO persons (name, age) VALUES (?, ?);
Parent topic: Cursor Handling Functions
Related reference
OdbcOpen Function
OdbcSetStmtAttr Function
OdbcGetStmtAttr Function
OdbcSetCursorName Function
OdbcGetCursorName Function
OdbcBind Function


Value Setting Functions

  • OdbcSetBinary Function
    Assigns binary data to a bound place holder of a SQL statement or to a result data column of a SQL query.
  • OdbcSetFloat Function
    Assigns a floating-point value to a bound place holder of a SQL statement or to a result data column of a SQL query.
  • OdbcSetInt Function
    Assigns a number to a bound place holder of a SQL statement or to a result data column of a SQL query.
  • OdbcSetString Function
    Assigns a string to a bound place holder of a SQL statement or to a result data column of a SQL query.
  • OdbcSetNull Function
    Assigns a NULL value to a bound place holder of a SQL statement or to a result data column of a SQL query.
  • OdbcSetMode Function
    Sets the indicator for an item of a bound place holder or a result data column.
Parent topic: ODBC Functions Overview


OdbcSetBinary Function

Action

Assigns binary data to a bound place holder of a SQL statement or to a result data column of a SQL query. Place holders and data columns are identified by number.

Include file

ODBC.bdh

Syntax

OdbcSetBinary( in cCursor     : cursor,
               in sIdentifier : string,
               in sBinary     : string,
               in nLength     : number,
               in nIndex      : number optional ): boolean;

Return value

  • true if successful

  • false otherwise

Parameter | Description
cCursor | Cursor associated with a database connection.
sIdentifier | Identifier of the place holder or the result data column. To identify a place holder, begin this parameter with a colon.
sBinary | Binary data that is assigned to the place holder or the result data column.
nLength | Amount of binary data (in bytes) that is assigned to the place holder or the result data column.
nIndex | Array index for the place holder or column item to be set (optional). By default, this function sets the first item.

Example

var
  hEnv, hDbc : number;
  cCursor : cursor;

dcltrans
  transaction TMain
  begin
    OdbcAlloc(SQL_HANDLE_ENV, hEnv);
    OdbcAlloc(SQL_HANDLE_DBC, hDbc, hEnv);
    OdbcConnect(hDbc, "DSN=database;UID=user;PWD=pass;");
    OdbcOpen(cCursor, hDbc);
    OdbcPrepare(cCursor, sqlInsert);
    OdbcBind(cCursor, ":1", SQL_C_CHAR, 32);
    OdbcBind(cCursor, ":2", SQL_C_BINARY);
    OdbcSetString(cCursor, ":1", "Bob", 1);
    OdbcSetBinary(cCursor, ":2", "\h54516170", 4, 1);
    OdbcSetString(cCursor, ":1", "Marcy", 2);
    OdbcSetBinary(cCursor, ":2", "\h5458516170", 5, 2);
    OdbcExecute(cCursor);
    OdbcClose(cCursor, SQL_DROP);
    OdbcCommit(hDbc);
    OdbcDisconnect(hDbc);
    OdbcFree(hDbc);
    OdbcFree(hEnv);
  end TMain;

dclsql
  sqlInsert:
    INSERT INTO persons (name, password) VALUES (?, ?);
Parent topic: Value Setting Functions
Related reference
OdbcSetFloat Function
OdbcSetInt Function
OdbcSetString Function
OdbcSetNull Function
OdbcSetMode Function


OdbcSetFloat Function

Action

Assigns a floating-point value to a bound place holder of a SQL statement or to a result data column of a SQL query. Place holders and data columns are identified by number.

Include file

ODBC.bdh

Syntax

OdbcSetFloat( in cCursor     : cursor,
              in sIdentifier : string,
              in fValue      : float,
              in nIndex      : number optional): boolean;

Return value

  • true if successful

  • false otherwise

Parameter | Description
cCursor | Cursor associated with a database connection.
sIdentifier | Identifier of the place holder or the result data column. To identify a place holder, begin this parameter with a colon.
fValue | Floating-point value that is assigned to the place holder or the result data column.
nIndex | Array index for the place holder or column item to be set (optional). By default, this function sets the first item.

Example

var
  hEnv, hDbc : number;
  cCursor : cursor;

dcltrans
  transaction TMain
  begin
    OdbcAlloc(SQL_HANDLE_ENV, hEnv);
    OdbcAlloc(SQL_HANDLE_DBC, hDbc, hEnv);
    OdbcConnect(hDbc, "DSN=database;UID=user;PWD=pass;");
    OdbcOpen(cCursor, hDbc);
    OdbcPrepare(cCursor, sqlInsert);
    OdbcBind(cCursor, ":1", SQL_C_CHAR, 32);
    OdbcBind(cCursor, ":2", SQL_C_FLOAT);
    OdbcSetString(cCursor, ":1", "Bob", 1);
    OdbcSetFloat(cCursor, ":2", 1704.4, 1);
    OdbcSetString(cCursor, ":1", "Marcy", 2);
    OdbcSetFloat(cCursor, ":2", 2844.7, 2);
    OdbcExecute(cCursor);
    OdbcClose(cCursor, SQL_DROP);
    OdbcCommit(hDbc);
    OdbcDisconnect(hDbc);
    OdbcFree(hDbc);
    OdbcFree(hEnv);
  end TMain;

dclsql
  sqlInsert:
    INSERT INTO persons (name, balance) VALUES (?, ?);
Parent topic: Value Setting Functions
Related reference
OdbcSetBinary Function
OdbcSetInt Function
OdbcSetString Function
OdbcSetNull Function
OdbcSetMode Function


OdbcSetInt Function

Action

Assigns a number to a bound place holder of a SQL statement or to a result data column of a SQL query. Place holders and data columns are identified by number.

Include file

ODBC.bdh

Syntax

OdbcSetInt( in cCursor     : cursor,
            in sIdentifier : string,
            in nValue      : number,
            in nIndex      : number optional): boolean;

Return value

  • true if successful

  • false otherwise

Parameter | Description
cCursor | Cursor associated with a database connection.
sIdentifier | Identifier of the place holder or the result data column. To identify a place holder, begin this parameter with a colon.
nValue | Number that is assigned to the place holder or the result data column.
nIndex | Array index for the place holder or column item to be set (optional). By default, this function sets the first item.

Example

var
  hEnv, hDbc : number;
  cCursor : cursor;

dcltrans
  transaction TMain
  begin
    OdbcAlloc(SQL_HANDLE_ENV, hEnv);
    OdbcAlloc(SQL_HANDLE_DBC, hDbc, hEnv);
    OdbcConnect(hDbc, "DSN=database;UID=user;PWD=pass;");
    OdbcOpen(cCursor, hDbc);
    OdbcPrepare(cCursor, sqlInsert);
    OdbcBind(cCursor, ":1", SQL_C_CHAR, 32);
    OdbcBind(cCursor, ":2", SQL_C_LONG);
    OdbcSetString(cCursor, ":1", "Bob", 1);
    OdbcSetInt(cCursor, ":2", 25, 1);
    OdbcSetString(cCursor, ":1", "Marcy", 2);
    OdbcSetInt(cCursor, ":2", 33, 2);
    OdbcExecute(cCursor);
    OdbcClose(cCursor, SQL_DROP);
    OdbcCommit(hDbc);
    OdbcDisconnect(hDbc);
    OdbcFree(hDbc);
    OdbcFree(hEnv);
  end TMain;

dclsql
  sqlInsert:
    INSERT INTO persons (name, age) VALUES (?, ?);
Parent topic: Value Setting Functions
Related reference
OdbcSetBinary Function
OdbcSetFloat Function
OdbcSetString Function
OdbcSetNull Function
OdbcSetMode Function


OdbcSetString Function

Action

Assigns a string to a bound place holder of a SQL statement or to a result data column of a SQL query. Place holders and data columns are identified by number.

Include file

ODBC.bdh

Syntax

OdbcSetString( in cCursor     : cursor,
               in sIdentifier : string,
               in sString     : string,
               in nIndex      : number optional ): boolean;

Return value

  • true if successful

  • false otherwise

Parameter | Description
cCursor | Cursor associated with a database connection.
sIdentifier | Identifier of the place holder or the result data column. To identify a place holder, begin this parameter with a colon.
sString | String that is assigned to the place holder or the result data column.
nIndex | Array index for the place holder or column item to be set (optional). By default, this function sets the first item.

Example

var
  hEnv, hDbc : number;
  cCursor : cursor;

dcltrans
  transaction TMain
  begin
    OdbcAlloc(SQL_HANDLE_ENV, hEnv);
    OdbcAlloc(SQL_HANDLE_DBC, hDbc, hEnv);
    OdbcConnect(hDbc, "DSN=database;UID=user;PWD=pass;");
    OdbcOpen(cCursor, hDbc);
    OdbcPrepare(cCursor, sqlInsert);
    OdbcBind(cCursor, ":1", SQL_C_CHAR, 32);
    OdbcBind(cCursor, ":2", SQL_C_LONG);
    OdbcSetString(cCursor, ":1", "Bob", 1);
    OdbcSetInt(cCursor, ":2", 25, 1);
    OdbcSetString(cCursor, ":1", "Marcy", 2);
    OdbcSetInt(cCursor, ":2", 33, 2);
    OdbcExecute(cCursor);
    OdbcClose(cCursor, SQL_DROP);
    OdbcCommit(hDbc);
    OdbcDisconnect(hDbc);
    OdbcFree(hDbc);
    OdbcFree(hEnv);
  end TMain;

dclsql
  sqlInsert:
    INSERT INTO persons (name, age) VALUES (?, ?);
Parent topic: Value Setting Functions
Related reference
OdbcSetBinary Function
OdbcSetFloat Function
OdbcSetInt Function
OdbcSetNull Function
OdbcSetMode Function


OdbcSetNull Function

Action

Assigns a NULL value to a bound place holder of a SQL statement or to a result data column of a SQL query. Place holders and data columns are identified by number.

Include file

ODBC.bdh

Syntax

OdbcSetNull( in cCursor     : cursor,
             in sIdentifier : string,
             in nIndex      : number optional ): boolean;

Return value

  • true if successful

  • false otherwise

Parameter | Description
cCursor | Cursor associated with a database connection.
sIdentifier | Identifier of the place holder or the result data column. To identify a place holder, begin this parameter with a colon.
nIndex | Array index for the place holder or column item to be set (optional). By default, this function sets the first item.

Example

var
  hEnv, hDbc : number;
  cCursor : cursor;

dcltrans
  transaction TMain
  begin
    OdbcAlloc(SQL_HANDLE_ENV, hEnv);
    OdbcAlloc(SQL_HANDLE_DBC, hDbc, hEnv);
    OdbcConnect(hDbc, "DSN=database;UID=user;PWD=pass;");
    OdbcOpen(cCursor, hDbc);
    OdbcPrepare(cCursor, sqlInsert);
    OdbcBind(cCursor, ":1", SQL_C_CHAR, 32);
    OdbcBind(cCursor, ":2", SQL_C_LONG);
    OdbcSetString(cCursor, ":1", "Bob", 1);
    OdbcSetInt(cCursor, ":2", 25, 1);
    OdbcSetString(cCursor, ":1", "Marcy", 2);
    OdbcSetNull(cCursor, ":2", 2);
    OdbcExecute(cCursor);
    OdbcClose(cCursor, SQL_DROP);
    OdbcCommit(hDbc);
    OdbcDisconnect(hDbc);
    OdbcFree(hDbc);
    OdbcFree(hEnv);
  end TMain;

dclsql
  sqlInsert:
    INSERT INTO persons (name, age) VALUES (?, ?);
Parent topic: Value Setting Functions
Related reference
OdbcSetBinary Function
OdbcSetFloat Function
OdbcSetInt Function
OdbcSetString Function
OdbcSetMode Function


OdbcSetMode Function

Action

Sets the indicator for an item of a bound place holder or a result data column.

Include file

ODBC.bdh

Syntax

OdbcSetMode( in cCursor     : cursor ,
             in sIdentifier : string,
             in nMode       : number,
             in nIndex      : number optional ): boolean;

Return value

  • true if successful

  • false otherwise

Parameter | Description
cCursor | Cursor associated with a database connection.
sIdentifier | Identifier of the place holder or the result data column. To identify a place holder, begin this parameter with a colon.
nMode

Indicator for the place holder or column item. This parameter must be set to one of the following values:

  • SQL_NULL_DATA. The data value associated with the place holder or result data column is NULL.

  • SQL_DATA_AT_EXEC. The data value must be sent to the data source at SQL statement execution time.

  • SQL_DEFAULT_PARAM. The default parameters of a stored procedure are used when calling a stored procedure.

  • SQL_IGNORE. The respective column is ignored when processing result data columns.
nIndex | Array index for the place holder or column item whose indicator is to be set (optional). By default, this function sets the indicator for the first item.

Example

var
  hEnv, hDbc : number;
  cCursor : cursor;

dcltrans
  transaction TMain
  var
    sIdentifier : string;
    nRow        : number;
  begin
    OdbcAlloc(SQL_HANDLE_ENV, hEnv);
    OdbcAlloc(SQL_HANDLE_DBC, hDbc, hEnv);
    OdbcConnect(hDbc, "DSN=database;UID=user;PWD=pass;");
    OdbcOpen(cCursor, hDbc);
    OdbcPrepare(cCursor, sqlInsert);
    OdbcBind(cCursor, ":1", SQL_C_CHAR, 32);
    OdbcBind(cCursor, ":2", SQL_C_LONG);
    OdbcSetMode(cCursor, ":1", SQL_DATA_AT_EXEC);
    OdbcSetMode(cCursor, ":2", SQL_DATA_AT_EXEC);
    OdbcExecute(cCursor);
    OdbcParamData(cCursor, sIdentifier, nRow);

    if sIdentifier = ":1" then
      OdbcSetString(cCursor, "", "Jim");
      OdbcParamData(cCursor);
      OdbcSetInt(cCursor, "", 25);
    elseif sIdentifier = ":2" then
      OdbcSetInt(cCursor, "", 25);
      OdbcParamData(cCursor);
      OdbcSetString(cCursor, "", "Jim");
    end;

    OdbcClose(cCursor, SQL_DROP);
    OdbcCommit(hDbc);
    OdbcDisconnect(hDbc);
    OdbcFree(hDbc);
    OdbcFree(hEnv);
  end TMain;

dclsql
  sqlInsert:
  INSERT INTO persons (name, age) VALUES (?, ?);
Parent topic: Value Setting Functions
Related reference
OdbcSetBinary Function
OdbcSetFloat Function
OdbcSetInt Function
OdbcSetString Function
OdbcSetNull Function


SQL Statement Execution Functions

  • OdbcPrepare Function
    Prepares a SQL statement and associates it with a cursor.
  • OdbcExecute Function
    Executes a SQL statement associated with a cursor.
  • OdbcExecDirect Function
    Prepares and executes a SQL statement.
  • OdbcParamData Function
    Determines which data the script has to send to the data source.
  • OdbcCancel Function
    Terminates the SQL statement processing.
Parent topic: ODBC Functions Overview


OdbcPrepare Function

Action

Prepares a SQL statement and associates it with a cursor.

Include file

ODBC.bdh

Syntax

OdbcPrepare( in cCursor      : cursor,
             in sqlStatement : sql ): boolean;

Return value

  • true if successful

  • false otherwise

Parameter | Description
cCursor | Cursor associated with a database connection.
sqlStatement | SQL statement to prepare.

Example

var
  hEnv, hDbc : number;
  cCursor : cursor;

dcltrans
  transaction TMain
  begin
    OdbcAlloc(SQL_HANDLE_ENV, hEnv);
    OdbcAlloc(SQL_HANDLE_DBC, hDbc, hEnv);
    OdbcConnect(hDbc, "DSN=database;UID=user;PWD=pass;");
    OdbcOpen(cCursor, hDbc);
    OdbcPrepare(cCursor, sqlInsert);
    OdbcBind(cCursor, ":1", SQL_C_CHAR, 32);
    OdbcBind(cCursor, ":2", SQL_C_LONG);
    OdbcSetString(cCursor, ":1", "Bob", 1);
    OdbcSetInt(cCursor, ":2", 25, 1);
    OdbcSetString(cCursor, ":1", "Marcy", 2);
    OdbcSetInt(cCursor, ":2", 33, 2);
    OdbcExecute(cCursor);
    OdbcClose(cCursor, SQL_DROP);
    OdbcCommit(hDbc);
    OdbcDisconnect(hDbc);
    OdbcFree(hDbc);
    OdbcFree(hEnv);
  end TMain;

dclsql
  sqlInsert:
    INSERT INTO persons (name, age) VALUES (?, ?);
Parent topic: SQL Statement Execution Functions
Related reference
OdbcExecute Function
OdbcExecDirect Function
OdbcParamData Function
OdbcCancel Function


OdbcExecute Function

Action

Executes a SQL statement associated with a cursor.

Before calling this function, you have to prepare the SQL statement using the OdbcPprepare function. Array binding can be used to process multiple rows of data in a single execute operation. If the SQL statement contains place holders, it is necessary to call the OdbcBind function for each place holder first.

Include file

ODBC.bdh

Syntax

OdbcExecute( in cCursor    : cursor,
             in nArraySize : number optional ): boolean;

Return value

  • true if successful

  • false otherwise

Parameter | Description
cCursor | Cursor associated with a database connection.
nArraySize | Size of the data array. Arrays are used to process multiple rows of data in a single execute operation.

Example

var
  hEnv, hDbc : number;
  cCursor : cursor;

dcltrans
  transaction TMain
  begin
    OdbcAlloc(SQL_HANDLE_ENV, hEnv);
    OdbcAlloc(SQL_HANDLE_DBC, hDbc, hEnv);
    OdbcConnect(hDbc, "DSN=database;UID=user;PWD=pass;");
    OdbcOpen(cCursor, hDbc);
    OdbcPrepare(cCursor, sqlInsert);
    OdbcBind(cCursor, ":1", SQL_C_CHAR, 32);
    OdbcBind(cCursor, ":2", SQL_C_LONG);
    OdbcSetString(cCursor, ":1", "Bob", 1);
    OdbcSetInt(cCursor, ":2", 25, 1);
    OdbcSetString(cCursor, ":1", "Marcy", 2);
    OdbcSetInt(cCursor, ":2", 33, 2);
    OdbcExecute(cCursor);
    OdbcClose(cCursor, SQL_DROP);
    OdbcCommit(hDbc);
    OdbcDisconnect(hDbc);
    OdbcFree(hDbc);
    OdbcFree(hEnv);
  end TMain;

dclsql
  sqlInsert:
    INSERT INTO persons (name, age) VALUES (?, ?);
Parent topic: SQL Statement Execution Functions
Related reference
OdbcPrepare Function
OdbcExecDirect Function
OdbcParamData Function
OdbcCancel Function
OdbcBind Function


OdbcExecDirect Function

Action

Prepares and executes a SQL statement. This function is the fastest way to submit a SQL statement that is to be executed only once to the data source. Because the SQL statement is both prepared and executed in the same step, the specified SQL statement must be reprepared each time it is executed.

Include file

ODBC.bdh

Syntax

OdbcExecDirect(  in cCursor      : cursor,
                 in sqlStatement : sql,
                 in nArraySize   : number optional ): boolean;

Return value

  • true if successful

  • false otherwise

Parameter | Description
cCursor | Cursor associated with a database connection.
sqlStatement | SQL statement to prepare and execute.
nArraySize | Size of the data array. Arrays are used to process multiple rows of data in a single execute operation.

Example

var
  hEnv, hDbc : number;
  cCursor : cursor;

dcltrans
  transaction TMain
  begin
    OdbcAlloc(SQL_HANDLE_ENV, hEnv);
    OdbcAlloc(SQL_HANDLE_DBC, hDbc, hEnv);
    OdbcConnect(hDbc, "DSN=database;UID=user;PWD=pass;");
    OdbcOpen(cCursor, hDbc);
    OdbcBind(cCursor, ":1", SQL_C_CHAR, 32);
    OdbcBind(cCursor, ":2", SQL_C_LONG);
    OdbcSetString(cCursor, ":1", "Bob", 1);
    OdbcSetInt(cCursor, ":2", 25, 1);
    OdbcSetString(cCursor, ":1", "Marcy", 2);
    OdbcSetInt(cCursor, ":2", 33, 2);
    OdbcExecDirect(cCursor, sqlInsert);
    OdbcClose(cCursor, SQL_DROP);
    OdbcCommit(hDbc);
    OdbcDisconnect(hDbc);
    OdbcFree(hDbc);
    OdbcFree(hEnv);
  end TMain;

dclsql
  sqlInsert:
    INSERT INTO persons (name, age) VALUES (?, ?);
Parent topic: SQL Statement Execution Functions
Related reference
OdbcPrepare Function
OdbcExecute Function
OdbcParamData Function
OdbcCancel Function


OdbcParamData Function

Action

Determines which data the script has to send to the data source.

When a Silk Performer script executes a SQL statement, the ODBC driver requests data when it encounters a data-at-execution parameter or column. This function then determines which data the script should send. Once the script knows what data to send, it must call the OdbcSet functions repeatedly until all the data-at-execution data has been sent to the data source.

Include file

ODBC.bdh

Syntax

OdbcParamData(
   in  cCursor     : cursor,
   out sIdentifier : string optional,
   out nIndex      : number optional ) : boolean;

Return value

  • true if the data source expects data

  • false otherwise

Parameter | Description
cCursor | Cursor associated with a database connection.
sIdentifier | Variable receiving the identifier of the place holder or result data column whose item has to be sent to the data source (optional).
nIndex | Variable receiving the array index of the place holder or column item that has to be sent to the data source (optional).

Example

var
  hEnv, hDbc : number;
  cCursor : cursor;

dcltrans
  transaction TMain
  var
    sIdentifier : string;
    nRow        : number;
  begin
    OdbcAlloc(SQL_HANDLE_ENV, hEnv);
    OdbcAlloc(SQL_HANDLE_DBC, hDbc, hEnv);
    OdbcConnect(hDbc, "DSN=database;UID=user;PWD=pass;");
    OdbcOpen(cCursor, hDbc);
    OdbcPrepare(cCursor, sqlInsert);
    OdbcBind(cCursor, ":1", SQL_C_CHAR, 32);
    OdbcBind(cCursor, ":2", SQL_C_LONG);
    OdbcSetMode(cCursor, ":1", SQL_DATA_AT_EXEC);
    OdbcSetMode(cCursor, ":2", SQL_DATA_AT_EXEC);
    OdbcExecute(cCursor);
    OdbcParamData(cCursor, sIdentifier, nRow);
    if sIdentifier = ":1" then
      OdbcSetString(cCursor, "", "Jim");
      OdbcParamData(cCursor);
      OdbcSetInt(cCursor, "", 25);
    elseif sIdentifier = ":2" then
      OdbcSetInt(cCursor, "", 25);
      OdbcParamData(cCursor);
      OdbcSetString(cCursor, "", "Jim");
    end;
    OdbcClose(cCursor, SQL_DROP);
    OdbcCommit(hDbc);
    OdbcDisconnect(hDbc);
    OdbcFree(hDbc);
    OdbcFree(hEnv);
  end TMain;

dclsql
  sqlInsert:
  INSERT INTO persons (name, age) VALUES (?, ?);
Parent topic: SQL Statement Execution Functions
Related reference
OdbcPrepare Function
OdbcExecute Function
OdbcExecDirect Function
OdbcCancel Function
OdbcSetBinary Function
OdbcSetFloat Function
OdbcSetInt Function
OdbcSetString Function
OdbcSetNull Function


OdbcCancel Function

Action

Terminates the SQL statement processing.

Include file

ODBC.bdh

Syntax

OdbcCancel( in cCursor : cursor ) : boolean;

Return value

  • true if successful

  • false otherwise

Parameter | Description
cCursor | Cursor associated with a database connection.

Example

var
  hEnv, hDbc : number;
  cCursor : cursor;

dcltrans
  transaction TMain
  begin
    OdbcAlloc(SQL_HANDLE_ENV, hEnv);
    OdbcAlloc(SQL_HANDLE_DBC, hDbc, hEnv);
    OdbcConnect(hDbc, "DSN=database;UID=user;PWD=pass;");
    OdbcOpen(cCursor, hDbc);
    OdbcPrepare(cCursor, sqlInsert);
    OdbcBind(cCursor, ":1", SQL_C_CHAR, 32);
    OdbcBind(cCursor, ":2", SQL_C_LONG);
    OdbcSetMode(cCursor, ":1", SQL_DATA_AT_EXEC);
    OdbcSetMode(cCursor, ":2", SQL_DATA_AT_EXEC);
    OdbcExecute(cCursor);
    OdbcParamData(cCursor);
    OdbcCancel(cCursor);
    OdbcClose(cCursor, SQL_DROP);
    OdbcDisconnect(hDbc);
    OdbcFree(hDbc);
    OdbcFree(hEnv);
  end TMain;

dclsql
  sqlInsert:
    INSERT INTO persons (name, age) VALUES (?, ?);
Parent topic: SQL Statement Execution Functions
Related reference
OdbcPrepare Function
OdbcExecute Function
OdbcExecDirect Function
OdbcParamData Function


Value Retrieving Functions

  • OdbcDefine Function
    Defines an output variable for a specified select-list item in a SQL query.
  • OdbcFetch Function
    Performs a specified number of fetch operations in order to retrieve data from a SQL query.
  • OdbcSetPos Function
    Sets the cursor position in a row set, refreshes data in a row set, or adds, updates and/or deletes data in an updatable result data set.
  • OdbcMoreResults Function
    Determines whether more result data sets or row counts are available for a cursor, and if so, initializes processing for the next result data set or row count information available.
  • OdbcGetValue Function
    Retrieves any value either from a bound place holder of a SQL statement or from a result data column of a SQL query.
  • OdbcGetFloat Function
    Retrieves a floating-point value either from a bound place holder of a SQL statement or from a result data column of a SQL query.
  • OdbcGetInt Function
    Retrieves a number either from a bound place holder of a SQL statement or from a result data column of a SQL query.
  • OdbcGetString Function
    Retrieves a string either from a bound place holder of a SQL statement or from a result data column of a SQL query.
Parent topic: ODBC Functions Overview


OdbcDefine Function

Action

Defines an output variable for a specified select-list item in a SQL query. It is necessary to call this function for each select-list item of a SQL query. After the OdbcExecute and OdbcFetch functions have been called, the OdbcGet functions can be used to retrieve the values of the select-list items:

Include file

ODBC.bdh

Syntax

OdbcDefine(
   in cCursor   : cursor,
   in sPosition : string,
   in nDataType : number optional,
   in nSize     : number optional ): boolean;

Return value

  • true if successful

  • false otherwise

Parameter | Description
cCursor | Cursor associated with a database connection.
sPosition | Index of the select-list item in the SQL query. Position indices start at 1 for the first (left-most) select-list item.
nDataType | ODBC data type of the select-list item (optional). The default value is SQL_C_CHAR.
nSize | Length of the select-list item in bytes (optional). This parameter should be omitted for data types of fixed length.

Example

var
  hEnv, hDbc : number;
  cCursor : cursor;

dcltrans
  transaction TMain
  begin
    OdbcAlloc(SQL_HANDLE_ENV, hEnv);
    OdbcAlloc(SQL_HANDLE_DBC, hDbc, hEnv);
    OdbcConnect(hDbc, "DSN=database;UID=user;PWD=pass;");
    OdbcOpen(cCursor, hDbc);
    OdbcPrepare(cCursor, sqlSelect);
    OdbcExecute(cCursor);
    OdbcDefine(cCursor, "1", SQL_C_CHAR, 32);
    OdbcDefine(cCursor, "2", SQL_C_LONG);
    while OdbcFetch(cCursor) do
      write("name: " + OdbcGetString(cCursor, "1"));
      writeln(" age: " + (string)OdbcGetInt(cCursor, "2"));
    end;
    OdbcClose(cCursor, SQL_DROP);
    OdbcCommit(hDbc);
    OdbcDisconnect(hDbc);
    OdbcFree(hDbc);
    OdbcFree(hEnv);
  end TMain;
dclsql
  sqlSelect:
  SELECT * FROM persons;
Parent topic: Value Retrieving Functions
Related reference
OdbcFetch Function
OdbcSetPos Function
OdbcMoreResults Function
OdbcGetValue Function
OdbcGetFloat Function
OdbcGetInt Function
OdbcGetString Function


OdbcFetch Function

Action

Performs a specified number of fetch operations in order to retrieve data from a SQL query. This function is used to fetch both single and multiple rows. It can be called only while a result data set exists. That is, after a SQL statement that creates a result set is executed and before the cursor associated with that result data is closed.

Include file

ODBC.bdh

Syntax

OdbcFetch( in  cCursor     : cursor,
           in  nIterations : number optional,
           in  nArraySize  : number optional,
           in  nDirection  : number optional,
           in  nOption     : number optional,
           in  nBookmark   : number optional,
           out nFetched    : number optional ): boolean;

Return value

  • true if successful

  • false otherwise

Parameter | Description
cCursor | Cursor associated with a database connection.
nIterations

Number of iterations to perform (optional). Predefined options are:

  • SQL_FETCH_ALL. Repeat the fetch operation until all rows have been fetched

The default option is to perform a single iteration
nArraySize | Number of rows to fetch per iteration (optional). The default option is to fetch a single row per iteration.
nDirection

Specifies the direction and type of fetch to perform (optional). This parameter must be set to one of the following values:

  • SQL_FETCH_NEXT

  • SQL_FETCH_FIRST

  • SQL_FETCH_LAST

  • SQL_FETCH_PRIOR

  • SQL_FETCH_ABSOLUTE

  • SQL_FETCH_RELATIVE

  • SQL_FETCH_RESUME

  • SQL_FETCH_BOOKMARK
nOption | Ordinal position of the first row in the row set to fetch (optional).
nBookmark | Bookmark value used to identify a row of data (optional).
nFetched | Variable receiving the actual number of rows fetched (optional).

Example

var
  hEnv, hDbc : number;
  c1, c2 : cursor;

dcltrans
  transaction TMain
  begin
    OdbcAlloc(SQL_HANDLE_ENV, hEnv);
    OdbcAlloc(SQL_HANDLE_DBC, hDbc, hEnv);
    OdbcConnect(hDbc, "DSN=database;UID=user;PWD=pass;");
    OdbcOpen(c1, hDbc);
    OdbcPrepare(c1, sqlSelect);
    OdbcSetCursorName(c1, "cursor_persons");
    OdbcExecute(c1);
    OdbcFetch(c1);
    OdbcOpen(c2, hDbc);
    OdbcPrepare(c2, sqlDelete);
    OdbcExecute(c2);
    OdbcClose(c1, SQL_DROP);
    OdbcClose(c2, SQL_DROP);
    OdbcCommit(hDbc);
    OdbcDisconnect(hDbc);
    OdbcFree(hDbc);
    OdbcFree(hEnv);
  end TMain;

dclsql
  sqlSelect:
    SELECT * FROM persons;
  sqlDelete:
    DELETE FROM persons WHERE CURRENT OF cursor_persons;
Parent topic: Value Retrieving Functions
Related reference
OdbcDefine Function
OdbcSetPos Function
OdbcMoreResults Function
OdbcGetValue Function
OdbcGetFloat Function
OdbcGetInt Function
OdbcGetString Function


OdbcSetPos Function

Action

Sets the cursor position in a row set, refreshes data in a row set, or adds, updates and/or deletes data in an updatable result data set.

Include file

ODBC.bdh

Syntax

OdbcSetPos(
   in cCursor    : cursor,
   in nRow       : number,
   in nOperation : number,
   in nLockType  : number): boolean;

Return value

  • true if successful

  • false otherwise

Parameter | Description
cCursor | Cursor associated with a database connection.
nRow | Ordinal position of the row in the row set on which to perform the operation specified in the nOperation parameter. If this parameter is set to 0, the operation specified is performed on every row in the row set.
nOperation

Operation to perform. This parameter must be set to one of the following values:

  • SQL_POSITION

  • SQL_REFRESH

  • SQL_UPDATE

  • SQL_DELETE

  • SQL_ADD
nLockType

Specifies how to lock the row after performing the operation specified in the nOperation parameter. This parameter must be set to one of the following values:

  • SQL_LOCK_NO_CHANGE

  • SQL_LOCK_EXCLUSIVE

  • SQL_LOCK_UNLOCK

Example

var
  hEnv, hDbc : number;
  cCursor : cursor;

dcltrans
  transaction TMain
  begin
    OdbcAlloc(SQL_HANDLE_ENV, hEnv);
    OdbcAlloc(SQL_HANDLE_DBC, hDbc, hEnv);
    OdbcConnect(hDbc, "DSN=database;UID=user;PWD=pass;");
    OdbcOpen(cCursor, hDbc);
    OdbcPrepare(cCursor, sqlSelect);
    OdbcExecute(cCursor);
    OdbcDefine(cCursor, "1", SQL_C_CHAR, 32);
    OdbcDefine(cCursor, "2", SQL_C_LONG);
    OdbcFetch(cCursor, 20);
    OdbcSetPos(cCursor, 5, SQL_POSITION, SQL_LOCK_NO_CHANGE);
    write("name: " + OdbcGetString(cCursor, "1"));
    writeln(" age: " + (string)OdbcGetInt(cCursor, "2"));
    OdbcClose(cCursor, SQL_DROP);
    OdbcCommit(hDbc);
    OdbcDisconnect(hDbc);
    OdbcFree(hDbc);
    OdbcFree(hEnv);
  end TMain;

dclsql
  sqlSelect:
  SELECT * FROM persons;
Parent topic: Value Retrieving Functions
Related reference
OdbcDefine Function
OdbcFetch Function
OdbcMoreResults Function
OdbcGetValue Function
OdbcGetFloat Function
OdbcGetInt Function
OdbcGetString Function


OdbcMoreResults Function

Action

Determines whether more result data sets or row counts are available for a cursor, and if so, initializes processing for the next result data set or row count information available.

Include file

ODBC.bdh

Syntax

OdbcMoreResults( in cCursor: cursor ) : boolean;

Return value

  • true if more result data sets or row counts are available for the cursor

  • false otherwise

Parameter | Description
cCursor | Cursor associated with a database connection.

Example

var
  hEnv, hDbc : number;
  cCursor : cursor;

dcltrans
  transaction TMain
  begin
    OdbcAlloc(SQL_HANDLE_ENV, hEnv);
    OdbcAlloc(SQL_HANDLE_DBC, hDbc, hEnv);
    OdbcConnect(hDbc, "DSN=database;UID=user;PWD=pass;");
    OdbcOpen(cCursor, hDbc);
    OdbcPrepare(cCursor, sqlSelect);
    OdbcExecute(cCursor);
    OdbcDefine(cCursor, "1", SQL_C_CHAR, 32);
    OdbcDefine(cCursor, "2", SQL_C_LONG);
    OdbcFetch(cCursor);
    write("name: " + OdbcGetString(cCursor, "1"));
    writeln(" age: " + (string)OdbcGetInt(cCursor, "2"));
    if OdbcMoreResult(cCursor) then
      writeln("more entries available");
    end;
    OdbcClose(cCursor, SQL_DROP);
    OdbcCommit(hDbc);
    OdbcDisconnect(hDbc);
    OdbcFree(hDbc);
    OdbcFree(hEnv);
  end TMain;

dclsql
  sqlSelect:
  SELECT * FROM persons;
Parent topic: Value Retrieving Functions
Related reference
OdbcDefine Function
OdbcFetch Function
OdbcSetPos Function
OdbcGetValue Function
OdbcGetFloat Function
OdbcGetInt Function
OdbcGetString Function


OdbcGetValue Function

Action

Retrieves any value either from a bound place holder of a SQL statement or from a result data column of a SQL query. Place holders and data columns are identified by number.

Include file

ODBC.bdh

Syntax

OdbcGetValue( in  cCursor     : cursor,
              in  sIdentifier : string,
              out sBuffer     : string,
              in  nBufferSize : number,
              in  nIndex      : number optional ): boolean;

Return value

  • true if successful

  • false otherwise

Parameter | Description
cCursor | Cursor associated with a database connection.
sIdentifier | Identifier of the place holder or the result data column. To identify a place holder, begin this parameter with a colon.
sBuffer | Variable receiving either the data assigned to the place holder or the data retrieved from a fetched row, as the case may be.
nBufferSize | Size of the variable receiving the value.
nIndex | Array index for the place holder or column item to be retrieved (optional). By default, this function retrieves the first item. An index greater than 1 requires the preceding OdbcFetch call to retrieve more than one data row at once by specifying the optional nArraySize parameter accordingly.

Example

var
  hEnv, hDbc : number;
  cCursor : cursor;

dcltrans
  transaction TMain
  var
    sBuffer : string;
    nLength : number;
  begin
    OdbcAlloc(SQL_HANDLE_ENV, hEnv);
    OdbcAlloc(SQL_HANDLE_DBC, hDbc, hEnv);
    OdbcConnect(hDbc, "DSN=database;UID=user;PWD=pass;");
    OdbcOpen(cCursor, hDbc);
    OdbcPrepare(cCursor, sqlSelect);
    OdbcExecute(cCursor);
    OdbcDefine(cCursor, "1", SQL_C_CHAR, 32);
    OdbcDefine(cCursor, "2", SQL_C_BINARY);

    while OdbcFetch(cCursor) do
      write("name: " + OdbcGetString(cCursor, "1"));
      OdbcGetValue(cCursor, "2", sBuffer, nLength);
      WriteData(sBuffer, nLength);
    end;

    OdbcClose(cCursor, SQL_DROP);
    OdbcCommit(hDbc);
    OdbcDisconnect(hDbc);
    OdbcFree(hDbc);
    OdbcFree(hEnv);
  end TMain;

dclsql
  sqlSelect:
    SELECT * FROM persons;
Parent topic: Value Retrieving Functions
Related reference
OdbcDefine Function
OdbcFetch Function
OdbcSetPos Function
OdbcMoreResults Function
OdbcGetFloat Function
OdbcGetInt Function
OdbcGetString Function


OdbcGetFloat Function

Action

Retrieves a floating-point value either from a bound place holder of a SQL statement or from a result data column of a SQL query. Place holders and data columns are identified by number.

Include file

ODBC.bdh

Syntax

OdbcGetFloat(
   in cCursor     : cursor,
   in sIdentifier : string,
   in nIndex      : number optional ): float;

Return value

Either the floating-point value assigned to the place holder or the value retrieved from a fetched row.

Parameter | Description
cCursor | Cursor associated with a database connection.
sIdentifier | Identifier of the place holder or the result data column. To identify a place holder, begin this parameter with a colon.
nIndex | Array index for the place holder or column item to be retrieved (optional). By default, this function retrieves the first item. An index greater than 1 requires the preceding OdbcFetch call to retrieve more than one data row at once by specifying the optional nArraySize parameter accordingly.

Example

var
  hEnv, hDbc : number;
  cCursor : cursor;

dcltrans
  transaction TMain
  begin
    OdbcAlloc(SQL_HANDLE_ENV, hEnv);
    OdbcAlloc(SQL_HANDLE_DBC, hDbc, hEnv);
    OdbcConnect(hDbc, "DSN=database;UID=user;PWD=pass;");
    OdbcOpen(cCursor, hDbc);
    OdbcPrepare(cCursor, sqlSelect);
    OdbcExecute(cCursor);
    OdbcDefine(cCursor, "1", SQL_C_CHAR, 32);
    OdbcDefine(cCursor, "2", SQL_C_FLOAT);
    while OdbcFetch(cCursor) do
      write("name: " + OdbcGetString(cCursor, "1"));
      writeln(" balance: " + (string)OdbcGetFloat(cCursor, "2"));
    end;
    OdbcClose(cCursor, SQL_DROP);
    OdbcCommit(hDbc);
    OdbcDisconnect(hDbc);
    OdbcFree(hDbc);
    OdbcFree(hEnv);
  end TMain;

dclsql
  sqlSelect:
  SELECT * FROM persons;
Parent topic: Value Retrieving Functions
Related reference
OdbcDefine Function
OdbcFetch Function
OdbcSetPos Function
OdbcMoreResults Function
OdbcGetValue Function
OdbcGetInt Function
OdbcGetString Function


OdbcGetInt Function

Action

Retrieves a number either from a bound place holder of a SQL statement or from a result data column of a SQL query. Place holders and data columns are identified by number.

Include file

ODBC.bdh

Syntax

OdbcGetInt(
   in cCursor     : cursor,
   in sIdentifier : string,
   in nIndex      : number optional ) : number;

Return value

Either the number assigned to the place holder or the number retrieved from a fetched row.

Parameter | Description
cCursor | Cursor associated with a database connection.
sIdentifier | Identifier of the place holder or the result data column. To identify a place holder, begin this parameter with a colon.
nIndex | Array index for the place holder or column item to be retrieved (optional). By default, this function retrieves the first item. An index greater than 1 requires the preceding OdbcFetch call to retrieve more than one data row at once by specifying the optional nArraySize parameter accordingly.

Example

var
  hEnv, hDbc : number;
  cCursor : cursor;

dcltrans
  transaction TMain
  begin
    OdbcAlloc(SQL_HANDLE_ENV, hEnv);
    OdbcAlloc(SQL_HANDLE_DBC, hDbc, hEnv);
    OdbcConnect(hDbc, "DSN=database;UID=user;PWD=pass;");
    OdbcOpen(cCursor, hDbc);
    OdbcPrepare(cCursor, sqlSelect);
    OdbcExecute(cCursor);
    OdbcDefine(cCursor, "1", SQL_C_CHAR, 32);
    OdbcDefine(cCursor, "2", SQL_C_LONG);
    while OdbcFetch(cCursor) do
      write("name: " + OdbcGetString(cCursor, "1"));
      writeln(" age: " + String(OdbcGetInt(cCursor, "2"));
    end;
    OdbcClose(cCursor, SQL_DROP);
    OdbcCommit(hDbc);
    OdbcDisconnect(hDbc);
    OdbcFree(hDbc);
    OdbcFree(hEnv);
  end TMain;

dclsql
  sqlSelect:
  SELECT * FROM persons;
Parent topic: Value Retrieving Functions
Related reference
OdbcDefine Function
OdbcFetch Function
OdbcSetPos Function
OdbcMoreResults Function
OdbcGetValue Function
OdbcGetFloat Function
OdbcGetString Function


OdbcGetString Function

Action

Retrieves a string either from a bound place holder of a SQL statement or from a result data column of a SQL query. Place holders and data columns are identified by number.

Include file

ODBC.bdh

Syntax

OdbcGetString(
   in cCursor     : cursor,
   in sIdentifier : string,
   in nIndex      : number optional ) : string;

Return value

Either the string assigned to the place holder or the string retrieved from a fetched row.

Parameter | Description
cCursor | Cursor associated with a database connection.
sIdentifier | Identifier of the place holder or the result data column. To identify a place holder, begin this parameter with a colon.
nIndex | Array index for the place holder or column item to be retrieved (optional). By default, this function retrieves the first item. An index greater than 1 requires the preceding OdbcFetch call to retrieve more than one data row at once by specifying the optional nArraySize parameter accordingly.

Example

var
  hEnv, hDbc : number;
  cCursor : cursor;

dcltrans
  transaction TMain
  begin
    OdbcAlloc(SQL_HANDLE_ENV, hEnv);
    OdbcAlloc(SQL_HANDLE_DBC, hDbc, hEnv);
    OdbcConnect(hDbc, "DSN=database;UID=user;PWD=pass;");
    OdbcOpen(cCursor, hDbc);
    OdbcPrepare(cCursor, sqlSelect);
    OdbcExecute(cCursor);
    OdbcDefine(cCursor, "1", SQL_C_CHAR, 32);
    OdbcDefine(cCursor, "2", SQL_C_LONG);
   while OdbcFetch(cCursor) do
      write("name: " + OdbcGetString(cCursor, "1"));
      writeln(" age: " + (string)OdbcGetInt(cCursor, "2"));
    end;
    OdbcClose(cCursor, SQL_DROP);
    OdbcCommit(hDbc);
    OdbcDisconnect(hDbc);
    OdbcFree(hDbc);
    OdbcFree(hEnv);
  end TMain;

dclsql
  sqlSelect:
  SELECT * FROM persons;
Parent topic: Value Retrieving Functions
Related reference
OdbcDefine Function
OdbcFetch Function
OdbcSetPos Function
OdbcMoreResults Function
OdbcGetValue Function
OdbcGetFloat Function
OdbcGetInt Function


Transaction Handling Functions

  • OdbcCommit Function
    Commits the current transaction.
  • OdbcRollback Function
    Rolls back the current transaction.
Parent topic: ODBC Functions Overview


OdbcCommit Function

Action

Commits the current transaction. All SQL statements since the last call of the OdbcConnect, OdbcCommit or OdbcRollback function are committed.

Include file

ODBC.bdh

Syntax

OdbcCommit( in hConnection : number ): boolean;

Return value

  • true if successful

  • false otherwise

Parameter | Description
hConnection | Handle to a database connection.

Example

var
  hEnv, hDbc : number;
  cCursor : cursor;

dcltrans
  transaction TMain
  begin
    OdbcAlloc(SQL_HANDLE_ENV, hEnv);
    OdbcAlloc(SQL_HANDLE_DBC, hDbc, hEnv);
    OdbcConnect(hDbc, "DSN=database;UID=user;PWD=pass;");
    OdbcOpen(cCursor, hDbc);
    OdbcPrepare(cCursor, sqlInsert);
    OdbcBind(cCursor, ":1", SQL_C_CHAR, 32);
    OdbcBind(cCursor, ":2", SQL_C_LONG);
    OdbcSetString(cCursor, ":1", "Bob", 1);
    OdbcSetInt(cCursor, ":2", 25, 1);
    OdbcSetString(cCursor, ":1", "Marcy", 2);
    OdbcSetInt(cCursor, ":2", 33, 2);
    OdbcExecute(cCursor);
    OdbcClose(cCursor, SQL_DROP);
    OdbcCommit(hDbc);
    OdbcDisconnect(hDbc);
    OdbcFree(hDbc);
    OdbcFree(hEnv);
  end TMain;

dclsql
  sqlInsert:
    INSERT INTO persons (name, age) VALUES (?, ?);
Parent topic: Transaction Handling Functions
Related reference
OdbcRollback Function
OdbcConnect Function


OdbcRollback Function

Action

Rolls back the current transaction. All SQL statements since the last call of the OdbcConnect, OdbcCommit or OdbcRollback function are rolled back.

Include file

ODBC.bdh

Syntax

OdbcRollback( in hConnection : number ): boolean;

Return value

  • true if successful

  • false otherwise

Parameter | Description
hConnection | Handle to a database connection.

Example

var
  hEnv, hDbc : number;
  cCursor    : cursor;

dcltrans
  transaction TMain
  begin
    OdbcAlloc(SQL_HANDLE_ENV, hEnv);
    OdbcAlloc(SQL_HANDLE_DBC, hDbc, hEnv);
    OdbcConnect(hDbc, "DSN=database;UID=user;PWD=pass;");
    OdbcOpen(cCursor, hDbc);
    OdbcPrepare(cCursor, sqlInsert);
    OdbcBind(cCursor, ":1", SQL_C_CHAR, 32);
    OdbcBind(cCursor, ":2", SQL_C_LONG);
    OdbcSetString(cCursor, ":1", "Bob", 1);
    OdbcSetInt(cCursor, ":2", 25, 1);
    OdbcSetString(cCursor, ":1", "Marcy", 2);
    OdbcSetInt(cCursor, ":2", 33, 2);
    OdbcExecute(cCursor);
    OdbcClose(cCursor, SQL_DROP);
    OdbcRollback(hDbc);
    OdbcDisconnect(hDbc);
    OdbcFree(hDbc);
    OdbcFree(hEnv);
  end TMain;

dclsql
  sqlInsert:
    INSERT INTO persons (name, age) VALUES (?, ?);
Parent topic: Transaction Handling Functions
Related reference
OdbcCommit Function
OdbcConnect Function


Error Handling Functions

  • OdbcIgnoreError Function
    Specifies that a specific ODBC error is to be ignored if it occurs during the next ODBC function call.
Parent topic: ODBC Functions Overview


OdbcIgnoreError Function

Action

Specifies that a specific ODBC error is to be ignored if it occurs during the next ODBC function call. Since the error is then treated in the same way as a warning, the simulation will not be aborted.

Include file

ODBC.bdh

Syntax

OdbcIgnoreError( in sState  : string,
                 in nNative : number optional );
Parameter | Description
sState | SQL state value that is generated when an ODBC function fails. This five-character string value must consist of a two-character class value followed by a three-character subclass value.
nNative | For general errors that generate an “HY000” SQL state, this parameter specifies the native ODBC error code (optional).
Parent topic: Error Handling Functions


Oracle API Functions Overview

Silk Performer provides Oracle API functions along with Oracle database traffic recording and replaying support. The new functions replace the obsolete Oracle call interface (OCI) functions whose names start with Ora_ and Oci_ (used in previous Silk Performer versions). Although the old OCI functions still work, use the new Oracle API functions since the Oracle OCI Recorder generates scripts based on these functions.

Oracle API functions provide a simple and powerful interface to Oracle databases version 7.x and version 8.x. All features of Oracle 7.x and Oracle 8.x except Oracle object support are accessible through these Oracle API functions, including

  • array binding and fetching

  • piecewise binding and fetching

  • binding PL/SQL tables

  • calling PL/SQL blocks and stored procedures

  • cursor binding

  • support for all Oracle data types, including LOB (Large Object) data types

All Oracle API functions were implemented with the help of Oracle's OCI functions version 7. The optional parameters concept enables both simple usage of the API on the one hand and performing specific database operations using the same functions on the other hand. All functions listed below are available:

  • Connection-handling and Cursor-handling Functions
    Lists the Oracle connection-handling and cursor-handling functions.
  • Parameter Binding Functions
    Lists the Oracle parameter binding functions.
  • Result Set Definition Functions
    Lists the Oracle result set definition functions.
  • Statement Processing Functions
    Lists the Oracle statement processing functions.
  • Placeholder Binding Functions
    Lists the Oracle placeholder binding functions.
  • Data Fetching Functions
    Lists the Oracle data fetching functions.
  • Date Functions
    Lists the Oracle date functions.
  • Error Handling Functions
    Lists the Oracle error handling functions.
  • Functions Identical to Original OCI Functions
    Lists the Oracle functions that are identical to the original OCI functions.
  • General Information About Oracle and OCI
    Distinguishes the Oracle version from the OCI version.
  • Oracle Data Types
    Lists the Oracle external data types that are supported in Oracle functions.
Parent topic: Database (DBMS) Functions


Connection-handling and Cursor-handling Functions

  • OraLogon Function
    Establishes a connection to an Oracle database.
  • OraLogoff Function
    Shuts down a connection to an Oracle database.
  • OraOpen Function
    Associates a cursor with a database connection.
  • OraClose Function
    Closes a cursor and releases all allocated resources.
Parent topic: Oracle API Functions Overview


OraLogon Function

Action

Establishes a connection to an Oracle database. Using this function, you can establish multiple connections to either a single database or to several Oracle instances at the same time.

Include file

Ora.bdh

Syntax

OraLogon( out hConnection : number,
          in  sUser       : string,
          in  sPassword   : string optional,
          in  sConnect    : string optional): boolean;

Return value

  • true if successful

  • false otherwise. In this case, you can use the OraOciError function to retrieve the Oracle OCI error code

Parameter | Description
hConnection | Variable receiving the handle to the database connection.
sUser

User Identification. This parameter contains either only the user name or the user name, the password, and the host machine identifier. In the latter case, it is necessary to insert a / character between the user name and the password, and a @ character between the password and the connect string. Valid examples are shown below:

  • name

  • name/password

  • name@service_name

  • name/password@service_name
sPassword | Password (optional). If the password is specified through the sUser parameter, this parameter should be omitted or set to NULL
sConnect | SQL*Net V2 connect descriptor (optional). If the connect string is passed through the sUser parameter, this parameter should be omitted

Example

var
  hConnection: number;
dcltrans
  transaction TMain
  var
    bOk: boolean;
  begin
    bOk := OraLogon(hConnection, "user", "password", "orclnet2");

    if bOk then
      write("Connection to database established"); writeln;
    else      write("Error connecting to database"); writeln;
    end;
    ...
    OraLogoff(hConnection);
  end TMain;

Output

Connection to database established

Sample scripts

OraArrayFetch.bdf, OraSample.bdf, OraLoadPers.bdf

Parent topic: Connection-handling and Cursor-handling Functions
Related reference
OraLogoff Function
OraOpen Function
OraClose Function
OraOciError Function


OraLogoff Function

Action

Shuts down a connection to an Oracle database. When a program establishes multiple simultaneous active connections, separate OraLogoff function calls must be performed for each active connection.

Include file

Ora.bdh

Syntax

OraLogoff( in hConnection : number ): boolean;

Return value

  • true if successful

  • false otherwise. In this case, you can use the OraOciError function to retrieve the Oracle OCI error code

Parameter | Description
hConnection | Valid handle to a database connection established using the OraLogon function

Example

var
  hConnection : number;
  cCursor     : cursor;

dcltrans
  transaction TMain
  begin
    OraLogon(hConnection, "user", "password", "orclnet2");
    OraOpen(cCursor, hConnection);
    ...
    OraLogoff(hConnection);
  end TMain;

Sample scripts

OraArrayFetch.bdf, OraSample.bdf, OraLoadPers.bdf

Parent topic: Connection-handling and Cursor-handling Functions
Related reference
OraLogon Function
OraOpen Function
OraClose Function
OraOciError Function


OraOpen Function

Action

Associates a cursor with a database connection. A cursor serves to maintain state information about processing a SQL statement. In a test script, multiple cursors can be used at the same time. Usually, immediately after opening a cursor, the OraParse function is called to parse a SQL statement and associate the statement with a cursor.

Include file

Ora.bdh

Syntax

OraOpen( out cCursor     : cursor,
         in  hConnection : number): boolean;

Return value

  • true if successful

  • false otherwise. In this case, you can use the OraOciError function to retrieve the Oracle OCI error code

Parameter | Description
cCursor | Variable receiving the cursor associated with the database connection
hConnection | Valid handle to a database connection

Example

var
  hConnection : number;
  cCursor     : cursor;

dcltrans
  transaction TMain
  begin
    OraLogon(hConnection, "user", "password", "orclnet2");
    OraOpen(cCursor, hConnection);
    ...
    OraClose(cCursor);
    OraLogoff(hConnection);
  end TMain;

Sample scripts

OraArrayFetch.bdf, OraSample.bdf, OraLoadPers.bdf

Parent topic: Connection-handling and Cursor-handling Functions
Related reference
OraLogon Function
OraLogoff Function
OraClose Function
OraOciError Function
OraParse Function


OraClose Function

Action

Closes a cursor and releases all allocated resources.

Include file

Ora.bdh

Syntax

OraClose( inout cCursor: cursor ): boolean;

Return value

  • true if successful

  • false otherwise. In this case, you can use the OraOciError function to retrieve the Oracle OCI error code

Parameter | Description
cCursor | Cursor associated with a database connection.

Example

var
  hConnection : number;
  cCursor     : cursor;

dcltrans
  transaction TMain
  var
    bOk  : boolean;
  begin
    OraLogon(hConnection, "user", "password", "orclnet2");
    OraOpen(cCursor, hConnection);
    ...

    bOk := OraClose(cCursor);
    if bOk then
      write("Cursor successfully closed"); writeln;
    else
      write("Could not close cursor"); writeln;
    end;

    OraLogoff(hConnection);
  end TMain;

Output

Cursor successfully closed

Sample scripts

OraArrayFetch.bdf, OraSample.bdf, OraLoadPers.bdf

Parent topic: Connection-handling and Cursor-handling Functions
Related reference
OraLogon Function
OraLogoff Function
OraOpen Function


Parameter Binding Functions

  • OraSetBinary Function
    Assigns binary data to the program variable that is bound to the specified place holder in the SQL statement or PL/SQL block.
  • OraSetFloat Function
    Assigns a floating-point value to the program variable that is bound to the specified place holder in the SQL statement or PL/SQL block.
  • OraSetInt Function
    Assigns a number value to the program variable that is bound to the specified place holder in the SQL statement or PL/SQL block.
  • OraSetNull Function
    Assigns a NULL value to the program variable that is bound to the specified place holder in the SQL statement or PL/SQL block.
  • OraSetPieces Function
    Assigns any data to the program variable that is bound to the specified place holder in the SQL statement for a piecewise INSERT or UPDATE operation.
  • OraSetString Function
    Assigns a string to the program variable that is bound to the specified place holder in the SQL statement or PL/SQL block.
Parent topic: Oracle API Functions Overview


OraSetBinary Function

Action

Assigns binary data to the program variable that is bound to the specified place holder in the SQL statement or PL/SQL block. The place holder is identified by the name or the number specified in the SQL statement or PL/SQL block. This function is used to assign values to both scalar and array program variables.

Using this function, any data type listed below can be assigned to the program variable that is bound to the specified place holder:

  • SQLT_NUM
  • SQLT_VNU
  • SQLT_RID
  • SQLT_DAT
  • SQLT_VBI
  • SQLT_BIN
  • SQLT_LBI
  • SQLT_LVB
  • SQLT_CUR

Include file

Ora.bdh

Syntax

OraSetBinary( in cCursor : cursor,
              in sSqlVar : string,
              in sBinary : string,
              in nLength : number,
              in nIndex  : number optional ): boolean;

Return value

  • true if successful

  • false otherwise. In this case, you can use the OraOciError function to retrieve the Oracle OCI error code

Parameter | Description
cCursor | Cursor associated with a database connection
sSqlVar | Name of the place holder in the SQL statement or PL/SQL block. This parameter must include the preceding colon identifying it as a place holder
sBinary | Binary data that is assigned to the program variable that is bound to the specified place holder in the SQL statement or PL/SQL block
nLength | Length of the binary data block (in bytes)
nIndex | Array index (optional). For array binding operations, this parameter specifies the array index of the program variable

Example

var
  hConnection : number;
  cCursor     : cursor;
dcltrans
  transaction TMain
  const
    PUBLIC_KEY := "\h59b20094...";
  begin
    OraLogon(hConnection, "user", "password", "orclnet2");
    OraOpen(cCursor, hConnection);
    OraParse(cCursor, sqlInsert);
    OraBind(cCursor, ":name", SQLT_CHR, 32);
    OraBind(cCursor, ":key", SQLT_BIN, 64);
    OraSetString(cCursor, ":name", "Michael");
    OraSetBinary(cCursor, ":key", PUBLIC_KEY, STRING_COMPLETE);
    OraExec(cCursor);
    OraClose(cCursor);
    OraLogoff(hConnection);
  end TMain;
dclsql
  sqlInsert:
    INSERT INTO keys (name, key) VALUES (:name, :key);
Parent topic: Parameter Binding Functions
Related reference
OraOciError Function


OraSetFloat Function

Action

Assigns a floating-point value to the program variable that is bound to the specified place holder in the SQL statement or PL/SQL block. The place holder is identified by the name or the number specified in the SQL statement or PL/SQL block. This function is used to assign values to both scalar and array program variables.

Include file

Ora.bdh

Syntax

OraSetFloat( in cCursor : cursor,
             in sSqlVar : string,
             in fValue  : float,
             in nIndex  : number optional): boolean;

Return value

  • true if successful

  • false otherwise. In this case, you can use the OraOciError function to retrieve the Oracle OCI error code

Parameter | Description
cCursor | Cursor associated with a database connection
sSqlVar | Name of the place holder in the SQL statement or PL/SQL block. This parameter must include the preceding colon identifying it as a place holder
fValue | Float value that is assigned to the program variable that is bound to the specified place holder in the SQL statement or PL/SQL block
nIndex | Array index (optional). For array binding operations, this parameter specifies the array index of the program variable

Example

var
  hConnection : number;
  cCursor     : cursor;

dcltrans
  transaction TMain
  var
    sName    : string;
    fBalance : float;
  begin
    OraLogon(hConnection, "user", "password", "orclnet2");
    OraOpen(cCursor, hConnection);
    OraParse(cCursor, sqlSelect);
    OraBind(cCursor, ":1", SQLT_FLT);
    OraSetFloat(cCursor, ":1", 2000.0);
    OraDefine(cCursor, 1, SQLT_CHR, 32);
    OraDefine(cCursor, 2, SQLT_FLT);
    OraExec(cCursor);

    while OraFetch(cCursor) do
      sName := OraGetString(cCursor, "1");
      fBalance := OraGetFloat(cCursor, "2");
      write(sName, 32); write(fBalance); writeln;
    end;

    OraClose(cCursor);
    OraLogoff(hConnection);
  end TMain;

dclsql
  sqlSelect:
    SELECT * FROM accounts WHERE balance > :1;

Output

Bob 13864.220000Pamela 4492.090000Richard 7309.580000

Sample scripts

OraSample.bdf

Parent topic: Parameter Binding Functions
Related reference
OraOciError Function


OraSetInt Function

Action

Assigns a number value to the program variable that is bound to the specified place holder in the SQL statement or PL/SQL block. The place holder is identified by the name or the number specified in the SQL statement or PL/SQL block. This function is used to assign values to both scalar and array program variables.

Include file

Ora.bdh

Syntax

OraSetInt( in cCursor : cursor,
           in sSqlVar : string,
           in nValue  : number,
           in nIndex  : number optional): boolean;

Return value

  • true if successful

  • false otherwise. In this case, you can use the OraOciError function to retrieve the Oracle OCI error code

Parameter | Description
cCursor | Cursor associated with a database connection
sSqlVar | Name of the place holder in the SQL statement or PL/SQL block. This parameter must include the preceding colon identifying it as a place holder
nValue | Number value that is assigned to the program variable that is bound to the specified place holder in the SQL statement or PL/SQL block
nIndex | Array index (optional). For array binding operations, this parameter specifies the array index of the program variable

Example

var
  hConnection : number;
  cCursor     : cursor;

dcltrans
  transaction TMain
  var
    nAge  : number;
    sName : string;
  begin
    OraLogon(hConnection, "user", "password", "orclnet2");
    OraOpen(cCursor, hConnection);
    OraParse(cCursor, sqlSelect);
    OraBind(cCursor, ":1", SQLT_INT);
    OraSetInt(cCursor, ":1", 25);
    OraDefine(cCursor, 1, SQLT_CHR, 32);
    OraDefine(cCursor, 2, SQLT_INT);
    OraExec(cCursor);

    while OraFetch(cCursor) do
      sName := OraGetString(cCursor, "1");
      nAge := OraGetInt(cCursor, "2");
      write(sName, 32); write(nAge, 5); writeln;
    end;

    OraClose(cCursor);
    OraLogoff(hConnection);
  end TMain;

dclsql
  sqlSelect:
    SELECT * FROM persons WHERE age > :1;

Output

Howard 33Michael 44Bobby 61Sara 38

Sample scripts

OraArrayFetch.bdf, OraSample.bdf, OraLoadPers.bdf

Parent topic: Parameter Binding Functions
Related reference
OraOciError Function


OraSetNull Function

Action

Assigns a NULL value to the program variable that is bound to the specified place holder in the SQL statement or PL/SQL block. The place holder is identified by the name or the number specified in the SQL statement or PL/SQL block. This function is used to assign values to both scalar and array program variables.

Include file

Ora.bdh

Syntax

OraSetNull( in cCursor : cursor,
            in sSqlVar : string,
            in nIndex  : number optional): boolean;

Return value

  • true if successful

  • false otherwise. In this case, you can use the OraOciError function to retrieve the Oracle OCI error code

Parameter | Description
cCursor | Cursor associated with a database connection
sSqlVar | Name of the place holder in the SQL statement or PL/SQL block. This parameter must include the preceding colon identifying it as a place holder
nIndex | Array index (optional). For array binding operations, this parameter specifies the array index of the program variable

Example

var
  hConnection : number;
  cCursor     : cursor;

dcltrans
  transaction TMain
  begin
    OraLogon(hConnection, "user", "password", "orclnet2");
    OraOpen(cCursor, hConnection);
    OraParse(cCursor, sqlInsert);
    OraBind(cCursor, ":name", SQLT_CHR, 32);
    OraBind(cCursor, ":age", SQLT_INT);
    OraSetString(cCursor, ":name", "Peter");
    OraSetNull(cCursor, ":age");
    OraExec(cCursor);
    OraClose(cCursor);
    OraLogoff(hConnection);
  end TMain;
dclsql
  sqlInsert:
    INSERT INTO persons (name, age) VALUES (:name, :age);
Parent topic: Parameter Binding Functions
Related reference
OraOciError Function


OraSetPieces Function

Action

Assigns any data to the program variable that is bound to the specified place holder in the SQL statement for a piecewise INSERT or UPDATE operation. The place holder is identified by the name or the number specified in the SQL statement.

Include file

Ora.bdh

Syntax

OraSetPieces( in cCursor     : cursor,
              in sSqlVar     : string,
              in sFilename   : string,
              in nCharacters : number optional,
              in nFirstChar  : number optional,
              in nLastChar   : number optional): boolean;

Return value

  • true if successful

  • false otherwise. In this case, you can use the OraOciError function to retrieve the Oracle OCI error code

Parameter | Description
cCursor | Cursor associated with a database connection
sSqlVar | Name of the place holder in the SQL statement or PL/SQL block. This parameter must include the preceding colon identifying it as a place holder
sFilename | Name of the file containing the data. If this parameter is set to NULL, random values are generated. In this case, you must specify the amount of random data to generate. The nFirstChar and the nLastChar parameters let you specify a set of characters used for random data generation
nCharacters | Number of random characters to generate (optional). This parameter has to be passed to the function only if sFilename is set to NULL
nFirstChar | First character belonging to the character set used for random data generation (optional). The default option is to use all characters defined in the ASCII table
nLastChar | Last character belonging to the character set used for random data generation (optional). The default option is to use all characters defined in the ASCII table

Example

var
  hConnection : number;
  cCursor     : cursor;

dcltrans
  transaction TMain
  begin
    OraLogon(hConnection, "user", "password", "orclnet2");
    OraOpen(cCursor, hConnection);
    OraParse(cCursor, sqlInsert);
    OraBind(cCursor, ":name", SQLT_STR, 32);
    OraBind(cCursor, ":data", SQLT_LBI, 4096, 64000, ORA_PIECEWISE);
    OraSetString(cCursor, ":name", "Sunset");
    OraSetPieces(cCursor, ":data", "TestData.dat");
    OraExec(cCursor);

    OraClose(cCursor);
    OraLogoff(hConnection);
  end TMain;

dclsql
  sqlInsert:
    INSERT INTO images (name, data) VALUES (:name, :data);

See also

Wrapped Oracle function: ogetpi, osetpi

Parent topic: Parameter Binding Functions
Related reference
OraOciError Function


OraSetString Function

Action

Assigns a string to the program variable that is bound to the specified place holder in the SQL statement or PL/SQL block. The place holder is identified by the name or the number specified in the SQL statement or PL/SQL block. This function is used to assign values to both scalar and array program variables.

Using this function, any of the following data types can be assigned to the program variable that is bound to the specified place holder:

  • SQLT_STR
  • SQLT_CHR
  • SQLT_VCS
  • SQLT_LVC
  • SQLT_AFC
  • SQLT_AVC
  • SQLT_LNG

Include file

Ora.bdh

Syntax

OraSetString( in cCursor : cursor,
              in sSqlVar : string,
              in sString : string,
              in nIndex  : number optional): boolean;

Return value

  • true if successful

  • false otherwise. In this case, you can use the OraOciError function to retrieve the Oracle OCI error code

Parameter | Description
cCursor | Cursor associated with a database connection
sSqlVar | Name of the place holder in the SQL statement or PL/SQL block. This parameter must include the preceding colon identifying it as a place holder
sString | String that is assigned to the program variable that is bound to the specified place holder in the SQL statement or PL/SQL block
nIndex | Array index (optional). For array binding operations, this parameter specifies the array index of the program variable

Example

var
  hConnection : number;
  cCursor     : cursor;

dcltrans
  transaction TMain
  begin
    OraLogon(hConnection, "user", "password", "orclnet2");
    OraOpen(cCursor, hConnection);
    OraParse(cCursor, sqlInsert);

    // bind array containing two elements
    OraBind(cCursor, ":name", SQLT_CHR, 32, 2);
    OraBind(cCursor, ":age", SQLT_INT, 0, 2);

    // set values
    OraSetString(cCursor, ":name", "Bob", 1);
    OraSetInt(cCursor, ":age", 25, 1);

    OraSetString(cCursor, ":name", "Marcy", 2);
    OraSetInt(cCursor, ":age", 33, 2);

    OraExec(cCursor);
    OraClose(cCursor);
    OraLogoff(hConnection);
  end TMain;

dclsql
  sqlInsert:
    INSERT INTO persons (name, age) VALUES (:name, :age);

Sample scripts

OraArrayFetch.bdf, OraSample.bdf, OraLoadPers.bdf

Parent topic: Parameter Binding Functions
Related reference
OraOciError Function


Result Set Definition Functions

  • OraDefine Function
    Defines an output variable for a specified select-list item in a SQL query.
  • OraDescribe Function
    Describes select-list items for SQL queries.
  • OraDescribeSP Function
    Describes the parameters of a PL/SQL procedure or function that is stored in an Oracle database.
Parent topic: Oracle API Functions Overview


OraDefine Function

Action

Defines an output variable for a specified select-list item in a SQL query. In a BDL script, it is necessary to call this function for each select-list item of a SQL query. After the OraExec (and OraFetch) function has been called, the following functions can be used to retrieve the value of the program variable that is defined for the specified select-list item:

  • OraGetFloat
  • OraGetInt
  • OraGetString
  • OraGetValue

Include file

Ora.bdh

Syntax

OraDefine( in cCursor     : cursor,
           in nPosition   : number,
           in nDatatype   : number optional,
           in nSize       : number optional,
           in nMaxColSize : number optional,
           in nDefineType : number optional,
           in nPieces     : number optional): boolean;

Return value

  • true if successful

  • false otherwise. In this case, you can use the OraOciError function to retrieve the Oracle OCI error code

Parameter | Description
cCursor | Cursor associated with a database connection
nPosition | Index of the select-list item in the SQL query. Position indices start at 1 for the first (leftmost) select-list item
nDatatype

Oracle external data type of the select-list item (optional). See Oracle data types for a list of Oracle data types.

The default value is SQLT_STR (null-terminated string)
nSize

Length of the select-list item in bytes (optional).

This parameter should be omitted or set to 0 for data types of fixed length (SQLT_NUM, SQLT_INT, SQLT_FLT, SQLT_VNU, SQLT_RID, SQLT_DAT, SQLT_UIN, SQLT_CUR)
nMaxColSize | Maximum possible size of the select-list item in bytes (optional). This parameter has to be specified whenever the select-list item is retrieved in multiple pieces
nDefineType

Special select-list option (optional). Possible options are:

  • ORA_PIECEWISE. The select-list item is retrieved in multiple pieces using the OCI ogetpi/osetpi functions

  • ORA_FETCHLONG. The select-list item has to be retrieved from a long column using the OCI oflng function
nPieces | Number of pieces (optional). Whenever nDefineType is set to ORA_FETCHLONG, this parameter can be used to specify the number of pieces

Example

var
  hConnection : number;
  cCursor : cursor;
dcltrans
  transaction TMain
  var
    sName : string;
    nFetched, nAge, i : number;
  begin
    OraLogon(hConnection, "user", "password", "orclnet2");
    OraOpen(cCursor, hConnection);
    OraParse(cCursor, sqlSelect);
    OraDefine(cCursor, 1, SQLT_CHR, 32);
    OraDefine(cCursor, 2, SQLT_INT);
    OraExec(cCursor, 1, 50, 0, 0, nFetched);
    for i := 1 to nFetched do
      sName := OraGetString(cCursor, "1", i);
      nAge := OraGetInt(cCursor, "2", i);
      write(sName, 32);  write(nAge, 5); writeln;
    end;
    OraClose(cCursor);
    OraLogoff(hConnection);
  end TMain;

 dclsql
  sqlSelect:
    SELECT * FROM persons;

Output

Howard 33Michael 44Bobby 61Sara 38

Sample scripts

OraArrayFetch.bdf, OraSample.bdf

See also

Oracle's Programmer's Guide to Oracle Call Interface for Wrapped Oracle function: odefin, odefinps
Parent topic: Result Set Definition Functions
Related reference
OraDescribe Function
OraDescribeSP Function
OraOciError Function
OraGetFloat Function
OraGetInt Function
OraGetString Function
OraGetValue Function
OraBind Function
Oracle Data Types


OraDescribe Function

Action

Describes select-list items for SQL queries. This function returns internal data type description and size information for a specified select-list item.

If it is used without specifying the select-list item, all select-list items of the SELECT statement are described and OraDefine function calls are performed implicitly in order to define an output variable for each select-list item of a SQL query. In this case, no values are returned in the out parameters and the select-list items are bound as strings regardless of the Oracle internal data type. The functions listed below can be used to retrieve values from the program variable that is defined for the select-list item.

  • OraGetFloat
  • OraGetInt
  • OraGetString
  • OraGetValue

Include file

Ora.bdh

Syntax

OraDescribe( in    cCursor      : cursor,
             in    nPosition    : number optional,
             out   nDBSize      : number optional,
             out   nDBType      : number optional,
             out   sColName     : string optional,
             inout nNameLen     : number optional,
             out   nDisplaySize : number optional,
             out   nPrecision   : number optional,
             out   nScale       : number optional,
             out   nNullOk      : number optional ): boolean;

Return value

  • true if successful

  • false otherwise. In this case, you can use the OraOciError function to retrieve the Oracle OCI error code

Parameter | Description
cCursor | Cursor associated with a database connection
nPosition | Position index of the select-list item in the SQL query (optional). Position indices start at 1 for the first (leftmost) select-list item.
nDBSize | Variable receiving the maximum size of the column, as stored in the Oracle data dictionary (optional)
nDBType | Variable receiving the data type code of the select-list item (optional). See Oracle data types for detailed information
sColName | Variable receiving the column name of the specified select-list item (optional)
nNameLen | Size of the variable receiving the column name (optional). After the function call, this parameter contains the actual length of the column name
nDisplaySize | Variable receiving the maximum display size of the select-list item if the select-list item is returned as a character string (optional)
nPrecision | Variable receiving the precision of numeric select-list items (optional). The precision is the total number of digits of a number.
nScale | Variable receiving the scale of numeric select-list items (optional)
nNullOk

Variable receiving an indicator whether null values are permitted.

  • If this parameter contains 0, null values are not permitted

  • Otherwise, null values are permitted

Example

var
  hConnection : number;
  cCursor : cursor;

dcltrans
  transaction TMain
  var
    nDBSize, nDBType, nNameLength, nDisplaySize : number;
    nPrecision, nScale, nNullOk                 : number;
    sColumnName                                 : string;
  begin
    OraLogon(hConnection, "user", "password", "orclnet2");
    OraOpen(cCursor, hConnection);
    OraParse(cCursor, sqlSelect);
    nNameLength := sizeof(sColumnName);
    OraDescribe(cCursor, 2, nDBSize, nDBType, sColumnName, nNameLength, nDisplaySize, nPrecision, nScale, nNullOk);
    write("maximum column size = "); write(nDBSize); writeln;
    write("column data type    = "); write(nDBType); writeln;
    write("column name         = "); write(sColumnName); writeln;
    write("name length         = "); write(nNameLength); writeln;
    write("display size        = "); write(nDisplaySize); writeln;
    write("precision           = "); write(nPrecision); writeln;
    write("scale               = "); write(nScale); writeln;
    write("NULL values         : ");

    if nNullOk = 0 then
      write("not permitted")
    else
      write("permitted")
    end;

    writeln;
    OraExec(cCursor);
    OraClose(cCursor);
    OraLogoff(hConnection);
  end TMain;

dclsql
  sqlSelect:
  SELECT * FROM accounts;

Output

maximum column size = 22
column data type    = 2
column name         = BALANCE
name length         = 7
display size        = 40
precision           = 36
scale               = 2
NULL values         : permitted

See also

Oracle's Programmer's Guide to Oracle Call Interface for Wrapped Oracle function: odescr
Parent topic: Result Set Definition Functions
Related reference
OraDefine Function
OraDescribeSP Function
OraOciError Function
OraGetFloat Function
OraGetInt Function
OraGetString Function
OraGetValue Function
OraBind Function
Oracle Data Types


OraDescribeSP Function

Action

Describes the parameters of a PL/SQL procedure or function that is stored in an Oracle database.

Include file

Ora.bdh

Syntax

OraDescribeSP( in    hConnection : number,
               inout sObjName    : string,
               inout nArraySize  : number optional,
               out   sName       : array of string(30) optional,
               out   nDatatype   : array of number optional,
               out   nMode       : array of number optional,
               out   nSize       : array of number optional ): boolean;

Return value

  • true if successful

  • false otherwise. In this case, you can use the OraOciError function to retrieve the Oracle OCI error code

Example

Parameter | Description
hConnection | Handle to an Oracle database connection
sObjName | Name of the PL/SQL procedure or function, including optional schema and package name. Quoted names are accepted. Synonyms are also accepted and are translated.
nArraySize | Array size of the sName, nDatatype, nMode and nSize parameter. This parameter receives the actual number of array elements described.
sName | String array receiving the name of each parameter of the PL/SQL procedure or function. Note: The size of each string buffer must be exactly 30 characters.
nDatatype | Array receiving the data type of each parameter of the procedure or function. See Oracle data types for a list of all data types.
nMode | Array receiving the mode of each parameter of the procedure or function. Zero (0) indicates an IN parameter, one (1) an OUT parameter, and two (2) an IN/OUT parameter.
nSize | Array receiving the size of each parameter of the procedure or function (in bytes). Character data types return the size of the parameter. For number types, 22 is returned.

Example

var
  hConnect : number;
  cCursor  : cursor;

dcltrans
  transaction TMain
  const
    MAXARR := 100;
  var
    nMaxArr, i : number;
    sParam     : array[MAXARR] of string(30);
  begin
    OraLogon(hConnect, "username/password@orclnet2");
    OraOpen(cCursor, hConnect);
    nMaxArr := MAXARR;
    OraDescribeSP(hConnect, "sp", nMaxArr, sParam);
    for i := 1 to nMaxArr do
      write("Param: "); write(sParam[i]); writeln;
    end;
    ...
  end TMain;

Output

Param: NO
Param: OPENING
Param: TITLE
Param: FIRSTNAME
Param: LASTNAME
Param: ALINE1
Param: ALINE2
Param: ZIP
Param: DISTRICT

See also

Oracle's Programmer's Guide to Oracle Call Interface for Wrapped Oracle function: odessp
Parent topic: Result Set Definition Functions
Related reference
OraDefine Function
OraDescribe Function
OraOciError Function
Oracle Data Types


Statement Processing Functions

  • OraParse Function
    Parses a SQL statement or a PL/SQL block and associates it with a cursor.
  • OraParse2 Function
    Parses a SQL statement or PL/SQL block passed to the function as a string and associates it with a cursor.
  • OraExec Function
    Executes a SQL statement or PL/SQL block associated with a cursor.
  • OraFetch Function
    Performs a specified number of fetch operations in order to retrieve data from a SQL query.
Parent topic: Oracle API Functions Overview


OraParse Function

Action

Parses a SQL statement or a PL/SQL block and associates it with a cursor. You can specify whether the parse should be deferred. If you defer parsing, the statement is parsed immediately before it is described or executed.

Include file

Ora.bdh

Syntax

OraParse( in cCursor      : cursor,
          in sqlStatement : sql,
          in nDeferred    : number optional,
          in nVersion     : number optional): boolean;

Return value

  • true if successful

  • false otherwise. In this case, you can use the OraOciError function to retrieve the Oracle OCI error code

Parameter | Description
cCursor | Cursor associated with a database connection.
sqlStatement | SQL statement or PL/SQL block to parse
nDeferred

Specifies whether the parse should be deferred (optional). Possible options are:

  • ORA_DEFERRED. The statement is parsed immediately before it is described or executed (default)

  • ORA_NONDEFERRED. The statement is parsed immediately

  • ORA_OSQL3. Indicates a call of the Oracle osql3 function rather than the oparse function
nVersion

Oracle version (optional). Possible options are:

  • ORA_VERSION_6

  • ORA_VERSION_DEFAULT (default)

  • ORA_VERSION_7

Example

var
  hConnection : number;
  cCursor : cursor;

dcltrans
  transaction TMain
  begin
    OraLogon(hConnection, "user", "password", "orclnet2");
    OraOpen(cCursor, hConnection);
    OraParse(cCursor, sqlDelete, ORA_NONDEFERRED);
    OraExec(cCursor);
    OraClose(cCursor);
    OraLogoff(hConnection);
  end TMain;

dclsql
  sqlDelete:
  DELETE FROM persons;

Sample scripts

OraArrayFetch.bdf, OraSample.bdf, OraLoadPers.bdf

Parent topic: Statement Processing Functions
Related reference
OraParse2 Function
OraExec Function
OraFetch Function
OraOciError Function
OraBind Function
OraDefine Function
OraDescribe Function


OraParse2 Function

Action

Parses a SQL statement or PL/SQL block passed to the function as a string and associates it with a cursor. It is possible to specify whether the parse should be deferred. In this case, it is parsed immediately before it is described or executed.

Include file

Ora.bdh

Syntax

OraParse2( in cCursor      : cursor,
           in sStatement   : string,
           in nDeferred    : number optional,
           in nVersion     : number optional): boolean;

Return value

  • true if successful

  • false otherwise. In this case, you can use the OraOciError function to retrieve the Oracle OCI error code

Parameter | Description
cCursor | Cursor associated with a database connection.
sStatement | SQL statement or PL/SQL block to parse
nDeferred

Specifies whether the parse should be deferred (optional). Possible options are:

  • ORA_DEFERRED. The statement is parsed immediately before it is described or executed (default)

  • ORA_NONDEFERRED. The statement is parsed immediately

  • ORA_OSQL3. Indicates a call of the Oracle osql3 function rather than the oparse function
nVersion

Oracle version (optional). Possible options are:

  • ORA_VERSION_6

  • ORA_VERSION_DEFAULT (default)

  • ORA_VERSION_7

Example

var
  hConnection : number;
  cCursor : cursor;

dcltrans
  transaction TMain
  begin
    OraLogon(hConnection, "user", "password", "orclnet2");
    OraOpen(cCursor, hConnection);
    OraParse2(cCursor, "DELETE FROM persons", ORA_NONDEFERRED);
    OraExec(cCursor);
    OraClose(cCursor);
    OraLogoff(hConnection);
  end TMain;
Parent topic: Statement Processing Functions
Related reference
OraParse Function
OraExec Function
OraFetch Function
OraOciError Function
OraBind Function
OraDefine Function
OraDescribe Function


OraExec Function

Action

Executes a SQL statement or PL/SQL block associated with a cursor. Besides executing a statement, this function can also fetch data after the execution if the statement is a SQL query.

Before calling this function, you have to parse the SQL statement using the OraParse function. Array binding can be used to process multiple rows of data in a single execute operation. If the SQL statement contains place holders, it is necessary to call the OraBind function for each place holder first.

Include file

Ora.bdh

Syntax

OraExec( in  cCursor     : cursor,
         in  nIterations : number optional,
         in  nRows       : number optional,
         in  nCancel     : number optional,
         in  nExact      : number optional,
         out nFetched    : number optional ): boolean;

Return value

  • true if successful

  • false otherwise. In this case, you can use the OraOciError function to retrieve the Oracle OCI error code

Parameter | Description
cCursor | Cursor associated with a database connection.
nIterations | Number of iterations (optional). This parameter specifies whether to perform multiple execute operations in order to process array parameters
nRows | Numbers of rows to fetch (optional). This parameter specifies whether to fetch data after a SQL query
nCancel

Specifies whether to cancel the cursor afterwards (optional).

  • If this parameter is set to 1, the cursor is canceled after the fetch operation. See OraCancel function for detailed information

  • If this parameter is set to 0, the cursor is not canceled (default)
nExact

Specifies whether to report an error if the actual number of fetched rows is greater than the specified number of rows to fetch (nRows parameter)

  • If this parameter is set to 1, Silk Performer terminates the simulation if the actual number of fetched rows is greater than the specified number of rows to fetch

  • If this parameter is set to 0, no error message is displayed (default)
nFetched | Variable receiving the number of rows actually fetched (optional)

Example

var
  hConnection : number;
  cCursor : cursor;

dcltrans
  transaction TMain
  var
    sName : string;
    nFetched, nAge, i : number;
  begin
    OraLogon(hConnection, "user", "password", "orclnet2");
    OraOpen(cCursor, hConnection);
    // insert two persons: Jimmy and Ronald
    OraParse(cCursor, sqlInsert);
    OraBind(cCursor, ":name", SQLT_CHR, 32, 2);
    OraBind(cCursor, ":age", SQLT_INT, 0, 2);
    OraSetString(cCursor, ":name", "Jimmy", 1);
    OraSetInt(cCursor, ":age", 55, 1);
    OraSetString(cCursor, ":name", "Ronald", 2);
    OraSetInt(cCursor, ":age", 18, 2);
    OraExec(cCursor, 2);
    // select all persons
    OraParse(cCursor, sqlSelect);
    OraDefine(cCursor, 1, SQLT_CHR, 32);
    OraDefine(cCursor, 2, SQLT_INT);
    OraExec(cCursor, 1, 50, 0, 0, nFetched);

    for i := 1 to nFetched do
      sName := OraGetString(cCursor, "1", i);
      nAge := OraGetInt(cCursor, "2", i);
      write(sName, 32); write(nAge, 5); writeln;
    end;

    OraClose(cCursor);
    OraLogoff(hConnection);
  end TMain;

dclsql
  sqlInsert:
  INSERT INTO persons (name, age) VALUES (:name, :age);
  sqlSelect:
    SELECT * FROM persons;

Output

Howard 33Michael 44Bobby 61Sara 38Jimmy 55Ronald 18

Sample scripts

OraArrayFetch.bdf, OraSample.bdf, OraLoadPers.bdf

See also

Wrapped Oracle function: oexec, oexn, oexfet

Parent topic: Statement Processing Functions
Related reference
OraParse Function
OraParse2 Function
OraFetch Function
OraOciError Function
OraBind Function
OraDefine Function
OraDescribe Function
OraCancel Function


OraFetch Function

Action

Performs a specified number of fetch operations in order to retrieve data from a SQL query. This function is used to fetch both single and multiple rows.

Afterwards, the following functions can be used to retrieve the fetched data:

  • OraGetFloat
  • OraGetInt
  • OraGetString
  • OraGetValue

Include file

Ora.bdh

Syntax

OraFetch( in  cCursor     : cursor,
          in  nIterations : number optional,
          in  nBatchSize  : number optional,
          out nFetched    : number optional ): boolean;

Return value

  • true if successful

  • false either if an error occurred during the fetch operation or if the number of rows actually fetched is not equal to the specified number of rows to fetch.

Parameter | Description
cCursor | Cursor associated with a database connection
nIterations

Number of iterations to perform (optional). Predefined options are:

  • ORA_FETCH_ALL. Repeat the fetch operation until all rows have been fetched

The default option is to perform a single iteration
nBatchSize | Number of rows to fetch per iteration (optional). The default option is to fetch a single row per iteration
nFetched | Variable receiving the actual number of rows fetched (optional)

Example

var
  hConnection : number;
  cCursor : cursor;

dcltrans
  transaction TMain
  const    MAX_ROWS := 1000; // maximum number of rows
  var
    nFetched, i, nAge : number;
    sName : string;
  begin
    OraLogon(hConnection, "user", "password", "orclnet2");
    OraOpen(cCursor, hConnection);
    OraParse(cCursor, sqlSelect);
    OraDefine(cCursor, 1, SQLT_CHR, 32);
    OraDefine(cCursor, 2, SQLT_INT);
    // first possibility to fetch all rows
    // in this case, nFetched must be smaller than MAX_ROWS
    OraExec(cCursor);
    OraFetch(cCursor, 1, MAX_ROWS, nFetched);

    for i := 1 to nFetched do
      sName := OraGetString(cCursor, "1", i);
      nAge := OraGetInt(cCursor, "2", i);
      write(sName, 32); write(nAge, 5); writeln;
    end;

     // second possibility to fetch all data
    OraExec(cCursor);

        while OraFetch(cCursor) do
      sName := OraGetString(cCursor, "1");
      nAge := OraGetInt(cCursor, "2");
      write(sName, 32);
 write(nAge, 5); writeln;
    end;

    OraClose(cCursor);
    OraLogoff(hConnection);
  end TMain;

dclsql
  sqlSelect:
  SELECT * FROM persons;

Output

Howard 33Michael 44Bobby 61Sara 38

Sample scripts

OraArrayFetch.bdf, OraSample.bdf

See also

Oracle's Programmer's Guide to Oracle Call Interface for Wrapped Oracle functions: ofetch, ofen
Parent topic: Statement Processing Functions
Related reference
OraParse Function
OraParse2 Function
OraExec Function
OraDefine Function
OraDescribe Function
OraGetFloat Function
OraGetInt Function
OraGetString Function
OraGetValue Function


Placeholder Binding Functions

  • OraBind Function
    Binds a place holder in a SQL statement or PL/SQL block to a program variable.
  • OraBindCursor Function
    Binds a PL/SQL cursor variable to a BDL cursor.
Parent topic: Oracle API Functions Overview


OraBind Function

Action

Binds a place holder in a SQL statement or PL/SQL block to a program variable. The variable is accessible through the OraSet and OraGet functions. The place holder is identified by the name or the number declared in the SQL statement or PL/SQL block. The functions listed below are used to assign values to the program variable that is bound to the specified place holder:

  • OraSetBinary
  • OraSetFloat
  • OraSetInt
  • OraSetNull
  • OraSetPieces
  • OraSetString

This function serves to bind place holders in SQL statements or PL/SQL blocks to both scalar and array variables. In addition, it can be used to bind place holders to be used in piecewise operations. The function must be called after parsing the SQL statement or PL/SQL block and before calling the OraSet function.

Include file

Ora.bdh

Syntax

OraBind( in cCursor     : cursor,
         in sSqlVar     : string,
         in nDatatype   : number optional,
         in nSize       : number optional,
         in nArraySize  : number optional,
         in nBindOption : number optional): boolean;

Return value

  • true if successful

  • false otherwise. In this case, you can use the OraOciError function to retrieve the Oracle OCI error code

Parameter | Description
cCursor | Cursor associated with a database connection
sSqlVar | Name of the place holder in the SQL statement or PL/SQL block. This parameter must include the preceding colon identifying it as a place holder
nDatatype

Oracle external data type of the program variable (optional). Oracle converts the program variable from external to internal format when the variable is sent to the database and vice versa when it is retrieved from the database. See Oracle data types for a list of data types

The default data type is SQLT_STR (null-terminated string)

nSize

Size of the program variable or the array element in bytes (optional). Since this function needs to be called only once for many different values on successive OraExec function calls, this parameter must contain the maximum size of the element to bind.

This parameter should be omitted for data types of fixed length (SQLT_NUM, SQLT_INT, SQLT_FLT, SQLT_VNU, SQLT_RID, SQLT_DAT, SQLT_UIN, SQLT_CUR). For string data types (SQLT_STR, SQLT_CHR, SQLT_LNG, SQLT_AFC, SQLT_AVC) omitting this parameter is possible when omitting the nArraySize parameter, too.

When performing piecewise binding of the variable to the place holder, this parameter specifies the piece size

nArraySize

Maximum number of array elements to bind (optional).

The default option is scalar binding.

When performing piecewise binding of the variable to the place holder, this parameter specifies the maximum column size

nBindOption

Specifies how to bind the place holder (optional). The following are the possible options for binding a place holder:

  • ORA_DEFAULT. This is the default option. A place holder is bound to a scalar or to an array program variable.

  • ORA_PIECEWISE. The program variable is bound to the place holder in multiple pieces. In this case, nSize specifies the piece size, and nArraySize the maximum column size. You have to call the OraSetPieces function in order to set the values for the pieces.

  • ORA_PLSQLTABLE_IN. The program variable is bound to a PL/SQL table that is used as an in parameter within a stored procedure.

  • ORA_PLSQLTABLE_OUT. The program variable is bound to a PL/SQL table that is used as an out parameter in a stored procedure.

  • ORA_PLSQLTABLE_INOUT: The program variable is bound to a PL/SQL table that is used as an inout parameter in a stored procedure.

A place holder in a SQL statement consists of a colon (:) followed by a SQL identifier. The place holder is not a test script variable. For example, the following SQL statement contains two place holders, :min_age and :max_age.

SELECT name, ageFROM personsWHERE age >= :min_age AND age <= :max_age;

It is also possible to define place holders that consist of a colon followed by a literal integer between 1 and 255.

The following SQL statement contains two place holders, :1 and :2.

SELECT name, age
FROM persons
WHERE age >= :1 AND age <= :2;

Example: scalar binding

var
  hConnection : number;
  cCursor : cursor;
dcltrans
  transaction TMain
  var
    nAge : number;
    sName : string;
  begin
    OraLogon(hConnection, "user", "password", "orclnet2");
    OraOpen(cCursor, hConnection);
    OraParse(cCursor, sqlSelect);
    OraBind(cCursor, ":1", SQLT_INT);
    OraSetInt(cCursor, ":1", 25);
    OraDefine(cCursor, 1, SQLT_CHR, 32);
    OraDefine(cCursor, 2, SQLT_INT);
    OraExec(cCursor);
    while OraFetch(cCursor) do
      sName := OraGetString(cCursor, "1");
      nAge:= OraGetInt(cCursor, "2");
      write(sName, 32); write(nAge, 5); writeln;
    end;
    OraClose(cCursor);
    OraLogoff(hConnection);
  end TMain;
dclsql
  sqlSelect:
    SELECT * FROM persons WHERE age > :1;

Output

Howard 33Michael 44Bobby 61Sara 38

Example: array binding

var
  hConnection : number;
  cCursor : cursor;
dcltrans
  transaction TMain
  begin
    OraLogon(hConnection, "user", "password", "orclnet2");
    OraOpen(cCursor, hConnection);
    OraParse(cCursor, sqlInsert);
    // bind array containing two elements
    OraBind(cCursor, ":name", SQLT_CHR, 32, 2);
    OraBind(cCursor, ":age", SQLT_INT, 0, 2);
    // set values
    OraSetString(cCursor, ":name", "Bob", 1);
    OraSetInt(cCursor, ":age", 25, 1);
    OraSetString(cCursor, ":name", "Marcy", 2);
    OraSetInt(cCursor, ":age", 33, 2);
    OraExec(cCursor, 2);
    OraClose(cCursor);
    OraLogoff(hConnection);
  end TMain;
dclsql
  sqlInsert:
    INSERT INTO persons (name, age) VALUES (:name, :age);

Example: piecewise binding

var
  hConnection : number;
  cCursor : cursor;
dcltrans
  transaction TMain
  begin
    OraLogon(hConnection, "user", "password", "orclnet2");
    OraOpen(cCursor, hConnection);
    OraParse(cCursor, sqlInsert);
    OraBind(cCursor, ":name", SQLT_STR, 32);
    OraBind(cCursor, ":data", SQLT_LBI, 4096, 64000, ORA_PIECEWISE);
    OraSetString(cCursor, ":name", "Sunset");
    OraSetPieces(cCursor, ":data", "TestData.dat");
    OraExec(cCursor);
    OraClose(cCursor);
    OraLogoff(hConnection);
  end TMain;
dclsql
  sqlInsert:
    INSERT INTO images (name, data) VALUES (:name, :data);

Example: PL/SQL table binding

var
  hConnection : number;
  cCursor : number;
dcltrans
  transaction TMain
  begin
    OraLogon(hConnection, "user", "password", "orclnet2");
    OraOpen(cCursor, hConnection);
    OraParse(cCursor, sqlProcedureWithPLSQLTable);
    OraBind(cCursor, ":num", SQLT_INT);
    OraBind(cCursor, ":description", SQLT_STR, 20, 3, ORA_PLSQLTABLE_INOUT);
    OraSetInt(cCursor, ":num", 5);
    OraSetString(cCursor, ":description", "Frammis_1", 1);
    OraSetString(cCursor, ":description", "Frammis_2", 2);
    OraSetString(cCursor, ":description", "Frammis_3", 3);
    OraExec(cCursor);
    OraClose(cCursor);
    OraLogoff(hConnection);
  end TMain;
dclsql
  sqlProcedureWithPLSQLTable:
  [BEGIN
    update_parts.add_parts(:num, :description);
  END;]

In this example, the parameter nBindOption specifies the option for binding the place holder. ORA_PLSQLTABLE_INOUT binds a PL/SQL table used as a parameter in a stored procedure with inout direction. The maximum length of a bind element is set to 20, the maximum number of array elements that can be sent/retrieved is set to 3.

Sample scripts

OraArrayFetch.bdf, OraSample.bdf, OraLoadPers.bdf

See also

Wrapped Oracle function: obndrn, obndrv, obndra, obindps, ogetpi, osetpi

Parent topic: Placeholder Binding Functions
Related reference
OraBindCursor Function
OraOciError Function
OraSetBinary Function
OraSetFloat Function
OraSetInt Function
OraSetNull Function
OraSetPieces Function
OraSetString Function
OraExec Function


OraBindCursor Function

Action

Binds a PL/SQL cursor variable to a BDL cursor.

A cursor can be defined in a PL/SQL block and as a stored procedure parameter. Within a BDL script, it is possible to reference to a PL/SQL cursor by binding it to a BDL cursor.

Include file

Ora.bdh

Syntax

OraBindCursor( in cCursor      : cursor,
               in sName        : string,
               out cPLCursor   : cursor): boolean;

Return value

  • true if successful

  • false otherwise. In this case, you can use the OraOciError function to retrieve the Oracle OCI error code

Parameter | Description
cCursor | Cursor associated with a database connection
sName | Name of the cursor defined in the PL/SQL block. This parameter must include the preceding colon identifying it as a cursor
cPLCursor | Variable receiving the cursor defined in the PL/SQL block

Example

var
  hConnection : number;
  cCursor, cSelect : cursor;
dcltrans
  transaction TMain
  var
    nAge : number;
    sName : string;
  begin
    OraLogon(hConnection, "user", "password", "orclnet2");
    OraOpen(cCursor, hConnection);
    OraParse(cCursor, sqlSelect);
    OraBindCursor(cCursor, ":cursor", cSelect);
    OraExec(cCursor);
    OraDefine(cSelect, 1, SQLT_CHR, 32);
    OraDefine(cSelect, 2, SQLT_INT);
    while OraFetch(cSelect) do
      sName := OraGetString(cSelect, "1");
      nAge := OraGetInt(cSelect, "2");
      write(sName, 32); write(nAge, 5); writeln;
    end;
    OraClose(cCursor);
    OraClose(cSelect);
    OraLogoff(hConnection);
  end TMain;
dclsql
  sqlSelect:
  [BEGIN OPEN :cursor FOR SELECT * FROM persons; END;]

Output

Howard 33Mark 12Michael 44Bobby 61Sara 38

See also

Oracle: Programmer's Guide to the Oracle Call Interface: Using PL/SQL in an OCI Program

Parent topic: Placeholder Binding Functions
Related reference
OraBind Function
OraOciError Function


Data Fetching Functions

  • OraGetFloat Function
    Retrieves a floating-point value either from the program variable that is bound with the specified place holder in the SQL statement or PL/SQL block, or from the output variable that is defined for the specified select-list item in the SQL query.
  • OraGetInt Function
    Retrieves a number value either from the program variable that is bound with the specified place holder in the SQL statement or PL/SQL block, or from the output variable that is defined for the specified select-list item in the SQL query.
  • OraGetString Function
    Retrieves a string either from the program variable that is bound with the specified place holder in the SQL statement or PL/SQL block, or from the output variable that is defined for the specified select-list item in the SQL query.
  • OraGetValue Function
    Retrieves any value either from the program variable that is bound with the specified place holder in the SQL statement or PL/SQL block, or from the output variable that is defined for the specified select-list item in the SQL query.
Parent topic: Oracle API Functions Overview


OraGetFloat Function

Action

Retrieves a floating-point value either from the program variable that is bound with the specified place holder in the SQL statement or PL/SQL block, or from the output variable that is defined for the specified select-list item in the SQL query. This function is used to retrieve values from both scalar and array program variables that are defined for the specified select-list item.

Include file

Ora.bdh

Syntax

OraGetFloat( in cCursor : cursor,
             in sSqlVar : string,
             in nIndex  : number optional): float;

Return value

Retrieved floating-point value

Parameter | Description
cCursor | Cursor associated with a database connection
sSqlVar

This parameter can be one of the following:

  • the name of the place holder in the SQL statement or PL/SQL block. In this case, the parameter must include the preceding colon identifying it as a place holder

  • the index of the select-list item in the SQL query. Position indices start at 1 for the first (leftmost) select-list item

Note: In the latter case, the column number has to be passed to the function as a string.
nIndex

Index or row number (optional). This parameter has to be passed to the function whenever retrieving a value assigned to an array place holder or fetching data from multiple rows. It can be one of the following:

  • the array index of the program variable

  • the row number for the floating-point value in the fetched data

Example

var
  hConnection : number;
  cCursor : cursor;

dcltrans
  transaction TMain
  var
    sName : string;
    fBalance : float;
  begin
    OraLogon(hConnection, "user", "password", "orclnet2");
    OraOpen(cCursor, hConnection);
    OraParse(cCursor, sqlSelect);
    OraBind(cCursor, ":1", SQLT_FLT);
    OraSetFloat(cCursor, ":1", 2000.0);
    OraDefine(cCursor, 1, SQLT_CHR, 32);
    OraDefine(cCursor, 2, SQLT_FLT);
    OraExec(cCursor);

    while OraFetch(cCursor) do
      sName := OraGetString(cCursor, "1");
      fBalance := OraGetFloat(cCursor, "2");
      write(sName, 32); write(fBalance); writeln;
    end;

    OraClose(cCursor);
    OraLogoff(hConnection);
  end TMain;

dclsql
  sqlSelect:
    SELECT * FROM accounts WHERE balance > :1;

Output

Bob 13864.220000Pamela 4492.090000Richard 7309.580000

Sample scripts

OraArrayFetch.bdf, OraSample.bdf

Parent topic: Data Fetching Functions
Related reference
OraGetInt Function
OraGetString Function
OraGetValue Function
OraDefine Function
OraDescribe Function
OraFetch Function


OraGetInt Function

Action

Retrieves a number value either from the program variable that is bound with the specified place holder in the SQL statement or PL/SQL block, or from the output variable that is defined for the specified select-list item in the SQL query. This function is used to retrieve values from both scalar and array program variables that are defined for the specified select-list item.

Include file

Ora.bdh

Syntax

OraGetInt( in cCursor : cursor,
           in sSqlVar : string,
           in nIndex  : number optional): number;

Return value

Retrieved long value

Parameter | Description
cCursor | Cursor associated with a database connection
sSqlVar

This parameter can be one of the following:

  • the name of the place holder in the SQL statement or PL/SQL block. In this case, the parameter must include the preceding colon identifying it as a place holder

  • the index of the select-list item in the SQL query. Position indices start at 1 for the first (leftmost) select-list item

Note: In the latter case, the column number has to be passed to the function as a string.
nIndex

Index or row number (optional). This parameter has to be passed to the function whenever retrieving a value assigned to an array place holder or fetching data from multiple rows. It can be one of the following:

  • the array index of the program variable

  • the row number for the long value in the fetched data

Example

var
  hConnection : number;
  cCursor : cursor;

dcltrans
  transaction TMain
  var
    nAge : number;
    sName : string;
  begin
    OraLogon(hConnection, "user", "password", "orclnet2");
    OraOpen(cCursor, hConnection);
    OraParse(cCursor, sqlSelect);
    OraBind(cCursor, ":1", SQLT_INT);
    OraSetInt(cCursor, ":1", 25);
    OraDefine(cCursor, 1, SQLT_CHR, 32);
    OraDefine(cCursor, 2, SQLT_INT);
    OraExec(cCursor);

    while OraFetch(cCursor) do
      sName := OraGetString(cCursor, "1");
      nAge := OraGetInt(cCursor, "2");
      write(sName, 32); write(nAge, 5); writeln;
    end;

    OraClose(cCursor);
    OraLogoff(hConnection);
  end TMain;

dclsql
  sqlSelect:
    SELECT * FROM persons WHERE age > :1;

Output

Howard 33Michael 44Bobby 61Sara 38

Sample scripts

OraArrayFetch.bdf, OraSample.bdf

Parent topic: Data Fetching Functions
Related reference
OraGetFloat Function
OraGetString Function
OraGetValue Function
OraDefine Function
OraDescribe Function
OraFetch Function


OraGetString Function

Action

Retrieves a string either from the program variable that is bound with the specified place holder in the SQL statement or PL/SQL block, or from the output variable that is defined for the specified select-list item in the SQL query. This function is used to retrieve values from both scalar and array program variables that are defined for the specified select-list item.

If this function is used to retrieve one of the following data types, the retrieved value is automatically converted to a string:

  • SQLT_DAT
  • SQL_INT
  • SQLT_FLT

Include file

Ora.bdh

Syntax

OraGetString( in cCursor : cursor,
              in sSqlVar : string,
              in nIndex  : number optional): string;

Return value

Retrieved string, containing at most 253 characters. If the string to be retrieved consists of more than 253 characters, it is automatically cut off at the corresponding position.

Parameter | Description
cCursor | Cursor associated with a database connection
sSqlVar

This parameter can be one of the following:

  • the name of the place holder in the SQL statement or PL/SQL block. In this case, the parameter must include the preceding colon identifying it as a place holder

  • the index of the select-list item in the SQL query. Position indices start at 1 for the first (leftmost) select-list item

Note: In the latter case, the column number has to be passed to the function as a string.
nIndex

Index or row number (optional). This parameter has to be passed to the function whenever retrieving a string assigned to an array place holder or fetching data from multiple rows. It can be one of the following:

  • the array index of the program variable

  • the row number for the string in the fetched data

Example

var
  hConnection : number;
  cCursor : cursor;

dcltrans
  transaction TMain
  var
    nAge : number;
    sName : string;
  begin
    OraLogon(hConnection, "user", "password", "orclnet2");
    OraOpen(cCursor, hConnection);
    OraParse(cCursor, sqlSelect);
    OraBind(cCursor, ":1", SQLT_INT);
    OraSetInt(cCursor, ":1", 25);
    OraDefine(cCursor, 1, SQLT_CHR, 32);
    OraDefine(cCursor, 2, SQLT_INT);
    OraExec(cCursor);

    while OraFetch(cCursor) do
      sName := OraGetString(cCursor, "1");
      nAge := OraGetInt(cCursor, "2");
      write(sName, 32); write(nAge, 5); writeln;
    end;

    OraClose(cCursor);
    OraLogoff(hConnection);
  end TMain;

dclsql
  sqlSelect:
    SELECT * FROM persons WHERE age > :1;

Output

Howard 33Michael 44Bobby 61Sara 38

Sample scripts

OraArrayFetch.bdf, OraSample.bdf

Parent topic: Data Fetching Functions
Related reference
OraGetFloat Function
OraGetInt Function
OraGetValue Function
OraDefine Function
OraDescribe Function
OraFetch Function


OraGetValue Function

Action

Retrieves any value either from the program variable that is bound with the specified place holder in the SQL statement or PL/SQL block, or from the output variable that is defined for the specified select-list item in the SQL query. This function is used to retrieve values from both scalar and array program variables that are defined for the specified select-list item.

Include file

Ora.bdh

Syntax

OraGetValue( in  cCursor     : cursor,
             in  sSqlVar     : string,
             out buffer      : string,
             in  nBufferSize : number,
             in  nIndex      : number optional,
             in  nDatatype   : number optional ): boolean;

Return value

  • true if successful

  • false otherwise. In this case, you can use the OraOciError function to retrieve the Oracle OCI error code

Parameter | Description
cCursor | Cursor associated with a database connection
sSqlVar

This parameter can be one of the following:

  • the name of the place holder in the SQL statement or PL/SQL block. In this case, the parameter must include the preceding colon identifying it as a place holder

  • the index of the select-list item in the SQL query. Position indices start at 1 for the first (leftmost) select-list item

Note: In the latter case, the column number has to be passed to the function as a string
buffer | Variable receiving either the value assigned to the place holder or the data retrieved from a fetched row, as the case may be
nBufferSize | Size of the variable receiving the value
nIndex

Index or row number (optional). This parameter has to be passed to the function whenever retrieving a value assigned to an array place holder or fetching data from multiple rows. It can be one of the following:

  • the array index of the program variable

  • the row number for the long value in the fetched data
nDatatype | Specifies which data type to retrieve (optional). See Oracle data types for a list of data types

Example

var
  hConnection : number;
  cCursor     : cursor;

dcltrans
  transaction TMain
  var
    nAge  : number;
    sName : string;
  begin
    OraLogon(hConnection, "user", "password", "orclnet2");
    OraOpen(cCursor, hConnection);
    OraParse(cCursor, sqlSelect);
    OraBind(cCursor, ":1", SQLT_INT);
    OraSetInt(cCursor, ":1", 25);
    OraDefine(cCursor, 1, SQLT_CHR, 32);
    OraDefine(cCursor, 2, SQLT_INT);
    OraExec(cCursor);

    while OraFetch(cCursor) do
      OraGetValue(cCursor, "1", sName, STRING_COMPLETE);
      nAge := OraGetInt(cCursor, "2");
      write(sName, 32); write(nAge, 5); writeln;
    end;

    OraClose(cCursor);
    OraLogoff(hConnection);
  end TMain;

dclsql
  sqlSelect:
    SELECT * FROM persons WHERE age > :1;

Output

Howard 33Michael 44Bobby 61Sara 38
Parent topic: Data Fetching Functions
Related reference
OraGetFloat Function
OraGetInt Function
OraGetString Function
OraOciError Function
OraDefine Function
OraDescribe Function
OraFetch Function
Oracle Data Types


Date Functions

  • OraDateToInt Function
    Converts an Oracle internal date to a date in integer format (YYYYMMDD).
  • OraIntToDate Function
    Converts a date from integer format (YYYYMMDD) to an Oracle internal date.
  • OraDateToString Function
    Converts an Oracle internal date to a string containing the date in the YYYY-MM-DD:hh.mm.ss format.
Parent topic: Oracle API Functions Overview


OraDateToInt Function

Action

Converts an Oracle internal date to a date in integer format (YYYYMMDD).

Include file

Ora.bdh

Syntax

OraDateToInt( in sOraDate: string ): number;

Return value

date in the YYYYMMDD integer format

Parameter | Description
sOraDate | Oracle internal date in the SQLT_DAT format

Example

var
  cCursor: cursor;

dcltrans
  transaction TMain
  var
    sOraDate : string;
    nDate    : number;
  begin
    ...
    OraGetValue(cCursor, ":colDATE", sOraDate, 7);
    nDate := OraDateToInt(sOraDate);
    write(nDate); writeln;
  end TMain;
Parent topic: Date Functions
Related reference
OraIntToDate Function
OraDateToString Function


OraIntToDate Function

Action

Converts a date from integer format (YYYYMMDD) to an Oracle internal date. This function may be used to generate an Oracle internal date, which can then be bound using Oracle's SQLT_DAT data type.

Include file

Ora.bdh

Syntax

OraIntToDate( in  nDate    : number,
              out sOraDate : string );

Parameter | Description
nDate | Date in integer format (YYYYMMDD)
sOraDate | Variable receiving the Oracle internal date

Example

var
  cCursor: cursor;

dcltrans
  transaction TMain
  var
    sOraDate: string;
  begin
    ...
    OraBind(cCursor, ":colDATE", SQLT_DAT);
    OraIntToDate(19980924, sOraDate);
    OraSetBinary(cCursor, ":colDATE", sOraDate, 7);
  end TMain;
Parent topic: Date Functions
Related reference
OraDateToInt Function
OraDateToString Function


OraDateToString Function

Action

Converts an Oracle internal date to a string containing the date in the YYYY-MM-DD:hh.mm.ss format.

Include file

Ora.bdh

Syntax

OraDateToString(in  sOraDate  : string,
                out sDate     : string,
                in  nDateSize : number);
Parameter | Description
sOraDate | Oracle date in the SQLT_DAT format
sDate | String receiving the date in the YYYY-MM-DD:hh.mm.ss format
nDateSize | Size of the string buffer receiving the converted date

Example

var
  cCursor: cursor;

dcltrans
  transaction TMain
  var
    sOraDate, sDate: string;
  begin
    ...
    OraGetValue(cCursor, ":colDATE", sOraDate, 7);
    OraDateToString(sOraDate, sDate, sizeof(sDate));
    write(sDate); writeln;
  end TMain;
Parent topic: Date Functions
Related reference
OraDateToInt Function
OraIntToDate Function


Error Handling Functions

  • OraOciError Function
    Retrieves the Oracle OCI error code if an OCI error occurred during the last Silk Performer Oracle API function call.
  • OraApiError Function
    Retrieves the Silk Performer Oracle API error code if an API error occurred during the last Silk Performer Oracle API function call.
  • OraLastErrorText Function
    Retrieves the error message describing the last error that occurred.
  • OraIgnoreError Function
    Specifies that a specific Oracle OCI error is to be ignored if it occurs during the next Silk Performer Oracle API function call.
Parent topic: Oracle API Functions Overview


OraOciError Function

Action

Retrieves the Oracle OCI error code if an OCI error occurred during the last Silk Performer Oracle API function call.

Include file

Ora.bdh

Syntax

OraOciError(): number;

Return value

Oracle OCI error code.

A Silk Performer Oracle API error has occurred if a Silk Performer Oracle API function fails and the OraOciError returns 0. In this case, the OraApiError function can be used to retrieve the Silk Performer Oracle API error code

Example

var
  hConnection : number;
  cCursor : cursor;

dcltrans
  transaction TMain
  begin
    OraLogon(hConnection, "user", "password", "orclnet2");
    OraOpen(cCursor, hConnection);
    OraParse(cCursor, sqlSelect);

    // select row from non existing table
    OraIgnoreError(cCursor, 942);
    OraExec(cCursor);
    write("Oracle OCI error: "); write(OraOciError()); writeln;
    write(OraLastErrorText()); writeln;

    OraClose(cCursor);
    OraLogoff(hConnection);
  end TMain;

dclsql
  sqlSelect:
    SELECT * FROM non_existing_table;

Output

Oracle OCI error: 942
OCI-API Class 0 Error (Warning) 942 in OraExec(OEXEC, OEXN):
ORA-00942: table or view does not exist
Parent topic: Error Handling Functions
Related reference
OraApiError Function
OraLastErrorText Function
OraIgnoreError Function


OraApiError Function

Action

Retrieves the Silk Performer Oracle API error code if an API error occurred during the last Silk Performer Oracle API function call. A Silk Performer Oracle API error occurs because of incorrect use of the Silk Performer Oracle API and stops the simulation by default.

Include file

Ora.bdh

Syntax

OraApiError(): number;

Return value

Oracle API error code

Example

var
  hConnection : number;
  cCursor : cursor;

dcltrans
  transaction TMain
  begin
    OraLogon(hConnection, "user", "password", "orclnet2");
    OraOpen(cCursor, hConnection);
    OraParse(cCursor, sqlInsert);

    // array binding: three elements
    OraBind(cCursor, ":name", SQLT_CHR, 32, 3);
    OraBind(cCursor, ":age", SQLT_INT, 0, 3);

    // cause API error: index is too large
    OraSetString(cCursor, ":name", "Tom", 5);
    write("Oracle API error: "); write(OraApiError()); writeln;
    write(OraLastErrorText()); writeln;

    OraExec(cCursor);
    OraClose(cCursor);
    OraLogoff(hConnection);
  end TMain;

dclsql
  sqlInsert:
    INSERT INTO persons (name, age) VALUES (:name, :age);

Output

Oracle API error: 26
ORA-API Class 0 Error (Warning) 26 in OraBind:
ORAAPI: 26 - Index in OraSet/OraGet function is larger than maximum
array size set in OraBind.
Parent topic: Error Handling Functions
Related reference
OraOciError Function
OraLastErrorText Function
OraIgnoreError Function


OraLastErrorText Function

Action

Retrieves the error message describing the last error that occurred. The error code can be retrieved using the OraOciError function and the OraApiError function.

Include file

Ora.bdh

Syntax

OraLastErrorText(): string;

Return value

error message

Example

var
  hConnection : number;
  cCursor : cursor;

dcltrans
  transaction TMain
  begin
    OraLogon(hConnection, "user", "password", "orclnet2");
    OraOpen(cCursor, hConnection);
    OraParse(cCursor, sqlDelete);

    // Oracle error 900: invalid SQL statement
    OraIgnoreError(cCursor, 900);

    // execute invalid SQL statement
    OraExec(cCursor);
     write(OraLastErrorText());

    OraClose(cCursor);
    OraLogoff(hConnection);
  end TMain;

dclsql
  sqlDelete:
    REMOVE FROM my_table;
    // invalid SQL statement

Output

OCI-API Class 0 Error (Warning) 900 in OraExec(OEXEC, OEXN):
ORA-00900: invalid SQL statement
Parent topic: Error Handling Functions
Related reference
OraOciError Function
OraApiError Function
OraIgnoreError Function


OraIgnoreError Function

Action

Specifies that a specific Oracle OCI error is to be ignored if it occurs during the next Silk Performer Oracle API function call. Since the error is then treated in the same way as a warning, the simulation will not be aborted.

Include file

Ora.bdh

Syntax

OraIgnoreError( in cCursor    : cursor,
                in nErrorCode : number): boolean;

Return value

  • true if successful

  • false otherwise

Parameter | Description
cCursor | Cursor associated with a database connection
nErrorCode | Oracle OCI error code. This error will be treated as a class 0 error (warning) for the next Silk Performer Oracle API call

Example

var
  hConnection : number;
  cCursor     : cursor;

dcltrans
  transaction TMain
  begin
    OraLogon(hConnection, "user", "password", "orclnet2");
    OraOpen(cCursor, hConnection);
    OraParse(cCursor, sqlDelete);

    // ignore Oracle error 900: invalid SQL statement
    OraIgnoreError(cCursor, 900);

    // execute invalid SQL statement
    OraExec(cCursor);

    OraClose(cCursor);
    OraLogoff(hConnection);
  end TMain;

dclsql
  sqlDelete:
    REMOVE FROM my_table; // invalid SQL statement
Parent topic: Error Handling Functions
Related reference
OraOciError Function
OraApiError Function
OraLastErrorText Function


Functions Identical to Original OCI Functions

  • OraCancel Function
    Cancels a query after a number of rows have been fetched.
  • OraCommit Function
    Commits the current transaction.
  • OraRollback Function
    Rolls back the current transaction.
  • OraFetchLong Function
    Fetches a portion of an Oracle LONG or LONG RAW column.
  • OraAutoCommit Function
    Enables or disables autocommit.
Parent topic: Oracle API Functions Overview


OraCancel Function

Action

Cancels a query after a number of rows have been fetched. This function releases any resources associated with the cursor except the internal representation of the parsed SQL statement.

Include file

Ora.bdh

Syntax

OraCancel(in cCursor: cursor): boolean;

Return value

  • true if successful

  • false otherwise. In this case, you can use the OraOciError function to retrieve the Oracle OCI error code

Parameter | Description
cCursor | Cursor associated with a database connection.

Example

var
  hConnection : number;
  cCursor : cursor;

dcltrans
  transaction TMain
  var
    sName : string;
    nAge : number;
  begin
    OraLogon(hConnection, "user", "password", "orclnet2");
    OraOpen(cCursor, hConnection);
    OraParse(cCursor, sqlSelect);
    OraExec(cCursor);
    OraDefine(cCursor, 1, SQLT_CHR, 32);
    OraDefine(cCursor, 2, SQLT_INT);
    // fetch first row
    OraFetch(cCursor);
    sName := OraGetString(cCursor, "1");
    nAge := OraGetInt(cCursor, "2");
    write(sName, 32); write(nAge, 3); writeln;
    OraCancel(cCursor);
    // Ignore Oracle error 1002: fetch out of sequence
    OraIgnoreError(cCursor, 1002);
    // try to fetch second row
    OraFetch(cCursor);
    OraClose(cCursor);
    OraLogoff(hConnection);
  end TMain;

dclsql
  sqlSelect:
    SELECT * FROM persons;

Output

Howard 33
OCI-API Class 0 Error (Warning) 1002 in OraFetch(OFETCH, OFEN):
ORA-01002: fetch out of sequence

See Also

Oracle's Programmer's Guide to Oracle Call Interface for the Wrapped Oracle function: ocan

Parent topic: Functions Identical to Original OCI Functions
Related reference
OraCommit Function
OraRollback Function
OraFetchLong Function
OraAutoCommit Function
OraOciError Function
OraFetch Function


OraCommit Function

Action

Commits the current transaction. All SQL statements since the last call of any of the following functions are committed:

OraLogon, OraCommit, OraRollback

Include file

Ora.bdh

Syntax

OraCommit(in hConnection: number): boolean;

Return value

  • true if successful

  • false otherwise. In this case, you can use the OraOciError function to retrieve the Oracle OCI error code

Parameter | Description
hConnection | Handle to the database connection

Example

var
  hConnection : number;
  cCursor     : cursor;

dcltrans
  transaction TMain
  begin
    OraLogon(hConnection, "user", "password", "orclnet2");
    OraOpen(cCursor, hConnection);
    OraParse(cCursor, sqlInsert);
    OraBind(cCursor, ":name", SQLT_CHR, 32, 2);
    OraBind(cCursor, ":age", SQLT_INT, 0, 2);
    OraSetString(cCursor, ":name", "Bob", 1);
    OraSetInt(cCursor, ":age", 25, 1);
    OraSetString(cCursor, ":name", "Marcy", 2);
    OraSetInt(cCursor, ":age", 33, 2);
    OraExec(cCursor);
    OraClose(cCursor);
    OraCommit(hConnection);
    OraLogoff(hConnection);
  end TMain;

dclsql
  sqlInsert:
    INSERT INTO persons (name, age) VALUES (:name, :age);

Sample scripts

OraSample.bdf

Parent topic: Functions Identical to Original OCI Functions
Related reference
OraCancel Function
OraRollback Function
OraFetchLong Function
OraAutoCommit Function
OraOciError Function


OraRollback Function

Action

Rolls back the current transaction. All SQL statements executed since the last call of any of the following functions are rolled back:

OraLogon, OraCommit, OraRollback

Include file

Ora.bdh

Syntax

OraRollback(in hConnection: number): boolean;

Return value

  • true if successful

  • false otherwise. In this case, you can use the OraOciError function to retrieve the Oracle OCI error code

Parameter | Description
hConnection | Handle to the database connection

Example

var
  hConnection : number;
  cCursor     : cursor;

dcltrans
  transaction TMain
  begin
    OraLogon(hConnection, "user", "password", "orclnet2");
    OraOpen(cCursor, hConnection);
    OraParse(cCursor, sqlInsert);
    OraBind(cCursor, ":name", SQLT_CHR, 32, 2);
    OraBind(cCursor, ":age", SQLT_INT, 0, 2);
    OraSetString(cCursor, ":name", "Bob", 1);
    OraSetInt(cCursor, ":age", 25, 1);
    OraSetString(cCursor, ":name", "Marcy", 2);
    OraSetInt(cCursor, ":age", 33, 2);
    OraExec(cCursor);
    OraClose(cCursor);
    OraRollback(hConnection);
    OraLogoff(hConnection);
  end TMain;

dclsql
  sqlInsert:
    INSERT INTO persons (name, age) VALUES (:name, :age);

Sample scripts

OraSample.bdf

Parent topic: Functions Identical to Original OCI Functions
Related reference
OraCancel Function
OraCommit Function
OraFetchLong Function
OraAutoCommit Function
OraOciError Function
OraLogon Function


OraFetchLong Function

Action

Fetches a portion of an Oracle LONG or LONG RAW column. This functions can be used to fetch amounts of data up to 64 KB, starting at any offset. This function uses the Oracle OCI oflng function to retrieve a long column in multiple pieces.

Note: To fetch a portion of a long column, you must call the OraFetch function before performing the OraFetchLong function call.

Include file

Ora.bdh

Syntax

OraFetchLong( in  cCursor     : cursor,
              in  nPosition   : number,
              in  nBufferSize : number,
              in  nDatatype   : number,
              out nReturnLen  : number
              in  nOffset     : number ): boolean;

Return value

  • true if successful

  • false otherwise. In this case, you can use the OraOciError function to retrieve the Oracle OCI error code

Parameter | Description
sCursor | Cursor associated with a database connection
nPosition | Index position of the long column in the row. The first (and leftmost) column is position 1
nBufferSize | Size of the buffer that receives the long column data
nDatatype | Oracle external data type of the select-list item. See Oracle data types for a list of Oracle data types.
nReturnLen | Number of bytes returned
nOffset | Offset of the first byte to receive within the select-list item

Example

var
  hConnection : number;
  cCursor : cursor;

dcltrans
  transaction TMain
  var
    sBuffer : string(64000);
    nLength : number;
  begin
    OraLogon(hConnection, "user", "password", "orclnet2");
    OraOpen(cCursor, hConnection);
    OraParse(cCursor, sqlSelect);
    OraDefine(cCursor, 1, SQLT_LBI, 64000);
    OraExec(cCursor);
    OraFetch(cCursor);
    OraFetchLong(cCursor, 1, sizeof(sBuffer), SQLT_LBI, nLength, 0);
    OraGetValue(cCursor, "1", sBuffer, STRING_COMPLETE);
    write("image size = "); write(nLength); writeln;
    OraClose(cCursor);
    OraLogoff(hConnection);
  end TMain;

dclsql
  sqlSelect:
    SELECT bitmap FROM images;

Output

image size = 48703

See Also

Oracle's Programmer's Guide to Oracle Call Interface for Wrapped Oracle function: oflng

Parent topic: Functions Identical to Original OCI Functions
Related reference
OraCancel Function
OraCommit Function
OraRollback Function
OraAutoCommit Function
OraFetch Function
OraOciError Function
Oracle Data Types


OraAutoCommit Function

Action

Enables or disables autocommit. If autocommit is enabled, every SQL data manipulation statement is automatically committed. Otherwise, OraCommit function calls are necessary to commit SQL statements.

Include file

Ora.bdh

Syntax

OraAutoCommit( in hConnection : number,
               in bAuto       : boolean): boolean;

Return value

  • true if successful

  • false otherwise. In this case, you can use the OraOciError function to retrieve the Oracle OCI error code

Parameter | Description
hConnection | Handle to the database connection
bAuto

  • If this parameter is set to true, autocommit is enabled

  • If this parameter is set to false, autocommit is disabled

Example

var
  hConnection: number;

dcltrans
  transaction TMain
  var
  bOk: boolean;
  begin
    OraLogon(hConnection, "user", "password", "orclnet2");
    bOk := OraAutoCommit(hConnection, true);
    if bOk thenwrite("Autocommit successfully set");
      writeln;
    elsewrite("Autocommit could not be set");
      writeln;
  end;
  OraLogoff(hConnection);
end TMain;

Output

Autocommit successfully set
Parent topic: Functions Identical to Original OCI Functions
Related reference
OraCancel Function
OraCommit Function
OraRollback Function
OraFetchLong Function
OraOciError Function


General Information About Oracle and OCI

Basically we have to distinguish the Oracle version from the OCI version. The Oracle version represents the version number of the Oracle client software or the version number of the Oracle Database Server. The OCI (Oracle Call Interface) version depicts the version number of the OCI protocol, which is used for the communication between the client and the database server.

For example, available Oracle versions are (Oracle Databases as well as the Client software):

  • Oracle 7.3

  • Oracle 8.0.5

  • Oracle 8.1.5

  • Oracle 9.0.1

  • ...

And available OCI versions are (Oracle Call Interface protocols):

  • OCI 7.3

  • OCI 8.x

It is now possible that a client application uses OCI 7 to communicate with a Oracle 7.x database as well as with a Oracle 8.x or 9.x database. But when using OCI 7 to connect to an Oracle 8 database you will not be able to access the Oracle 8 Object features.

OCI 7.x contains about 40 API functions whereas OCI 8.x contains about 550 functions. The majority of the OCI 8 functions are necessary to assist Oracle 8 Objects.

Silk Performer specific information on Oracle and OCI

Silk Performer supports the complete OCI 7.x protocol, regardless if an Oracle 7.x or Oracle 8.x database is used (see above).

Silk Performer supports a subset of the OCI 8.x protocol.

Please note that the OCI 8 API includes also all functions from the OCI 7 API (OCI 7 API is a subset of the OCI 8 API). If a client appplication is now linked with the OCI 8 library, the Silk Performer Recorder will detect and record all functions used from the OCI 7 subset and a subset of the OCI 8 functions.

Rather than asking yourself if Silk Performer supports a specific Oracle version, ask yourself which OCI version does Silk Performer support.

The answer to this question will prove that Silk Performer supports the OCI 7 API as well as the OCI 7 subset of the OCI 8 API and a subset of the OCI 8 API.

Functions identical to original OCI functions

For a detailed description of Oracle's native call interface (foundation of all Oracle functions), refer to Oracle's Programmer's Guide to Oracle Call Interface.

Parent topic: Oracle API Functions Overview
Parent topic: Oracle 8 API Functions Overview


Oracle Data Types

The following Oracle external data types are supported in Oracle functions:

  • SQLT_CHR - (ORANET TYPE) character string
  • SQLT_NUM - (ORANET TYPE) oracle numeric
  • SQLT_INT - (ORANET TYPE) integer
  • SQLT_FLT - (ORANET TYPE) floating-point number
  • SQLT_STR - zero-terminated string
  • SQLT_VNU - NUM with preceding length byte
  • SQLT_PDN - (ORANET TYPE) Packed Decimal Numeric
  • SQLT_LNG - long
  • SQLT_VCS - variable character string
  • SQLT_NON - null/empty PCC Descriptor entry
  • SQLT_RID - rowid
  • SQLT_DAT - date in Oracle format
  • SQLT_VBI - binary in VCS format
  • SQLT_BIN - binary data (DTYBIN)
  • SQLT_LBI - long binary
  • SQLT_UIN - unsigned integer
  • SQLT_SLS - display sign leading separate
  • SQLT_LVC - longer longs (char)
  • SQLT_LVB - longer long binary
  • SQLT_AFC - ANSI fixed char
  • SQLT_AVC - ANSI Var char
  • SQLT_CUR - cursor type
  • SQLT_LAB - label type
  • SQLT_OSL - oslabel type
Parent topic: Oracle API Functions Overview


Oracle 8 API Functions Overview

Silk Performer provides Oracle 8 API functions along with Oracle 8 database traffic recording and replaying support.

Oracle 8 API functions provide a simple and powerful interface to Oracle databases version 7.x, 8.x and version 9.x. All features of Oracle 7.x and Oracle 8.x except Oracle object support are accessible through these Oracle 8 API functions, including:

  • array binding and fetching

  • piecewise binding and fetching

  • binding PL/SQL tables

  • calling PL/SQL blocks and stored procedures

  • cursor binding

  • support for all Oracle data types, including LOB (Large Object) data types

Supported Functions

All Oracle API functions were implemented with the help of Oracle's OCI functions version 8. The optional parameters concept enables both simple usage of the API on the one hand and performing specific database operations using the same functions on the other hand. All functions listed below are available:

  • Connect, Authorize, and Initialize Functions
    Lists the Oracle 8 connect, authorize, and initialize functions.
  • Handle and Descriptor Functions
    Lists the Oracle 8 handle and descriptor functions.
  • Placeholder Binding Functions
    Lists the Oracle 8 placeholder binding functions.
  • Parameter Binding Functions
    Lists the Oracle 8 parameter binding functions.
  • Result Set Definition Functions
    Lists the Oracle 8 result set definition functions.
  • Statement Processing Functions
    Lists the Oracle 8 statement processing functions.
  • Data Fetching Functions
    Lists the Oracle 8 data fetching functions.
  • Transaction Functions
    Lists the Oracle 8 transaction functions.
  • Miscellaneous Functions
    Lists the Oracle 8 miscellaneous functions.
  • LOB Functions
    Lists the Oracle 8 LOB functions.
  • Error Handling Functions
    Lists the Oracle 8 error handling functions.
  • General Information About Oracle and OCI
    Distinguishes the Oracle version from the OCI version.
  • Oracle 8 Data Types
    Lists the Oracle external data types that are supported in Oracle functions.
Parent topic: Database (DBMS) Functions


Connect, Authorize, and Initialize Functions

  • Ora8Init Function
    Initializes the OCI environment and allocates a handle to the initialized environment.
  • Ora8ServerAttach Function
    Creates an access path to a data source for OCI operations.
  • Ora8ServerDetach Function
    Deletes an access path to a data source for OCI operations.
  • Ora8SessionBegin Function
    Creates a user session and begins a user session for a given server.
  • Ora8SessionEnd Function
    Terminates a user session context which has been started with Ora8SessionBegin.
  • Ora8Logon Function
    Create a simple logon session.
  • Ora8Logoff Function
    Release a session that was retrieved using Ora8Logon.
Parent topic: Oracle 8 API Functions Overview


Ora8Init Function

Action

Initializes the OCI environment and allocates a handle to the initialized environment.

Include file

Ora8.bdh

Syntax

Ora8Init (out hEnv  : number,
          in  nMode : number optional ): boolean;

Return value

  • true if successful

  • false otherwise

Parameter | Description
hEnv | Variable receiving the handle to the initialized environment.
nMode

Specifies initialization of an environment mode (optional).

Valid modes are:

  • OCI_DEFAULT (default)

  • OCI_THREADED

  • OCI_OBJECT

  • OCI_SHARED

  • OCI_EVENTS

  • OCI_NO_MUTEX

  • OCI_NO_UCB

Example

var
  ghEnv0        : number;

 dcltrans
  transaction TMain
  var
    bOK : boolean;
  begin
    bOK := Ora8Init(ghEnv0, OCI_DEFAULT);

    if bOK then
      write("OCI environment successfully initialized."); writeln;
    else
      write("Error initializing OCI environment."); writeln;
    end;

    ...

    Ora8HandleFree(ghEnv0, OCI_HTYPE_ENV);
  end TMain;

Output

OCI environment successfully initialized.

See Also

Oracle's Programmer's Guide to Oracle Call Interface for Wrapped Oracle functions: OCIEnvCreate, OCIEnvNlsCreate, OCIInitialize, OCIEnvInit
Parent topic: Connect, Authorize, and Initialize Functions
Related reference
Ora8ServerAttach Function
Ora8ServerDetach Function
Ora8SessionBegin Function
Ora8SessionEnd Function
Ora8Logon Function
Ora8Logoff Function
Ora8HandleFree Function
Ora8HandleAlloc Function


Ora8ServerAttach Function

Action

Creates an access path to a data source for OCI operations.

Include file

Ora8.bdh

Syntax

Ora8ServerAttach( in hServer : number,
                  in sServer : string,
                  in nMode   : number optional ) : boolean;

Return value

  • true if successful

  • false otherwise

Parameter | Description
hServer | An uninitialized server handle, which gets initialized by this call.
sServer | SQL*Net connect descriptor.
nMode

Specifies the various modes of operation.

The valid modes are:

  • OCI_DEFAULT (default)

  • OCI_CPOOL

Example

var
  ghEnv0        : number;
  ghError0      : number;
  ghServer0     : number;

dcltrans
  transaction TMain
  begin
    Ora8Init(ghEnv0);
    Ora8HandleAlloc(ghEnv0, ghError0, OCI_HTYPE_ERROR);
    Ora8HandleAlloc(ghEnv0, ghServer0, OCI_HTYPE_SERVER);
    Ora8ServerAttach(ghServer0, "ORCLNET2");

    ...

    Ora8ServerDetach(ghServer0);
    Ora8HandleFree(ghServer0, OCI_HTYPE_SERVER);
    Ora8HandleFree(ghError0, OCI_HTYPE_ERROR);
    Ora8HandleFree(ghEnv0, OCI_HTYPE_ENV);
  end TMain;

See Also

Oracle's Programmer's Guide to Oracle Call Interface for Wrapped Oracle function: OCIServerAttach
Parent topic: Connect, Authorize, and Initialize Functions
Related reference
Ora8Init Function
Ora8ServerDetach Function
Ora8SessionBegin Function
Ora8SessionEnd Function
Ora8Logon Function
Ora8Logoff Function
Ora8HandleFree Function
Ora8HandleAlloc Function


Ora8ServerDetach Function

Action

Deletes an access path to a data source for OCI operations.

Include file

Ora8.bdh

Syntax

Ora8ServerDetach( in hServer : number,
                  in nMode   : number optional ) : boolean;

Return value

  • true if successful

  • false otherwise

Parameter | Description
hServer | An initialized server handle, which gets reset to uninitialized state. The handle is not de-allocated.
nMode | Specifies the various modes of operation (optional). The only valid mode is OCI_DEFAULT for the default mode. Omit the parameter in order to use the default parameter.

Example

var
  ghEnv0        : number;
  ghError0      : number;
  ghServer0     : number;

dcltrans
  transaction TMain
  begin
    Ora8Init(ghEnv0);
    Ora8HandleAlloc(ghEnv0, ghError0, OCI_HTYPE_ERROR);
    Ora8HandleAlloc(ghEnv0, ghServer0, OCI_HTYPE_SERVER);
    Ora8ServerAttach(ghServer0, "ORCLNET2");

    ...

    Ora8ServerDetach(ghServer0);
    Ora8HandleFree(ghServer0, OCI_HTYPE_SERVER);
    Ora8HandleFree(ghError0, OCI_HTYPE_ERROR);
    Ora8HandleFree(ghEnv0, OCI_HTYPE_ENV);
  end TMain;

See Also

Oracle's Programmer's Guide to Oracle Call Interface for Wrapped Oracle function: OCIServerDetach
Parent topic: Connect, Authorize, and Initialize Functions
Related reference
Ora8Init Function
Ora8ServerAttach Function
Ora8SessionBegin Function
Ora8SessionEnd Function
Ora8Logon Function
Ora8Logoff Function
Ora8HandleFree Function
Ora8HandleAlloc Function


Ora8SessionBegin Function

Action

Creates a user session and begins a user session for a given server.

Include file

Ora8.bdh

Syntax

Ora8SessionBegin( in hSvcCtx  : number,
                  in hSession : number,
                  in nCredt   : number optional,
                  in nMode    : number optional ) : boolean;

Return value

  • true if successful

  • false otherwise

Parameter | Description
hSvcCtx | A handle to a service context. There must be a valid server handle set in the service context handle.
hSession | A handle to a user session context, which is initialized by this call.
nCredt

Specifies the type of credentials to use for establishing the user session (optional).

Valid values are:

  • OCI_CRED_RDBMS

  • OCI_CRED_EXT
nMode

Specifies the various modes of operation (optional).

Valid modes are:

  • OCI_DEFAULT (default)

  • OCI_MIGRATE

  • OCI_SYSDBA

  • OCI_SYSOPER

  • OCI_PRELIM_AUTH

Example

var
  ghEnv0        : number;
  ghError0      : number;
  ghServer0     : number;
  ghSvcCtx0     : number;
  ghSession0    : number;

dcltrans
  transaction TMain
  begin
    Ora8Init(ghEnv0);
    Ora8HandleAlloc(ghEnv0, ghError0, OCI_HTYPE_ERROR);
    Ora8HandleAlloc(ghEnv0, ghServer0, OCI_HTYPE_SERVER);
    Ora8HandleAlloc(ghEnv0, ghSvcCtx0, OCI_HTYPE_SVCCTX);
    Ora8ServerAttach(ghServer0, "ORCLNET2");
    Ora8AttrSetHandle(ghSvcCtx0, OCI_HTYPE_SVCCTX, ghServer0, OCI_ATTR_SERVER);
    Ora8HandleAlloc(ghEnv0, ghSession0, OCI_HTYPE_SESSION);
    Ora8AttrSetString(ghSession0, OCI_HTYPE_SESSION, "SCOTT", OCI_ATTR_USERNAME);
    Ora8AttrSetString(ghSession0, OCI_HTYPE_SESSION, "TIGER", OCI_ATTR_PASSWORD);
    Ora8SessionBegin(ghSvcCtx0, ghSession0, OCI_CRED_RDBMS);
    Ora8AttrSetHandle(ghSvcCtx0, OCI_HTYPE_SVCCTX, ghSession0, OCI_ATTR_SESSION);

    ...

    Ora8SessionEnd(ghSvcCtx0, ghSession0);
    Ora8HandleFree(ghSession0, OCI_HTYPE_SESSION);
    Ora8ServerDetach(ghServer0);
    Ora8HandleFree(ghSvcCtx0, OCI_HTYPE_SVCCTX);
    Ora8HandleFree(ghServer0, OCI_HTYPE_SERVER);
    Ora8HandleFree(ghError0, OCI_HTYPE_ERROR);
    Ora8HandleFree(ghEnv0, OCI_HTYPE_ENV);
  end TMain;

See Also

Oracle's Programmer's Guide to Oracle Call Interface for Wrapped Oracle function: OCISessionBegin
Parent topic: Connect, Authorize, and Initialize Functions
Related reference
Ora8Init Function
Ora8ServerAttach Function
Ora8ServerDetach Function
Ora8SessionEnd Function
Ora8Logon Function
Ora8Logoff Function
Ora8HandleFree Function
Ora8HandleAlloc Function
Ora8AttrSetHandle Function
Ora8AttrSetString Function


Ora8SessionEnd Function

Action

Terminates a user session context which has been started with Ora8SessionBegin.

Include file

Ora8.bdh

Syntax

Ora8SessionEnd( in hSvcCtx  : number,
                in hSession : number,
                in nMode    : number optional ) : boolean;

Return value

  • true if successful

  • false otherwise

Parameter | Description
hSvcCtx | The service context handle.
hSession | The session handle which should be de-authenticated.
nMode | Specifies the various modes of operation (optional). The only valid mode is OCI_DEFAULT. Omit the parameter in order to use the default parameter.

Example

var
  ghEnv0        : number;
  ghError0      : number;
  ghServer0     : number;
  ghSvcCtx0     : number;
  ghSession0    : number;

dcltrans
  transaction TMain
  begin
    Ora8Init(ghEnv0);
    Ora8HandleAlloc(ghEnv0, ghError0, OCI_HTYPE_ERROR);
    Ora8HandleAlloc(ghEnv0, ghServer0, OCI_HTYPE_SERVER);
    Ora8HandleAlloc(ghEnv0, ghSvcCtx0, OCI_HTYPE_SVCCTX);
    Ora8ServerAttach(ghServer0, "ORCLNET2");
    Ora8AttrSetHandle(ghSvcCtx0, OCI_HTYPE_SVCCTX, ghServer0, OCI_ATTR_SERVER);
    Ora8HandleAlloc(ghEnv0, ghSession0, OCI_HTYPE_SESSION);
    Ora8AttrSetString(ghSession0, OCI_HTYPE_SESSION, "SCOTT", OCI_ATTR_USERNAME);
    Ora8AttrSetString(ghSession0, OCI_HTYPE_SESSION, "TIGER", OCI_ATTR_PASSWORD);
    Ora8SessionBegin(ghSvcCtx0, ghSession0, OCI_CRED_RDBMS);
    Ora8AttrSetHandle(ghSvcCtx0, OCI_HTYPE_SVCCTX, ghSession0, OCI_ATTR_SESSION);

    ...

    Ora8SessionEnd(ghSvcCtx0, ghSession0);
    Ora8HandleFree(ghSession0, OCI_HTYPE_SESSION);
    Ora8ServerDetach(ghServer0);
    Ora8HandleFree(ghSvcCtx0, OCI_HTYPE_SVCCTX);
    Ora8HandleFree(ghServer0, OCI_HTYPE_SERVER);
    Ora8HandleFree(ghError0, OCI_HTYPE_ERROR);
    Ora8HandleFree(ghEnv0, OCI_HTYPE_ENV);
  end TMain;

See Also

Oracle's Programmer's Guide to Oracle Call Interface for Wrapped Oracle function: OCISessionEnd
Parent topic: Connect, Authorize, and Initialize Functions
Related reference
Ora8Init Function
Ora8ServerAttach Function
Ora8ServerDetach Function
Ora8SessionBegin Function
Ora8Logon Function
Ora8Logoff Function
Ora8HandleFree Function
Ora8HandleAlloc Function
Ora8AttrSetHandle Function
Ora8AttrSetString Function


Ora8Logon Function

Action

Create a simple logon session.

Include file

Ora8.bdh

Syntax

Ora8Logon( in  hEnv      : number,
           out hSvcCtx   : number,
           in  sUser     : string,
           in  sPassword : string optional,
           in  sConnect  : string optional,
           in  nMode     : number optional): boolean;

Return value

  • true if successful

  • false otherwise; In this case, you can use the Ora8OciError function to retrieve the Oracle OCI error code.

Parameter | Description
hEnv | The environment handle.
hSvcCtx | Variable receiving the initialized service context handle.
sUser

User Identification. This parameter contains either only the user name or the user name, the password, and the host machine identifier. In the latter case, it is necessary to insert a / character between the user name and the password, and a @ character between the password and the connect string. Valid examples are shown below:

  • name

  • name/password

  • name@service_name

  • name/password@service_name
sPassword | Password (optional). If the password is specified through the sUser parameter, this parameter should be omitted or set to NULL.
sConnect | SQL*Net connect descriptor (optional). If the connect string is passed through the sUser parameter, this parameter should be omitted.
nMode

Specifies the various modes of operation (optional).

Valid values are:

  • OCI_DFAULT (default)

Example

var
  ghEnv0        : number;
  ghError0      : number;
  ghSvcCtx0     : number;
  bOK           : boolean;

dcltrans
  transaction TMain
  begin
    Ora8Init(ghEnv0, OCI_DEFAULT);
    Ora8HandleAlloc(ghEnv0, ghError0, OCI_HTYPE_ERROR);
    bOK := Ora8Logon(ghEnv0, ghSvcCtx0, "user", "password", "orclnet2");

    if bOk then
      write("Connection to database established."); writeln;
    else
      write("Error connecting to database."); writeln;
    end;

    ...

    Ora8Logoff(ghSvcCtx0);
    Ora8HandleFree(ghError0, OCI_HTYPE_ERROR);
    Ora8HandleFree(ghEnv0, OCI_HTYPE_ENV);
  end TMain;

Output

Connection to database established.

See Also

Oracle's Programmer's Guide to Oracle Call Interface for Wrapped Oracle function: OCILogon, OCILogon2
Parent topic: Connect, Authorize, and Initialize Functions
Related reference
Ora8Init Function
Ora8ServerAttach Function
Ora8ServerDetach Function
Ora8SessionBegin Function
Ora8SessionEnd Function
Ora8Logoff Function
Ora8HandleFree Function
Ora8HandleAlloc Function


Ora8Logoff Function

Action

Release a session that was retrieved using Ora8Logon.

Include file

Ora8.bdh

Syntax

Ora8Logoff( in hSvcCtx: number ): boolean;

Return value

  • true if successful

  • false otherwise. In this case, you can use the Ora8OciError function to retrieve the Oracle OCI error code

Parameter | Description
hSvcCtx | Valid service context handle established using the Ora8Logon function

Example

var
  ghEnv0        : number;
  ghError0      : number;
  ghSvcCtx0     : number;

dcltrans
  transaction TMain
  begin
    Ora8Init(ghEnv0, OCI_DEFAULT);
    Ora8HandleAlloc(ghEnv0, ghError0, OCI_HTYPE_ERROR);
    Ora8Logon(ghEnv0, ghSvcCtx0, "user", "password", "orclnet2");

    ...

    Ora8Logoff(ghSvcCtx0);
    Ora8HandleFree(ghError0, OCI_HTYPE_ERROR);
    Ora8HandleFree(ghEnv0, OCI_HTYPE_ENV);
  end TMain;

See Also

Oracle's Programmer's Guide to Oracle Call Interface for Wrapped Oracle function: OCILogoff
Parent topic: Connect, Authorize, and Initialize Functions
Related reference
Ora8Init Function
Ora8ServerAttach Function
Ora8ServerDetach Function
Ora8SessionBegin Function
Ora8SessionEnd Function
Ora8Logon Function
Ora8HandleFree Function
Ora8HandleAlloc Function
Ora8OciError Function


Handle and Descriptor Functions

  • Ora8HandleAlloc Function
    Allocates and initializes a handle of the specified type.
  • Ora8HandleFree Function
    Deallocates the given handle of the specified type and releases all allocated resources.
  • Ora8DescriptorAlloc Function
    Allocates and initializes a descriptor or LOB locator of the specified type.
  • Ora8DescriptorFree Function
    Deallocates a previously allocated descriptor.
  • Ora8AttrSetHandle Function
    Sets a handle attribute of a handle or a descriptor.
  • Ora8AttrSetString Function
    Sets a string attribute of a handle or a descriptor.
  • Ora8AttrSetNumber Function
    Sets a numeric attribute of a handle or a descriptor.
  • Ora8AttrSetBoolean Function
    Sets a boolean attribute of a handle or a descriptor.
  • Ora8AttrGetHandle Function
    Gets a handle attribute of a handle or a descriptor.
  • Ora8AttrGetString Function
    Gets a string attribute of a handle or a descriptor.
  • Ora8AttrGetNumber Function
    Gets a number attribute of a handle or a descriptor.
  • Ora8AttrGetBoolean Function
    Gets a boolean attribute of a handle or a descriptor.
  • Ora8ParamGet Function
    Returns a descriptor of a parameter specified by position in the describe handle or statement handle.
  • Ora8ParamSet Function
    Used to set a complex object retrieval (COR) descriptor into a COR handle.
Parent topic: Oracle 8 API Functions Overview


Ora8HandleAlloc Function

Action

Allocates and initializes a handle of the specified type.

Include file

Ora8.bdh

Syntax

Ora8HandleAlloc( in  hEnv     : number,
                 out hHandle  : number,
                 in  nType    : number): boolean;

Return value

  • true if successful

  • false otherwise

Parameter | Description
hEnv | An initialized environment handle. This is used as parent handle.
hHandle | Variable receiving the handle to be allocated.
nType

Specifies the type of handle to be allocated.

The allowed types are:

  • OCI_HTYPE_ERROR

  • OCI_HTYPE_SVCCTX

  • OCI_HTYPE_STMT

  • OCI_HTYPE_SERVER

  • OCI_HTYPE_SESSION

  • OCI_HTYPE_TRANS

Example

var
  ghEnv0        : number;
  ghError0      : number;
  ghStmt0       : number;
  ghSvcCtx0     : number;

dcltrans
  transaction TMain
  const
    PUBLIC_KEY := "\h59b20094...";
  begin
    Ora8Init(ghEnv0, OCI_DEFAULT);
    Ora8HandleAlloc(ghEnv0, ghError0, OCI_HTYPE_ERROR);
    Ora8Logon(ghEnv0, ghSvcCtx0, "user", "password", "orclnet2");

    Ora8HandleAlloc(ghEnv0, ghStmt0, OCI_HTYPE_STMT);
    Ora8StmtPrepare(ghStmt0, sqlInsert, OCI_NTV_SYNTAX);

    Ora8Bind(ghStmt0, ":name", SQLT_CHR, 32);
    Ora8Bind(ghStmt0, ":key", SQLT_BIN, 64);

    Ora8SetString(ghStmt0, ":name", "Michael");
    Ora8SetBinary(ghStmt0, ":key",  PUBLIC_KEY, STRING_COMPLETE);

    Ora8StmtExecute(ghSvcCtx0, ghStmt0);

    Ora8HandleFree(ghStmt0, OCI_HTYPE_STMT);
    Ora8Logoff(ghSvcCtx0);
    Ora8HandleFree(ghError0, OCI_HTYPE_ERROR);
    Ora8HandleFree(ghEnv0, OCI_HTYPE_ENV);
  end TMain;

dclsql
  sqlInsert:
    INSERT INTO keys (name, key) VALUES (:name, :key);

See also

Oracle's Programmer's Guide to Oracle Call Interface for Wrapped Oracle functions: OCIHandleAlloc
Parent topic: Handle and Descriptor Functions
Related reference
Ora8HandleFree Function
Ora8DescriptorAlloc Function
Ora8DescriptorFree Function
Ora8AttrSetHandle Function
Ora8AttrSetString Function
Ora8AttrSetNumber Function
Ora8AttrSetBoolean Function
Ora8AttrGetHandle Function
Ora8AttrGetString Function
Ora8AttrGetNumber Function
Ora8AttrGetBoolean Function
Ora8ParamGet Function
Ora8ParamSet Function
Ora8Bind Function
Ora8Define Function


Ora8HandleFree Function

Action

Deallocates the given handle of the specified type and releases all allocated resources. The handle must have been initialized with the given type.

Include file

Ora8.bdh

Syntax

Ora8HandleFree( in hHandle : number,
                in nType   : number ): boolean;

Return value

  • true if successful

  • false otherwise

Parameter | Description
hHandle | An allocated and initialized handle that should be freed.
nType

Specifies the type of the given handle.

The specific types are:

  • OCI_HTYPE_ENV

  • OCI_HTYPE_ERROR

  • OCI_HTYPE_SVCCTX

  • OCI_HTYPE_STMT

  • OCI_HTYPE_SERVER

  • OCI_HTYPE_SESSION

  • OCI_HTYPE_TRANS

Example

var
  ghEnv0        : number;
  ghError0      : number;
  ghStmt0       : number;
  ghSvcCtx0     : number;

dcltrans
  transaction TMain
  const
    PUBLIC_KEY := "\h59b20094...";
  begin
    Ora8Init(ghEnv0, OCI_DEFAULT);
    Ora8HandleAlloc(ghEnv0, ghError0, OCI_HTYPE_ERROR);
    Ora8Logon(ghEnv0, ghSvcCtx0, "user", "password", "orclnet2");

    Ora8HandleAlloc(ghEnv0, ghStmt0, OCI_HTYPE_STMT);
    Ora8StmtPrepare(ghStmt0, sqlInsert, OCI_NTV_SYNTAX);

    Ora8Bind(ghStmt0, ":name", SQLT_CHR, 32);
    Ora8Bind(ghStmt0, ":key", SQLT_BIN, 64);

    Ora8SetString(ghStmt0, ":name", "Michael");
    Ora8SetBinary(ghStmt0, ":key",  PUBLIC_KEY, STRING_COMPLETE);

    Ora8StmtExecute(ghSvcCtx0, ghStmt0);

    Ora8HandleFree(ghStmt0, OCI_HTYPE_STMT);
    Ora8Logoff(ghSvcCtx0);
    Ora8HandleFree(ghError0, OCI_HTYPE_ERROR);
    Ora8HandleFree(ghEnv0, OCI_HTYPE_ENV);
  end TMain;

dclsql
  sqlInsert:
    INSERT INTO keys (name, key) VALUES (:name, :key);

See also

Oracle's Programmer's Guide to Oracle Call Interface for Wrapped Oracle function: OCIHandleFree
Parent topic: Handle and Descriptor Functions
Related reference
Ora8HandleAlloc Function
Ora8DescriptorAlloc Function
Ora8DescriptorFree Function
Ora8AttrSetHandle Function
Ora8AttrSetString Function
Ora8AttrSetNumber Function
Ora8AttrSetBoolean Function
Ora8AttrGetHandle Function
Ora8AttrGetString Function
Ora8AttrGetNumber Function
Ora8AttrGetBoolean Function
Ora8ParamGet Function
Ora8ParamSet Function


Ora8DescriptorAlloc Function

Action

Allocates and initializes a descriptor or LOB locator of the specified type.

Include file

Ora8.bdh

Syntax

Ora8DescriptorAlloc( in  hEnv        : number,
                     out hDescriptor : number,
                     in  nType       : number): boolean;

Return value

  • true if successful

  • false otherwise.

Parameter | Description
hEnv | An initialized environment handle. This is used as parent handle.
hDescriptor | Variable receiving the descriptor or LOB locator to be allocated.
nType

Type of descriptor or LOB locator to be allocated.

Could be one of the following:

  • OCI_DTYPE_SNAP

  • OCI_DTYPE_LOB

  • OCI_DTYPE_FILE

  • OCI_DTYPE_ROWID

Example

var
  ghEnv0        : number;
  ghError0      : number;
  ghSvcCtx0     : number;
  ghDescriptor0 : number;

dcltrans
  transaction TMain
  begin
    Ora8Init(ghEnv0, OCI_DEFAULT);
    Ora8HandleAlloc(ghEnv0, ghError0, OCI_HTYPE_ERROR);
    Ora8Logon(ghEnv0, ghSvcCtx0, "user", "password", "orclnet2");

    Ora8DescriptorAlloc(ghEnv0, ghDescriptor0, OCI_DTYPE_SNAP);

    ...

    Ora8DescriptorFree(ghDescriptor0, OCI_DTYPE_SNAP);
    Ora8HandleFree(ghStmt0, OCI_HTYPE_STMT);
    Ora8Logoff(ghSvcCtx0);
    Ora8HandleFree(ghError0, OCI_HTYPE_ERROR);
    Ora8HandleFree(ghEnv0, OCI_HTYPE_ENV);
  end TMain;

See also

Oracle's Programmer's Guide to Oracle Call Interface for Wrapped Oracle functions: OCIDescriptorAlloc
Parent topic: Handle and Descriptor Functions
Related reference
Ora8HandleAlloc Function
Ora8HandleFree Function
Ora8DescriptorFree Function
Ora8AttrSetHandle Function
Ora8AttrSetString Function
Ora8AttrSetNumber Function
Ora8AttrSetBoolean Function
Ora8AttrGetHandle Function
Ora8AttrGetString Function
Ora8AttrGetNumber Function
Ora8AttrGetBoolean Function
Ora8ParamGet Function
Ora8ParamSet Function
Ora8Init Function


Ora8DescriptorFree Function

Action

Deallocates a previously allocated descriptor.

Include file

Ora8.bdh

Syntax

Ora8DescriptorFree( in hDescriptor : number,
                    in nType       : number) : boolean;

Return value

  • true if successful

  • false otherwise

Parameter | Description
hDescriptor | An allocated and initialized descriptor that should be freed.
nType

Specifies the type of the given descriptor.

Could be one of the following:

  • OCI_DTYPE_SNAP

  • OCI_DTYPE_LOB

  • OCI_DTYPE_FILE

  • OCI_DTYPE_ROWID

Example

var
  ghEnv0        : number;
  ghError0      : number;
  ghSvcCtx0     : number;
  ghDescriptor0 : number;

dcltrans
  transaction TMain
  begin
    Ora8Init(ghEnv0, OCI_DEFAULT);
    Ora8HandleAlloc(ghEnv0, ghError0, OCI_HTYPE_ERROR);
    Ora8Logon(ghEnv0, ghSvcCtx0, "user", "password", "orclnet2");

    Ora8DescriptorAlloc(ghEnv0, ghDescriptor0, OCI_DTYPE_SNAP);

    ...

    Ora8DescriptorFree(ghDescriptor0, OCI_DTYPE_SNAP);
    Ora8HandleFree(ghStmt0, OCI_HTYPE_STMT);
    Ora8Logoff(ghSvcCtx0);
    Ora8HandleFree(ghError0, OCI_HTYPE_ERROR);
    Ora8HandleFree(ghEnv0, OCI_HTYPE_ENV);
  end TMain;

See also

Oracle's Programmer's Guide to Oracle Call Interface for Wrapped Oracle functions: OCIDescriptorFree
Parent topic: Handle and Descriptor Functions
Related reference
Ora8HandleAlloc Function
Ora8HandleFree Function
Ora8DescriptorAlloc Function
Ora8AttrSetHandle Function
Ora8AttrSetString Function
Ora8AttrSetNumber Function
Ora8AttrSetBoolean Function
Ora8AttrGetHandle Function
Ora8AttrGetString Function
Ora8AttrGetNumber Function
Ora8AttrGetBoolean Function
Ora8ParamGet Function
Ora8ParamSet Function
Ora8Init Function


Ora8AttrSetHandle Function

Action

Sets a handle attribute of a handle or a descriptor. The type of the target handle whose attribute gets modified must be specified in the nType parameter. The attribute type must be specified in the nAttrType parameter.

Include file

Ora8.bdh

Syntax

Ora8AttrSetHandle( in hTargetHandle : number,
                   in nType         : number,
                   in hAttrValue    : number,
                   in nAttrType     : number ): boolean;

Return value

  • true if successful

  • false otherwise

Parameter | Description
hTargetHandle | Initialized handle whose attribute gets modified.
nType

Specifies the type of the handle whose attribute gets modified.

The specific types are:

  • OCI_HTYPE_ENV

  • OCI_HTYPE_ERROR

  • OCI_HTYPE_SVCCTX

  • OCI_HTYPE_STMT

  • OCI_HTYPE_BIND

  • OCI_HTYPE_DEFINE

  • OCI_HTYPE_DESCRIBE

  • OCI_HTYPE_SERVER

  • OCI_HTYPE_SESSION

  • OCI_HTYPE_TRANS
hAttrValue | Handle that should be set as attribute value into the target handle.
nAttrType

The type of attribute being set.

The valid types are listed in the table "ORA 8 attributes".

Example

var
  ghEnv0        : number;
  ghError0      : number;
  ghStmt0       : number;
  ghSvcCtx0     : number;
  ghServer0     : number;

dcltrans
  transaction TMain
  begin
    Ora8Init(ghEnv0);
    Ora8HandleAlloc(ghEnv0, ghError0, OCI_HTYPE_ERROR);
    Ora8HandleAlloc(ghEnv0, ghServer0, OCI_HTYPE_SERVER);
    Ora8HandleAlloc(ghEnv0, ghSvcCtx0, OCI_HTYPE_SVCCTX);
    Ora8ServerAttach(ghServer0, "ORCLNET2");
    Ora8AttrSetHandle(ghSvcCtx0, OCI_HTYPE_SVCCTX, ghServer0, OCI_ATTR_SERVER);
    Ora8HandleAlloc(ghEnv0, ghSession0, OCI_HTYPE_SESSION);
    Ora8AttrSetString(ghSession0, OCI_HTYPE_SESSION, "SCOTT", OCI_ATTR_USERNAME);
    Ora8AttrSetString(ghSession0, OCI_HTYPE_SESSION, "TIGER", OCI_ATTR_PASSWORD);
    Ora8SessionBegin(ghSvcCtx0, ghSession0, OCI_CRED_RDBMS);
    Ora8AttrSetHandle(ghSvcCtx0, OCI_HTYPE_SVCCTX, ghSession0, OCI_ATTR_SESSION);
    Ora8HandleAlloc(ghEnv0, ghStmt0, OCI_HTYPE_STMT);

    ...

    Ora8HandleFree(ghStmt0, OCI_HTYPE_STMT);
    Ora8SessionEnd(ghSvcCtx0, ghSession0);
    Ora8HandleFree(ghSession0, OCI_HTYPE_SESSION);
    Ora8ServerDetach(ghServer0);
    Ora8HandleFree(ghSvcCtx0, OCI_HTYPE_SVCCTX);
    Ora8HandleFree(ghServer0, OCI_HTYPE_SERVER);
    Ora8HandleFree(ghError0, OCI_HTYPE_ERROR);
    Ora8HandleFree(ghEnv0, OCI_HTYPE_ENV);
  end TMain;

See also

Oracle's Programmer's Guide to Oracle Call Interface for Wrapped Oracle functions: OCIAttrSet
Parent topic: Handle and Descriptor Functions
Related reference
Ora8HandleAlloc Function
Ora8HandleFree Function
Ora8DescriptorAlloc Function
Ora8DescriptorFree Function
Ora8AttrSetString Function
Ora8AttrSetNumber Function
Ora8AttrSetBoolean Function
Ora8AttrGetHandle Function
Ora8AttrGetString Function
Ora8AttrGetNumber Function
Ora8AttrGetBoolean Function
Ora8ParamGet Function
Ora8ParamSet Function
Ora8Init Function


Ora8AttrSetString Function

Action

Sets a string attribute of a handle or a descriptor. The type of the target handle whose attribute gets modified must be specified in the nType parameter. The attribute type must be specified in the nAttrType parameter.

Include file

Ora8.bdh

Syntax

Ora8AttrSetString( in hTargetHandle : number,
                   in nType         : number,
                   in sAttrValue    : string,
                   in nAttrType     : number ): boolean;

Return value

  • true if successful

  • false otherwise

Parameter | Description
hTargetHandle | Initialized handle whose attribute gets modified.
nType

Specifies the type of the handle whose attribute gets modified.

The specific types are:

  • OCI_HTYPE_ENV

  • OCI_HTYPE_ERROR

  • OCI_HTYPE_SVCCTX

  • OCI_HTYPE_STMT

  • OCI_HTYPE_BIND

  • OCI_HTYPE_DEFINE

  • OCI_HTYPE_DESCRIBE

  • OCI_HTYPE_SERVER

  • OCI_HTYPE_SESSION

  • OCI_HTYPE_TRANS
sAttrValue | String that should be set as attribute value into the target handle.
nAttrType

The type of attribute being set.

The valid types are listed in the table "ORA 8 attributes".

Example

var
  ghEnv0        : number;
  ghError0      : number;
  ghStmt0       : number;
  ghSvcCtx0     : number;
  ghServer0     : number;

dcltrans
  transaction TMain
  begin
    Ora8Init(ghEnv0);
    Ora8HandleAlloc(ghEnv0, ghServer0, OCI_HTYPE_SERVER);
    Ora8HandleAlloc(ghEnv0, ghSvcCtx0, OCI_HTYPE_SVCCTX);
    Ora8HandleAlloc(ghEnv0, ghError0, OCI_HTYPE_ERROR);
    Ora8ServerAttach(ghServer0, "ORCLNET2");
    Ora8AttrSetHandle(ghSvcCtx0, OCI_HTYPE_SVCCTX, ghServer0, OCI_ATTR_SERVER);
    Ora8HandleAlloc(ghEnv0, ghSession0, OCI_HTYPE_SESSION);
    Ora8AttrSetString(ghSession0, OCI_HTYPE_SESSION, "SCOTT", OCI_ATTR_USERNAME);
    Ora8AttrSetString(ghSession0, OCI_HTYPE_SESSION, "TIGER", OCI_ATTR_PASSWORD);
    Ora8SessionBegin(ghSvcCtx0, ghSession0, OCI_CRED_RDBMS);
    Ora8AttrSetHandle(ghSvcCtx0, OCI_HTYPE_SVCCTX, ghSession0, OCI_ATTR_SESSION);
    Ora8HandleAlloc(ghEnv0, ghStmt0, OCI_HTYPE_STMT);

    ...

    Ora8HandleFree(ghStmt0, OCI_HTYPE_STMT);
    Ora8SessionEnd(ghSvcCtx0, ghSession0);
    Ora8HandleFree(ghSession0, OCI_HTYPE_SESSION);
    Ora8ServerDetach(ghServer0);
    Ora8HandleFree(ghServer0, OCI_HTYPE_SERVER);
    Ora8HandleFree(ghSvcCtx0, OCI_HTYPE_SVCCTX);
    Ora8HandleFree(ghError0, OCI_HTYPE_ERROR);
    Ora8HandleFree(ghEnv0, OCI_HTYPE_ENV);
  end TMain;

See also

Oracle's Programmer's Guide to Oracle Call Interface for Wrapped Oracle functions: OCIAttrSet
Parent topic: Handle and Descriptor Functions
Related reference
Ora8HandleAlloc Function
Ora8HandleFree Function
Ora8DescriptorAlloc Function
Ora8DescriptorFree Function
Ora8AttrSetHandle Function
Ora8AttrSetNumber Function
Ora8AttrSetBoolean Function
Ora8AttrGetHandle Function
Ora8AttrGetString Function
Ora8AttrGetNumber Function
Ora8AttrGetBoolean Function
Ora8ParamGet Function
Ora8ParamSet Function
Ora8Init Function


Ora8AttrSetNumber Function

Action

Sets a numeric attribute of a handle or a descriptor. The type of the target handle whose attribute gets modified must be specified in the nType parameter. The attribute type must be specified in the nAttrType parameter.

Include file

Ora8.bdh

Syntax

Ora8AttrSetNumber( in hTargetHandle : number,
                   in nType         : number,
                   in nAttrValue    : number,
                   in nAttrType     : number ): boolean;

Return value

  • true if successful

  • false otherwise

Parameter | Description
hTargetHandle | Initialized handle whose attribute gets modified.
nType

Specifies the type of the handle whose attribute gets modified.

The specific types are:

  • OCI_HTYPE_ENV

  • OCI_HTYPE_ERROR

  • OCI_HTYPE_SVCCTX

  • OCI_HTYPE_STMT

  • OCI_HTYPE_BIND

  • OCI_HTYPE_DEFINE

  • OCI_HTYPE_DESCRIBE

  • OCI_HTYPE_SERVER

  • OCI_HTYPE_SESSION

  • OCI_HTYPE_TRANS
nAttrValue | Numeric value that should be set as attribute value into the target handle.
nAttrType

The type of attribute being set.

The valid types are listed in the table "ORA 8 attributes".

Example

var
  ghEnv0        : number;
  ghError0      : number;
  ghServer0     : number;
  ghStmt0       : number;
  ghSvcCtx0     : number;
  ghSession0    : number;

dcltrans
  transaction TMain
  begin
    Ora8Init(ghEnv0);
    Ora8HandleAlloc(ghEnv0, ghServer0, OCI_HTYPE_SERVER);
    Ora8HandleAlloc(ghEnv0, ghSvcCtx0, OCI_HTYPE_SVCCTX);
    Ora8HandleAlloc(ghEnv0, ghError0, OCI_HTYPE_ERROR);
    Ora8ServerAttach(ghServer0, "ORCLNET2");
    Ora8AttrSetHandle(ghSvcCtx0, OCI_HTYPE_SVCCTX, ghServer0, OCI_ATTR_SERVER);
    Ora8HandleAlloc(ghEnv0, ghSession0, OCI_HTYPE_SESSION);
    Ora8AttrSetString(ghSession0, OCI_HTYPE_SESSION, "SCOTT", OCI_ATTR_USERNAME);
    Ora8AttrSetString(ghSession0, OCI_HTYPE_SESSION, "TIGER", OCI_ATTR_PASSWORD);
    Ora8SessionBegin(ghSvcCtx0, ghSession0, OCI_CRED_RDBMS);
    Ora8AttrSetHandle(ghSvcCtx0, OCI_HTYPE_SVCCTX, ghSession0, OCI_ATTR_SESSION);
    Ora8HandleAlloc(ghEnv0, ghStmt0, OCI_HTYPE_STMT);
    Ora8AttrSetNumber(ghStmt0, OCI_HTYPE_STMT, 10, OCI_ATTR_PREFETCH_ROWS);

    ...

    Ora8HandleFree(ghStmt0, OCI_HTYPE_STMT);
    Ora8SessionEnd(ghSvcCtx0, ghSession0);
    Ora8HandleFree(ghSession0, OCI_HTYPE_SESSION);
    Ora8ServerDetach(ghServer0);
    Ora8HandleFree(ghServer0, OCI_HTYPE_SERVER);
    Ora8HandleFree(ghSvcCtx0, OCI_HTYPE_SVCCTX);
    Ora8HandleFree(ghError0, OCI_HTYPE_ERROR);
    Ora8HandleFree(ghEnv0, OCI_HTYPE_ENV);
  end TMain;

See also

Oracle's Programmer's Guide to Oracle Call Interface for Wrapped Oracle functions: OCIAttrSet
Parent topic: Handle and Descriptor Functions
Related reference
Ora8HandleAlloc Function
Ora8HandleFree Function
Ora8DescriptorAlloc Function
Ora8DescriptorFree Function
Ora8AttrSetHandle Function
Ora8AttrSetString Function
Ora8AttrSetBoolean Function
Ora8AttrGetHandle Function
Ora8AttrGetString Function
Ora8AttrGetNumber Function
Ora8AttrGetBoolean Function
Ora8ParamGet Function
Ora8ParamSet Function
Ora8Init Function


Ora8AttrSetBoolean Function

Action

Sets a boolean attribute of a handle or a descriptor. The type of the target handle whose attribute gets modified must be specified in the nType parameter. The attribute type must be specified in the nAttrType parameter.

Include file

Ora8.bdh

Syntax

Ora8AttrSetBoolean( in hTargetHandle : number,
                    in nType         : number,
                    in bAttrValue    : boolean,
                    in nAttrType     : number ): boolean;

Return value

  • true if successful

  • false otherwise

Parameter | Description
hTargetHandle | Initialized handle whose attribute gets modified.
nType

Specifies the type of the handle whose attribute gets modified.

The specific types are:

  • OCI_HTYPE_ENV

  • OCI_HTYPE_ERROR

  • OCI_HTYPE_SVCCTX

  • OCI_HTYPE_STMT

  • OCI_HTYPE_BIND

  • OCI_HTYPE_DEFINE

  • OCI_HTYPE_DESCRIBE

  • OCI_HTYPE_SERVER

  • OCI_HTYPE_SESSION

  • OCI_HTYPE_TRANS
bAttrValue | Boolean value that should be set as attribute value into the target handle.
nAttrType

The type of attribute being set.

The valid types are listed in the table "ORA 8 attributes".

See also

Oracle's Programmer's Guide to Oracle Call Interface for Wrapped Oracle functions: OCIAttrSet
Parent topic: Handle and Descriptor Functions
Related reference
Ora8HandleAlloc Function
Ora8HandleFree Function
Ora8DescriptorAlloc Function
Ora8DescriptorFree Function
Ora8AttrSetHandle Function
Ora8AttrSetString Function
Ora8AttrSetNumber Function
Ora8AttrGetHandle Function
Ora8AttrGetString Function
Ora8AttrGetNumber Function
Ora8AttrGetBoolean Function
Ora8ParamGet Function
Ora8ParamSet Function


Ora8AttrGetHandle Function

Action

Gets a handle attribute of a handle or a descriptor. The type of the target handle whose attribute gets modified must be specified in the nType parameter. The attribute type must be specified in the nAttrType parameter.

Include file

Ora8.bdh

Syntax

Ora8AttrGetHandle( in  hTargetHandle : number,
                   in  nType         : number,
                   out hAttrValue    : number,
                   in  nAttrType     : number ): boolean;

Return value

  • true if successful

  • false otherwise

Parameter | Description
hTargetHandle | Initialized handle whose attribute is retrieved.
nType

Specifies the type of the handle whose attribute is retrieved.

The specific types are:

  • OCI_HTYPE_ENV

  • OCI_HTYPE_ERROR

  • OCI_HTYPE_SVCCTX

  • OCI_HTYPE_STMT

  • OCI_HTYPE_BIND

  • OCI_HTYPE_DEFINE

  • OCI_HTYPE_DESCRIBE

  • OCI_HTYPE_SERVER

  • OCI_HTYPE_SESSION

  • OCI_HTYPE_TRANS
hAttrValue | Variable receiving the handle attribute value.
nAttrType

The type of attribute being retrieved.

The valid types are listed in the table "ORA 8 attributes".

Example

var
  ghEnv0        : number;
  ghError0      : number;
  ghSvcCtx0     : number;

dcltrans
  transaction TMain
  var
    hEnvironment : number;
  begin
    Ora8Init(ghEnv0, OCI_DEFAULT);
    Ora8HandleAlloc(ghEnv0, ghError0, OCI_HTYPE_ERROR);
    Ora8Logon(ghEnv0, ghSvcCtx0, "user", "password", "orclnet2");

    Ora8AttrGetHandle(ghSvcCtx0, OCI_HTYPE_SVCCTX, hEnvironment, OCI_ATTR_ENV);

    Ora8Logoff(ghSvcCtx0);
    Ora8HandleFree(ghError0, OCI_HTYPE_ERROR);
    Ora8HandleFree(ghEnv0, OCI_HTYPE_ENV);
  end TMain;

See also

Oracle's Programmer's Guide to Oracle Call Interface for Wrapped Oracle functions: OCIAttrGet
Parent topic: Handle and Descriptor Functions
Related reference
Ora8HandleAlloc Function
Ora8HandleFree Function
Ora8DescriptorAlloc Function
Ora8DescriptorFree Function
Ora8AttrSetHandle Function
Ora8AttrSetString Function
Ora8AttrSetNumber Function
Ora8AttrSetBoolean Function
Ora8AttrGetString Function
Ora8AttrGetNumber Function
Ora8AttrGetBoolean Function
Ora8ParamGet Function
Ora8ParamSet Function
Ora8Init Function


Ora8AttrGetString Function

Action

Gets a string attribute of a handle or a descriptor. The type of the target handle whose attribute gets modified must be specified in the nType parameter. The attribute type must be specified in the nAttrType parameter.

Include file

Ora8.bdh

Syntax

Ora8AttrGetString( in  hTargetHandle : number,
                   in  nType         : number,
                   out sAttrValue    : string,
                   in  nAttrType     : number ): boolean;

Return value

  • true if successful

  • false otherwise

Parameter | Description
hTargetHandle | Initialized handle whose attribute is retrieved.
nType

Specifies the type of the handle whose attribute is retrieved.

The specific types are:

  • OCI_HTYPE_ENV

  • OCI_HTYPE_ERROR

  • OCI_HTYPE_SVCCTX

  • OCI_HTYPE_STMT

  • OCI_HTYPE_BIND

  • OCI_HTYPE_DEFINE

  • OCI_HTYPE_DESCRIBE

  • OCI_HTYPE_SERVER

  • OCI_HTYPE_SESSION

  • OCI_HTYPE_TRANS
sAttrValue | Variable receiving the string attribute value.
nAttrType

The type of attribute being retrieved.

The valid types are listed in the table "ORA 8 attributes".

Example

var
  ghEnv0        : number;
  ghError0      : number;
  ghSvcCtx0     : number;

dcltrans
  transaction TMain
  var
    sPwd : string;
  begin
    Ora8Init(ghEnv0, OCI_DEFAULT);
    Ora8HandleAlloc(ghEnv0, ghError0, OCI_HTYPE_ERROR);
    Ora8Logon(ghEnv0, ghSvcCtx0, "user", "password", "orclnet2");

    Ora8AttrGetString(ghSvcCtx0, OCI_HTYPE_SVCCTX, sPwd, OCI_ATTR_LDAP_CRED);

    Ora8Logoff(ghSvcCtx0);
    Ora8HandleFree(ghError0, OCI_HTYPE_ERROR);
    Ora8HandleFree(ghEnv0, OCI_HTYPE_ENV);
  end TMain;

See also

Oracle's Programmer's Guide to Oracle Call Interface for Wrapped Oracle functions: OCIAttrGet
Parent topic: Handle and Descriptor Functions
Related reference
Ora8HandleAlloc Function
Ora8HandleFree Function
Ora8DescriptorAlloc Function
Ora8DescriptorFree Function
Ora8AttrSetHandle Function
Ora8AttrSetString Function
Ora8AttrSetNumber Function
Ora8AttrSetBoolean Function
Ora8AttrGetHandle Function
Ora8AttrGetNumber Function
Ora8AttrGetBoolean Function
Ora8ParamGet Function
Ora8ParamSet Function
Ora8Init Function


Ora8AttrGetNumber Function

Action

Gets a number attribute of a handle or a descriptor. The type of the target handle whose attribute gets modified must be specified in the nType parameter. The attribute type must be specified in the nAttrType parameter.

Include file

Ora8.bdh

Syntax

Ora8AttrGetNumber( in  hTargetHandle : number,
                   in  nType         : number,
                   out nAttrValue    : number,
                   in  nAttrType     : number ): boolean;

Return value

  • true if successful

  • false otherwise

Parameter | Description
hTargetHandle | Initialized handle whose attribute is retrieved.
nType

Specifies the type of the handle whose attribute is retrieved.

The specific types are:

  • OCI_HTYPE_ENV

  • OCI_HTYPE_ERROR

  • OCI_HTYPE_SVCCTX

  • OCI_HTYPE_STMT

  • OCI_HTYPE_BIND

  • OCI_HTYPE_DEFINE

  • OCI_HTYPE_DESCRIBE

  • OCI_HTYPE_SERVER

  • OCI_HTYPE_SESSION

  • OCI_HTYPE_TRANS
nAttrValue | Variable receiving the number attribute value.
nAttrType

The type of attribute being retrieved.

The valid types are listed in the table "ORA 8 attributes".

Example

var
  ghEnv0        : number;
  ghError0      : number;
  ghSvcCtx0     : number;

dcltrans
  transaction TMain
  var
    nCacheMaxSize: number;
  begin
    Ora8Init(ghEnv0, OCI_DEFAULT);
    Ora8HandleAlloc(ghEnv0, ghError0, OCI_HTYPE_ERROR);
    Ora8Logon(ghEnv0, ghSvcCtx0, "user", "password", "orclnet2");

    Ora8AttrGetNumber(ghSvcCtx0, OCI_HTYPE_SVCCTX, nCacheMaxSize, OCI_ATTR_CACHE_MAX_SIZE);

    Ora8Logoff(ghSvcCtx0);
    Ora8HandleFree(ghError0, OCI_HTYPE_ERROR);
    Ora8HandleFree(ghEnv0, OCI_HTYPE_ENV);
  end TMain;

See also

Oracle's Programmer's Guide to Oracle Call Interface for Wrapped Oracle functions: OCIAttrGet
Parent topic: Handle and Descriptor Functions
Related reference
Ora8HandleAlloc Function
Ora8HandleFree Function
Ora8DescriptorAlloc Function
Ora8DescriptorFree Function
Ora8AttrSetHandle Function
Ora8AttrSetString Function
Ora8AttrSetNumber Function
Ora8AttrSetBoolean Function
Ora8AttrGetHandle Function
Ora8AttrGetString Function
Ora8AttrGetBoolean Function
Ora8ParamGet Function
Ora8ParamSet Function
Ora8Init Function


Ora8AttrGetBoolean Function

Action

Gets a boolean attribute of a handle or a descriptor. The type of the target handle whose attribute gets modified must be specified in the nType parameter. The attribute type must be specified in the nAttrType parameter.

Include file

Ora8.bdh

Syntax

Ora8AttrGetBoolean( in  hTargetHandle : number,
                    in  nType         : number,
                    out bAttrValue    : boolean,
                    in  nAttrType     : number ) : boolean;

Return value

  • true if successful

  • false otherwise

Parameter | Description
hTargetHandle | Initialized handle whose attribute is retrieved.
nType

Specifies the type of the handle whose attribute is retrieved.

The specific types are:

  • OCI_HTYPE_ENV

  • OCI_HTYPE_ERROR

  • OCI_HTYPE_SVCCTX

  • OCI_HTYPE_STMT

  • OCI_HTYPE_BIND

  • OCI_HTYPE_DEFINE

  • OCI_HTYPE_DESCRIBE

  • OCI_HTYPE_SERVER

  • OCI_HTYPE_SESSION

  • OCI_HTYPE_TRANS
bAttrValue | Variable receiving the boolean attribute value.
nAttrType

The type of attribute being retrieved.

The valid types are listed in the table "ORA 8 attributes".

Example

var
  ghEnv0        : number;
  ghError0      : number;
  ghSvcCtx0     : number;

dcltrans
  transaction TMain
  var
    bObject : boolean;
  begin
    Ora8Init(ghEnv0, OCI_DEFAULT);
    Ora8HandleAlloc(ghEnv0, ghError0, OCI_HTYPE_ERROR);
    Ora8Logon(ghEnv0, ghSvcCtx0, "user", "password", "orclnet2");

    Ora8AttrGetBoolean(ghEnv0, OCI_HTYPE_ENV, bObject, OCI_ATTR_OBJECT);

    Ora8Logoff(ghSvcCtx0);
    Ora8HandleFree(ghError0, OCI_HTYPE_ERROR);
    Ora8HandleFree(ghEnv0, OCI_HTYPE_ENV);
  end TMain;

See also

Oracle's Programmer's Guide to Oracle Call Interface for Wrapped Oracle functions: OCIAttrGet
Parent topic: Handle and Descriptor Functions
Related reference
Ora8HandleAlloc Function
Ora8HandleFree Function
Ora8DescriptorAlloc Function
Ora8DescriptorFree Function
Ora8AttrSetHandle Function
Ora8AttrSetString Function
Ora8AttrSetNumber Function
Ora8AttrSetBoolean Function
Ora8AttrGetHandle Function
Ora8AttrGetString Function
Ora8AttrGetNumber Function
Ora8ParamGet Function
Ora8ParamSet Function


Ora8ParamGet Function

Action

Returns a descriptor of a parameter specified by position in the describe handle or statement handle.

Include file

Ora8.bdh

Syntax

Ora8ParamGet( in  hHandle     : number
              in  nType       : number,
              out hParamDesc  : number,
              in  nPosition   : number) : boolean;

Return value

  • true if successful

  • false otherwise

Parameter | Description
hHandle | A statement handle or describe handle.
nType

Specifies the type of the handle.

Valid types are:

  • OCI_HTYPE_STMT

  • OCI_DTYPE_PARAM

  • OCI_HTYPE_COMPLEXOBJECT
hParamDesc | Variable receiving the descriptor of the parameter at the given position, of handle type OCI_DTYPE_PARAM.
nPosition | Position number in the statement handle or describe handle.

Example

var
  ghEnv0        : number;
  ghError0      : number;
  ghStmt0       : number;
  ghSvcCtx0     : number;
  ghDescriptor0 : number;

dcltrans
  transaction TMain
  begin
    Ora8Init(ghEnv0, OCI_DEFAULT);
    Ora8HandleAlloc(ghEnv0, ghError0, OCI_HTYPE_ERROR);
    Ora8Logon(ghEnv0, ghSvcCtx0, "user", "password", "orclnet2");

    Ora8HandleAlloc(ghEnv0, ghStmt0, OCI_HTYPE_STMT);
    Ora8StmtPrepare(ghStmt0, sqlSelect, OCI_NTV_SYNTAX);
    Ora8StmtExecute(ghSvcCtx0, ghStmt0);

    Ora8ParamGet(ghStmt0, OCI_HTYPE_STMT, ghDescriptor0, 1);

    ...

    Ora8HandleFree(ghStmt0, OCI_HTYPE_STMT);
    Ora8Logoff(ghSvcCtx0);
    Ora8HandleFree(ghError0, OCI_HTYPE_ERROR);
    Ora8HandleFree(ghEnv0, OCI_HTYPE_ENV);
  end TMain;

dclsql
  sqlSelect:
    SELECT empno FROM emp;

See also

Oracle's Programmer's Guide to Oracle Call Interface for Wrapped Oracle function: OCIParamGet
Parent topic: Handle and Descriptor Functions
Related reference
Ora8HandleAlloc Function
Ora8HandleFree Function
Ora8DescriptorAlloc Function
Ora8DescriptorFree Function
Ora8AttrSetHandle Function
Ora8AttrSetString Function
Ora8AttrSetNumber Function
Ora8AttrSetBoolean Function
Ora8AttrGetHandle Function
Ora8AttrGetString Function
Ora8AttrGetNumber Function
Ora8AttrGetBoolean Function
Ora8ParamSet Function
Ora8Init Function


Ora8ParamSet Function

Action

Used to set a complex object retrieval (COR) descriptor into a COR handle.

Include file

Ora8.bdh

Syntax

Ora8ParamSet( in hHandle     : number,
              in nType       : number,
              in hParamDesc  : number,
              in nDescType   : number,
              in nPosition   : number ) : boolean;

Return value

  • true if successful

  • false otherwise

Parameter | Description
hHandle | Target handle.
nType | Specifies the type of the handle.
hParamDesc | Descriptor to be set.
nDescType | Specifies the type of the descriptor. The descriptor type for a COR descriptor is OCI_DTYPE_COMPLEXOBJECTCOMP.
nPosition | Position number.

Example

var
  ghEnv0        : number;
  ghError0      : number;
  ghSvcCtx0     : number;
  ghCOR         : number;
  ghDescriptor0 : number;

dcltrans
  transaction TMain
  const
    PUBLIC_KEY := "\h59b20094...";
  begin
    Ora8Init(ghEnv0, OCI_DEFAULT);
    Ora8HandleAlloc(ghEnv0, ghError0, OCI_HTYPE_ERROR);
    Ora8Logon(ghEnv0, ghSvcCtx0, "user", "password", "orclnet2");

    Ora8ParamSet(ghCOR, OCI_HTYPE_COMPLEXOBJECT, ghDescriptor0, OCI_DTYPE_COMPLEXOBJECTCOMP, 1);

    ...

    Ora8Logoff(ghSvcCtx0);
    Ora8HandleFree(ghError0, OCI_HTYPE_ERROR);
    Ora8HandleFree(ghEnv0, OCI_HTYPE_ENV);
  end TMain;

See also

Oracle's Programmer's Guide to Oracle Call Interface for Wrapped Oracle function: OCIParamSet
Parent topic: Handle and Descriptor Functions
Related reference
Ora8HandleAlloc Function
Ora8HandleFree Function
Ora8DescriptorAlloc Function
Ora8DescriptorFree Function
Ora8AttrSetHandle Function
Ora8AttrSetString Function
Ora8AttrSetNumber Function
Ora8AttrSetBoolean Function
Ora8AttrGetHandle Function
Ora8AttrGetString Function
Ora8AttrGetNumber Function
Ora8AttrGetBoolean Function
Ora8ParamGet Function
Ora8Init Function


Placeholder Binding Functions

  • Ora8Bind Function
    Binds a placeholder in a SQL statement or PL/SQL block to a program variable.
  • Ora8BindLob Function
    Binds a placeholder for a LOB parameter in a SQL statement or PL/SQL block to a program variable.
  • Ora8BindRefCur Function
    Binds a place holder in a SQL statement or PL/SQL block to a program variable.
Parent topic: Oracle 8 API Functions Overview


Ora8Bind Function

Action

Binds a placeholder in a SQL statement or PL/SQL block to a program variable. The variable is accessible through the Ora8Set and Ora8Get functions. The placeholder is identified by the name or the number declared in the SQL statement or PL/SQL block. The functions listed below are used to assign values to the program variable that is bound to the specified placeholder:

  • Ora8SetString
  • Ora8SetBinary
  • Ora8SetInt
  • Ora8SetFloat
  • Ora8SetNull

This function serves to bind placeholders in SQL statements or PL/SQL blocks to both scalar and array variables. In addition, it can be used to bind placeholders to be used in piecewise operations. The function must be called after preparing the SQL statement or PL/SQL block and before calling the Ora8Set function.

Include file

Ora8.bdh

Syntax

Ora8Bind( in  hStmt        : number,
          in  sSqlVar      : string,
          in  nDatatype    : number optional,
          in  nSize        : number optional,
          in  nArraySize   : number optional,
          in  nBindOption  : number optional,
          out hBindHandle  : number optional): boolean;

Return value

  • true if successful

  • false otherwise. In this case, you can use the Ora8OciError function to retrieve the Oracle OCI error code

Parameter | Description
hStmt | Statement handle.
sSqlVar | Name of the placeholder in the SQL statement or PL/SQL block. This parameter must include the preceding colon identifying it as a placeholder.
nDatatype

Oracle external data type of the program variable (optional). Oracle converts the program variable from external to internal format when the variable is sent to the database and vice versa when it is retrieved from the database. See Oracle 8 data types for a list of data types

The default data type is SQLT_STR (null-terminated string)
nSize

Size of the program variable or the array element in bytes (optional). Since this function needs to be called only once for many different values on successive Ora8StmtExecute function calls, this parameter must contain the maximum size of the element to bind.

This parameter should be omitted for data types of fixed length (SQLT_NUM, SQLT_INT, SQLT_FLT, SQLT_VNU, SQLT_RID, SQLT_DAT, SQLT_UIN, SQLT_CUR). If specified, the parameter is ignored and set to the fixed length of the data type.

This parameter should not be omitted for the following data types: SQLT_CHR, SQLT_LNG, SQLT_BIN, SQLT_LBI, SQLT_AFC, SQLT_AVC, SQLT_VCS, SQLT_LVC, SQLT_VBI, SQLT_LVB

When performing piecewise binding of the variable to the placeholder, this parameter specifies the piece size.
nArraySize

Maximum number of array elements to bind (optional).

The default option is scalar binding.

When performing piecewise binding of the variable to the placeholder, this parameter specifies the maximum column size.
nBindOption

Specifies how to bind the placeholder (optional). The following are the possible options for binding a placeholder:

  • ORA_DEFAULT. This is the default option. A placeholder is bound to a scalar or to an array program variable.

  • ORA_PIECEWISE. The program variable is bound to the placeholder in multiple pieces. In this case, nSize specifies the piece size, and nArraySize the maximum column size. You have to call the Ora8SetPieces function in order to set the values for the pieces.

  • ORA_PLSQLTABLE_IN. The program variable is bound to a PL/SQL table that is used as an in parameter within a stored procedure.

  • ORA_PLSQLTABLE_OUT. The program variable is bound to a PL/SQL table that is used as an out parameter in a stored procedure.

  • ORA_PLSQLTABLE_INOUT: The program variable is bound to a PL/SQL table that is used as an inout parameter in a stored procedure.

  • ORA_PLSQL_IN. The program variable is bound to a PL/SQL scalar parameter that is used as an in parameter within a stored procedure.

  • ORA_PLSQL_OUT. The program variable is bound to a PL/SQL scalar parameter that is used as an out parameter in a stored procedure.

  • ORA_PLSQL_INOUT. The program variable is bound to a PL/SQL scalar parameter that is used as an inout parameter in a stored procedure.
hBindHandle | Variable receiving the bind handle (optional).

A placeholder in a SQL statement consists of a colon (:) followed by a SQL identifier. The placeholder is not a test script variable. For example, the following SQL statement contains two placeholders, :min_age and :max_age.

SELECT name, age
FROM persons
WHERE age >= :min_age AND age <= :max_age;

It is also possible to define placeholders that consist of a colon followed by a literal integer between 1 and 255.

The following SQL statement contains two placeholders, :1 and :2.

SELECT name, age
FROM persons
WHERE age >= :1 AND age <= :2;

Example: scalar binding

var
  ghEnv0        : number;
  ghError0      : number;
  ghStmt0       : number;
  ghSvcCtx0     : number;

dcltrans
  transaction TMain
  var
    nAge : number;
    sName : string;
  begin
    Ora8Init(ghEnv0, OCI_DEFAULT);
    Ora8HandleAlloc(ghEnv0, ghError0, OCI_HTYPE_ERROR);
    Ora8Logon(ghEnv0, ghSvcCtx0, "user", "password", "orclnet2");

    Ora8HandleAlloc(ghEnv0, ghStmt0, OCI_HTYPE_STMT);
    Ora8StmtPrepare(ghStmt0, sqlSelect, OCI_NTV_SYNTAX);

    Ora8Bind(ghStmt0, ":1", SQLT_INT);
    Ora8SetInt(ghStmt0, ":1", 25);
    Ora8Define(ghStmt0, 1, SQLT_CHR, 32);
    Ora8Define(ghStmt0, 2, SQLT_INT);
    Ora8StmtExecute(ghSvcCtx0, ghStmt0);
    while Ora8StmtFetch(ghStmt0, 1, 1) do
      sName := Ora8GetString(ghStmt0, "1");
      nAge  := Ora8GetInt(ghStmt0, "2");
      write(sName, 32); write(nAge, 5); writeln;
    end;

    Ora8HandleFree(ghStmt0, OCI_HTYPE_STMT);
    Ora8Logoff(ghSvcCtx0);
    Ora8HandleFree(ghError0, OCI_HTYPE_ERROR);
    Ora8HandleFree(ghEnv0, OCI_HTYPE_ENV);
  end TMain;

dclsql
  sqlSelect:
    SELECT * FROM persons WHERE age > :1;

Output

Howard 33Michael 44Bobby 61Sara 38

Example: array binding

var
  ghEnv0        : number;
  ghError0      : number;
  ghStmt0       : number;
  ghSvcCtx0     : number;

dcltrans
  transaction TMain
  begin
    Ora8Init(ghEnv0, OCI_DEFAULT);
    Ora8HandleAlloc(ghEnv0, ghError0, OCI_HTYPE_ERROR);
    Ora8Logon(ghEnv0, ghSvcCtx0, "user", "password", "orclnet2");

    Ora8HandleAlloc(ghEnv0, ghStmt0, OCI_HTYPE_STMT);
    Ora8StmtPrepare(ghStmt0, sqlInsert, OCI_NTV_SYNTAX);

    // bind array containing two elements
    Ora8Bind(ghStmt0, ":name", SQLT_CHR, 32, 2);
    Ora8Bind(ghStmt0, ":age", SQLT_INT, 0, 2);
    // set values
    Ora8SetString(ghStmt0, ":name", "Bob", 1);
    Ora8SetInt(ghStmt0, ":age", 25, 1);
    Ora8SetString(ghStmt0, ":name", "Marcy", 2);
    Ora8SetInt(ghStmt0, ":age", 33, 2);
    Ora8StmtExecute(ghSvcCtx0, ghStmt0, 2);

    Ora8HandleFree(ghStmt0, OCI_HTYPE_STMT);
    Ora8Logoff(ghSvcCtx0);
    Ora8HandleFree(ghError0, OCI_HTYPE_ERROR);
    Ora8HandleFree(ghEnv0, OCI_HTYPE_ENV);
  end TMain;

dclsql
  sqlInsert:
    INSERT INTO persons (name, age) VALUES (:name, :age);

Example: PL/SQL table binding

var
  ghEnv0        : number;
  ghError0      : number;
  ghStmt0       : number;
  ghSvcCtx0     : number;

dcltrans
  transaction TMain
  begin
    Ora8Init(ghEnv0, OCI_DEFAULT);
    Ora8HandleAlloc(ghEnv0, ghError0, OCI_HTYPE_ERROR);
    Ora8Logon(ghEnv0, ghSvcCtx0, "user", "password", "orclnet2");

    Ora8HandleAlloc(ghEnv0, ghStmt0, OCI_HTYPE_STMT);
    Ora8StmtPrepare(ghStmt0, sqlProcedureWithPLSQLTable, OCI_NTV_SYNTAX);

    Ora8Bind(ghStmt0, ":num", SQLT_INT);
    Ora8Bind(ghStmt0, ":description", SQLT_STR, 20, 3, ORA_PLSQLTABLE_INOUT);
    Ora8SetInt(ghStmt0, ":num", 5);
    Ora8SetString(ghStmt0, ":description", "Frammis_1", 1);
    Ora8SetString(ghStmt0, ":description", "Frammis_2", 2);
    Ora8SetString(ghStmt0, ":description", "Frammis_3", 3);
    Ora8StmtExecute(ghSvcCtx0, ghStmt0);

    Ora8HandleFree(ghStmt0, OCI_HTYPE_STMT);
    Ora8Logoff(ghSvcCtx0);
    Ora8HandleFree(ghError0, OCI_HTYPE_ERROR);
    Ora8HandleFree(ghEnv0, OCI_HTYPE_ENV);
  end TMain;

dclsql
  sqlProcedureWithPLSQLTable:
  [BEGIN
    update_parts.add_parts(:num, :description);
  END;]

In this example, the parameter nBindOption specifies the option for binding the placeholder. ORA_PLSQLTABLE_INOUT binds a PL/SQL table used as a parameter in a stored procedure with inout direction. The maximum length of a bind element is set to 20, the maximum number of array elements that can be sent/retrieved is set to 3.

See also

Oracle's Programmer's Guide to Oracle Call Interface for Wrapped Oracle functions: OCIBindByName, OCIBindByPos
Parent topic: Placeholder Binding Functions
Related reference
Ora8BindLob Function
Ora8BindRefCur Function
Ora8SetString Function
Ora8SetBinary Function
Ora8SetInt Function
Ora8SetFloat Function
Ora8SetNull Function
Ora8OciError Function
Ora8StmtExecute Function
Ora8SetPieces Function
Oracle 8 Data Types


Ora8BindLob Function

Action

Binds a placeholder for a LOB parameter in a SQL statement or PL/SQL block to a program variable.

Include file

Ora8.bdh

Syntax

Ora8BindLob( in  hStmt        : number,
             in  sSqlVar      : string,
             in  nDatatype    : number,
             in  nSize        : number,
             in  nArraySize   : number,
             in  nBindOption  : number,
             out hDescriptor  : number ): boolean;

Return value

  • true if successful

  • false otherwise

Parameter | Description
hStmt | Statement handle.
sSqlVar | Name of the place holder in the SQL statement or PL/SQL block. This parameter must include the preceding colon identifying it as a place holder.
nDatatype | Oracle external data type of the program variable. Oracle converts the program variable from external to internal format when the variable is sent to the database and vice versa when it is retrieved from the database. See Oracle 8 data types for a list of data types.
nSize | Size of the program variable or the array element in bytes.
nArraySize

Maximum number of array elements to bind.

The default option is scalar binding.
nBindOption

Specifies how to bind the place holder. The following are the possible options for binding a place holder:

  • ORA_DEFAULT. This is the default option. A place holder is bound to a scalar or to an array program variable.

  • ORA_PIECEWISE. The program variable is bound to the place holder in multiple pieces. In this case, nSize specifies the piece size, and nArraySize the maximum column size. You have to call the Ora8SetPieces function in order to set the values for the pieces.

  • ORA_PLSQLTABLE_IN. The program variable is bound to a PL/SQL table that is used as an in parameter within a stored procedure.

  • ORA_PLSQLTABLE_OUT. The program variable is bound to a PL/SQL table that is used as an out parameter in a stored procedure.

  • ORA_PLSQLTABLE_INOUT: The program variable is bound to a PL/SQL table that is used as an inout parameter in a stored procedure.

  • ORA_PLSQL_IN. The program variable is bound to a PL/SQL scalar parameter that is used as an in parameter within a stored procedure.

  • ORA_PLSQL_OUT. The program variable is bound to a PL/SQL scalar parameter that is used as an out parameter in a stored procedure.

  • ORA_PLSQL_INOUT. The program variable is bound to a PL/SQL scalar parameter that is used as an inout parameter in a stored procedure.
hDescriptor | Variable that is bound to the placeholder in the SQL statement or PL/SQL block.

Example

var
  ghEnv0        : number;
  ghError0      : number;
  ghStmt0       : number;
  ghSvcCtx0     : number;
  ghDescriptor0 : number;

dcltrans
  transaction TMain
  begin
    Ora8Init(ghEnv0, OCI_DEFAULT);
    Ora8HandleAlloc(ghEnv0, ghError0, OCI_HTYPE_ERROR);
    Ora8Logon(ghEnv0, ghSvcCtx0, "user", "password", "orclnet2");

    Ora8HandleAlloc(ghEnv0, ghStmt0, OCI_HTYPE_STMT);
    Ora8StmtPrepare(ghStmt0, TMain_SQL001, OCI_NTV_SYNTAX);
    Ora8DescriptorAlloc(ghEnv0, ghDescriptor0, OCI_DTYPE_LOB);

    Ora8Bind(ghStmt0, "1", SQLT_INT, 0, 1, ORA_PLSQL_IN);                     //p_productid, in, number
    Ora8BindLob(ghStmt0, "2", SQLT_BLOB, 4, 1, ORA_PLSQL_OUT, ghDescriptor0); //p_productimage, out, blob

    Ora8SetInt(ghStmt0, "1", 2254);  //p_productid

    Ora8StmtExecute(ghSvcCtx0, ghStmt0, 1, 0, 0, 0, OCI_COMMIT_ON_SUCCESS);

    Ora8LobRead(ghSvcCtx0, ghDescriptor0, 9894, 9894, 1, 178);

    Ora8HandleFree(ghStmt0, OCI_HTYPE_STMT);
    Ora8Logoff(ghSvcCtx0);
    Ora8HandleFree(ghError0, OCI_HTYPE_ERROR);
    Ora8HandleFree(ghEnv0, OCI_HTYPE_ENV);
  end TMain;

dclsql
  TMain_SQL001:
    [BEGIN getproductimage(:1,:2); END;]

See also

Oracle's Programmer's Guide to Oracle Call Interface for Wrapped Oracle functions: OCIBindByName, OCIBindByPos
Parent topic: Placeholder Binding Functions
Related reference
Ora8Bind Function
Ora8BindRefCur Function
Ora8SetPieces Function
Oracle 8 Data Types
Ora8DefineLob Function
Ora8Define Function


Ora8BindRefCur Function

Action

Binds a place holder in a SQL statement or PL/SQL block to a program variable. The variable is accessible through the Ora8Set and Ora8Get functions. The place holder is identified by the name or the number declared in the SQL statement or PL/SQL block. The functions listed below are used to assign values to the program variable that is bound to the specified place holder:

  • Ora8SetString
  • Ora8SetBinary
  • Ora8SetInt
  • Ora8SetFloat
  • Ora8SetNull

This function serves to bind place holders in SQL statements or PL/SQL blocks to both scalar and array variables. In addition, it can be used to bind place holders to be used in piecewise operations. The function must be called after preparing the SQL statement or PL/SQL block and before calling the Ora8Set function.

Include file

Ora8.bdh

Syntax

Ora8BindRefCur( in  hStmt        : number,
                in  sSqlVar      : string,
                in  hStmtRefCur  : number): boolean;

Return value

  • true if successful

  • false otherwise. In this case, you can use the Ora8OciError function to retrieve the Oracle OCI error code

Parameter | Description
hStmt | Statement handle.
sSqlVar | Name of the place holder in the SQL statement or PL/SQL block. This parameter must include the preceding colon identifying it as a place holder.
hStmtRefCur | REF CURSOR statement handle.

See also

Oracle's Programmer's Guide to Oracle Call Interface for Wrapped Oracle functions: OCIBindByName, OCIBindByPos
Parent topic: Placeholder Binding Functions
Related reference
Ora8Bind Function
Ora8BindLob Function
Ora8SetString Function
Ora8SetBinary Function
Ora8SetInt Function
Ora8SetFloat Function
Ora8SetNull Function
Ora8OciError Function
Oracle 8 Data Types


Parameter Binding Functions

  • Ora8SetBinary Function
    Assigns binary data to the program variable that is bound to the specified place holder in the SQL statement or PL/SQL block.
  • Ora8SetInt Function
    Assigns a number value to the program variable that is bound to the specified place holder in the SQL statement or PL/SQL block.
  • Ora8SetFloat Function
    Assigns a floating-point value to the program variable that is bound to the specified place holder in the SQL statement or PL/SQL block.
  • Ora8SetPieces Function
    Assigns any data to the program variable that is bound to the specified place holder in the SQL statement for a piecewise INSERT or UPDATE operation.
  • Ora8SetNull Function
    Assigns a NULL value to the program variable that is bound to the specified place holder in the SQL statement or PL/SQL block.
  • Ora8SetString Function
    Assigns a string to the program variable that is bound to the specified place holder in the SQL statement or PL/SQL block.
Parent topic: Oracle 8 API Functions Overview


Ora8SetBinary Function

Action

Assigns binary data to the program variable that is bound to the specified place holder in the SQL statement or PL/SQL block. The place holder is identified by the name or the number specified in the SQL statement or PL/SQL block. This function is used to assign values to both scalar and array program variables.

Using this function, any data type listed below can be assigned to the program variable that is bound to the specified place holder:

  • SQLT_NUM
  • SQLT_VNU
  • SQLT_RID
  • SQLT_DAT
  • SQLT_VBI
  • SQLT_BIN
  • SQLT_LBI
  • SQLT_LVB
  • SQLT_CUR

Include file

Ora8.bdh

Syntax

Ora8SetBinary( in hStmt   : number,
               in sSqlVar : string,
               in sBinary : string,
               in nLength : number,
               in nIndex  : number optional): boolean;

Return value

  • true if successful

  • false otherwise; In this case, you can use the Ora8OciError function to retrieve the Oracle OCI error code.

Parameter | Description
hStmt | Statement handle.
sSqlVar | Name of the place holder in the SQL statement or PL/SQL block. This parameter must include the preceding colon identifying it as a place holder.
sBinary | Binary data that is assigned to the program variable that is bound to the specified place holder in the SQL statement or PL/SQL block.
nLength | Length of the binary data block (in bytes).
nIndex | Array index (optional). For array binding operations, this parameter specifies the array index of the program variable.

Example

var
  ghEnv0        : number;
  ghError0      : number;
  ghStmt0       : number;
  ghSvcCtx0     : number;

dcltrans
  transaction TMain
  const
    PUBLIC_KEY := "\h59b20094...";
  begin
    Ora8Init(ghEnv0, OCI_DEFAULT);
    Ora8HandleAlloc(ghEnv0, ghError0, OCI_HTYPE_ERROR);
    Ora8Logon(ghEnv0, ghSvcCtx0, "user", "password", "orclnet2");

    Ora8HandleAlloc(ghEnv0, ghStmt0, OCI_HTYPE_STMT);
    Ora8StmtPrepare(ghStmt0, sqlInsert, OCI_NTV_SYNTAX);

    Ora8Bind(ghStmt0, ":name", SQLT_CHR, 32);
    Ora8Bind(ghStmt0, ":key", SQLT_BIN, 64);

    Ora8SetString(ghStmt0, ":name", "Michael");
    Ora8SetBinary(ghStmt0, ":key",  PUBLIC_KEY, 0);

    Ora8StmtExecute(ghSvcCtx0, ghStmt0);

    Ora8HandleFree(ghStmt0, OCI_HTYPE_STMT);
    Ora8Logoff(ghSvcCtx0);
    Ora8HandleFree(ghError0, OCI_HTYPE_ERROR);
    Ora8HandleFree(ghEnv0, OCI_HTYPE_ENV);
  end TMain;

dclsql
  sqlInsert:
    INSERT INTO keys (name, key) VALUES (:name, :key);
Parent topic: Parameter Binding Functions
Related reference
Ora8SetInt Function
Ora8SetFloat Function
Ora8SetPieces Function
Ora8SetNull Function
Ora8SetString Function
Ora8OciError Function
Ora8Bind Function


Ora8SetInt Function

Action

Assigns a number value to the program variable that is bound to the specified place holder in the SQL statement or PL/SQL block. The place holder is identified by the name or the number specified in the SQL statement or PL/SQL block. This function is used to assign values to both scalar and array program variables.

Include file

Ora8.bdh

Syntax

Ora8SetInt( in hStmt   : number,
            in sSqlVar : string,
            in nValue  : number,
            in nIndex  : number optional): boolean;

Return value

  • true if successful

  • false otherwise. In this case, you can use the Ora8OciError function to retrieve the Oracle OCI error code

Parameter | Description
hStmt | Statement handle.
sSqlVar | Name of the place holder in the SQL statement or PL/SQL block. This parameter must include the preceding colon identifying it as a place holder.
nValue | Number value that is assigned to the program variable that is bound to the specified place holder in the SQL statement or PL/SQL block.
nIndex | Array index (optional). For array binding operations, this parameter specifies the array index of the program variable.

Example

var
  ghEnv0        : number;
  ghError0      : number;
  ghStmt0       : number;
  ghSvcCtx0     : number;

dcltrans
  transaction TMain
  var
    sName : string;
    nAge  : number;
  begin
    Ora8Init(ghEnv0, OCI_DEFAULT);
    Ora8HandleAlloc(ghEnv0, ghError0, OCI_HTYPE_ERROR);
    Ora8Logon(ghEnv0, ghSvcCtx0, "user", "password", "orclnet2");

    Ora8HandleAlloc(ghEnv0, ghStmt0, OCI_HTYPE_STMT);
    Ora8StmtPrepare(ghStmt0, sqlSelect, OCI_NTV_SYNTAX);

    Ora8Bind(ghStmt0, ":1", SQLT_INT);

    Ora8SetInt(ghStmt0, ":1", 25);
    Ora8Define(ghStmt0, 1, SQLT_CHR, 32);
    Ora8Define(ghStmt0, 2, SQLT_INT);
    Ora8StmtExecute(ghSvcCtx0, ghStmt0);

    while Ora8StmtFetch(ghStmt0, 1, 1) do
      sName := Ora8GetString(ghStmt0, "1");
      nAge := Ora8GetInt(ghStmt0, "2");
      write(sName, 32); write(nAge, 5); writeln;
    end;

    Ora8HandleFree(ghStmt0, OCI_HTYPE_STMT);
    Ora8Logoff(ghSvcCtx0);
    Ora8HandleFree(ghError0, OCI_HTYPE_ERROR);
    Ora8HandleFree(ghEnv0, OCI_HTYPE_ENV);
  end TMain;

dclsql
  sqlSelect:
    SELECT * FROM persons WHERE age > :1;

Output

Howard 33Michael 44Bobby 61Sara 38
Parent topic: Parameter Binding Functions
Related reference
Ora8SetBinary Function
Ora8SetFloat Function
Ora8SetPieces Function
Ora8SetNull Function
Ora8SetString Function
Ora8OciError Function
Ora8Bind Function


Ora8SetFloat Function

Action

Assigns a floating-point value to the program variable that is bound to the specified place holder in the SQL statement or PL/SQL block. The place holder is identified by the name or the number specified in the SQL statement or PL/SQL block. This function is used to assign values to both scalar and array program variables.

Include file

Ora8.bdh

Syntax

Ora8SetFloat( in hStmt   : number,
              in sSqlVar : string,
              in fValue  : float,
              in nIndex  : number optional ): boolean;

Return value

  • true if successful

  • false otherwise; In this case, you can use the Ora8OciError function to retrieve the Oracle OCI error code.

Parameter | Description
hStmt | Statement handle.
sSqlVar | Name of the place holder in the SQL statement or PL/SQL block. This parameter must include the preceding colon identifying it as a place holder.
fValue | Float value that is assigned to the program variable that is bound to the specified place holder in the SQL statement or PL/SQL block.
nIndex | Array index (optional). For array binding operations, this parameter specifies the array index of the program variable.

Example

var
  ghEnv0        : number;
  ghError0      : number;
  ghStmt0       : number;
  ghSvcCtx0     : number;

dcltrans
  transaction TMain
  var
    sName    : string;
    fBalance : float;
  begin
    Ora8Init(ghEnv0, OCI_DEFAULT);
    Ora8HandleAlloc(ghEnv0, ghError0, OCI_HTYPE_ERROR);
    Ora8Logon(ghEnv0, ghSvcCtx0, "user", "password", "orclnet2");

    Ora8HandleAlloc(ghEnv0, ghStmt0, OCI_HTYPE_STMT);
    Ora8StmtPrepare(ghStmt0, sqlSelect, OCI_NTV_SYNTAX);

    Ora8Bind(ghStmt0, ":1", SQLT_FLT);

    Ora8SetFloat(ghStmt0, ":1", 2000.0);
    Ora8Define(ghStmt0, 1, SQLT_CHR, 32);
    Ora8Define(ghStmt0, 2, SQLT_FLT);
    Ora8StmtExecute(ghSvcCtx0, ghStmt0);

     while Ora8StmtFetch(ghStmt0, 1, 1) do
      sName    := Ora8GetString(ghStmt0, "1");
      fBalance := Ora8GetFloat(ghStmt0, "2");
      write(sName, 32); write(fBalance); writeln;
    end;

    Ora8HandleFree(ghStmt0, OCI_HTYPE_STMT);
    Ora8Logoff(ghSvcCtx0);
    Ora8HandleFree(ghError0, OCI_HTYPE_ERROR);
    Ora8HandleFree(ghEnv0, OCI_HTYPE_ENV);
  end TMain;

dclsql
  sqlSelect:
    SELECT * FROM accounts WHERE balance > :1;

Output

Bob 13864.220000Pamela 4492.090000Richard 7309.580000
Parent topic: Parameter Binding Functions
Related reference
Ora8SetBinary Function
Ora8SetInt Function
Ora8SetPieces Function
Ora8SetNull Function
Ora8SetString Function
Ora8OciError Function
Ora8Bind Function


Ora8SetPieces Function

Action

Assigns any data to the program variable that is bound to the specified place holder in the SQL statement for a piecewise INSERT or UPDATE operation. The place holder is identified by the name or the number specified in the SQL statement.

Include file

Ora8.bdh

Syntax

Ora8SetPieces( in hStmt       : number,
               in sSqlVar     : string,
               in sFilename   : string,
               in nCharacters : number optional,
               in nFirstChar  : number optional,
               in nLastChar   : number optional): boolean;

Return value

  • true if successful

  • false otherwise. In this case, you can use the Ora8OciError function to retrieve the Oracle OCI error code

Parameter | Description
hStmt | Statement handle.
sSqlVar | Name of the place holder in the SQL statement or PL/SQL block. This parameter must include the preceding colon identifying it as a place holder.
sFilename | Name of the file containing the data. If this parameter is set to NULL, random values are generated. In this case, you must specify the amount of random data to generate. The nFirstChar and the nLastChar parameters let you specify a set of characters used for random data generation.
nCharacters | Number of random characters to generate (optional). This parameter has to be passed to the function only if sFilename is set to NULL.
nFirstChar | First character belonging to the character set used for random data generation (optional). The default option is to use all characters defined in the ASCII table.
nLastChar | Last character belonging to the character set used for random data generation (optional). The default option is to use all characters defined in the ASCII table.

Example

var
  ghEnv0        : number;
  ghError0      : number;
  ghStmt0       : number;
  ghSvcCtx0     : number;

dcltrans
  transaction TMain
  const
    PUBLIC_KEY := "\h59b20094...";
  begin
    Ora8Init(ghEnv0, OCI_DEFAULT);
    Ora8HandleAlloc(ghEnv0, ghError0, OCI_HTYPE_ERROR);
    Ora8Logon(ghEnv0, ghSvcCtx0, "user", "password", "orclnet2");

    Ora8HandleAlloc(ghEnv0, ghStmt0, OCI_HTYPE_STMT);
    Ora8StmtPrepare(ghStmt0, sqlInsert, OCI_NTV_SYNTAX);

    Ora8Bind(ghStmt0, ":name", SQLT_CHR, 32);
    Ora8Bind(ghStmt0, ":key", SQLT_BIN, 64);

    Ora8SetString(ghStmt0, ":name", "Michael");
    Ora8SetPieces(ghStmt0, ":data", "TestData.dat");

    Ora8StmtExecute(ghSvcCtx0, ghStmt0);

    Ora8HandleFree(ghStmt0, OCI_HTYPE_STMT);
    Ora8Logoff(ghSvcCtx0);
    Ora8HandleFree(ghError0, OCI_HTYPE_ERROR);
    Ora8HandleFree(ghEnv0, OCI_HTYPE_ENV);
  end TMain;

dclsql
  sqlInsert:
    INSERT INTO images (name, data) VALUES (:name, :data);
Parent topic: Parameter Binding Functions
Related reference
Ora8SetBinary Function
Ora8SetInt Function
Ora8SetFloat Function
Ora8SetNull Function
Ora8SetString Function
Ora8OciError Function
Ora8Bind Function


Ora8SetNull Function

Action

Assigns a NULL value to the program variable that is bound to the specified place holder in the SQL statement or PL/SQL block. The place holder is identified by the name or the number specified in the SQL statement or PL/SQL block. This function is used to assign values to both scalar and array program variables.

Include file

Ora8.bdh

Syntax

Ora8SetNull( in hStmt   : number,
             in sSqlVar : string,
             in nIndex  : number optional): boolean;

Return value

  • true if successful

  • false otherwise. In this case, you can use the Ora8OciError function to retrieve the Oracle OCI error code

Parameter | Description
hStmt | Statement handle.
sSqlVar | Name of the place holder in the SQL statement or PL/SQL block. This parameter must include the preceding colon identifying it as a place holder.
nIndex | Array index (optional). For array binding operations, this parameter specifies the array index of the program variable.

Example

var
  ghEnv0        : number;
  ghError0      : number;
  ghStmt0       : number;
  ghSvcCtx0     : number;

dcltrans
  transaction TMain
  begin
    Ora8Init(ghEnv0, OCI_DEFAULT);
    Ora8HandleAlloc(ghEnv0, ghError0, OCI_HTYPE_ERROR);
    Ora8Logon(ghEnv0, ghSvcCtx0, "user", "password", "orclnet2");
        Ora8HandleAlloc(ghEnv0, ghStmt0, OCI_HTYPE_STMT);
        Ora8StmtPrepare(ghStmt0, sqlInsert, OCI_NTV_SYNTAX);
     Ora8Bind(ghStmt0, ":name", SQLT_CHR, 32);
    Ora8Bind(ghStmt0, ":key", SQLT_BIN, 64);
        Ora8SetString(ghStmt0, ":name", "Michael");
    Ora8SetNull(ghStmt0, ":age");
        Ora8StmtExecute(ghSvcCtx0, ghStmt0);

    Ora8HandleFree(ghStmt0, OCI_HTYPE_STMT);
    Ora8Logoff(ghSvcCtx0);
    Ora8HandleFree(ghError0, OCI_HTYPE_ERROR);
    Ora8HandleFree(ghEnv0, OCI_HTYPE_ENV);
  end TMain;

dclsql
  sqlInsert:
    INSERT INTO persons (name, age) VALUES (:name, :age);
Parent topic: Parameter Binding Functions
Related reference
Ora8SetBinary Function
Ora8SetInt Function
Ora8SetFloat Function
Ora8SetPieces Function
Ora8SetString Function
Ora8OciError Function
Ora8Bind Function


Ora8SetString Function

Action

Assigns a string to the program variable that is bound to the specified place holder in the SQL statement or PL/SQL block. The place holder is identified by the name or the number specified in the SQL statement or PL/SQL block. This function is used to assign values to both scalar and array program variables.

Using this function, any of the following data types can be assigned to the program variable that is bound to the specified place holder:

  • SQLT_STR
  • SQLT_CHR
  • SQLT_VCS
  • SQLT_LVC
  • SQLT_AFC
  • SQLT_AVC
  • SQLT_LNG
  • SQLT_RDD

Include file

Ora8.bdh

Syntax

Ora8SetString( in hStmt   : number,
               in sSqlVar : string,
               in sString : string,
               in nIndex  : number optional): boolean;

Return value

  • true if successful

  • false otherwise. In this case, you can use the Ora8OciError function to retrieve the Oracle OCI error code

Parameter | Description
hStmt | Statement handle.
sSqlVar | Name of the place holder in the SQL statement or PL/SQL block. This parameter must include the preceding colon identifying it as a place holder.
sString | String that is assigned to the program variable that is bound to the specified place holder in the SQL statement or PL/SQL block.
nIndex | Array index (optional). For array binding operations, this parameter specifies the array index of the program variable.

Example

var
  ghEnv0        : number;
  ghError0      : number;
  ghStmt0       : number;
  ghSvcCtx0     : number;

dcltrans
  transaction TMain
  begin
    Ora8Init(ghEnv0, OCI_DEFAULT);
    Ora8HandleAlloc(ghEnv0, ghError0, OCI_HTYPE_ERROR);
    Ora8Logon(ghEnv0, ghSvcCtx0, "user", "password", "orclnet2");

    Ora8HandleAlloc(ghEnv0, ghStmt0, OCI_HTYPE_STMT);
    Ora8StmtPrepare(ghStmt0, sqlInsert, OCI_NTV_SYNTAX);

    // bind array containing two elements
    Ora8Bind(ghStmt0, ":name", SQLT_CHR, 32, 2);
    Ora8Bind(ghStmt0, ":age", SQLT_INT, 0, 2);

    // set values
    Ora8SetString(ghStmt0, ":name", "Bob", 1);
    Ora8SetInt(ghStmt0, ":age", 25, 1);

    Ora8SetString(ghStmt0, ":name", "Marcy", 2);
    Ora8SetInt(ghStmt0, ":age", 33, 2);

    Ora8StmtExecute(ghSvcCtx0, ghStmt0);

    Ora8HandleFree(ghStmt0, OCI_HTYPE_STMT);
    Ora8Logoff(ghSvcCtx0);
    Ora8HandleFree(ghError0, OCI_HTYPE_ERROR);
    Ora8HandleFree(ghEnv0, OCI_HTYPE_ENV);
  end TMain;

dclsql
  sqlInsert:
    INSERT INTO persons (name, age) VALUES (:name, :age);
Parent topic: Parameter Binding Functions
Related reference
Ora8SetBinary Function
Ora8SetInt Function
Ora8SetFloat Function
Ora8SetPieces Function
Ora8SetNull Function
Ora8OciError Function
Ora8Bind Function


Result Set Definition Functions

  • Ora8Define Function
    Defines an output variable for a specified select-list item in a SQL query.
  • Ora8DefineLob Function
    Defines the specified LOB descriptor as output variable for the specified select-list item in the SQL query.
Parent topic: Oracle 8 API Functions Overview


Ora8Define Function

Action

Defines an output variable for a specified select-list item in a SQL query. In a BDL script, it is necessary to call this function for each select-list item of a SQL query. After the Ora8StmtExecute function (and Ora8StmtFetch function) has been called, the following functions can be used to retrieve the value of the program variable that is defined for the specified select-list item:

  • Ora8GetString
  • Ora8GetInt
  • Ora8GetFloat
  • Ora8GetValue

Include file

Ora8.bdh

Syntax

Ora8Define( in  hStmt          : number,
            in  nPosition      : number,
            in  nDatatype      : number optional,
            in  nSize          : number optional,
            in  nMaxColSize    : number optional,
            in  nDefineType    : number optional,
            in  nPieces        : number optional,
            out hDefineHandle  : number optional ): boolean;

Return value

  • true if successful

  • false otherwise; In this case, you can use the Ora8ApiError function to retrieve the Oracle OCI error code.

Parameter | Description
hStmt | Statement handle.
nPosition | Index of the select-list item in the SQL query. Position indices start at 1 for the first (leftmost) select-list item.
nDatatype

Oracle external data type of the select-list item (optional). See Oracle 8 data types for a list of Oracle data types.

The default value is SQLT_STR (null-terminated string).

nSize

Length of the select-list item in bytes (optional).

This parameter should be omitted or set to 0 for data types of fixed length (SQLT_NUM, SQLT_INT, SQLT_FLT, SQLT_VNU, SQLT_RID, SQLT_DAT, SQLT_UIN, SQLT_CUR).

nMaxColSize | Maximum possible size of the select-list item in bytes (optional). This parameter has to be specified whenever the select-list item is retrieved in multiple pieces.
nDefineType

Special select-list option (optional). Possible options are:

  • ORA_PIECEWISE

  • ORA_FETCHLONG

nPieces | Number of pieces (optional). Whenever nDefineType is set to ORA_FETCHLONG, this parameter can be used to specify the number of pieces.
hDefineHandle | Variable receiving the define handle (optional).

Example

var
  ghEnv0        : number;
  ghError0      : number;
  ghStmt0       : number;
  ghSvcCtx0     : number;

dcltrans
  transaction TMain
  var
    sName             : string;
    nFetched, nAge, i : number;
  begin
    Ora8Init(ghEnv0, OCI_DEFAULT);
    Ora8HandleAlloc(ghEnv0, ghError0, OCI_HTYPE_ERROR);
    Ora8Logon(ghEnv0, ghSvcCtx0, "user", "password", "orclnet2");

    Ora8HandleAlloc(ghEnv0, ghStmt0, OCI_HTYPE_STMT);
    Ora8StmtPrepare(ghStmt0, sqlSelect, OCI_NTV_SYNTAX);

    Ora8Define(ghStmt0, 1, SQLT_CHR, 32);
    Ora8Define(ghStmt0, 2, SQLT_INT);
    Ora8StmtExecute(ghSvcCtx0, ghStmt0, 1, 50, 0, 0, 0, nFetched);
    for i := 1 to nFetched do
      sName := Ora8GetString(ghStmt0, "1", i);
      nAge  := Ora8GetInt(ghStmt0, "2", i);
      write(sName, 32); write(nAge, 5); writeln;
    end;

    Ora8HandleFree(ghStmt0, OCI_HTYPE_STMT);
    Ora8Logoff(ghSvcCtx0);
    Ora8HandleFree(ghError0, OCI_HTYPE_ERROR);
    Ora8HandleFree(ghEnv0, OCI_HTYPE_ENV);
  end TMain;

dclsql
  sqlSelect:
    SELECT * FROM persons;

Output

Howard 33Michael 44Bobby 61Sara 38

See also

Oracle's Programmer's Guide to Oracle Call Interface for Wrapped Oracle function: OCIDefineByPos
Parent topic: Result Set Definition Functions
Related reference
Ora8DefineLob Function
Ora8GetInt Function
Ora8GetString Function
Ora8GetFloat Function
Ora8GetValue Function
Ora8StmtExecute Function
Ora8StmtFetch Function
Oracle 8 Data Types


Ora8DefineLob Function

Action

Defines the specified LOB descriptor as output variable for the specified select-list item in the SQL query.

Include file

Ora8.bdh

Syntax

Ora8DefineLob( in  hStmt       : number,
               in  nPosition   : number,
               in  nDatatype   : number,
               in  nSize       : number,
               in  hDescriptor : number ): boolean;

Return value

  • true if successful

  • false otherwise

Parameter | Description
hStmt | Statement handle.
nPosition | Index of the select-list item in the SQL query. Position indices start at 1 for the first (leftmost) select-list item.
nDatatype | Oracle external data type of the select-list item. See Oracle 8 data types for a list of Oracle data types.
nSize | Length of the select-list item in bytes.
hDescriptor | Variable used as output buffer for the specified select-list item.

Example

var
  ghEnv0        : number;
  ghError0      : number;
  ghStmt0       : number;
  ghSvcCtx0     : number;
  ghDescriptor0 : number;

dcltrans
  transaction TMain
  begin
    Ora8Init(ghEnv0, OCI_DEFAULT);
    Ora8HandleAlloc(ghEnv0, ghError0, OCI_HTYPE_ERROR);
    Ora8Logon(ghEnv0, ghSvcCtx0, "user", "password", "orclnet2");

    Ora8HandleAlloc(ghEnv0, ghStmt0, OCI_HTYPE_STMT);
    Ora8StmtPrepare(ghStmt0, sqlSelect, OCI_NTV_SYNTAX);
    Ora8DescriptorAlloc(ghEnv0, ghDescriptor0, OCI_DTYPE_LOB);
    Ora8DefineLob(ghStmt0, 1, SQLT_BLOB, 0, ghDescriptor0);
    Ora8StmtExecute(ghSvcCtx0, ghStmt0, 0, 1); // rows fetched: 1

    Ora8HandleFree(ghStmt0, OCI_HTYPE_STMT);
    Ora8Logoff(ghSvcCtx0);
    Ora8HandleFree(ghError0, OCI_HTYPE_ERROR);
    Ora8HandleFree(ghEnv0, OCI_HTYPE_ENV);
  end TMain;

dclsql
  sqlSelect:
    SELECT PRODUCT_IMAGE FROM PRODUCT_INFORMATION WHERE ROWID = 'AAAeUrAASAAABFUAAQ';

See also

Oracle's Programmer's Guide to Oracle Call Interface for Wrapped Oracle functions: OCIDefineByPos
Parent topic: Result Set Definition Functions
Related reference
Ora8Define Function
Oracle 8 Data Types
Ora8Bind Function


Statement Processing Functions

  • Ora8StmtPrepare Function
    Prepares a SQL statement or a PL/SQL block and associates it with a statement handle.
  • Ora8StmtPrepare2 Function
    Prepares a SQL statement or a PL/SQL block and associates it with a statement handle.
  • Ora8StmtPrepare3 Function
    Prepares a SQL statement or a PL/SQL block and associates it with a statement handle.
  • Ora8StmtRelease Function
    Releases the statement handle obtained by a call to Ora8StmtPrepare3.
  • Ora8StmtExecute Function
    Executes a SQL statement or PL/SQL block associated with a statement handle.
  • Ora8StmtFetch Function
    Performs a specified number of fetch operations in order to retrieve data from a SQL query.
Parent topic: Oracle 8 API Functions Overview


Ora8StmtPrepare Function

Action

Prepares a SQL statement or a PL/SQL block and associates it with a statement handle.

Include file

Ora8.bdh

Syntax

Ora8StmtPrepare( in  hStmt     : number,
                 in  sql       : sql,
                 in  nLanguage : number optional,
                 in  nMode     : number optional ): boolean;

Return value

  • true if successful

  • false otherwise.

Parameter | Description
hStmt | Statement handle.
sql | SQL statement or PL/SQL block to prepare.
nLanguage

Specifies language options (optional).

Possible values are:

  • OCI_NTV_SYNTAX

  • OCI_V7_SYNTAX

  • OCI_V8_SYNTAX
nMode

Specifies various modes of operation (optional).

The possible values are:

  • OCI_DEFAULT (default)

  • OCI_NO_SHARING

Example

var
  ghEnv0        : number;
  ghError0      : number;
  ghStmt0       : number;
  ghSvcCtx0     : number;

dcltrans
  transaction TMain
  begin
    Ora8Init(ghEnv0, OCI_DEFAULT);
    Ora8HandleAlloc(ghEnv0, ghError0, OCI_HTYPE_ERROR);
    Ora8Logon(ghEnv0, ghSvcCtx0, "user", "password", "orclnet2");

    Ora8HandleAlloc(ghEnv0, ghStmt0, OCI_HTYPE_STMT);
    Ora8StmtPrepare(ghStmt0, sqlDelete, OCI_NTV_SYNTAX);
    Ora8StmtExecute(ghSvcCtx0, ghStmt0);

    Ora8HandleFree(ghStmt0, OCI_HTYPE_STMT);
    Ora8Logoff(ghSvcCtx0);
    Ora8HandleFree(ghError0, OCI_HTYPE_ERROR);
    Ora8HandleFree(ghEnv0, OCI_HTYPE_ENV);
  end TMain;

dclsql
  sqlDelete:
    DELETE FROM persons;

See also

Oracle's Programmer's Guide to Oracle Call Interface for Wrapped Oracle function: OCIStmtPrepare
Parent topic: Statement Processing Functions
Related reference
Ora8StmtPrepare2 Function
Ora8StmtPrepare3 Function
Ora8StmtRelease Function
Ora8StmtExecute Function
Ora8StmtFetch Function
Ora8Bind Function
Ora8Define Function


Ora8StmtPrepare2 Function

Action

Prepares a SQL statement or a PL/SQL block and associates it with a statement handle.

Include file

Ora8.bdh

Syntax

Ora8StmtPrepare2( in  hStmt      : number,
                  in  sStatement : string,
                  in  nLanguage  : number optional,
                  in  nMode      : number optional ): boolean;

Return value

  • true if successful

  • false otherwise.

Parameter | Description
hStmt | Statement handle.
sStatement | SQL statement or PL/SQL to prepare.
nLanguage

Specifies language options (optional).

Possible values are:

  • OCI_NTV_SYNTAX

  • OCI_V7_SYNTAX

  • OCI_V8_SYNTAX
nMode

Specifies various modes of operation (optional).

The possible values are:

  • OCI_DEFAULT (default)

  • OCI_NO_SHARING

Example

var
  ghEnv0        : number;
  ghError0      : number;
  ghStmt0       : number;
  ghSvcCtx0     : number;

dcltrans
  transaction TMain
  begin
    Ora8Init(ghEnv0, OCI_DEFAULT);
    Ora8HandleAlloc(ghEnv0, ghError0, OCI_HTYPE_ERROR);
    Ora8Logon(ghEnv0, ghSvcCtx0, "user", "password", "orclnet2");

    Ora8HandleAlloc(ghEnv0, ghStmt0, OCI_HTYPE_STMT);
    Ora8StmtPrepare2(ghStmt0, "DELETE from persons", OCI_NTV_SYNTAX);
    Ora8StmtExecute(ghSvcCtx0, ghStmt0);

    Ora8HandleFree(ghStmt0, OCI_HTYPE_STMT);
    Ora8Logoff(ghSvcCtx0);
    Ora8HandleFree(ghError0, OCI_HTYPE_ERROR);
    Ora8HandleFree(ghEnv0, OCI_HTYPE_ENV);
  end TMain;

See also

Oracle's Programmer's Guide to Oracle Call Interface for Wrapped Oracle function: OCIStmtPrepare
Parent topic: Statement Processing Functions
Related reference
Ora8StmtPrepare Function
Ora8StmtPrepare3 Function
Ora8StmtRelease Function
Ora8StmtExecute Function
Ora8StmtFetch Function
Ora8Bind Function
Ora8Define Function


Ora8StmtPrepare3 Function

Action

Prepares a SQL statement or a PL/SQL block and associates it with a statement handle.

Include file

Ora8.bdh

Syntax

Ora8StmtPrepare3( in  hCtx     : number,
                 out hStmt     : number,
                 in  sql       : sql,
                 in  sKey      : string optional,
                 in  nLanguage : number optional,
                 in  nMode     : number optional ) : boolean;

Return value

  • true if successful

  • false otherwise

Parameter | Description
hCtx | Service context handle to be associated with the statement.
hStmt | Statement handle.
sql | SQL statement or PL/SQL block to prepare.
sKey | For statement caching only. The key to the returned statement in the cache. This can be used for future calls to Ora8StmtPrepare3, in which case there is no need to pass in the statement text and related parameters. If the key is passed in, then the statement text and other parameters are ignored and the search is solely based on the key.
nLanguage

Specifies language options (optional).

Possible values are:

  • OCI_V7_SYNTAX: V7 ORACLE parsing syntax
  • OCI_NTV_SYNTAX: Syntax depends upon the version of the server
nMode

Specifies various modes of operation (optional).

The possible values are:

  • OCI_DEFAULT (default)
  • OCI_STMTCACHE_SEARCH_ONLY

Example

var
  ghEnv0        : number;
  ghError0      : number;
  ghStmt0       : number;
  ghSvcCtx0     : number;

dcltrans
  transaction TMain
  begin
    Ora8Init(ghEnv0, OCI_DEFAULT);
    Ora8HandleAlloc(ghEnv0, ghError0, OCI_HTYPE_ERROR);
    Ora8Logon(ghEnv0, ghSvcCtx0, "user", "password", "orclnet2");

    Ora8StmtPrepare3(ghSvcCtx0, ghStmt0, sqlDelete);
    Ora8StmtExecute(ghSvcCtx0, ghStmt0);

    Ora8StmtRelease(ghStmt0);

    Ora8Logoff(ghSvcCtx0);
    Ora8HandleFree(ghError0, OCI_HTYPE_ERROR);
    Ora8HandleFree(ghEnv0, OCI_HTYPE_ENV);
  end TMain;

dclsql
  sqlDelete:
    DELETE FROM persons;

See also

Oracle Call Interface Programmer's Guide for wrapped Oracle function OCIStmtPrepare2.

Parent topic: Statement Processing Functions
Related reference
Ora8StmtPrepare Function
Ora8StmtPrepare2 Function
Ora8StmtRelease Function
Ora8StmtExecute Function
Ora8StmtFetch Function


Ora8StmtRelease Function

Action

Releases the statement handle obtained by a call to Ora8StmtPrepare3.

Include file

Ora8.bdh

Syntax

Ora8StmtRelease( inout hHandle : number,
                 in   sKey     : string optional,
                 in   nMode    : number optional ) : boolean;

Return value

  • true if successful

  • false otherwise

Parameter | Description
hHandle | The statement handle returned by Ora8StmtPrepare3.
sKey | For statement caching only. The key to the returned statement in the cache. This can be used for future calls to Ora8StmtPrepare3 or can be a new key. If a null key is passed in, the statement will not be tagged.
nMode

Specifies various modes of operation (optional).

The possible values are:

  • OCI_DEFAULT (default)
  • OCI_STMTCACHE_DELETE: Only valid for statement caching. The statement will not be kept in the cache any more.

Example

var
  ghEnv0        : number;
  ghError0      : number;
  ghStmt0       : number;
  ghSvcCtx0     : number;

dcltrans
  transaction TMain
  begin
    Ora8Init(ghEnv0, OCI_DEFAULT);
    Ora8HandleAlloc(ghEnv0, ghError0, OCI_HTYPE_ERROR);
    Ora8Logon(ghEnv0, ghSvcCtx0, "user", "password", "orclnet2");

    Ora8StmtPrepare3(ghSvcCtx0, ghStmt0, sqlDelete);
    Ora8StmtExecute(ghSvcCtx0, ghStmt0);

    Ora8StmtRelease(ghStmt0);

    Ora8Logoff(ghSvcCtx0);
    Ora8HandleFree(ghError0, OCI_HTYPE_ERROR);
    Ora8HandleFree(ghEnv0, OCI_HTYPE_ENV);
  end TMain;

dclsql
  sqlDelete:
    DELETE FROM persons;

See also

Oracle Call Interface Programmer's Guide for wrapped Oracle function OCIStmtRelease.

Parent topic: Statement Processing Functions
Related reference
Ora8StmtPrepare Function
Ora8StmtPrepare2 Function
Ora8StmtPrepare3 Function
Ora8StmtExecute Function
Ora8StmtFetch Function


Ora8StmtExecute Function

Action

Executes a SQL statement or PL/SQL block associated with a statement handle. Besides executing a statement, this function can also fetch data after the execution if the statement is a SQL query.

Before calling this function, you have to prepare the SQL statement using the Ora8StmtPrepare function. Array binding can be used to process multiple rows of data in a single execute operation. If the SQL statement contains place holders, it is necessary to call the Ora8Bind function for each place holder first.

Include file

Ora8.bdh

Syntax

Ora8StmtExecute( in  hSvcCtx     : number,
                 in  hStmt       : number,
                 in  nIterations : number optional,
                 in  nRows       : number optional,
                 in  nCancel     : number optional,
                 in  nExact      : number optional,
                 in  nMode       : number optional,
                 out nFetched    : number optional ) : boolean;

Return value

  • true if successful

  • false otherwise

Parameter | Description
hSvcCtx | Service context handle.
hStmt | Statement handle.
nIterations | Number of iterations (optional). This parameter specifies whether to perform multiple execute operations in order to process array parameters.
nRows | Numbers of rows to fetch (optional). This parameter specifies whether to fetch data after a SQL query.
nCancel | Reserved. (optional)
nExact | Reserved. (optional)
nMode

Specifies the various modes of operation (optional).

The modes are:

  • OCI_DEFAULT (default)

  • OCI_BATCH_ERRORS

  • OCI_COMMIT_ON_SUCCESS

  • OCI_DESCRIBE_ONLY

  • OCI_EXACT_FETCH

  • OCI_PARSE_ONLY

  • OCI_STMT_SCROLLABLE_READ_ONLY
nFetched | Variable receiving the actual number of rows fetched (optional)

Example

var
  ghEnv0        : number;
  ghError0      : number;
  ghStmt0       : number;
  ghSvcCtx0     : number;

dcltrans
  transaction TMain
  const
    PUBLIC_KEY := "\h59b20094...";
  var
    nFetched, i, nAge : number;
    sName             : string;
  begin
    Ora8Init(ghEnv0, OCI_DEFAULT);
    Ora8HandleAlloc(ghEnv0, ghError0, OCI_HTYPE_ERROR);
    Ora8Logon(ghEnv0, ghSvcCtx0, "user", "password", "orclnet2");

    Ora8HandleAlloc(ghEnv0, ghStmt0, OCI_HTYPE_STMT);
    Ora8StmtPrepare(ghStmt0, sqlInsert, OCI_NTV_SYNTAX);

    // insert two persons: Jimmy and Ronald
    Ora8Bind(ghStmt0, ":name", SQLT_CHR, 32, 2);
    Ora8Bind(ghStmt0, ":age", SQLT_INT, 0, 2);

    Ora8SetString(ghStmt0, ":name", "Jimmy", 1);
    Ora8SetInt(ghStmt0, ":age", 55, 1);
    Ora8SetString(ghStmt0, ":name", "Ronald", 2);
    Ora8SetInt(ghStmt0, ":age", 18, 2);

    Ora8StmtExecute(ghSvcCtx0, ghStmt0, 2);

    // select all persons
    Ora8StmtPrepare(ghStmt0, sqlSelect, OCI_NTV_SYNTAX);

    Ora8Define(ghStmt0, 1, SQLT_CHR, 32);
    Ora8Define(ghStmt0, 2, SQLT_INT);
    Ora8StmtExecute(ghSvcCtx0, ghStmt0, 1, 50, 0, 0, 0, nFetched);

    for i := 1 to nFetched do
      sName := Ora8GetString(ghStmt0, "1", i);
      nAge  := Ora8GetInt(ghStmt0, "2", i);
      write(sName, 32); write(nAge, 5); writeln;
    end;

    Ora8HandleFree(ghStmt0, OCI_HTYPE_STMT);
    Ora8Logoff(ghSvcCtx0);
    Ora8HandleFree(ghError0, OCI_HTYPE_ERROR);
    Ora8HandleFree(ghEnv0, OCI_HTYPE_ENV);
  end TMain;

dclsql
  sqlInsert:
    INSERT INTO persons (name, age) VALUES (:name, :age);

  sqlSelect:
    SELECT * FROM persons;

Output

Howard 33Michael 44Bobby 61Sara 38Jimmy 55Ronald 18

See also

Oracle's Programmer's Guide to Oracle Call Interface for Wrapped Oracle function: OCIStmtExecute
Parent topic: Statement Processing Functions
Related reference
Ora8StmtPrepare Function
Ora8StmtPrepare2 Function
Ora8StmtPrepare3 Function
Ora8StmtRelease Function
Ora8StmtFetch Function
Ora8Bind Function
Ora8Define Function


Ora8StmtFetch Function

Action

Performs a specified number of fetch operations in order to retrieve data from a SQL query. This function is used to fetch both single and multiple rows.

Afterwards, the following functions can be used to retrieve the fetched data:

  • Ora8GetString
  • Ora8GetInt
  • Ora8GetFloat
  • Ora8GetValue

Include file

Ora8.bdh

Syntax

Ora8StmtFetch( in  hStmt         : number,
               in  nIterations   : number optional,
               in  nBatchSize    : number optional,
               in  nOrientation  : number optional,
               in  nScrollOffset : number optional,
               in  nMode         : number optional,
               out nFetched      : number optional ) : boolean;

Return value

  • true if successful

  • false either if an error occurred during the fetch operation or if the number of rows actually fetched is not equal to the specified number of rows to fetch.

Parameter | Description
hStmt | Statement handle.
nIterations | Number of iterations to perform (optional). Predefined options are: ORA_FETCH_ALL. Repeat the fetch operation until all rows have been fetched. The default option is to perform a single iteration.
nBatchSize | Number of rows to fetch per iteration (optional). The default option is to fetch a single row per iteration
nOrientation | Orientation (optional).
nScrollOffset | Scroll offset (optional).
nMode | Mode. (optional)
nFetched | Variable receiving the actual number of rows fetched (optional).

Example

var
  ghEnv0        : number;
  ghError0      : number;
  ghStmt0       : number;
  ghSvcCtx0     : number;

dcltrans
  transaction TMain
  const
    MAX_ROWS := 1000; // maximum number of rows
  var
    nFetched, i, nAge : number;
    sName             : string;
  begin
    Ora8Init(ghEnv0, OCI_DEFAULT);
    Ora8HandleAlloc(ghEnv0, ghError0, OCI_HTYPE_ERROR);
    Ora8Logon(ghEnv0, ghSvcCtx0, "user", "password", "orclnet2");

    Ora8HandleAlloc(ghEnv0, ghStmt0, OCI_HTYPE_STMT);
    Ora8StmtPrepare(ghStmt0, sqlSelect, OCI_NTV_SYNTAX);

    Ora8Define(ghStmt0, 1, SQLT_CHR, 32);
    Ora8Define(ghStmt0, 2, SQLT_INT);

    // first possibility to fetch all rows
    // in this case, nFetched must be smaller than MAX_ROWS
    Ora8StmtExecute(ghSvcCtx0, ghStmt0);
    Ora8StmtFetch(ghStmt0, 1, MAX_ROWS, 0, 0, 0, nFetched);

    for i := 1 to nFetched do
      sName := Ora8GetString(ghStmt0, "1", i);
      nAge  := Ora8GetInt(ghStmt0, "2", i);
      write(sName, 32); write(nAge, 5);  writeln;
    end;

    // second possibility to fetch all data
    Ora8StmtExecute(ghSvcCtx0, ghStmt0);

    while Ora8StmtFetch(ghStmt0, 1, 1) do
      sName := Ora8GetString(ghStmt0, "1");
      nAge  := Ora8GetInt(ghStmt0, "2");
      write(sName, 32); write(nAge, 5); writeln;
    end;

    Ora8HandleFree(ghStmt0, OCI_HTYPE_STMT);
    Ora8Logoff(ghSvcCtx0);
    Ora8HandleFree(ghError0, OCI_HTYPE_ERROR);
    Ora8HandleFree(ghEnv0, OCI_HTYPE_ENV);
  end TMain;

dclsql
  sqlSelect:
    SELECT * FROM persons;

Output

Howard 33Michael 44Bobby 61Sara 38

See also

Oracle's Programmer's Guide to Oracle Call Interface for Wrapped Oracle function: OCIStmtFetch
Parent topic: Statement Processing Functions
Related reference
Ora8StmtPrepare Function
Ora8StmtPrepare2 Function
Ora8StmtPrepare3 Function
Ora8StmtRelease Function
Ora8StmtExecute Function
Ora8Define Function
Ora8GetInt Function
Ora8GetString Function
Ora8GetFloat Function
Ora8GetValue Function


Data Fetching Functions

  • Ora8GetValue Function
    Retrieves any value either from the program variable that is bound with the specified place holder in the SQL statement or PL/SQL block, or from the output variable that is defined for the specified select-list item in the SQL query.
  • Ora8GetInt Function
    Retrieves a number value either from the program variable that is bound with the specified place holder in the SQL statement or PL/SQL block, or from the output variable that is defined for the specified select-list item in the SQL query.
  • Ora8GetFloat Function
    Retrieves a floating-point value either from the program variable that is bound with the specified place holder in the SQL statement or PL/SQL block, or from the output variable that is defined for the specified select-list item in the SQL query.
  • Ora8GetString Function
    Retrieves a string either from the program variable that is bound with the specified place holder in the SQL statement or PL/SQL block, or from the output variable that is defined for the specified select-list item in the SQL query.
Parent topic: Oracle 8 API Functions Overview


Ora8GetValue Function

Action

Retrieves any value either from the program variable that is bound with the specified place holder in the SQL statement or PL/SQL block, or from the output variable that is defined for the specified select-list item in the SQL query. This function is used to retrieve values from both scalar and array program variables that are defined for the specified select-list item.

Include file

Ora8.bdh

Syntax

Ora8GetValue( in  hStmt       : number,
              in  sSqlVar     : string,
              out sValue      : string,
              in  nBufferSize : number,
              in  nIndex      : number optional,
              in  nDatatype   : number optional ): boolean;

Return value

  • true if successful

  • false otherwise; In this case, you can use the Ora8OciError function to retrieve the Oracle OCI error code.

Parameter | Description
hStmt | Statement handle.
sSqlVar

This parameter can be one of the following:

  • The name of the place holder in the SQL statement or PL/SQL block. In this case, the parameter must include the preceding colon identifying it as a place holder.

  • The index of the select-list item in the SQL query. Position indices start at 1 for the first (leftmost) select-list item.

Note: In the latter case, the column number has to be passed to the function as a string.
sValue | Variable receiving either the value assigned to the place holder or the data retrieved from a fetched row, as the case may be
nBufferSize | Size of the variable receiving the value
nIndex

Index or row number (optional). This parameter has to be passed to the function whenever retrieving a value assigned to an array place holder or fetching data from multiple rows. It can be one of the following:

  • The array index of the program variable.

  • The row number for the long value in the fetched data.
nDatatype | Specifies which data type to retrieve (optional). See Oracle 8 data types for a list of data types.

Example

var
  ghEnv0        : number;
  ghError0      : number;
  ghStmt0       : number;
  ghSvcCtx0     : number;

dcltrans
  transaction TMain
  var
    nAge : number;
    sName : string;
  begin
    Ora8Init(ghEnv0, OCI_DEFAULT);
    Ora8HandleAlloc(ghEnv0, ghError0, OCI_HTYPE_ERROR);
    Ora8Logon(ghEnv0, ghSvcCtx0, "user", "password", "orclnet2");

    Ora8HandleAlloc(ghEnv0, ghStmt0, OCI_HTYPE_STMT);
    Ora8StmtPrepare(ghStmt0, sqlSelect, OCI_NTV_SYNTAX);

    Ora8Bind(ghStmt0, ":1", SQLT_INT);
    Ora8SetInt(ghStmt0, ":1", 25);
    Ora8Define(ghStmt0, 1, SQLT_CHR, 32);
    Ora8Define(ghStmt0, 2, SQLT_INT);
    Ora8StmtExecute(ghSvcCtx0, ghStmt0);

    while Ora8StmtFetch(ghStmt0, 1, 1) do
      Ora8GetValue(ghStmt0, "1", sName, STRING_COMPLETE);
      nAge  := Ora8GetInt(ghStmt0, "2");
      write(sName, 32); write(nAge, 5); writeln;
    end;

    Ora8HandleFree(ghStmt0, OCI_HTYPE_STMT);
    Ora8Logoff(ghSvcCtx0);
    Ora8HandleFree(ghError0, OCI_HTYPE_ERROR);
    Ora8HandleFree(ghEnv0, OCI_HTYPE_ENV);
  end TMain;

dclsql
  sqlSelect:
    SELECT * FROM persons WHERE age > :1;

Output

Howard 33Michael 44Bobby 61Sara 38
Parent topic: Data Fetching Functions
Related reference
Ora8GetInt Function
Ora8GetFloat Function
Ora8GetString Function
Ora8OciError Function
Oracle 8 Data Types


Ora8GetInt Function

Action

Retrieves a number value either from the program variable that is bound with the specified place holder in the SQL statement or PL/SQL block, or from the output variable that is defined for the specified select-list item in the SQL query. This function is used to retrieve values from both scalar and array program variables that are defined for the specified select-list item.

Include file

Ora8.bdh

Syntax

Ora8GetInt( in hStmt   : number,
            in sSqlVar : string,
            in nIndex  : number optional): number;

Return value

Retrieved long value

Parameter | Description
hStmt | Statement handle.
sSqlVar

This parameter can be one of the following:

  • The name of the place holder in the SQL statement or PL/SQL block. In this case, the parameter must include the preceding colon identifying it as a place holder.

  • The index of the select-list item in the SQL query. Position indices start at 1 for the first (leftmost) select-list item.

Note: In the latter case, the column number has to be passed to the function as a string.
nIndex

Index or row number (optional). This parameter has to be passed to the function whenever retrieving a value assigned to an array place holder or fetching data from multiple rows. It can be one of the following:

  • The array index of the program variable.

  • The row number for the long value in the fetched data.

Example

var
  ghEnv0        : number;
  ghError0      : number;
  ghStmt0       : number;
  ghSvcCtx0     : number;

dcltrans
  transaction TMain
  var
    nAge : number;
    sName : string;
  begin
    Ora8Init(ghEnv0, OCI_DEFAULT);
    Ora8HandleAlloc(ghEnv0, ghError0, OCI_HTYPE_ERROR);
    Ora8Logon(ghEnv0, ghSvcCtx0, "user", "password", "orclnet2");

    Ora8HandleAlloc(ghEnv0, ghStmt0, OCI_HTYPE_STMT);
    Ora8StmtPrepare(ghStmt0, sqlSelect, OCI_NTV_SYNTAX);

    Ora8Bind(ghStmt0, ":1", SQLT_INT);
    Ora8SetInt(ghStmt0, ":1", 25);
    Ora8Define(ghStmt0, 1, SQLT_CHR, 32);
    Ora8Define(ghStmt0, 2, SQLT_INT);
    Ora8StmtExecute(ghSvcCtx0, ghStmt0);

    while Ora8StmtFetch(ghStmt0, 1, 1) do
      sName := Ora8GetString(ghStmt0, "1");
      nAge  := Ora8GetInt(ghStmt0, "2");
      write(sName, 32); write(nAge, 5); writeln;
    end;

    Ora8HandleFree(ghStmt0, OCI_HTYPE_STMT);
    Ora8Logoff(ghSvcCtx0);
    Ora8HandleFree(ghError0, OCI_HTYPE_ERROR);
    Ora8HandleFree(ghEnv0, OCI_HTYPE_ENV);
  end TMain;

dclsql
  sqlSelect:
    SELECT * FROM persons WHERE age > :1;

Output

Howard 33Michael 44Bobby 61Sara 38
Parent topic: Data Fetching Functions
Related reference
Ora8GetValue Function
Ora8GetFloat Function
Ora8GetString Function


Ora8GetFloat Function

Action

Retrieves a floating-point value either from the program variable that is bound with the specified place holder in the SQL statement or PL/SQL block, or from the output variable that is defined for the specified select-list item in the SQL query. This function is used to retrieve values from both scalar and array program variables that are defined for the specified select-list item.

Include file

Ora8.bdh

Syntax

Ora8GetFloat( in hStmt   : number,
              in sSqlVar : string,
              in nIndex  : number optional): float;

Return value

Retrieved floating-point value.

Parameter | Description
hStmt | Statement handle.
sSqlVar

This parameter can be one of the following:

  • The name of the place holder in the SQL statement or PL/SQL block. In this case, the parameter must include the preceding colon identifying it as a place holder.

  • The index of the select-list item in the SQL query. Position indices start at 1 for the first (leftmost) select-list item.

Note: In the latter case, the column number has to be passed to the function as a string.
nIndex

Index or row number (optional). This parameter has to be passed to the function whenever retrieving a value assigned to an array place holder or fetching data from multiple rows. It can be one of the following:

  • The array index of the program variable.

  • The row number for the floating-point value in the fetched data.

Example

var
  ghEnv0        : number;
  ghError0      : number;
  ghStmt0       : number;
  ghSvcCtx0     : number;

dcltrans
  transaction TMain
  var
    sName    : string;
    fBalance : float;
  begin
    Ora8Init(ghEnv0, OCI_DEFAULT);
    Ora8HandleAlloc(ghEnv0, ghError0, OCI_HTYPE_ERROR);
    Ora8Logon(ghEnv0, ghSvcCtx0, "user", "password", "orclnet2");

    Ora8HandleAlloc(ghEnv0, ghStmt0, OCI_HTYPE_STMT);
    Ora8StmtPrepare(ghStmt0, sqlSelect, OCI_NTV_SYNTAX);

    Ora8Bind(ghStmt0, ":1", SQLT_INT);
    Ora8SetInt(ghStmt0, ":1", 25);
    Ora8Define(ghStmt0, 1, SQLT_CHR, 32);
    Ora8Define(ghStmt0, 2, SQLT_INT);
    Ora8StmtExecute(ghSvcCtx0, ghStmt0);

    while Ora8StmtFetch(ghStmt0, 1, 1) do
      sName    := Ora8GetString(ghStmt0, "1");
     fBalance := Ora8GetFloat(ghStmt0, "2");
      write(sName, 32); write(fBalance , 5); writeln;
    end;

    Ora8HandleFree(ghStmt0, OCI_HTYPE_STMT);
    Ora8Logoff(ghSvcCtx0);
    Ora8HandleFree(ghError0, OCI_HTYPE_ERROR);
    Ora8HandleFree(ghEnv0, OCI_HTYPE_ENV);
  end TMain;

dclsql
  sqlSelect:
    SELECT * FROM accounts WHERE balance > :1;

Output

Howard 33Michael 44Bobby 61Sara 38
Parent topic: Data Fetching Functions
Related reference
Ora8GetValue Function
Ora8GetInt Function
Ora8GetString Function


Ora8GetString Function

Action

Retrieves a string either from the program variable that is bound with the specified place holder in the SQL statement or PL/SQL block, or from the output variable that is defined for the specified select-list item in the SQL query. This function is used to retrieve values from both scalar and array program variables that are defined for the specified select-list item.

If this function is used to retrieve one of the following data types, the retrieved value is automatically converted to a string:

  • SQLT_DAT
  • SQL_INT
  • SQLT_FLT

Include file

Ora8.bdh

Syntax

Ora8GetString( in hStmt   : number,
               in sSqlVar : string,
               in nIndex  : number optional): string;

Return value

Retrieved string, containing at most 253 characters. If the string to be retrieved consists of more than 253 characters, it is automatically cut off at the corresponding position.

Parameter | Description
hStmt | Statement handle.
sSqlVar

This parameter can be one of the following:

  • The name of the place holder in the SQL statement or PL/SQL block. In this case, the parameter must include the preceding colon identifying it as a place holder.

  • The index of the select-list item in the SQL query. Position indices start at 1 for the first (leftmost) select-list item.

Note: In the latter case, the column number has to be passed to the function as a string.
nIndex

Index or row number (optional). This parameter has to be passed to the function whenever retrieving a string assigned to an array place holder or fetching data from multiple rows. It can be one of the following:

  • The array index of the program variable.

  • The row number for the string in the fetched data.

Example

var
  ghEnv0        : number;
  ghError0      : number;
  ghStmt0       : number;
  ghSvcCtx0     : number;

dcltrans
  transaction TMain
  var
    nAge : number;
    sName : string;
  begin
    Ora8Init(ghEnv0, OCI_DEFAULT);
    Ora8HandleAlloc(ghEnv0, ghError0, OCI_HTYPE_ERROR);
    Ora8Logon(ghEnv0, ghSvcCtx0, "user", "password", "orclnet2");

    Ora8HandleAlloc(ghEnv0, ghStmt0, OCI_HTYPE_STMT);
    Ora8StmtPrepare(ghStmt0, sqlSelect, OCI_NTV_SYNTAX);

    Ora8Bind(ghStmt0, ":1", SQLT_INT);
    Ora8SetInt(ghStmt0, ":1", 25);
    Ora8Define(ghStmt0, 1, SQLT_CHR, 32);
    Ora8Define(ghStmt0, 2, SQLT_INT);
    Ora8StmtExecute(ghSvcCtx0, ghStmt0);

      while Ora8StmtFetch(ghStmt0, 1, 1) do
      sName := Ora8GetString(ghStmt0, "1");
      nAge  := Ora8GetInt(ghStmt0, "2");
      write(sName, 32); write(nAge, 5); writeln;
    end;

    Ora8HandleFree(ghStmt0, OCI_HTYPE_STMT);
    Ora8Logoff(ghSvcCtx0);
    Ora8HandleFree(ghError0, OCI_HTYPE_ERROR);
    Ora8HandleFree(ghEnv0, OCI_HTYPE_ENV);
  end TMain;

dclsql
  sqlSelect:
    SELECT * FROM persons WHERE age > :1;

Output

Howard 33Michael 44Bobby 61Sara 38
Parent topic: Data Fetching Functions
Related reference
Ora8GetValue Function
Ora8GetInt Function
Ora8GetFloat Function


Transaction Functions

  • Ora8TransCommit Function
    Commits the transaction associated with a specified service context.
  • Ora8TransDetach Function
    Detaches a transaction.
  • Ora8TransForget Function
    Causes the server to forget a heuristically completed global transaction.
  • Ora8TransPrepare Function
    Prepares a transaction for commit.
  • Ora8TransRollback Function
    Rolls back the current transaction.
  • Ora8TransStart Function
    Sets the beginning of a transaction.
Parent topic: Oracle 8 API Functions Overview


Ora8TransCommit Function

Action

Commits the transaction associated with a specified service context.

Include file

Ora8.bdh

Syntax

Ora8TransCommit( in hSvcCtx  : number,
                 in nOptions : number optional ) : boolean;

Return value

  • true if successful

  • false otherwise.

Parameter | Description
hSvcCtx | The service context handle.
nOptions

Flags (optional).

Valid options are:

  • OCI_DEFAULT (default)

  • OCI_TRANS_TWOPHASE

Example

var
  ghEnv0        : number;
  ghError0      : number;
  ghStmt0       : number;
  ghSvcCtx0     : number;

dcltrans
  transaction TMain
  begin
    Ora8Init(ghEnv0, OCI_DEFAULT);
    Ora8HandleAlloc(ghEnv0, ghError0, OCI_HTYPE_ERROR);
    Ora8Logon(ghEnv0, ghSvcCtx0, "user", "password", "orclnet2");

    Ora8HandleAlloc(ghEnv0, ghStmt0, OCI_HTYPE_STMT);
    Ora8StmtPrepare(ghStmt0, sqlDelete, OCI_NTV_SYNTAX);
    Ora8StmtExecute(ghSvcCtx0, ghStmt0);

    Ora8TransCommit(ghSvcCtx0);

    Ora8HandleFree(ghStmt0, OCI_HTYPE_STMT);
    Ora8Logoff(ghSvcCtx0);
    Ora8HandleFree(ghError0, OCI_HTYPE_ERROR);
    Ora8HandleFree(ghEnv0, OCI_HTYPE_ENV);
  end TMain;

dclsql
  sqlDelete:
    DELETE FROM persons;

See also

Oracle's Programmer's Guide to Oracle Call Interface for Wrapped Oracle function: OCITransCommit
Parent topic: Transaction Functions
Related reference
Ora8TransDetach Function
Ora8TransForget Function
Ora8TransPrepare Function
Ora8TransRollback Function
Ora8TransStart Function


Ora8TransDetach Function

Action

Detaches a transaction.

Include file

Ora8.bdh

Syntax

Ora8TransDetach( in hSvcCtx  : number,
                 in nOptions : number optional ) : boolean;

Return value

  • true if successful

  • false otherwise.

Parameter | Description
hSvcCtx | The service context handle.
nOptions

Flags (optional).

Valid options are:

  • OCI_DEFAULT (default)

Example

var
  ghEnv0        : number;
  ghError0      : number;
  ghStmt0       : number;
  ghSvcCtx0     : number;

dcltrans
  transaction TMain
  begin
    Ora8Init(ghEnv0, OCI_DEFAULT);
    Ora8HandleAlloc(ghEnv0, ghError0, OCI_HTYPE_ERROR);
    Ora8Logon(ghEnv0, ghSvcCtx0, "user", "password", "orclnet2");

    Ora8TransStart(ghSvcCtx0, 60, OCI_TRANS_NEW);
    ...
    Ora8TransDetach(ghSvcCtx0);

    Ora8HandleFree(ghStmt0, OCI_HTYPE_STMT);
    Ora8Logoff(ghSvcCtx0);
    Ora8HandleFree(ghError0, OCI_HTYPE_ERROR);
    Ora8HandleFree(ghEnv0, OCI_HTYPE_ENV);
  end TMain;

See also

Oracle's Programmer's Guide to Oracle Call Interface for Wrapped Oracle function: OCITransDetach
Parent topic: Transaction Functions
Related reference
Ora8TransCommit Function
Ora8TransForget Function
Ora8TransPrepare Function
Ora8TransRollback Function
Ora8TransStart Function


Ora8TransForget Function

Action

Causes the server to forget a heuristically completed global transaction.

Include file

Ora8.bdh

Syntax

Ora8TransForget( in hSvcCtx  : number,
                 in nOptions : number optional ) : boolean;

Return value

  • true if successful

  • false otherwise.

Parameter | Description
hSvcCtx | The service context handle.
nOptions

Flags (optional).

Valid options are:

  • OCI_DEFAULT (default)

Example

var
  ghEnv0        : number;
  ghError0      : number;
  ghStmt0       : number;
  ghSvcCtx0     : number;

dcltrans
  transaction TMain
  begin
    Ora8Init(ghEnv0, OCI_DEFAULT);
    Ora8HandleAlloc(ghEnv0, ghError0, OCI_HTYPE_ERROR);
    Ora8Logon(ghEnv0, ghSvcCtx0, "user", "password", "orclnet2");

    Ora8TransForget(ghSvcCtx0);

    ...

    Ora8HandleFree(ghStmt0, OCI_HTYPE_STMT);
    Ora8Logoff(ghSvcCtx0);
    Ora8HandleFree(ghError0, OCI_HTYPE_ERROR);
    Ora8HandleFree(ghEnv0, OCI_HTYPE_ENV);
  end TMain;

See also

Oracle's Programmer's Guide to Oracle Call Interface for Wrapped Oracle function: OCITransForget
Parent topic: Transaction Functions
Related reference
Ora8TransCommit Function
Ora8TransDetach Function
Ora8TransPrepare Function
Ora8TransRollback Function
Ora8TransStart Function


Ora8TransPrepare Function

Action

Prepares a transaction for commit.

Include file

Ora8.bdh

Syntax

Ora8TransPrepare( in hSvcCtx  : number,
                  in nOptions : number optional ) : boolean;

Return value

  • true if successful

  • false otherwise.

Parameter | Description
hSvcCtx | The service context handle.
nOptions

Flags (optional).

Valid options are:

  • OCI_DEFAULT (default)

Example

var
  ghEnv0        : number;
  ghError0      : number;
  ghStmt0       : number;
  ghSvcCtx0     : number;

dcltrans
  transaction TMain
  begin
    Ora8Init(ghEnv0, OCI_DEFAULT);
    Ora8HandleAlloc(ghEnv0, ghError0, OCI_HTYPE_ERROR);
    Ora8Logon(ghEnv0, ghSvcCtx0, "user", "password", "orclnet2");

    Ora8TransPrepare(ghSvcCtx0);

    ...

    Ora8HandleFree(ghStmt0, OCI_HTYPE_STMT);
    Ora8Logoff(ghSvcCtx0);
    Ora8HandleFree(ghError0, OCI_HTYPE_ERROR);
    Ora8HandleFree(ghEnv0, OCI_HTYPE_ENV);
  end TMain;

See also

Oracle's Programmer's Guide to Oracle Call Interface for Wrapped Oracle function: OCITransPrepare
Parent topic: Transaction Functions
Related reference
Ora8TransCommit Function
Ora8TransDetach Function
Ora8TransForget Function
Ora8TransRollback Function
Ora8TransStart Function


Ora8TransRollback Function

Action

Rolls back the current transaction.

Include file

Ora8.bdh

Syntax

Ora8TransRollback( in hSvcCtx  : number,
                   in nOptions : number optional ) : boolean;

Return value

  • true if successful

  • false otherwise

Parameter | Description
hSvcCtx | The service context handle.
nOptions | Flags (optional). The only valid mode is OCI_DEFAULT. Omit the parameter in order to use the default parameter.

Example

var
  ghEnv0        : number;
  ghError0      : number;
  ghStmt0       : number;
  ghSvcCtx0     : number;

dcltrans
  transaction TMain
  begin
    Ora8Init(ghEnv0, OCI_DEFAULT);
    Ora8HandleAlloc(ghEnv0, ghError0, OCI_HTYPE_ERROR);
    Ora8Logon(ghEnv0, ghSvcCtx0, "user", "password", "orclnet2");

    Ora8HandleAlloc(ghEnv0, ghStmt0, OCI_HTYPE_STMT);
    Ora8StmtPrepare(ghStmt0, sqlDelete, OCI_NTV_SYNTAX);
    Ora8StmtExecute(ghSvcCtx0, ghStmt0);

    Ora8TransRollback(ghSvcCtx0);
    Ora8HandleFree(ghStmt0, OCI_HTYPE_STMT);
    Ora8Logoff(ghSvcCtx0);
    Ora8HandleFree(ghError0, OCI_HTYPE_ERROR);
    Ora8HandleFree(ghEnv0, OCI_HTYPE_ENV);
  end TMain;

dclsql
  sqlDelete:
    DELETE FROM persons;

See also

Oracle's Programmer's Guide to Oracle Call Interface for Wrapped Oracle function: OCITransRollback
Parent topic: Transaction Functions
Related reference
Ora8TransCommit Function
Ora8TransDetach Function
Ora8TransForget Function
Ora8TransPrepare Function
Ora8TransStart Function


Ora8TransStart Function

Action

Sets the beginning of a transaction.

Include file

Ora8.bdh

Syntax

Ora8TransStart( in hSvcCtx  : number,
                in nTimeout : number optional,
                in nOptions : number optional ): boolean;

Return value

  • true if successful

  • false otherwise

Parameter | Description
hSvcCtx | The service context handle.
nTimeout | The time, in seconds, to wait for a transaction to become available for resumption when OCI_TRANS_RESUME is specified (optional). When OCI_TRANS_NEW is specified, the timeout parameter indicates the number of seconds the transaction can bee inactive before it is automatically aborted by the system.
nOptions

Flags (optional).

Valid options are:

  • OCI_TRANS_NEW

  • OCI_TRANS_TIGHT

  • OCI_TRANS_LOOSE

  • OCI_TRANS_RESUME

  • OCI_TRANS_READONLY

  • OCI_TRANS_SERIALIZABLE

  • OCI_TRANS_SEPARABLE

Example

  var
  ghEnv0        : number;
  ghError0      : number;
  ghStmt0       : number;
  ghSvcCtx0     : number;

dcltrans
  transaction TMain
  begin
    Ora8Init(ghEnv0, OCI_DEFAULT);
    Ora8HandleAlloc(ghEnv0, ghError0, OCI_HTYPE_ERROR);
    Ora8Logon(ghEnv0, ghSvcCtx0, "user", "password", "orclnet2");

    Ora8TransStart(ghSvcCtx0, 60, OCI_TRANS_NEW);
    ...
    Ora8TransDetach(ghSvcCtx0);

    Ora8HandleFree(ghStmt0, OCI_HTYPE_STMT);
    Ora8Logoff(ghSvcCtx0);
    Ora8HandleFree(ghError0, OCI_HTYPE_ERROR);
    Ora8HandleFree(ghEnv0, OCI_HTYPE_ENV);
  end TMain;

See also

Oracle's Programmer's Guide to Oracle Call Interface for Wrapped Oracle function: OCITransStart
Parent topic: Transaction Functions
Related reference
Ora8TransCommit Function
Ora8TransDetach Function
Ora8TransForget Function
Ora8TransPrepare Function
Ora8TransRollback Function


Miscellaneous Functions

  • Ora8SvcCtxToLda Function
    Converts a V8 or later service context handle into a V7 connection.
  • Ora8LdaToSvcCtx Function
    Converts a V7 connection into a V8 or later service context handle.
Parent topic: Oracle 8 API Functions Overview


Ora8SvcCtxToLda Function

Action

Converts a V8 or later service context handle into a V7 connection.

Include file

Ora8.bdh

Syntax

Ora8SvcCtxToLda( in  hV8SvcCtx     : number,
                 out hV7Connection : number) : boolean;

Return value

  • true if successful

  • false otherwise

Parameter | Description
hV8SvcCtx | An initialized V8 or later service context handle.
hV7Connection | Variable receiving the handle to the V7 database connection.

Example

var
  ghEnv0        : number;
  ghError0      : number;
  ghStmt0       : number;
  ghSvcCtx0     : number;
  ghConnect0    : number;
  cCursor       : cursor;

dcltrans
  transaction TMain
  begin
    Ora8Init(ghEnv0, OCI_DEFAULT);
    Ora8HandleAlloc(ghEnv0, ghError0, OCI_HTYPE_ERROR);
    Ora8Logon(ghEnv0, ghSvcCtx0, "user", "password", "orclnet2");

    Ora8SvcCtxToLda(ghSvcCtx0, ghConnect0);

    OraOpen(cCursor, ghConnect0);
    OraParse(cCursor, sqlDelete, ORA_NONDEFERRED);
    OraExec(cCursor);
    OraClose(cCursor);

    Ora8LdaToSvcCtx(ghSvcCtx0, ghConnect0);

    Ora8Logoff(ghSvcCtx0);
    Ora8HandleFree(ghError0, OCI_HTYPE_ERROR);
    Ora8HandleFree(ghEnv0, OCI_HTYPE_ENV);
  end TMain;

dclsql
  sqlDelete:
    DELETE FROM persons;

See also

Oracle's Programmer's Guide to Oracle Call Interface for Wrapped Oracle function: OCISvcCtxToLda
Parent topic: Miscellaneous Functions
Related concepts
Oracle API Functions Overview
Related reference
Ora8LdaToSvcCtx Function
Ora8HandleFree Function
Ora8HandleAlloc Function
Ora8Init Function


Ora8LdaToSvcCtx Function

Action

Converts a V7 connection into a V8 or later service context handle.

This function should be used only for resetting a V7 connection obtained from Ora8SvcCtxToLda back to a V8 or later service context handle.

Include file

Ora8.bdh

Syntax

Ora8LdaToSvcCtx( out hV8SvcCtx     : number,
                 in  hV7Connection : number) : boolean;

Return value

  • true if successful

  • false otherwise.

Parameter | Description
hV8SvcCtx | Variable receiving the V8 or later service context handle.
hV7Connection | The V7 connection returned by Ora8SvcCtxToLda from this service context.

Example

var
  ghEnv0        : number;
  ghError0      : number;
  ghStmt0       : number;
  ghSvcCtx0     : number;
  ghConnect0    : number;
  cCursor       : cursor;

dcltrans
  transaction TMain
  begin
    Ora8Init(ghEnv0, OCI_DEFAULT);
    Ora8HandleAlloc(ghEnv0, ghError0, OCI_HTYPE_ERROR);
    Ora8Logon(ghEnv0, ghSvcCtx0, "user", "password", "orclnet2");

    Ora8SvcCtxToLda(ghSvcCtx0, ghConnect0);

    OraOpen(cCursor, ghConnect0);
    OraParse(cCursor, sqlDelete, ORA_NONDEFERRED);
    OraExec(cCursor);
    OraClose(cCursor);

    Ora8LdaToSvcCtx(ghSvcCtx0, ghConnect0);

    Ora8Logoff(ghSvcCtx0);
    Ora8HandleFree(ghError0, OCI_HTYPE_ERROR);
    Ora8HandleFree(ghEnv0, OCI_HTYPE_ENV);
  end TMain;

dclsql
  sqlDelete:
    DELETE FROM persons;

See also

Oracle's Programmer's Guide to Oracle Call Interface for Wrapped Oracle functions: OCILdaToSvcCtx
Parent topic: Miscellaneous Functions
Related concepts
Oracle API Functions Overview
Related reference
Ora8SvcCtxToLda Function
Ora8HandleFree Function
Ora8HandleAlloc Function
Ora8Init Function


LOB Functions

  • Ora8LobGetLength Function
    Gets the length of a LOB.
  • Ora8LobRead Function
    Reads a portion of a LOB/FILE, as specified by the call.
  • Ora8LobWrite Function
    Writes data into a LOB.
  • Ora8LobCreateTemporary Function
    Creates a temporary LOB.
  • Ora8LobOpen Function
    Opens a LOB, internal or external, in the specified mode.
  • Ora8LobWrite2 Function
    Writes data into a LOB.
Parent topic: Oracle 8 API Functions Overview


Ora8LobGetLength Function

Action

Gets the length of a LOB.

Include file

Ora8.bdh

Syntax

Ora8LobGetLength( in  hSvcCtx : number,
                  in  hLobLoc : number,
                  out nLength : number optional ) : boolean;

Return value

  • true if successful

  • false otherwise

Parameter | Description
hSvcCtx | An initialized service context handle.
hLobLoc | A LOB locator that references the LOB.
nLength | Variable receiving the length of the LOB (optional).

Example

var
  ghEnv0        : number;
  ghError0      : number;
  ghStmt0       : number;
  ghSvcCtx0     : number;
  ghDescriptor0 : number;

dcltrans
  transaction TMain
  var
    nLen : number;
  begin
    Ora8Init(ghEnv0, OCI_DEFAULT);
    Ora8HandleAlloc(ghEnv0, ghError0, OCI_HTYPE_ERROR);
    Ora8Logon(ghEnv0, ghSvcCtx0, "user", "password", "orclnet2");

    ...

    Ora8LobGetLength(ghSvcCtx0, ghDescriptor0, nLen);

    ...

    Ora8Logoff(ghSvcCtx0);
    Ora8HandleFree(ghError0, OCI_HTYPE_ERROR);
    Ora8HandleFree(ghEnv0, OCI_HTYPE_ENV);
  end TMain;

See also

Oracle's Programmer's Guide to Oracle Call Interface for Wrapped Oracle functions: OCILobGetLength
Parent topic: LOB Functions
Related reference
Ora8LobRead Function
Ora8LobWrite Function
Ora8LobCreateTemporary Function
Ora8LobOpen Function
Ora8LobWrite2 Function


Ora8LobRead Function

Action

Reads a portion of a LOB/FILE, as specified by the call.

Include file

Ora8.bdh

Syntax

Ora8LobRead( in  hSvcCtx       : number,
             in  hLobLoc       : number,
             in  nSizeOfPieces : number,
             in  nSizeToRead   : number,
             in  nStartOffset  : number,
             in  nCharsetID    : number optional,
             in  nCharsetForm  : number optional,
             out nCntRead      : number optional ) : boolean;

Return value

  • true if successful

  • false otherwise.

Parameter | Description
hSvcCtx | The service context handle.
hLobLoc | A LOB/FILE locator that references the LOB/FILE.
nSizeOfPieces | Size of pieces to read.
nSizeToRead | Cumulated size to read.
nStartOffset | Start offset for first piece.
nCharsetID | Charset ID (optional).
nCharsetForm | Charset form (optional).
nCntRead | Count read (optional).

Example

var
  ghEnv0        : number;
  ghError0      : number;
  ghStmt0       : number;
  ghSvcCtx0     : number;
  ghDescriptor0 : number;

dcltrans
  transaction TMain
  begin
    Ora8Init(ghEnv0, OCI_DEFAULT);
    Ora8HandleAlloc(ghEnv0, ghError0, OCI_HTYPE_ERROR);
    Ora8Logon(ghEnv0, ghSvcCtx0, "user", "password", "orclnet2");

    ...

    Ora8LobRead(ghSvcCtx0, ghDescriptor0, 500, 30000, 0);

    ...

    Ora8Logoff(ghSvcCtx0);
    Ora8HandleFree(ghError0, OCI_HTYPE_ERROR);
    Ora8HandleFree(ghEnv0, OCI_HTYPE_ENV);
  end TMain;

See also

Oracle's Programmer's Guide to Oracle Call Interface for Wrapped Oracle functions: OCILobRead
Parent topic: LOB Functions
Related reference
Ora8LobGetLength Function
Ora8LobWrite Function
Ora8LobCreateTemporary Function
Ora8LobOpen Function
Ora8LobWrite2 Function


Ora8LobWrite Function

Action

Writes data into a LOB.

Include file

Ora8.bdh

Syntax

Ora8LobWrite( in  hSvcCtx      : number,
              in  hLobLoc      : number,
              in  nSizeOfPieces: number,
              in  nSizeToWrite : number,
              in  nStartOffset : number,
              in  nCharsetID   : number optional,
              in  nCharsetForm : number optional,
              out nCntWritten  : number optional ) : boolean;

Return value

  • true if successful

  • false otherwise.

Parameter | Description
hSvcCtx | The service context handle.
hLobLoc | An internal LOB locator that references the LOB.
nSizeOfPieces | Size of pieces to write.
nSizeToWrite | Cumulated size to write.
nStartOffset | Start offset for first piece.
nCharsetID | Charset ID (optional).
nCharsetForm | Charset form (optional).
nCntWritten | Count written (optional).

Example

var
  ghEnv0        : number;
  ghError0      : number;
  ghStmt0       : number;
  ghSvcCtx0     : number;
  ghDescriptor0 : number;

dcltrans
  transaction TMain
  begin
    Ora8Init(ghEnv0, OCI_DEFAULT);
    Ora8HandleAlloc(ghEnv0, ghError0, OCI_HTYPE_ERROR);
    Ora8Logon(ghEnv0, ghSvcCtx0, "user", "password", "orclnet2");

    ...

    Ora8LobWrite(ghSvcCtx0, ghDescriptor0, 100, 30000, 0);

    ...

    Ora8Logoff(ghSvcCtx0);
    Ora8HandleFree(ghError0, OCI_HTYPE_ERROR);
    Ora8HandleFree(ghEnv0, OCI_HTYPE_ENV);
  end TMain;

See also

Oracle's Programmer's Guide to Oracle Call Interface for Wrapped Oracle functions: OCILobWrite
Parent topic: LOB Functions
Related reference
Ora8LobGetLength Function
Ora8LobRead Function
Ora8LobCreateTemporary Function
Ora8LobOpen Function
Ora8LobWrite2 Function


Ora8LobCreateTemporary Function

Action

Creates a temporary LOB.

Include file

Ora8.bdh

Syntax

Ora8LobCreateTemporary( in hSvcCtx      : number,
                        in hLobLoc      : number,
                        in nLobType     : number,
                        in nDuration    : number,
                        in bCache       : boolean ): boolean;

Return value

  • true if successful

  • false otherwise

Parameter | Description
hSvcCtx | The service context handle.
hLobLoc | An internal LOB locator that references the LOB.
nLobType

The type of LOB to create.

Valid values are:

  • OCI_TEMP_BLOB

  • OCI_TEMP_CLOB
nDuration

The duration of the temporary LOB.

Valid values are:

  • OCI_DURATION_SESSION

  • OCI_DURATION_CALL
bCache | Boolean flag whether or not the temporary LOB should be read into the cache.

Example

var
  ghEnv0        : number;
  ghError0      : number;
  ghStmt0       : number;
  ghSvcCtx0     : number;
  ghDescriptor0 : number;

dcltrans
  transaction TMain
  begin
    Ora8Init(ghEnv0, OCI_DEFAULT);
    Ora8HandleAlloc(ghEnv0, ghError0, OCI_HTYPE_ERROR);
    Ora8Logon(ghEnv0, ghSvcCtx0, "user", "password", "orclnet2");

    Ora8HandleAlloc(ghEnv0, ghStmt0, OCI_HTYPE_STMT);

    Ora8StmtPrepare(ghStmt0, TMain_SQL001, OCI_NTV_SYNTAX);
    Ora8DescriptorAlloc(ghEnv0, ghDescriptor0, OCI_DTYPE_LOB);
    Ora8LobCreateTemporary(ghSvcCtx0, ghDescriptor0, OCI_TEMP_BLOB, OCI_DURATION_SESSION, true);
    Ora8LobOpen(ghSvcCtx0, ghDescriptor0, OCI_LOB_READWRITE);
    Ora8LobWrite(ghSvcCtx0, ghDescriptor0, 9894, 9894, 1);

    Ora8Bind(ghStmt0, "1", SQLT_CHR, 5, 1, ORA_PLSQL_IN);                    //p_productid, in, number
    Ora8BindLob(ghStmt0, "2", SQLT_BLOB, 4, 1, ORA_PLSQL_IN, ghDescriptor0); //p_productimage, in, blob

    Ora8SetString(ghStmt0, "1", "2254"); //p_productid

    Ora8StmtExecute(ghSvcCtx0, ghStmt0, 1, 0, 0, 0, OCI_COMMIT_ON_SUCCESS);
    Ora8HandleFree(ghStmt0, OCI_HTYPE_STMT);
    Ora8Logoff(ghSvcCtx0);
    Ora8HandleFree(ghError0, OCI_HTYPE_ERROR);
    Ora8HandleFree(ghEnv0, OCI_HTYPE_ENV);
  end TMain;

 dclsql
  TMain_SQL001:
    [BEGIN setproductimage(:1,:2); END;]

See also

Oracle's Programmer's Guide to Oracle Call Interface for Wrapped Oracle functions: OCILobCreateTemporary
Parent topic: LOB Functions
Related reference
Ora8LobGetLength Function
Ora8LobRead Function
Ora8LobWrite Function
Ora8LobOpen Function
Ora8LobWrite2 Function
Ora8DescriptorAlloc Function
Ora8BindLob Function


Ora8LobOpen Function

Action

Opens a LOB, internal or external, in the specified mode.

Include file

Ora8.bdh

Syntax

Ora8LobOpen( in hSvcCtx : number,
             in hLobLoc : number,
             in nMode   : number ): boolean;

Return value

  • true if successful

  • false otherwise

Parameter | Description
hSvcCtx | The service context handle.
hLobLoc | An internal LOB locator that references the LOB.
nMode

The mode in which to open the LOB.

Valid modes are:

  • OCI_LOB_READONLY

  • OCI_LOB_READWRITE

Example

var
  ghEnv0        : number;
  ghError0      : number;
  ghStmt0       : number;
  ghSvcCtx0     : number;
  ghDescriptor0 : number;

dcltrans
  transaction TMain
  begin
    Ora8Init(ghEnv0, OCI_DEFAULT);
    Ora8HandleAlloc(ghEnv0, ghError0, OCI_HTYPE_ERROR);
    Ora8Logon(ghEnv0, ghSvcCtx0, "user", "password", "orclnet2");

    Ora8HandleAlloc(ghEnv0, ghStmt0, OCI_HTYPE_STMT);

    Ora8StmtPrepare(ghStmt0, TMain_SQL001, OCI_NTV_SYNTAX);
    Ora8DescriptorAlloc(ghEnv0, ghDescriptor0, OCI_DTYPE_LOB);
    Ora8LobCreateTemporary(ghSvcCtx0, ghDescriptor0, OCI_TEMP_BLOB, OCI_DURATION_SESSION, true);
    Ora8LobOpen(ghSvcCtx0, ghDescriptor0, OCI_LOB_READWRITE);
    Ora8LobWrite(ghSvcCtx0, ghDescriptor0, 9894, 9894, 1);

    Ora8Bind(ghStmt0, "1", SQLT_CHR, 5, 1, ORA_PLSQL_IN);                    //p_productid, in, number
    Ora8BindLob(ghStmt0, "2", SQLT_BLOB, 4, 1, ORA_PLSQL_IN, ghDescriptor0); //p_productimage, in, blob

    Ora8SetString(ghStmt0, "1", "2254"); //p_productid

    Ora8StmtExecute(ghSvcCtx0, ghStmt0, 1, 0, 0, 0, OCI_COMMIT_ON_SUCCESS);
    Ora8HandleFree(ghStmt0, OCI_HTYPE_STMT);
    Ora8Logoff(ghSvcCtx0);
    Ora8HandleFree(ghError0, OCI_HTYPE_ERROR);
    Ora8HandleFree(ghEnv0, OCI_HTYPE_ENV);
  end TMain;

dclsql
  TMain_SQL001:
    [BEGIN setproductimage(:1,:2); END;]

See also

Oracle's Programmer's Guide to Oracle Call Interface for Wrapped Oracle functions: OCILobOpen
Parent topic: LOB Functions
Related reference
Ora8LobGetLength Function
Ora8LobRead Function
Ora8LobWrite Function
Ora8LobCreateTemporary Function
Ora8LobWrite2 Function
Ora8DescriptorAlloc Function
Ora8BindLob Function


Ora8LobWrite2 Function

Action

Writes data into a LOB. The data to be written is read from the specified file.

Include file

Ora8.bdh

Syntax

Ora8LobWrite2( in  hSvcCtx       : number,
               in  hLobLoc       : number,
               in  nSizeOfPieces : number,
               in  sFile         : string,
               out nCntWritten   : number optional ): boolean;

Return value

  • true if successful

  • false otherwise

Parameter | Description
hSvcCtx | The service context handle.
hLobLoc | An internal LOB locator that references the LOB.
nSizeOfPieces | Size of pieces to write.
sFile | Name of the file containing the data.
nCntWritten | Count written (optional).

Example

var
  ghEnv0        : number;
  ghError0      : number;
  ghStmt0       : number;
  ghSvcCtx0     : number;
  ghDescriptor0 : number;

dcltrans
  transaction TMain
  begin
    Ora8Init(ghEnv0, OCI_DEFAULT);
    Ora8HandleAlloc(ghEnv0, ghError0, OCI_HTYPE_ERROR);
    Ora8Logon(ghEnv0, ghSvcCtx0, "user", "password", "orclnet2");

    ...

    Ora8LobWrite2(ghSvcCtx0, ghDescriptor0, 5278, "Descriptor_103292907.dat");

    ...

    Ora8Logoff(ghSvcCtx0);
    Ora8HandleFree(ghError0, OCI_HTYPE_ERROR);
    Ora8HandleFree(ghEnv0, OCI_HTYPE_ENV);
  end TMain;

See also

Oracle's Programmer's Guide to Oracle Call Interface for Wrapped Oracle functions: OCILobWrite
Parent topic: LOB Functions
Related reference
Ora8LobGetLength Function
Ora8LobRead Function
Ora8LobWrite Function
Ora8LobCreateTemporary Function
Ora8LobOpen Function
Ora8DescriptorAlloc Function


Error Handling Functions

  • Ora8OciError Function
    Retrieves the Oracle 8 OCI error code if an OCI error occurred during the last Silk Performer Oracle 8 API function call.
  • Ora8ApiError Function
    Retrieves the Silk Performer Oracle 8 API error code if an API error occurred during the last Silk Performer Oracle 8 API function call.
  • Ora8IgnoreError Function
    Specifies that a specific Oracle 8 OCI error is to be ignored if it occurs during the next Silk Performer Oracle 8 API function call.
Parent topic: Oracle 8 API Functions Overview


Ora8OciError Function

Action

Retrieves the Oracle 8 OCI error code if an OCI error occurred during the last Silk Performer Oracle 8 API function call.

Include file

Ora8.bdh

Syntax

Ora8OciError(): number;

Return value

Oracle 8 OCI error code.

A Silk Performer Oracle API error has occurred if a Silk Performer Oracle API function fails and the Ora8OciError returns 0. In this case, the OraApiError function can be used to retrieve the Silk Performer Oracle API error code.

Example

var
  ghEnv0        : number;
  ghError0      : number;
  ghStmt0       : number;
  ghSvcCtx0     : number;

dcltrans
  transaction TMain
  begin
    Ora8Init(ghEnv0, OCI_DEFAULT);
    Ora8HandleAlloc(ghEnv0, ghError0, OCI_HTYPE_ERROR);
    Ora8Logon(ghEnv0, ghSvcCtx0, "user", "password", "orclnet2");
    Ora8HandleAlloc(ghEnv0, ghStmt0, OCI_HTYPE_STMT);
    Ora8StmtPrepare(ghStmt0, sqlSelect, OCI_NTV_SYNTAX);

    // select row from non existing table
    Ora8IgnoreError(ghStmt0, 942);
    Ora8StmtExecute(ghSvcCtx0, ghStmt0);
    write("Oracle OCI error: "); write(Ora8OciError()); writeln;

    Ora8HandleFree(ghStmt0, OCI_HTYPE_STMT);
    Ora8Logoff(ghSvcCtx0);
    Ora8HandleFree(ghError0, OCI_HTYPE_ERROR);
    Ora8HandleFree(ghEnv0, OCI_HTYPE_ENV);
  end TMain;

dclsql
  sqlSelect:
    SELECT * FROM non_existing_table;

Output

Oracle OCI error: 942OCI-API Class 0 Error (Warning) 942 in Ora8StmtExecute:
ORA-00942: table or view does not exist
Parent topic: Error Handling Functions
Related reference
Ora8ApiError Function
Ora8IgnoreError Function


Ora8ApiError Function

Action

Retrieves the Silk Performer Oracle 8 API error code if an API error occurred during the last Silk Performer Oracle 8 API function call. A Silk Performer Oracle 8 API error occurs because of incorrect use of the Silk Performer Oracle 8 API and stops the simulation by default.

Include file

Ora8.bdh

Syntax

Ora8ApiError(): number;

Return value

Oracle 8 API error code

Example

var
  ghEnv0        : number;
  ghError0      : number;
  ghStmt0       : number;
  ghSvcCtx0     : number;

dcltrans
  transaction TMain
  begin
    Ora8Init(ghEnv0, OCI_DEFAULT);
    Ora8HandleAlloc(ghEnv0, ghError0, OCI_HTYPE_ERROR);
    Ora8Logon(ghEnv0, ghSvcCtx0, "user", "password", "orclnet2");
    Ora8HandleAlloc(ghEnv0, ghStmt0, OCI_HTYPE_STMT);
    Ora8StmtPrepare(ghStmt0, sqlInsert, OCI_NTV_SYNTAX);

    // array binding: three elements
    Ora8Bind(ghStmt0, ":name", SQLT_CHR, 32, 3);
    Ora8Bind(ghStmt0, ":age", SQLT_INT, 0, 3);

    // cause API error: index is too large
    Ora8SetString(ghStmt0, ":name", "Tom", 5);
    write("Oracle API error: "); write(Ora8ApiError()); writeln;

    Ora8StmtExecute(ghSvcCtx0, ghStmt0);

    Ora8HandleFree(ghStmt0, OCI_HTYPE_STMT);
    Ora8Logoff(ghSvcCtx0);
    Ora8HandleFree(ghError0, OCI_HTYPE_ERROR);
    Ora8HandleFree(ghEnv1, OCI_HTYPE_ENV);
  end TMain;

dclsql
  sqlInsert:
    INSERT INTO persons (name, age) VALUES (:name, :age);

Output

Oracle API error: 26
ORA-API Class 0 Error (Warning) 26 in Ora8Bind:
ORAAPI: 26 - Index in Ora8Set/Ora8Get function is larger than maximum
array size set in Ora8Bind.
Parent topic: Error Handling Functions
Related reference
Ora8OciError Function
Ora8IgnoreError Function


Ora8IgnoreError Function

Action

Specifies that a specific Oracle 8 OCI error is to be ignored if it occurs during the next Silk Performer Oracle 8 API function call. Since the error is then treated in the same way as a warning, the simulation will not be aborted.

Include file

Ora8.bdh

Syntax

Ora8IgnoreError( in hHandle    : number,
                 in nErrorCode : number ): boolean;

Return value

  • true if successful

  • false otherwise

Parameter | Description
hHandle | Handle.
nErrorCode | Oracle 8 OCI error code. This error will be treated as a class 0 error (warning) for the next Silk Performer Oracle 8 API call.

Example

var
  ghEnv0        : number;
  ghError0      : number;
  ghStmt0       : number;
  ghSvcCtx0     : number;

dcltrans
  transaction TMain
  begin
    Ora8Init(ghEnv0, OCI_DEFAULT);
    Ora8HandleAlloc(ghEnv0, ghError0, OCI_HTYPE_ERROR);
    Ora8Logon(ghEnv0, ghSvcCtx0, "user", "password", "orclnet2");
    Ora8HandleAlloc(ghEnv0, ghStmt0, OCI_HTYPE_STMT);
    Ora8StmtPrepare(ghStmt0, sqlDelete, OCI_NTV_SYNTAX);

    // ignore Oracle error 900: invalid SQL statement
    Ora8IgnoreError(ghStmt0, 942);

    // execute invalid SQL statement
    Ora8StmtExecute(ghSvcCtx0, ghStmt0);

    Ora8HandleFree(ghStmt0, OCI_HTYPE_STMT);
    Ora8Logoff(ghSvcCtx0);
    Ora8HandleFree(ghError0, OCI_HTYPE_ERROR);
    Ora8HandleFree(ghEnv0, OCI_HTYPE_ENV);
  end TMain;

dclsql
  sqlDelete:
    REMOVE FROM my_table;   // invalid SQL statement
Parent topic: Error Handling Functions
Related reference
Ora8OciError Function
Ora8ApiError Function


Oracle 8 Data Types

The following Oracle external data types are supported in Oracle functions:

  • SQLT_CHR - (ORANET TYPE) character string

  • SQLT_NUM - (ORANET TYPE) oracle numeric

  • SQLT_INT - (ORANET TYPE) integer

  • SQLT_FLT - (ORANET TYPE) floating-point number

  • SQLT_STR - zero-terminated string

  • SQLT_VNU - NUM with preceding length byte

  • SQLT_PDN - (ORANET TYPE) Packed Decimal Numeric

  • SQLT_LNG - long

  • SQLT_VCS - variable character string

  • SQLT_NON - null/empty PCC Descriptor entry

  • SQLT_RID - rowid

  • SQLT_DAT - date in Oracle format

  • SQLT_VBI - binary in VCS format

  • SQLT_BIN - binary data (DTYBIN)

  • SQLT_LBI - long binary

  • SQLT_UIN - unsigned integer

  • SQLT_SLS - display sign leading separate

  • SQLT_LVC - longer longs (char)

  • SQLT_LVB - longer long binary

  • SQLT_AFC - ANSI fixed char

  • SQLT_AVC - ANSI Var char

  • SQLT_CUR - cursor type

  • SQLT_LAB - label type

  • SQLT_OSL - oslabel type

  • SQLT_CLOB - Character LOB

  • SQLT_BLOB - Binary LOB

  • SQLT_BFILEE - Binary File LOB

  • SQLT_CFILEE - Character File LOB

  • SQLT_RSET - Result Set

Parent topic: Oracle 8 API Functions Overview
Related reference
Ora8Define Function
Ora8Bind Function


Binding Setting Functions

  • SetAutoBindCol Function
    Sets the Silk Performer autobindcol setting.
  • GetAutoBindCol Function
    Gets the value of the Silk Performer autobindcol setting.
Parent topic: Database (DBMS) Functions


SetAutoBindCol Function

Action

Sets the Silk Performer autobindcol setting.

Include file

Kernel.bdh

Syntax

SetAutoBindCol( in bAutoBind: boolean );
Parameter Description
bAutoBind

  • true. Automatic binding for columns in a SELECT clause of a SQL statement

  • false. No automatic binding for columns in a SELECT clause

Example

dcltrans
  transaction TSetAutoBindCol
  begin
    SetAutoBindCol(true);
    write("automatic binding for columns set"); writeln;
  end TSetAutoBindCol;

Output

automatic binding for columns set
Parent topic: Binding Setting Functions
Related concepts
Database (DBMS) Functions
Related reference
GetAutoBindCol Function


GetAutoBindCol Function

Action

Gets the value of the Silk Performer autobindcol setting.

Include file

Kernel.bdh

Syntax

GetAutoBindCol(): boolean;

Return value

  • true. Automatic binding for columns in a SELECT clause of a SQL statement will be performed. If you have not specified an INTO clause for the columns in the SELECT clause, columns will be bound to a Silk Performer buffer array automatically.

  • false. No automatic binding for columns in a SELECT clause.

Example

dcltrans
  transaction TGetAutoBindCol
  var
    bAutoBind: boolean;
  begin
    bAutoBind := GetAutoBindCol();
    if bAutoBind then
      write("automatic binding"); writeln;
    else
      write("no automatic binding"); writeln;
    end;
  end TGetAutoBindCol;

Output

automatic binding
Parent topic: Binding Setting Functions
Related concepts
Database (DBMS) Functions
Related reference
SetAutoBindCol Function


Result Set Functions Overview

To get generalized access to the result sets of different database APIs (generated with e.g. OraFetch, OdbcFetch, AdoFetch,…), which can be used within Silk Performer, you can use the result set functions.

These functions provide a common interface to retrieve data from the result sets and to apply verification functions, which rely on result set data.

Silk Performer provides the following scripting functions for such tasks:

  • Value Retrieving Functions
    Lists the value retrieving functions.
  • Verification Functions
    Lists the verification functions.
Parent topic: Database (DBMS) Functions
Related reference
OdbcFetch Function
OraFetch Function


Value Retrieving Functions

  • RsGetInt Function
    Retrieves a number value from the internal result set, which is filled whenever a data generating SQL statement is executed (SELECT statement), no matter which database API (ORA, ODBC) has generated it.
  • RsGetFloat Function
    Retrieves a floating-point value from the internal result set, which is filled whenever a data generating SQL statement is executed (SELECT statement), no matter which database API (ORA, ODBC) has generated it.
  • RsGetValue Function
    Retrieves any value from the internal result set, which is filled whenever a data generating SQL statement is executed (SELECT statement), no matter which database API (ORA, ODBC) has generated it.
  • RsGetString Function
    Retrieves a string from the internal result set, which is filled whenever a data generating SQL statement is executed (SELECT statement), no matter which database API (ORA, ODBC) has generated it.
  • RsGetString2 Function
    Retrieves a string from the internal result set, which is filled whenever a data generating SQL statement is executed (SELECT statement), no matter which database API (ORA, ODBC) has generated it.
  • RsIsNull Function
    Checks whether the value from the internal result set, which is filled whenever a data generating SQL statement is executed (SELECT statement) no matter which database API (ORA, ODBC) has generated it, is null.
  • RsRows Function
    Retrieves the number of rows in the internal result set, which is filled whenever a data generating SQL statement is executed (SELECT statement), no matter which database API (ORA, ODBC) has generated it.
  • RsCols Function
    Retrieves the number of columns in the internal result set, which is filled whenever a data generating SQL statement is executed (SELECT statement), no matter which database API (ORA, ODBC) has generated it.
Parent topic: Result Set Functions Overview


RsGetInt Function

Action

Retrieves a number value from the internal result set, which is filled whenever a data generating SQL statement is executed (SELECT statement), no matter which database API (ORA, ODBC) has generated it.

Include file

db.bdh

Syntax

RsGetInt( in  sIdentifier : string,
          in  nIndex      : number optional,
          out nResultCode : number optional ): number;

Return value

  • Returns the number value of the chosen item in the result set.
Parameter | Description
sIdentifier | Identifier of the result data column.
nIndex | Array index for the column item (optional).
nResultCode

Variable receiving the result code of the operation (optional). It can be one of the following:

  • RS_RESULTCODE_SUCCESS: function succeeded

  • RS_RESULTCODE_INVALID_INPUTPARAMETER: invalid input parameter

  • RS_RESULTCODE_INVLAID_COLUMN: the 'sIdentifier' is invalid

  • RS_RESULTCODE_INVALID_CELL: there exists no item at the chosen position

Example

var
  hConnection : number;
  cCursor     : cursor;

dcltrans
  transaction TMain
  var
    nAge  : number;
    sName : string;
  begin
    OraLogon(hConnection, "user", "password", "orclnet2");
    OraOpen(cCursor, hConnection);
    OraParse(cCursor, sqlSelect);
    OraBind(cCursor, ":1", SQLT_INT);
    OraSetInt(cCursor, ":1", 25);
    OraDefine(cCursor, 1, SQLT_CHR, 32);
    OraDefine(cCursor, 2, SQLT_INT);
    OraExec(cCursor);

    while OraFetch(cCursor) do
      sName := RsGetString("1");
      nAge  := RsGetInt("2");
      write(sName, 32); write(nAge, 5); writeln;
    end;

    OraClose(cCursor);
    OraLogoff(hConnection);
  end TMain;

dclsql
  sqlSelect:
  SELECT * FROM persons WHERE age > :1;
Parent topic: Value Retrieving Functions
Related reference
RsGetFloat Function
RsGetValue Function
RsGetString Function
RsGetString2 Function
RsIsNull Function
RsRows Function
RsCols Function
RsVerifyInt Function


RsGetFloat Function

Action

Retrieves a floating-point value from the internal result set, which is filled whenever a data generating SQL statement is executed (SELECT statement), no matter which database API (ORA, ODBC) has generated it.

Include file

db.bdh

Syntax

RsGetFloat( in sIdentifier : string,
            in  nIndex      : number optional,
            out nResultCode : number optional ): float;

Return value

  • Returns the floating-point value of the chosen item in the result set.
Parameter | Description
sIdentifier | Identifier of the result data column.
nIndex | Array index for the column item (optional).
nResultCode

Variable receiving the result code of the operation (optional). It can be one of the following:

  • RS_RESULTCODE_SUCCESS: function succeeded

  • RS_RESULTCODE_INVALID_INPUTPARAMETER: invalid input parameter

  • RS_RESULTCODE_INVLAID_COLUMN: the 'sIdentifier' is invalid

  • RS_RESULTCODE_INVALID_CELL: there exists no item at the chosen position

Example

var
  hConnection : number;
  cCursor     : cursor;

dcltrans
  transaction TMain
  var
    sName    : string;
    fBalance : float;
  begin
    OraLogon(hConnection, "user", "password", "orclnet2");
    OraOpen(cCursor, hConnection);
    OraParse(cCursor, sqlSelect);
    OraBind(cCursor, ":1", SQLT_FLT);
    OraSetFloat(cCursor, ":1", 2000.0);
    OraDefine(cCursor, 1, SQLT_CHR, 32);
    OraDefine(cCursor, 2, SQLT_FLT);    OraExec(cCursor);

    while OraFetch(cCursor) do
      sName    := RsGetString("1");
      fBalance := RsGetFloat("2");
      write(sName, 32); write(fBalance); writeln;
    end;

    OraClose(cCursor);
    OraLogoff(hConnection);
  end TMain;

dclsql
  sqlSelect:
  SELECT * FROM accounts WHERE balance > :1;
Parent topic: Value Retrieving Functions
Related reference
RsGetInt Function
RsGetValue Function
RsGetString Function
RsGetString2 Function
RsIsNull Function
RsRows Function
RsCols Function
RsVerifyFloat Function


RsGetValue Function

Action

Retrieves any value from the internal result set, which is filled whenever a data generating SQL statement is executed (SELECT statement), no matter which database API (ORA, ODBC) has generated it.

Include file

db.bdh

Syntax

RsGetValue( out sResult       : string,
            in  nResultMaxLen : number,
            in  sIdentifier   : string,
            in  nIndex        : number optional,
            out nResultCode   : number optional ): boolean;

Return value

  • Returns true if successfull,
  • false otherwise
Parameter | Description
sResult | Variable receiving the data retrieved from a fetched row.
nResultMaxLen | Size of the variable receiving the value.
sIdentifier | Identifier of the result data column.
nIndex | Array index for the column item (optional).
nResultCode

Variable receiving the result code of the operation (optional). It can be one of the following:

  • RS_RESULTCODE_SUCCESS: function succeeded

  • RS_RESULTCODE_INVALID_INPUTPARAMETER: invalid input parameter

  • RS_RESULTCODE_INVLAID_COLUMN: the 'sIdentifier' is invalid

  • RS_RESULTCODE_INVALID_CELL: there exists no item at the chosen position

Example

var
  hConnection : number;
  cCursor     : cursor;

dcltrans
  transaction TMain
  var
    nAge  : number;
    sName : string;
  begin
    OraLogon(hConnection, "user", "password", "orclnet2");
    OraOpen(cCursor, hConnection);
    OraParse(cCursor, sqlSelect);
    OraBind(cCursor, ":1", SQLT_INT);
    OraSetInt(cCursor, ":1", 25);
    OraDefine(cCursor, 1, SQLT_CHR, 32);
    OraDefine(cCursor, 2, SQLT_INT);
    OraExec(cCursor);

    while OraFetch(cCursor) do
      RsGetValue(sName, STRING_COMPLETE, "1");
      nAge  := RsGetInt("2");
      write(sName, 32); write(nAge, 5); writeln;
    end;

    OraClose(cCursor);
    OraLogoff(hConnection);
  end TMain;

dclsql
  sqlSelect:
  SELECT * FROM persons WHERE age > :1;
Parent topic: Value Retrieving Functions
Related reference
RsGetInt Function
RsGetFloat Function
RsGetString Function
RsGetString2 Function
RsIsNull Function
RsRows Function
RsCols Function
RsVerifyValue Function


RsGetString Function

Action

Retrieves a string from the internal result set, which is filled whenever a data generating SQL statement is executed (SELECT statement), no matter which database API (ORA, ODBC) has generated it.

Include file

db.bdh

Syntax

RsGetString( in  sIdentifier : string,
             in  nIndex      : number optional,
             out nResultCode : number optional ): string;

Return value

  • Returns the number value of the chosen item in the result set.
Parameter | Description
sIdentifier | Identifier of the result data column.
nIndex | Array index for the column item (optional).
nResultCode

Variable receiving the result code of the operation (optional). It can be one of the following:

  • RS_RESULTCODE_SUCCESS: function succeeded

  • RS_RESULTCODE_INVALID_INPUTPARAMETER: invalid input parameter

  • RS_RESULTCODE_INVLAID_COLUMN: the 'sIdentifier' is invalid

  • RS_RESULTCODE_INVALID_CELL: there exists no item at the chosen position

Example

var
  hConnection : number;
  cCursor     : cursor;

 dcltrans
  transaction TMain
  var
    nAge  : number;
    sName : string;
  begin
    OraLogon(hConnection, "user", "password", "orclnet2");
    OraOpen(cCursor, hConnection);
    OraParse(cCursor, sqlSelect);
    OraBind(cCursor, ":1", SQLT_INT);
    OraSetInt(cCursor, ":1", 25);
    OraDefine(cCursor, 1, SQLT_CHR, 32);
    OraDefine(cCursor, 2, SQLT_INT);
    OraExec(cCursor);

    while OraFetch(cCursor) do
      sName := RsGetString("1");
      nAge  := RsGetInt("2");
      write(sName, 32); write(nAge, 5); writeln;
    end;

    OraClose(cCursor);
    OraLogoff(hConnection);
  end TMain;

 dclsql
  sqlSelect:
  SELECT * FROM persons WHERE age > :1;
Parent topic: Value Retrieving Functions
Related reference
RsGetInt Function
RsGetFloat Function
RsGetValue Function
RsGetString2 Function
RsIsNull Function
RsRows Function
RsCols Function
RsVerifyString Function


RsGetString2 Function

Action

Retrieves a string from the internal result set, which is filled whenever a data generating SQL statement is executed (SELECT statement), no matter which database API (ORA, ODBC) has generated it.

Include file

db.bdh

Syntax

RsGetString2( out sResult       : string,
              in  nResultMaxLen : number,
              in  sIdentifier   : string,
              in  nIndex        : number optional,
              out nResultCode   : number optional ): boolean;

Return value

  • true if successful
  • false otherwise
Parameter | Description
sResult | Variable receiving the data retrieved from a fetched row.
nResultMaxLen | Size of the variable receiving the value.
sIdentifier | Identifier of the result data column.
nIndex | Array index for the column item (optional).
nResultCode

Variable receiving the result code of the operation (optional). It can be one of the following:

  • RS_RESULTCODE_SUCCESS: function succeeded

  • RS_RESULTCODE_INVALID_INPUTPARAMETER: invalid input parameter

  • RS_RESULTCODE_INVLAID_COLUMN: the 'sIdentifier' is invalid

  • RS_RESULTCODE_INVALID_CELL: there exists no item at the chosen position

Example

var
  hConnection : number;
  cCursor     : cursor;

dcltrans
  transaction TMain
  var
    nAge  : number;
    sName : string;
  begin
    OraLogon(hConnection, "user", "password", "orclnet2");
    OraOpen(cCursor, hConnection);
    OraParse(cCursor, sqlSelect);
    OraBind(cCursor, ":1", SQLT_INT);
    OraSetInt(cCursor, ":1", 25);
    OraDefine(cCursor, 1, SQLT_CHR, 32);
    OraDefine(cCursor, 2, SQLT_INT);
    OraExec(cCursor);

    while OraFetch(cCursor) do
      RsGetString2(sName, STRING_COMPLETE, "1");
      nAge  := RsGetInt("2");
      write(sName, 32); write(nAge, 5); writeln;
    end;

    OraClose(cCursor);
    OraLogoff(hConnection);
  end TMain;

dclsql
  sqlSelect:
  SELECT * FROM persons WHERE age > :1;
Parent topic: Value Retrieving Functions
Related reference
RsGetInt Function
RsGetFloat Function
RsGetValue Function
RsGetString Function
RsIsNull Function
RsRows Function
RsCols Function
RsVerifyString Function


RsIsNull Function

Action

Checks whether the value from the internal result set, which is filled whenever a data generating SQL statement is executed (SELECT statement) no matter which database API (ORA, ODBC) has generated it, is null.

Include file

db.bdh

Syntax

RsIsNull( in sIdentifier : string,
          in nIndex      : number optional): boolean;

Return value

  • true if the value is null,
  • false otherwise.
Parameter | Description
sIdentifier | Identifier of the result data column.
nIndex | Array index for the column item (optional).

Example

var
  hConnection : number;
  cCursor     : cursor;

dcltrans
  transaction TMain
  var
    nAge  : number;
    sName : string;
  begin
    OraLogon(hConnection, "user", "password", "orclnet2");
    OraOpen(cCursor, hConnection);    OraParse(cCursor, sqlSelect);
    OraBind(cCursor, ":1", SQLT_INT);
    OraSetInt(cCursor, ":1", 25);
    OraDefine(cCursor, 1, SQLT_CHR, 32);
    OraDefine(cCursor, 2, SQLT_INT);
    OraExec(cCursor);

    while OraFetch(cCursor) do

      if ( not RsIsNull("1")) then
        sName := RsGetString("1");
      end;

      fBalance := RsGetFloat("2");
      write(sName, 32); write(nAge, 5); writeln;
    end;

    OraClose(cCursor);
    OraLogoff(hConnection);
  end TMain;

dclsql
  sqlSelect:
  SELECT * FROM persons WHERE age > :1;
Parent topic: Value Retrieving Functions
Related reference
RsGetInt Function
RsGetFloat Function
RsGetValue Function
RsGetString Function
RsGetString2 Function
RsRows Function
RsCols Function
RsVerifyNull Function


RsRows Function

Action

Retrieves the number of rows in the internal result set, which is filled whenever a data generating SQL statement is executed (SELECT statement), no matter which database API (ORA, ODBC) has generated it.

Include file

db.bdh

Syntax

RsRows(): number;

Return value

  • Number of rows in the result set.

Example

var
  hConnection : number;
  cCursor     : cursor;

dcltrans
  transaction TMain
  var
    nRows : number;
  begin
    OraLogon(hConnection, "user", "password", "orclnet2");
    OraOpen(cCursor, hConnection);
    OraParse(cCursor, sqlSelect);
    OraBind(cCursor, ":1", SQLT_INT);

    OraSetFloat(cCursor, ":1", 2000.0);
    OraDefine(cCursor, 1, SQLT_CHR, 32);
    OraDefine(cCursor, 2, SQLT_FLT);
    OraExec(cCursor);
    OraFetch(cCursor, ORA_FETCH_ALL);
    nRows := RsRows();

    OraClose(cCursor);
    OraLogoff(hConnection);
  end TMain;

dclsql
  sqlSelect:
  SELECT * FROM accounts WHERE balance > :1;
Parent topic: Value Retrieving Functions
Related reference
RsGetInt Function
RsGetFloat Function
RsGetValue Function
RsGetString Function
RsGetString2 Function
RsIsNull Function
RsCols Function
RsVerifyRowCount Function


RsCols Function

Action

Retrieves the number of columns in the internal result set, which is filled whenever a data generating SQL statement is executed (SELECT statement), no matter which database API (ORA, ODBC) has generated it.

Include file

db.bdh

Syntax

RsCols(): number;

Return value

  • Number of columns in the result set

Example

var
  hConnection : number;
  cCursor     : cursor;

dcltrans
  transaction TMain
  var
    nCols : number;
  begin
    OraLogon(hConnection, "user", "password", "orclnet2");
    OraOpen(cCursor, hConnection);
    OraParse(cCursor, sqlSelect);
    OraBind(cCursor, ":1", SQLT_FLT);
    OraSetFloat(cCursor, ":1", 2000.0);
    OraDefine(cCursor, 1, SQLT_CHR, 32);
    OraDefine(cCursor, 2, SQLT_FLT);
    OraExec(cCursor);
    OraFetch(cCursor, ORA_FETCH_ALL);
    nCols := RsCols();

    OraClose(cCursor);
    OraLogoff(hConnection);
  end TMain;

dclsql
  sqlSelect:
  SELECT * FROM accounts WHERE balance > :1;
Parent topic: Value Retrieving Functions
Related reference
RsGetInt Function
RsGetFloat Function
RsGetValue Function
RsGetString Function
RsGetString2 Function
RsIsNull Function
RsRows Function
RsVerifyRowCount Function


Verification Functions

  • RsVerifyFloat Function
    Verifies a floating-point element at a given row/column within the internal result set, which is filled whenever a data generating SQL statement is executed (SELECT statement), no matter which database API (ORA, ODBC) has generated it.
  • RsVerifyInt Function
    Verifies a number element at a given row/column within the internal result set, which is filled whenever a data generating SQL statement is executed (SELECT statement), no matter which database API (ORA, ODBC) has generated it.
  • RsVerifyNull Function
    Verifies, that an element is null at a given row/column within the internal result set, which is filled whenever a data generating SQL statement is executed (SELECT statment), no matter which database API (ORA, ODBC) has generated it.
  • RsVerifyRowCount Function
    Checks whether the internal result set, which is filled whenever a data generating SQL statement is executed (SELECT statement), no matter which database API (ORA, ODBC) has generated it, has a specific amount of rows.
  • RsVerifyString Function
    Verifies a string element at a given row/column within the internal result set, which is filled whenever a data generating SQL statement is executed (SELECT statement), no matter which database API (ORA, ODBC) has generated it.
  • RsVerifyValue Function
    Verifies a binary element at a given row/column within the internal result set, which is filled whenever a data generating SQL statement is executed (SELECT statement), no matter which database API (ORA, ODBC) has generated it.
Parent topic: Result Set Functions Overview


RsVerifyFloat Function

Action

Verifies a floating-point element at a given row/column within the internal result set, which is filled whenever a data generating SQL statement is executed (SELECT statement), no matter which database API (ORA, ODBC) has generated it.

Include file

db.bdh

Syntax

RsVerifyFloat( in fVerify     : float,
               in sIdentifier : string,
               in nIndex      : number optional,
               in nOptions    : number optional,
               in nSeverity   : number optional ): boolean;

Return value

  • true if verification was performed successfully,
  • false otherwise
Parameter | Description
fVerify | Floating-point value to verify.
sIdentifier | Identifier of the result data column.
nIndex | Array index for the column item (optional).
nOptions

Options (optional).

  • DB_FLAG_NONE (default)

nSeverity Optional: Severity of the error that is raised if the verification fails. Can be one of the following values:
  • SEVERITY_SUCCESS: Success; no error (numerical value: 0)
  • SEVERITY_INFORMATIONAL: Informational; no error (numerical value: 1)
  • SEVERITY_WARNING: Warning; no error (numerical value: 2)
  • SEVERITY_ERROR: (Default) Error; simulation continues (numerical value: 3)
  • SEVERITY_TRANS_EXIT: Error; the active transaction is aborted (numerical value: 4)
  • SEVERITY_PROCESS_EXIT: Error; the simulation is aborted (numerical value: 5)

Example

var
  hConnection : number;
  cCursor     : cursor;

dcltrans
  transaction TMain
  var
    sName : string;
  begin
    OraLogon(hConnection, "user", "password", "orclnet2");
    OraOpen(cCursor, hConnection);
    OraParse(cCursor, sqlSelect);
    OraBind(cCursor, ":1", QLT_INT);
    OraSetInt(cCursor, ":1", 25);
    OraDefine(cCursor, 1, SQLT_CHR, 32);
    OraDefine(cCursor, 2, SQLT_FLT);
    OraExec(cCursor);

    while OraFetch(cCursor) do
      sName := RsGetString("1");
      RsVerifyFloat(1.5, "2");
    end;

    OraClose(cCursor);
    OraLogoff(hConnection);
  end TMain;

dclsql
  sqlSelect:
  SELECT * FROM persons WHERE age > :1;
Parent topic: Verification Functions
Related reference
RsGetFloat Function


RsVerifyInt Function

Action

Verifies a number element at a given row/column within the internal result set, which is filled whenever a data generating SQL statement is executed (SELECT statement), no matter which database API (ORA, ODBC) has generated it.

Include file

db.bdh

Syntax

RsVerifyInt( in nVerify     : number,
             in sIdentifier : string,
             in nIndex      : number optional,
             in nOptions    : number optional,
             in nSeverity   : number optional ): boolean;

Return value

  • true if verification was performed successfully,
  • false otherwise
Parameter | Description
nVerify | Number value to verify.
sIdentifier | Identifier of the result data column.
nIndex | Array index for the column item (optional).
nOptions

Options (optional).

  • DB_FLAG_NONE (default)

nSeverity Optional: Severity of the error that is raised if the verification fails. Can be one of the following values:
  • SEVERITY_SUCCESS: Success; no error (numerical value: 0)
  • SEVERITY_INFORMATIONAL: Informational; no error (numerical value: 1)
  • SEVERITY_WARNING: Warning; no error (numerical value: 2)
  • SEVERITY_ERROR: (Default) Error; simulation continues (numerical value: 3)
  • SEVERITY_TRANS_EXIT: Error; the active transaction is aborted (numerical value: 4)
  • SEVERITY_PROCESS_EXIT: Error; the simulation is aborted (numerical value: 5)

Example

var
  hConnection : number;
  cCursor     : cursor;

dcltrans
  transaction TMain
  var
    nAge  : number;
    sName : string;
  begin
    OraLogon(hConnection, "user", "password", "orclnet2");
    OraOpen(cCursor, hConnection);
    OraParse(cCursor, sqlSelect);
    OraBind(cCursor, ":1", SQLT_INT);
    OraSetInt(cCursor, ":1", 25);
    OraDefine(cCursor, 1, SQLT_CHR, 32);
    OraDefine(cCursor, 2, SQLT_INT);
    OraExec(cCursor);

    while OraFetch(cCursor) do
      sName := RsGetString("1");
      RsVerifyInt(10, "2");
      write(sName, 32); write(nAge, 5); writeln;
    end;

    OraClose(cCursor);
    OraLogoff(hConnection);
  end TMain;

dclsql
  sqlSelect:
  SELECT * FROM persons WHERE age > :1;
Parent topic: Verification Functions
Related reference
RsGetInt Function


RsVerifyNull Function

Action

Verifies, that an element is null at a given row/column within the internal result set, which is filled whenever a data generating SQL statement is executed (SELECT statment), no matter which database API (ORA, ODBC) has generated it.

Include file

db.bdh

Syntax

RsVerifyNull( in sIdentifier : string,
              in nIndex      : number optional,
              in nOptions    : number optional,
              in nSeverity   : number optional ): boolean;

Return value

  • true if verification was performed successfully,
  • false otherwise
Parameter | Description
sIdentifier | Identifier of the result data column.
nIndex | Array index for the column item (optional).
nOptions

Options. Can be one of the following (optional):

  • DB_FLAG_NONE (default)

nSeverity Optional: Severity of the error that is raised if the verification fails. Can be one of the following values:
  • SEVERITY_SUCCESS: Success; no error (numerical value: 0)
  • SEVERITY_INFORMATIONAL: Informational; no error (numerical value: 1)
  • SEVERITY_WARNING: Warning; no error (numerical value: 2)
  • SEVERITY_ERROR: (Default) Error; simulation continues (numerical value: 3)
  • SEVERITY_TRANS_EXIT: Error; the active transaction is aborted (numerical value: 4)
  • SEVERITY_PROCESS_EXIT: Error; the simulation is aborted (numerical value: 5)

Example

var
  hConnection : number;
  cCursor     : cursor;

dcltrans
  transaction TMain
  begin
    OraLogon(hConnection, "user", "password", "orclnet2");
    OraOpen(cCursor, hConnection);
    OraParse(cCursor, sqlSelect);
    OraBind(cCursor, ":1", SQLT_INT);
    OraSetInt(cCursor, ":1", 25);
    OraDefine(cCursor, 1, SQLT_CHR, 32);
    OraExec(cCursor);

    while OraFetch(cCursor) do
      RsVerifyNull("1");
    end;

    OraClose(cCursor);
    OraLogoff(hConnection);
  end TMain;

dclsql
  sqlSelect:
  SELECT * FROM persons WHERE age > :1;
Parent topic: Verification Functions
Related reference
RsIsNull Function


RsVerifyRowCount Function

Action

Checks whether the internal result set, which is filled whenever a data generating SQL statement is executed (SELECT statement), no matter which database API (ORA, ODBC) has generated it, has a specific amount of rows.

Include file

db.bdh

Syntax

RsVerifyRowCount( in  nRows     : number,
                  in  nOptions  : number optional,
                  in  nSeverity : number optional,
                  out nActRows  : number optional ): boolean;

Return value

  • true if verification was performed successfully,
  • false otherwise
Parameter | Description
nRows | Number of rows to verify.
nOptions Specifies the relation of the given result row count and the row count of the received data (optional).

Can be one of the following:

  • DB_FLAG_EQUAL (default)

  • DB_FLAG_LESSEQUAL

  • DB_FLAG_GREATEREQUAL

nSeverity Optional: Severity of the error that is raised if the verification fails. Can be one of the following values:
  • SEVERITY_SUCCESS: Success; no error (numerical value: 0)
  • SEVERITY_INFORMATIONAL: Informational; no error (numerical value: 1)
  • SEVERITY_WARNING: Warning; no error (numerical value: 2)
  • SEVERITY_ERROR: (Default) Error; simulation continues (numerical value: 3)
  • SEVERITY_TRANS_EXIT: Error; the active transaction is aborted (numerical value: 4)
  • SEVERITY_PROCESS_EXIT: Error; the simulation is aborted (numerical value: 5)
nActRows | If this variable is provided, it will receive the actual number of rows (optional).

Example

var
  hConnection : number;
  cCursor     : cursor;

dcltrans
  transaction TMain
  var
    nAge : number;
  begin
    OraLogon(hConnection, "user", "password", "orclnet2");
    OraOpen(cCursor, hConnection);
    OraParse(cCursor, sqlSelect);
    OraBind(cCursor, ":1", SQLT_INT);
    OraSetInt(cCursor, ":1", 25);
    OraDefine(cCursor, 1, SQLT_CHR, 32);
    OraDefine(cCursor, 2, SQLT_INT);
    OraExec(cCursor);
    OraFetch(cCursor, ORA_FETCH_ALL);

    if ( not RsVerifyRowCount(10, 0, SEVERITY_WARNING) ) then
      writeln("Wrong row count!!!");
    end;

    nAge := RsGetInt("2");
    OraClose(cCursor);
    OraLogoff(hConnection);
  end TMain;

dclsql
  sqlSelect:
  SELECT * FROM persons WHERE age > :1;
Parent topic: Verification Functions
Related reference
RsRows Function
RsCols Function


RsVerifyString Function

Action

Verifies a string element at a given row/column within the internal result set, which is filled whenever a data generating SQL statement is executed (SELECT statement), no matter which database API (ORA, ODBC) has generated it.

Include file

db.bdh

Syntax

RsVerifyString( in sVerify     : string,
                in sIdentifier : string,
                in nIndex      : number optional,
                in nOptions    : number optional,
                in nSeverity   : number optional ): boolean;

Return value

  • true if verification was performed successfully,
  • false otherwise
Parameter | Description
sVerify | String value to verify.
sIdentifier | Identifier of the result data column.
nIndex | Array index for the column item (optional).
nOptions

Options. Can be one of the following (optional):

  • DB_FLAG_NONE (default)

  • DB_FLAG_CASE_SENSITIVE

nSeverity Optional: Severity of the error that is raised if the verification fails. Can be one of the following values:
  • SEVERITY_SUCCESS: Success; no error (numerical value: 0)
  • SEVERITY_INFORMATIONAL: Informational; no error (numerical value: 1)
  • SEVERITY_WARNING: Warning; no error (numerical value: 2)
  • SEVERITY_ERROR: (Default) Error; simulation continues (numerical value: 3)
  • SEVERITY_TRANS_EXIT: Error; the active transaction is aborted (numerical value: 4)
  • SEVERITY_PROCESS_EXIT: Error; the simulation is aborted (numerical value: 5)

Example

var
  hConnection : number;
  cCursor     : cursor;

dcltrans
  transaction TMain
  begin
    OraLogon(hConnection, "user", "password", "orclnet2");
    OraOpen(cCursor, hConnection);
    OraParse(cCursor, sqlSelect);
    OraBind(cCursor, ":1", SQLT_INT);
    OraSetInt(cCursor, ":1", 25);
    OraDefine(cCursor, 1, SQLT_CHR, 32);
    OraExec(cCursor);

    while OraFetch(cCursor) do
      RsVerifyString("Jones", "1");
    end;

    OraClose(cCursor);
    OraLogoff(hConnection);
  end TMain;

dclsql
  sqlSelect:
  SELECT * FROM persons WHERE age > :1;
Parent topic: Verification Functions
Related reference
RsGetString Function
RsGetString2 Function


RsVerifyValue Function

Action

Verifies a binary element at a given row/column within the internal result set, which is filled whenever a data generating SQL statement is executed (SELECT statement), no matter which database API (ORA, ODBC) has generated it.

Include file

db.bdh

Syntax

RsVerifyValue( in sVerify     : string,
               in nVerifyLen  : number,
               in sIdentifier : string,
               in nIndex      : number optional,
               in nOptions    : number optional,
               in nSeverity   : number optional ): boolean;

Return value

  • true if verification was performed successfully,
  • false otherwise
Parameter | Description
sVerify | Binary value to verify.
nVerifyLen | Length of the binary value to verify.
sIdentifier | Identifier of the result data column.
nIndex | Array index for the column item (optional).
nOptions

Options (optional).

  • DB_FLAG_NONE (default)

nSeverity Optional: Severity of the error that is raised if the verification fails. Can be one of the following values:
  • SEVERITY_SUCCESS: Success; no error (numerical value: 0)
  • SEVERITY_INFORMATIONAL: Informational; no error (numerical value: 1)
  • SEVERITY_WARNING: Warning; no error (numerical value: 2)
  • SEVERITY_ERROR: (Default) Error; simulation continues (numerical value: 3)
  • SEVERITY_TRANS_EXIT: Error; the active transaction is aborted (numerical value: 4)
  • SEVERITY_PROCESS_EXIT: Error; the simulation is aborted (numerical value: 5)

Example

var
  hConnection : number;
  cCursor     : cursor;

dcltrans
  transaction TMain
  begin
    OraLogon(hConnection, "user", "password", "orclnet2");
    OraOpen(cCursor, hConnection);
    OraParse(cCursor, sqlSelect);
    OraBind(cCursor, ":1", SQLT_INT);
    OraSetInt(cCursor, ":1", 25);
    OraDefine(cCursor, 1, SQLT_CHR, 32);
    OraExec(cCursor);

    while OraFetch(cCursor) do
      RsVerifyValue("\h8ADB4720A47CC8", 8, "1");
    end;

    OraClose(cCursor);
    OraLogoff(hConnection);
  end TMain;

dclsql
  sqlSelect:
  SELECT * FROM persons WHERE age > :1;
Parent topic: Verification Functions
Related reference
RsGetValue Function


ERP/CRM Functions

  • Remedy Functions Reference
    Lists the functions for testing BMC Remedy IT Service Management.
  • SAP Functions
    Lists the function groups offered for SAP testing.
  • Siebel Functions Overview
    Lists the Siebel functions.
  • PeopleSoft Overview
    Describes Silk Performer support for load testing PeopleSoft applications.
Parent topic: Benchmark Description Language (BDL) Reference


Remedy Functions Reference

Silk Performer provides functions for testing BMC Remedy IT Service Management.

  • RemedyInit Function
    Initializes Remedy Web support by installing global verification rules to catch application level errors.
  • RemedyBackChannelData Function
    Assembles a Remedy data string from the provided XML data.
  • WebRemedyBackChannelUrl Function
    Performs a WebPageUrl function call and converts the form data from an XML representation to the native Remedy BackChannel representation.
  • WebRemedyBackChannelPost Function
    Performs a WebPagePost to the server and converts the post data from an XML representation to the native Remedy BackChannel representation.
Parent topic: ERP/CRM Functions


RemedyInit Function

Action

This function initializes Remedy Web support by installing global verification rules to catch application level errors.
Note: This function is only available with Remedy projects.

Include file

Remedy.bdh

Syntax

RemedyInit( );

Example

dcltrans
transaction TInit
  begin
    RemedyInit();
  end TInit;
Parent topic: Remedy Functions Reference
Related reference
RemedyBackChannelData Function
WebRemedyBackChannelUrl Function
WebRemedyBackChannelPost Function


RemedyBackChannelData Function

Action

Assembles a Remedy data string from the provided XML data.
Note: This function is only available with Remedy projects.

Include file

Remedy.bdh

Syntax

RemedyBackChannelData( in sXmlData : string ): string;

Return value

Remedy data string to be used by functions WebPagePost and WebPageUrl.

Parameter | Description
sXmlData | XML representation of Remedy data to be submitted to the server.

Example

dcltrans
transaction TParam
begin
  Writeln(RemedyBackChannelData("<RemedyXml operation=\"GetURLForForm\">\r\n"
     "  <string name=\"server\">lab50</string>\r\n"
     "  <string name=\"app_name\"></string>\r\n"
     "  <string name=\"form\">Sample:Cities</string>\r\n"
     "  <string name=\"view\"></string>\r\n"
     "  <bool name=\"fetch_dimensions\">0</bool>\r\n"
     "  <string name=\"win_name\">lab50Sample:CitiesARRoot</string>\r\n"
     "  <string name=\"win_arg\">window.openingArgs={fvlist:{},wMode:&quot;2&quot;,wForceClear:1,fvSetDefaults:0};</string>\r\n"
     "</RemedyXml>"));
end TParam;
Parent topic: Remedy Functions Reference
Related reference
RemedyInit Function
WebRemedyBackChannelUrl Function
WebRemedyBackChannelPost Function
WebPageUrl Function
WebPagePost Function


WebRemedyBackChannelUrl Function

Action

This function converts an XML representation of data, which is contained in the form formUrl, to the format expected by Remedy Web servers on the BackChannel URL by means of the function RemedyBackChannelData. It then performs a WebPageUrl call using this converted data.
Note: This function is only available with Remedy projects.

Include file

Remedy.bdh

Syntax

WebRemedyBackChannelUrl( in sUrl    : string
                         in sTimer  : string optional
                         in formUrl : form optional ): boolean;

Return value

  • true if successful

  • false otherwise

Parameter | Description
sUrl | Absolute URL to the document on the server. All characters that are part of the query string are not URL-encoded.
sTimer | Optional: Name of the timer used for page measurements. If this parameter is omitted, no measurements are performed.
formUrl | Optional: Form identifier used in the dclform section. The expanded form is added to the URL after the "?". The XML representation of the BackChannel data which is contained in the form is converted to the Remedy native data format by use of the function RemedyBackChannelData.

Example

dcltrans
transaction TWeb
begin
  WebRemedyBackChannelUrl("http://10.10.1.30/arsys/BackChannel/",
  "BackChannel - GetURLForForm (#1)", ARSYS_BACKCHANNEL_016);
end TWeb;

dclform
ARSYS_BACKCHANNEL_016:
  "param"              := "<?xml version='1.0'?>\r\n"
                          "<RemedyXml operation=\"GetURLForForm\">\r\n"
                          "  <string name=\"server\">dev-sun-001</string>\r\n"
                          "  <string name=\"app_name\"></string>\r\n"
                          "  <string name=\"form\">PBCT:SelectClient_dlg</string>\r\n"
                          "  <string name=\"view\"></string>\r\n"
                          "  <bool name=\"fetch_dimensions\">1</bool>\r\n"
                          "  <string name=\"win_name\"></string>\r\n"
                          "  <string name=\"win_arg\"></string>\r\n"
                          "</RemedyXml>";
Parent topic: Remedy Functions Reference
Related reference
RemedyInit Function
RemedyBackChannelData Function
WebRemedyBackChannelPost Function
WebPageUrl Function


WebRemedyBackChannelPost Function

Action

This function converts an XML representation of data, which is given by the parameter sData, to the format expected by Remedy Web servers on the BackChannel URL by means of the function RemedyBackChannelData. It then posts this converted data to the server by means of the function WebPagePost.
Note: This function is only available with Remedy projects.

Include file

Remedy.bdh

Syntax

WebRemedyBackChannelPost( in sUrl        : string;
                          in sData       : string;
                          in nDataLength : number optional;
                          in sContent    : string optional;
                          in sTimer      : string optional;
                          in formUrl     : form optional ): boolean;

Return value

  • true if successful

  • false otherwise

Parameter | Description
sUrl | Absolute URL to the document on the server. All characters that are part of the query string are not URL-encoded.
sData | XML representation of Data to post to the server. The actual data which is posted is obtained by a call of the function WebRemedyBackChannelData.
nDataLength | Optional: This parameter is ignored. The purpose of this parameter is to make the parameter list of this function identical to the parameter list of the function WebPagePost.
sContent | Optional: Content type string used in the request, for example, "text/plain; charset=UTF-8".
sTimer | Optional: Name of the timer used for page measurements. If this parameter is omitted, no measurements are performed.
formUrl | Optional: Form identifier used in the dclform section. The expanded form is added to the URL after the "?".

Example

dcltrans
transaction TWeb
begin
  WebRemedyBackChannelPost("http://lab50/arsys/BackChannel", "<?xml version='1.0'?>\r\n"
    "<SegueRemedyXml operation=\"GetURLForForm\">\r\n"
    "  <string name=\"server\">lab50</string>\r\n"
    "  <string name=\"app_name\"></string>\r\n"
    "  <string name=\"form\">Sample:Cities</string>\r\n"
    "  <string name=\"view\"></string>\r\n"
    "  <bool name=\"fetch_dimensions\">0</bool>\r\n"
    "  <string name=\"win_name\">lab50Sample:CitiesARRoot" + GetTimeStamp() + "</string>\r\n"
    "  <string name=\"win_arg\">window.openingArgs={fvlist:{},wMode:&quot;2&quot;,wForceClear:1,fvSetDefaults:0};</string>\r\n"
    "</SegueRemedyXml>", STRING_COMPLETE, "text/plain; charset=UTF-8", "BackChannel - GetURLForForm");
end TWeb;
Parent topic: Remedy Functions Reference
Related reference
RemedyInit Function
RemedyBackChannelData Function
WebRemedyBackChannelUrl Function
WebPagePost Function


SAP Functions

Silk Performer offers support for testing of SAP systems. It uses a testing interface called SAPGUI Scripting API, which has been introduced by SAP for SAPGUI Windows Clients.

In order to record and replay SAPGUI scripts some pre-requirements must be met. Read Checking your SAP Patch Level and Enable SAP Scripting in order to prepare your environment for SAP testing.

Silk Performer offers both - low and high-level API for testing SAP systems.

  • Low-Level Functions
    Lists the SAP low-level functions.
  • Connection and Session Functions
    Lists the SAP connection and session-handling functions.
  • Control Functions
    Lists the SAP control functions.
  • Logging Functions
    Lists the SAP logging functions.
  • Parsing Functions
    Lists the SAP parsing functions.
  • Verifying Functions
    Lists the SAP verifying functions.
Parent topic: ERP/CRM Functions
Related tasks
Checking the SAP Patch Level
Checking the SAP Patch Level on the Server
Checking SAP R/3 Support Packages
Enabling SAPGUI Scripting on the Server
Enabling SAPGUI Scripting API on the Client


Low-Level Functions

  • SapGuiSetOption Function
    This function allows setting certain SapGui specific runtime settings such as timeouts during replay or enabling certain log options.
  • SapGuiInvokeMethod Function
    Calls any method exposed by SapGui controls.
  • SapGuiSetBoolean Function
    Sets a boolean value that will be used as a parameter with the next call of a SapGuiInvoke function.
  • SapGuiSetByte Function
    Sets a byte value that will be used as a parameter with the next call of a SapGuiInvoke function.
  • SapGuiSetFloat Function
    Sets a float value that will be used as a parameter with the next call of a SapGuiInvoke function.
  • SapGuiSetLong Function
    Sets a long value that will be used as a parameter with the next call of a SapGuiInvoke function.
  • SapGuiSetDouble Function
    Sets a double value that will be used as a parameter with the next call of a SapGuiInvoke function.
  • SapGuiSetShort Function
    Sets a short value that will be used as a parameter with the next call of a SapGuiInvoke function.
  • SapGuiSetNull Function
    Sets a null value that will be used as a parameter with the next call of a SapGuiInvoke function.
  • SapGuiSetString Function
    Sets a string value that will be used as a parameter with the next call of a SapGuiInvoke function.
  • SapGuiGetString Function
    Retrieves the return value of the last SapGuiInvokeMethod call.
  • SapGuiSetProperty Function
    Sets any accessible property of an SapGui control.
  • SapGuiGetProperty Function
    Retrieves any accessible property of a SapGui control.
  • SapGuiCreateCollection Function
    Creates a collection object that can be used as a parameter.
Parent topic: SAP Functions


SapGuiSetOption Function

Action

This function allows setting certain SapGui specific runtime settings such as timeouts during replay or enabling certain log options.

Include file

SapGui.bdh

Syntax

SapGuiSetOption( in nOption : number,
                 in nValue  : number ) : boolean;
Parameter | Description
nOption

The SapGui runtime option to be set. Available options are:

  • SAPGUI_OPT_TIMEOUT - Set this option to the amount of seconds after which a timeout should occur. If an SapGui API function call takes longer than the specified amount of seconds, the SapGui replay process is considered stuck and gets restarted automatically. Additionally an error of severity SEVERITY_TRANS_EXIT is raised.
  • SAPGUI_OPT_LOGCONTROLS - Set this option to 1 to enable control logging. Note that logging controls has a severe impact on the SapGui client performance. Therefore, it is usually recommended that you disable this option.
  • SAPGUI_OPT_LOGCONTROLS_ON_ERROR - Set this option to 1 to enable control logging in case of an error. Logging controls has a severe impact on the SapGui client performance. Therefore, general logging is usually disabled. This option can be used to have controls logged only in case of an error.
  • SAPGUI_OPT_LOGSCREENSHOTS - Set this option to 1 to enable the logging of a screenshot for each new window during replay. This option only applies if the UI is displayed during replay.
  • SAPGUI_OPT_LOGSCREENSHOTS_ACTION - Set this option to 1 to enable the logging of screenshots for each individual action during replay. This option only applies if the UI is displayed during replay.
  • SAPGUI_OPT_LOGLEVEL - Set this option to specify the amount of data that is written to the Virtual User Log File. Possible values are:
    • 0 (Disabled) - Does not generate any log output.
    • 1 (Normal) - Generates some log output.
    • 2 (Debug) - Generate verbose log output.
  • SAPGUI_OPT_LOGON_BEHAVIOR - Set this option to specify how multiple login attempts of the same user account are handled. Possible values are:
    • 0 - Do not handle multiple login attempts automatically.
    • 1 - Do no allow multiple login attempts.
    • 2 - Allow multiple login attempts.
    • 3 - Allow multiple login attempt, but kill the existing sessions.
nValue | The value to be set for the specified option.

Return value

  • true if successful
  • false otherwise

Example

transaction TMain
  var
  begin
    // Connecting to SAP
    SapGuiSetOption(SAPGUI_OPT_LOGCONTROLS_ON_ERROR, 1);
    SapGuiOpenConnection(" /SAP_CODEPAGE=1100 /FULLMENU lab77 00 /3");
    SapGuiSetActiveConnection("/app/con[0]");
    SapGuiSetActiveSession("ses[0]");

    // SAP
    SapGuiSetActiveWindow("wnd[0]", "SAP", SAPGUI_MATCH_Exact);
    SapGuiWindowResize(117, 28, false);

    // Logon to SAP System
    // Before running a test you have to customize the password parameter!
    ThinkTime(5.3);
    SapGuiLogon("bcuser", "*******", "000", "");

    // Copyright
    SapGuiSetActiveWindow("wnd[1]", "Copyright", SAPGUI_MATCH_Exact);
  end TMain;
Parent topic: Low-Level Functions


SapGuiInvokeMethod Function

Action

This function can be used to call any method exposed by SapGui controls. It is a low level function and has to be used together with SapGuiSet* functions. These SapGuiSet* functions are used to push parameters on the callstack for the method to be executed by SapGuiInvokeMethod.

Include file

SapGui.bdh

Syntax

SapGuiInvokeMethod( in sControlId  : string allownull,
                    in sMethodName : string,
                    in sTimer      : string optional ) : boolean;
Parameter | Description
sControlId | This parameter uniquely identifies a SapGui control. The second parameter specifies the name of the method to be called on this control.
sMethodName | The name of the method to be called on the control.
sTimer | Name of the timer to be used for measurements.

Return value

  • true if successful
  • false otherwise

Example

transaction TMain
  var
  begin

    // Connecting to SAP
    gsConnID := SapGuiOpenConnection(" /SAP_CODEPAGE=1100 /FULLMENU 10.5.2.198 0 /3");
    SapGuiSetActiveConnection(gsConnID);
    SapGuiSetActiveSession("ses[0]");

    // SAP
    SapGuiSetActiveWindow("wnd[0]", "SAP", SAPGUI_MATCH_Exact);

    // maximize
    // wnd[0]
    SapGuiInvokeMethod("wnd[0]", "maximize");

    // Logon to SAP System
    // Before running a test you have to customize the password parameter!
    ThinkTime(3.1);
    SapGuiLogon("ddic", "*******", "000", "");

    // Copyright
    SapGuiSetActiveWindow("wnd[1]", "Copyright", SAPGUI_MATCH_Exact);

    // press
    // btn[0]
    SapGuiInvokeMethod("tbar[0]/btn[0]", "press");

    // SAP Easy Access
    ThinkTime(20.2);
    SapGuiSetActiveWindow("wnd[0]", "SAP Easy Access", SAPGUI_MATCH_Exact);

    // expandNode
    // shell
    SapGuiSetString("0000000003");
    SapGuiInvokeMethod("usr/cntlIMAGE_CONTAINER/shellcont/shell/shellcont[0]/shell", "expandNode");

    // selectedNode
    SapGuiSetProperty("usr/cntlIMAGE_CONTAINER/shellcont/shell/shellcont[0]/shell", "selectedNode", "0000000004");

    // topNode
    SapGuiSetProperty("usr/cntlIMAGE_CONTAINER/shellcont/shell/shellcont[0]/shell", "topNode", "Favo");

    // doubleClickNode
    // shell
    SapGuiSetString("0000000004");
    SapGuiInvokeMethod("usr/cntlIMAGE_CONTAINER/shellcont/shell/shellcont[0]/shell", "doubleClickNode");

    // press
    // btn[15]
    ThinkTime(20.6);
    SapGuiInvokeMethod("tbar[0]/btn[15]", "press");

    // press
    // btn[15]
    SapGuiInvokeMethod("tbar[0]/btn[15]", "press");

    // Log Off
    SapGuiSetActiveWindow("wnd[1]", "Log Off", SAPGUI_MATCH_Exact);

    // press
    // SPOP-OPTION1
    SapGuiInvokeMethod("usr/btnSPOP-OPTION1", "press");
  end TMain;
Parent topic: Low-Level Functions
Related reference
SapGuiGetString Function
SapGuiGetProperty Function
SapGuiSetProperty Function
SapGuiSetBoolean Function
SapGuiSetNull Function
SapGuiSetString Function
SapGuiSetByte Function
SapGuiSetFloat Function
SapGuiSetLong Function
SapGuiSetShort Function


SapGuiSetBoolean Function

Action

Sets a boolean value that will be used as a parameter with the next call of a SapGuiInvoke function.

Include file

SapGui.bdh

Syntax

SapGuiSetBoolean( in bParam : boolean );
Parameter | Description
bParam | The boolean value to be set as a parameter for the next call of SapGuiInvoke.
Parent topic: Low-Level Functions
Related reference
SapGuiInvokeMethod Function
SapGuiGetProperty Function
SapGuiSetProperty Function
SapGuiSetNull Function
SapGuiSetString Function
SapGuiSetByte Function
SapGuiSetFloat Function
SapGuiSetLong Function
SapGuiSetShort Function


SapGuiSetByte Function

Action

Sets a byte value that will be used as a parameter with the next call of a SapGuiInvoke function.

Include file

SapGui.bdh

Syntax

SapGuiSetByte( in bParam : unsigned short );
Parameter | Description
bParam | The byte value to be set as a parameter for the next call of SapGuiInvoke.
Parent topic: Low-Level Functions
Related reference
SapGuiInvokeMethod Function
SapGuiGetProperty Function
SapGuiSetProperty Function
SapGuiSetBoolean Function
SapGuiSetNull Function
SapGuiSetString Function
SapGuiSetFloat Function
SapGuiSetLong Function
SapGuiSetShort Function


SapGuiSetFloat Function

Action

Sets a float value that will be used as a parameter with the next call of a SapGuiInvoke function.

Include file

SapGui.bdh

Syntax

SapGuiSetFloat( in fParam : float );
Parameter | Description
fParam | The float value to be set as a parameter for the next call of SapGuiInvoke.
Parent topic: Low-Level Functions
Related reference
SapGuiInvokeMethod Function
SapGuiGetProperty Function
SapGuiSetProperty Function
SapGuiSetBoolean Function
SapGuiSetNull Function
SapGuiSetString Function
SapGuiSetByte Function
SapGuiSetLong Function
SapGuiSetShort Function


SapGuiSetLong Function

Action

Sets a long value that will be used as a parameter with the next call of a SapGuiInvoke function.

Include file

SapGui.bdh

Syntax

SapGuiSetLong( in nParam : number );
Parameter | Description
nParam | The long value to be set as a parameter for the next call of SapGuiInvoke.
Parent topic: Low-Level Functions
Related reference
SapGuiInvokeMethod Function
SapGuiGetProperty Function
SapGuiSetProperty Function
SapGuiSetBoolean Function
SapGuiSetNull Function
SapGuiSetString Function
SapGuiSetByte Function
SapGuiSetFloat Function
SapGuiSetShort Function


SapGuiSetDouble Function

Action

Sets a double value that will be used as a parameter with the next call of a SapGuiInvoke function.

Include file

SapGui.bdh

Syntax

SapGuiSetDouble( dParam : in double );
Parameter | Description
dParam | The double value to be set as a parameter for the next call of SapGuiInvoke.
Parent topic: Low-Level Functions


SapGuiSetShort Function

Action

Sets a short value that will be used as a parameter with the next call of a SapGuiInvoke function.

Include file

SapGui.bdh

Syntax

SapGuiSetShort( in nParam : number );
Parameter | Description
nParam | The short value to be set as a parameter for the next call of SapGuiInvoke.
Parent topic: Low-Level Functions
Related reference
SapGuiInvokeMethod Function
SapGuiGetProperty Function
SapGuiSetProperty Function
SapGuiSetBoolean Function
SapGuiSetNull Function
SapGuiSetString Function
SapGuiSetByte Function
SapGuiSetFloat Function
SapGuiSetLong Function


SapGuiSetNull Function

Action

Sets a null value that will be used as a parameter with the next call of a SapGuiInvoke function.

Include file

SapGui.bdh

Syntax

SapGuiSetNull();
Parent topic: Low-Level Functions
Related reference
SapGuiInvokeMethod Function
SapGuiGetProperty Function
SapGuiSetProperty Function
SapGuiSetBoolean Function
SapGuiSetString Function
SapGuiSetByte Function
SapGuiSetFloat Function
SapGuiSetLong Function
SapGuiSetShort Function


SapGuiSetString Function

Action

Sets a string value that will be used as a parameter with the next call of a SapGuiInvoke function.

Include file

SapGui.bdh

Syntax

SapGuiSetString( in sParam : string allownull );
Parameter | Description
sParam | The string value to be set as a parameter for the next call of SapGuiInvoke.

Example

transaction TMain
  var
    sConnID : string;
  begin
    // Connecting to SAP
    gsConnID := SapGuiOpenConnection(" /SAP_CODEPAGE=1100 /FULLMENU 10.5.2.198 0 /3");
    SapGuiSetActiveConnection(sConnID);
    SapGuiSetActiveSession("ses[0]");

    // SAP
    SapGuiSetActiveWindow("wnd[0]", "SAP", SAPGUI_MATCH_Exact);

    // maximize
    // wnd[0]
    SapGuiInvokeMethod("wnd[0]", "maximize");

    // Logon to SAP System
    // Before running a test you have to customize the password parameter!
    SapGuiIgnoreError(SAPENGINE_STATUSBAR_CHANGED, SEVERITY_SUCCESS);
    ThinkTime(2.5);
    SapGuiLogon("ddic", "*******", "000", "");

    // Copyright
    ThinkTime(2.8);
    SapGuiSetActiveWindow("wnd[1]", "Copyright", SAPGUI_MATCH_Exact);

    // press
    // btn[0]
    SapGuiInvokeMethod("tbar[0]/btn[0]", "press");

    // SAP Easy Access
    ThinkTime(9.4);
    SapGuiSetActiveWindow("wnd[0]", "SAP Easy Access", SAPGUI_MATCH_Exact);

    // expandNode
    // shell
    SapGuiSetString("0000000003");
    SapGuiInvokeMethod("usr/cntlIMAGE_CONTAINER/shellcont/shell/shellcont[0]/shell", "expandNode");

    // selectedNode
    SapGuiSetProperty("usr/cntlIMAGE_CONTAINER/shellcont/shell/shellcont[0]/shell", "selectedNode", "0000000004");

    // topNode
    SapGuiSetProperty("usr/cntlIMAGE_CONTAINER/shellcont/shell/shellcont[0]/shell", "topNode", "Favo");

    // doubleClickNode
    // shell
    SapGuiSetString("0000000004");
    SapGuiInvokeMethod("usr/cntlIMAGE_CONTAINER/shellcont/shell/shellcont[0]/shell", "doubleClickNode");
    // Grid Control Info:
    // /app/con[0]/ses[0]/wnd[0]/usr/cntlSINWP_CONTAINER/shellcont/shell/shellcont[1]/shell/shellcont[0]/shell/0 columns
    // -------------------------------------

    // Business Workplace von DDIC
    ThinkTime(8.5);
    SapGuiSetActiveWindow("wnd[0]","Business Workplace von DDIC", SAPGUI_MATCH_Exact);
  end TMain;
Parent topic: Low-Level Functions
Related reference
SapGuiInvokeMethod Function
SapGuiGetProperty Function
SapGuiSetProperty Function
SapGuiSetBoolean Function
SapGuiSetNull Function
SapGuiSetByte Function
SapGuiSetFloat Function
SapGuiSetLong Function
SapGuiSetShort Function


SapGuiGetString Function

Action

Retrieves the return value of the last SapGuiInvokeMethod call. A method invoked by SapGuiInvokeMethod may return a value, however this value is not returned by the SapGuiInvokeMethod call itself. Therefore you can use SapGuiGetString to get the return value of the invoked method. SapGuiGetString works on different return types, like String, numbers, Boolean. The values will be converted to a string.

Include file

SapGui.bdh

Syntax

SapGuiGetString( out sValue : string ): boolean;
Parameter | Description
sValue | Retrieves the return value of the last SapGuiInvokeMethod call

Return value

  • true if successful

  • false otherwise

Example

transaction TMain
  var
    sConnID, sValue : string;
  begin
    // Connecting to SAP
    sConnID := SapGuiOpenConnection(" /SAP_CODEPAGE=1100 /FULLMENU 10.5.2.198 0 /3");
    SapGuiSetActiveConnection(sConnID);
    SapGuiSetActiveSession("ses[0]");

    // SAP
    SapGuiSetActiveWindow("wnd[0]", "SAP", SAPGUI_MATCH_Exact);
    SapGuiWindowAction(SAPGUI_WND_MAXIMIZE);

    // Logon to SAP System
    // Before running a test you have to customize the password parameter!
    SapGuiIgnoreError(SAPENGINE_STATUSBAR_CHANGED, SEVERITY_SUCCESS);
    ThinkTime(2.8);
    SapGuiLogon("ddic", "minisap", "000", "");

    // SAP Easy Access
    ThinkTime(9.9);
    SapGuiSetActiveWindow("wnd[0]", "SAP Easy Access", SAPGUI_MATCH_Exact);
    SapGuiSetString("0000003");
    SapGuiInvokeMethod("/usr/cntlIMAGE_CONTAINER/shellcont/shell/shellcont[0]/shell", "GetNodeKeyByPath");

    // Get the return value of the previous InvokeMethod
    SapGuiGetString(sValue);
  end TMain;
Parent topic: Low-Level Functions
Related reference
SapGuiInvokeMethod Function


SapGuiSetProperty Function

Action

This function is used to set any accessible property of an SapGui control. It can be used for all data types.

Include file

SapGui.bdh

Syntax

SapGuiSetProperty( in sControlId     : string allownull,
                   in sPropertyName  : string,
                   in sPropertyValue : number,
                   in sTimer         : string optional ) : boolean;
Parameter | Description
sControlId | The uniquely identifying id of a SapGui control.
sPropertyName | The name of the property to be set.
sPropertyValue | The value to be set for this property.
sTimer | Name of the timer to be used for measurements.

Return value

  • true if successful
  • false otherwise

Example

transaction TMain
  var
    sConnID : string;
  begin
    // Connecting to SAP
    sConnID := SapGuiOpenConnection(" /SAP_CODEPAGE=1100 /FULLMENU 10.5.2.198 0 /3");
    SapGuiSetActiveConnection(sConnID);
    SapGuiSetActiveSession("ses[0]");

    // SAP
    SapGuiSetActiveWindow("wnd[0]", "SAP", SAPGUI_MATCH_Exact);

    // maximize
    // wnd[0]
    SapGuiInvokeMethod("wnd[0]", "maximize");

    // Logon to SAP System
    // Before running a test you have to customize the password parameter!
    ThinkTime(2.7);
    SapGuiLogon("ddic", "minisap", "000", "");

    // Copyright
    ThinkTime(2.2);
    SapGuiSetActiveWindow("wnd[1]", "Copyright", SAPGUI_MATCH_Exact);

    // press
    // btn[0]
    SapGuiInvokeMethod("tbar[0]/btn[0]", "press");

    // SAP Easy Access
    ThinkTime(4.4);
    SapGuiSetActiveWindow("wnd[0]", "SAP Easy Access",SAPGUI_MATCH_Exact);

    // expandNode
    // shell
    SapGuiSetString("0000000003");
    SapGuiInvokeMethod("usr/cntlIMAGE_CONTAINER/shellcont/shell/shellcont[0]/shell", "expandNode");

    // selectedNode
    SapGuiSetProperty("usr/cntlIMAGE_CONTAINER/shellcont/shell/shellcont[0]/shell", "selectedNode", "0000000004");

    // topNode
    SapGuiSetProperty("usr/cntlIMAGE_CONTAINER/shellcont/shell/shellcont[0]/shell", "topNode", "Favo");

    // doubleClickNode
    // shell
    SapGuiSetString("0000000004");
    SapGuiInvokeMethod("usr/cntlIMAGE_CONTAINER/shellcont/shell/shellcont[0]/shell", "doubleClickNode");

    // press
    // btn[15]
    ThinkTime(6.0);
    SapGuiInvokeMethod("tbar[0]/btn[15]", "press");

    // press
    // btn[15]
    SapGuiInvokeMethod("tbar[0]/btn[15]", "press");

    // Log Off
    SapGuiSetActiveWindow("wnd[1]", "Log Off", SAPGUI_MATCH_Exact);

    // press
    // SPOP-OPTION1
    SapGuiInvokeMethod("usr/btnSPOP-OPTION1", "press");
  end TMain;
Parent topic: Low-Level Functions
Related reference
SapGuiInvokeMethod Function
SapGuiGetProperty Function
SapGuiSetBoolean Function
SapGuiSetNull Function
SapGuiSetString Function
SapGuiSetByte Function
SapGuiSetFloat Function
SapGuiSetLong Function
SapGuiSetShort Function


SapGuiGetProperty Function

Action

This function is used to retrieve any accessible property of a SapGui control.

Include file

SapGui.bdh

Syntax

SapGuiGetProperty( in  sControlId     : string allownull,
                   in  sPropertyName  : string,
                   out sPropertyValue : string optional,
                   in  nSize          : number sizespec optional ) : boolean;
Parameter | Description
sControlId | The uniquely identifying id of a SapGui control
sPropertyName | The name of the property to be set.
sPropertyValue | The buffer to be assigned the value
nSize | The size of the buffer

Return value

  • true if successful

  • false otherwise

Example

transaction TMain
  var
    buffer : string;
    sConnID : string;
  begin

    // Connecting to SAP
    sConnID := SapGuiOpenConnection( " /SAP_CODEPAGE=1100 /FULLMENU 10.5.2.198 0 /3");
    SapGuiSetActiveConnection(sConnID);
    SapGuiSetActiveSession("ses[0]");

    // SAP
    SapGuiSetActiveWindow("wnd[0]", "SAP", SAPGUI_MATCH_Exact);

    // maximize
    // wnd[0]
    SapGuiInvokeMethod("wnd[0]", "maximize");

    // Logon to SAP System
    // Before running a test you have to customize the password parameter!
    ThinkTime(2.7);
    SapGuiLogon("ddic", "*******", "000", "");

    // Copyright
    ThinkTime(2.2);
    SapGuiSetActiveWindow("wnd[1]", "Copyright", SAPGUI_MATCH_Exact);

    // press
    // btn[0]
    SapGuiInvokeMethod("tbar[0]/btn[0]", "press");

    // SAP Easy Access
    ThinkTime(4.4);
    SapGuiSetActiveWindow("wnd[0]", "SAP Easy Access", SAPGUI_MATCH_Exact);

    // expandNode
    // shell
    SapGuiSetString("0000000003");
    SapGuiInvokeMethod("usr/cntlIMAGE_CONTAINER/shellcont/shell/shellcont[0]/shell", "expandNode");

    // selectedNode
    SapGuiSetProperty("usr/cntlIMAGE_CONTAINER/shellcont/shell/shellcont[0]/shell", "selectedNode", "0000000004");
    // topNode
    SapGuiSetProperty("usr/cntlIMAGE_CONTAINER/shellcont/shell/shellcont[0]/shell", "topNode", "Favo");

    SapGuiGetProperty("usr/cntlIMAGE_CONTAINER/shellcont/shell/shellcont[0]/shell", "topNode", buffer);

    // doubleClickNode
    // shell
    SapGuiSetString("0000000004");
    SapGuiInvokeMethod("usr/cntlIMAGE_CONTAINER/shellcont/shell/shellcont[0]/shell", "doubleClickNode");

    // press
    // btn[15]
    ThinkTime(6.0);
    SapGuiInvokeMethod("tbar[0]/btn[15]", "press");

    // press
    // btn[15]
    SapGuiInvokeMethod("tbar[0]/btn[15]", "press");

    // Log Off
    SapGuiSetActiveWindow("wnd[1]", "Log Off", SAPGUI_MATCH_Exact);

    // press
    // SPOP-OPTION1
    SapGuiInvokeMethod("usr/btnSPOP-OPTION1", "press");
  end TMain;
Parent topic: Low-Level Functions
Related reference
SapGuiInvokeMethod Function
SapGuiSetProperty Function
SapGuiSetBoolean Function
SapGuiSetNull Function
SapGuiSetString Function
SapGuiSetByte Function
SapGuiSetFloat Function
SapGuiSetLong Function
SapGuiSetShort Function


SapGuiCreateCollection Function

Action

Some functions accept collections as parameters. This function creates a collection object that can then be used as a parameter.

Include file

SapGui.bdh

Syntax

SapGuiCreateCollection();
Parent topic: Low-Level Functions


Connection and Session Functions

  • SapGuiCreateSession Function
    Creates a new SAP session for the current SAP connection.
  • SapGuiCloseSession Function
    Closes a specified session or all session of the current virtual user.
  • SapGuiLogon Function
    Logs on a user to the SAP system using the provided credentials.
  • SapGuiOpenConnection Function
    Opens a connection to the SAP server specified by a connection string.
  • SapGuiOpenConnectionByName Function
    Opens a connection to the SAP server specified by the name of connection as specified in the Saplogon tool.
  • SapGuiSetActiveConnection Function
    Sets the active SapGui connection.
  • SapGuiSetActiveSession Function
    Sets the active session to be used be the virtual user.
  • SapGuiRestart Function
    Restarts the SapGui engine.
Parent topic: SAP Functions


SapGuiCreateSession Function

Action

Creates a new SAP session for the current SAP connection. The SAP system normally allows 6 sessions per connection.

Include file

SapGui.bdh

Syntax

SapGuiCreateSession( );

Return value

  • true if successful
  • false otherwise

Example

transaction TMain
  var
  begin
    // Connecting to SAP
    SapGuiOpenConnection(" /SAP_CODEPAGE=1100 /FULLMENU lab77 00/3");
    SapGuiSetActiveConnection("/app/con[0]");
    SapGuiSetActiveSession("ses[0]");

    //SAP
    SapGuiSetActiveWindow("wnd[0]", "SAP", SAPGUI_MATCH_Exact);
    SapGuiWindowResize(117, 28, false);

    //Logon to SAP System// Before running a test you have to customize the password parameter!
    ThinkTime(5.3);
    SapGuiLogon("bcuser", "*******", "000", "");
    SapGuiCreateSession();
    SapSetActiveSession("ses[1]");

    // Copyright
    SapGuiSetActiveWindow("wnd[1]", "Copyright", SAPGUI_MATCH_Exact);

    // Continue (Enter)
    SapGuiPressButton("tbar[0]/btn[0]", "Continue (Enter)");

    // SAP Easy Access
    SapGuiSetActiveWindow("wnd[0]", "SAP Easy Access", SAPGUI_MATCH_Exact);

    // Other menu
    SapGuiPressButton("tbar[1]/btn[17]", " Other menu");

    // Restrict Values
    SapGuiSetActiveWindow("wnd[1]", "Restrict Values", SAPGUI_MATCH_Exact);
    SapGuiPressButton("tbar[0]/btn[12]", "Cancel (F12)");

    // SAP Easy Access
    SapGuiSetActiveWindow("wnd[0]", "SAP Easy Access", SAPGUI_MATCH_Exact);

    // Log off (Shift+F3)
    SapGuiPressButton("tbar[0]/btn[15]", "Log off (Shift+F3)");

    // Log Off
    SapGuiSetActiveWindow("wnd[1]", "Log Off", SAPGUI_MATCH_Exact);

    // Yes
    SapGuiPressButton("usr/btnSPOP-OPTION1", "Yes");
  end TMain;
Parent topic: Connection and Session Functions


SapGuiCloseSession Function

Action

This function closes a specified session or all session of the current virtual user.

Include file

SapGui.bdh

Syntax

SapGuiCloseSession( in sSession : string optional );
Parameter | Description
sSession | The id of the session to be closed. Set this parameter to NULL to close all assigned sessions.

Return value

  • true if successful
  • false otherwise

Example

transaction TMain
  var
    iCol : number;
    sName : string;
    sConnID : string;
  begin// Connecting to SAP
    sConnID := SapGuiOpenConnection(" /SAP_CODEPAGE=1100 /FULLMENU 10.5.2.132 0/3");

    SapGuiSetActiveConnection(gsConnID);

    SapGuiSetActiveSession("ses[0]");

    // SAP
    SapGuiSetActiveWindow("wnd[0]", "SAP", SAPGUI_MATCH_ExactNoCase);

    SapGuiWindowAction(SAPGUI_WND_MAXIMIZE);

    SapGuiLogon("ddic", "*******", "000", "");
    SapGuiCloseSession();
  end TMain;
Parent topic: Connection and Session Functions


SapGuiLogon Function

Action

Logs on a user to the SAP system using the provided credentials.

Include file

SapGui.bdh

Syntax

SapGuiLogon( in sUsername  : string,
             in sPassword  : string,
             in sClientNum : string,
             in sLanguage  : string,
             in sTimer     : string ) : boolean;
Parameter | Description
sUserName | The user to be logged using the SapGuiLogon function.
sPassword | The user's password.
sClientNum | SAP specific client number.
sLanguage | SAP specific language code.
sTimer | Timer name used for measurements.

Return value

  • true if successful
  • false otherwise

Example

transaction TMain
  var
    sId : string;
  begin
    // Connecting to SAP
    sId := SapGuiOpenConnection(" /SAP_CODEPAGE=1100 /FULLMENU lab77 00 /3");
    SapGuiSetActiveConnection(sId);
    SapGuiSetActiveSession("ses[0]");

    // SAP
    SapGuiSetActiveWindow("wnd[0]", "SAP", SAPGUI_MATCH_Exact);
    SapGuiWindowResize(117, 28, false);

    // Logon to SAP System// Before running a test you have to customize the password parameter!
    ThinkTime(5.3);
    SapGuiLogon("bcuser", "fantastic", "000", "");
  end TMain;
Parent topic: Connection and Session Functions


SapGuiOpenConnection Function

Action

Opens a connection to the SAP server specified by a connection string.

Include file

SapGui.bdh

Syntax

SapGuiOpenConnection( in sConnString : string ) : string;
Parameter | Description
sConnString | SAP Connection String

Return value

  • Connection ID if successful
  • Null otherwise

Example

transaction TMain
  var
  begin
    // Connecting to SAP
    SapGuiOpenConnection(" /SAP_CODEPAGE=1100 /FULLMENU lab77 00 /3");
    SapGuiSetActiveConnection("/app/con[0]");

    SapGuiSetActiveSession("ses[0]");

    //SAP
    SapGuiSetActiveWindow("wnd[0]", "SAP", SAPGUI_MATCH_Exact);

    SapGuiWindowResize(117, 28, false);

    // Logon to SAP System// Before running a test you have to customize the password parameter!
    ThinkTime(5.3);
    SapGuiLogon("bcuser", "*******", "000", "");

    // Copyright
    SapGuiSetActiveWindow("wnd[1]", "Copyright", SAPGUI_MATCH_Exact);

    // Continue (Enter)
    SapGuiPressButton("tbar[0]/btn[0]", "Continue (Enter)");

    // SAP Easy Access
    SapGuiSetActiveWindow("wnd[0]", "SAP Easy Access", SAPGUI_MATCH_Exact);

    // Other menu
    SapGuiPressButton("tbar[1]/btn[17]", " Other menu");

    // Restrict Values
    SapGuiSetActiveWindow("wnd[1]", "Restrict Values", SAPGUI_MATCH_Exact);

    // Cancel (F12)
    SapGuiPressButton("tbar[0]/btn[12]", "Cancel (F12)");

    // SAP Easy Access
    SapGuiSetActiveWindow("wnd[0]", "SAP Easy Access", SAPGUI_MATCH_Exact);

    // Log off (Shift+F3)
    SapGuiPressButton("tbar[0]/btn[15]", "Log off (Shift+F3)");

    // Log Off
    SapGuiSetActiveWindow("wnd[1]", "Log Off", SAPGUI_MATCH_Exact);

    // Yes
    SapGuiPressButton("usr/btnSPOP-OPTION1", "Yes");
  end TMain;
Parent topic: Connection and Session Functions


SapGuiOpenConnectionByName Function

Action

Opens a connection to the SAP server specified by the name of connection as specified in the Saplogon tool.

Include file

SapGui.bdh

Syntax

SapGuiOpenConnectionByName( in    sConnName : string,
                            inout sId       : dstring optional ) : boolean;
Parameter | Description
sConnName | The name of the connection profile as specified in the SapLogon tool
sId | This parameter will be assigned the id of the connection.

Return value

  • true if successful
  • false otherwise

Example

transaction TMain
  var
    sId : string;
  begin
    // Connecting to SAP
    SapGuiOpenConnectionByName("incantation", sId);

    SapGuiSetActiveConnection("/app/con[0]");

    SapGuiSetActiveSession("ses[0]");

    // SAP
    SapGuiSetActiveWindow("wnd[0]", "SAP", SAPGUI_MATCH_Exact);

    SapGuiWindowResize(117, 28, false);

    // Logon to SAP System
    // Before running a test you have to customize the password parameter!
    ThinkTime(5.3);
    SapGuiLogon("bcuser", "*******", "000", "");

    // Copyright
    SapGuiSetActiveWindow("wnd[1]", "Copyright", SAPGUI_MATCH_Exact);

    // Continue (Enter)
    SapGuiPressButton("tbar[0]/btn[0]", "Continue (Enter)");

    // SAP Easy Access
    SapGuiSetActiveWindow("wnd[0]", "SAP Easy Access", SAPGUI_MATCH_Exact);

    // Other menu
    SapGuiPressButton("tbar[1]/btn[17]", " Other menu");

    // Restrict Values
    SapGuiSetActiveWindow("wnd[1]", "Restrict Values", SAPGUI_MATCH_Exact);

    // Cancel (F12)
    SapGuiPressButton("tbar[0]/btn[12]", "Cancel (F12)");

    // SAP Easy Access
    SapGuiSetActiveWindow("wnd[0]", "SAP Easy Access", SAPGUI_MATCH_Exact);

    // Log off (Shift+F3)
    SapGuiPressButton("tbar[0]/btn[15]", "Log off (Shift+F3)");

    // Log Off
    SapGuiSetActiveWindow("wnd[1]", "Log Off", SAPGUI_MATCH_Exact);

    // Yes
    SapGuiPressButton("usr/btnSPOP-OPTION1", "Yes");
  end TMain;
Parent topic: Connection and Session Functions


SapGuiSetActiveConnection Function

Action

This function sets the active SapGui connection. All subsequent SapGui calls will use this connection.

Include file

SapGui.bdh

Syntax

SapGuiSetActiveConnection( in sConnId : string ) : boolean;
Parameter | Description
sConnId | The id uniquely identifying the connection.

Return value

  • true if successful
  • false otherwise

Example

transaction TMain
  var
    sId : string;
  begin
    // Connecting to SAP
    sId := SapGuiOpenConnection(" /SAP_CODEPAGE=1100 /FULLMENU 10.5.2.198 0 /3");
    SapGuiSetActiveConnection(sId);
    SapGuiSetActiveSession("ses[0]");

    // SAP
    SapGuiSetActiveWindow("wnd[0]", "SAP", SAPGUI_MATCH_Exact);
    SapGuiWindowResize(117, 28, false);

    // Logon to SAP System
    // Before running a test you have to customize the password parameter!
    ThinkTime(5.3);
    SapGuiLogon("bcuser", "*******", "000", "");
  end TMain;
Parent topic: Connection and Session Functions


SapGuiSetActiveSession Function

Action

Sets the active session to be used be the virtual user. Any subsequent calls will be made using the active session.

Include file

SapGui.bdh

Syntax

SapGuiSetActiveSession( in sSessionId : string ) : boolean;
Parameter | Description
sSessionId | Id uniquely identifying the session to be set as the active one.

Return value

  • true if successful
  • false otherwise

Example

transaction TMain
  var
    sId : string;
  begin
    // Connecting to SAP
    sId := SapGuiOpenConnection(" /SAP_CODEPAGE=1100 /FULLMENU 10.5.2.198 0 /3");
    SapGuiSetActiveConnection(sId);
    SapGuiSetActiveSession("ses[0]");

    // SAP
    SapGuiSetActiveWindow("wnd[0]", "SAP", SAPGUI_MATCH_Exact);
    SapGuiWindowResize(117, 28, false);

    // Logon to SAP System
    // Before running a test you have to customize the password parameter!
    ThinkTime(5.3);
    SapGuiLogon("bcuser", "*******", "000", "");
  end TMain;
Parent topic: Connection and Session Functions


SapGuiRestart Function

Action

Restarts the SapGui engine. The restart is not performed gracefully, and open sessions or open connections will not be closed gracefully. Instead, the whole SapGui engine will be restarted, which involves starting a new process. Therefore, this function should only be called in exceptional situations where the script detects an unstable or inconsistent state from which it cannot recover to a consistent starting state for the next transaction.

Include File

SapGui.bdh

Syntax

SapGuiRestart() : boolean;

Return Value

  • true if successful
  • false otherwise

Example

transaction TMain
  var
    inconsistentStateDetected : boolean;
    gsConnID : string;
  begin
    // Connecting to SAP
    gsConnID := SapGuiOpenConnection("/SAP_CODEPAGE=1100  /FULLMENU  atlis-minisap 00 /3 /UPDOWNLOAD_CP=2", "SapGuiOpenConnection");
    SapGuiSetActiveConnection(gsConnID);
    SapGuiSetActiveSession("ses[0]");

    // SAP
    SapGuiSetActiveWindow("wnd[0]", "SAP", SAPGUI_MATCH_ExactNoCase);
    SapGuiWindowAction(SAPGUI_WND_MAXIMIZE, "SapGuiWindowAction\\SAPGUI_WND_MAXIMIZE");

    // Logon to SAP System
    // Before running a test you have to customize the password parameter!
    ThinkTime(5.8);
    SapGuiLogon("bcuser", "minisap", "001", "", "SapGuiLogon");

    // SAP Easy Access
    SapGuiIgnoreError(SAPENGINE_STATUSBAR_CHANGED, SEVERITY_SUCCESS);
    SapGuiSetActiveWindow("wnd[0]", "SAP Easy Access", SAPGUI_MATCH_ExactNoCase);

    // do some SapGui actions ...
    inconsistentStateDetected := true;

    // TODO: write code to check for inconsistent state (dependent on the certain script)
    if (inconsistentStateDetected) then SapGuiRestart();

      // Now we have a clean state for the next transaction.
    else

      // In normal situations we just log out.
      SapGuiWindowAction(SAPGUI_WND_CLOSE, "SapGuiWindowAction\\SAPGUI_WND_CLOSE");
      ThinkTime(0.5);

      // Log Off
      SapGuiSetActiveWindow("wnd[1]", "Log Off", SAPGUI_MATCH_ExactNoCase);

      // Yes
      SapGuiPressButton("usr/btnSPOP-OPTION1", "SapGuiPressButton\\Yes");
    end;
  end TMain;
Parent topic: Connection and Session Functions


Control Functions

  • SapGuiWindowAction Function
    Performs certain actions on the active window.
  • SapGuiWindowResize Function
    Resizes the active window.
  • SapGuiSetActiveWindow Function
    Sets the active window for the virtual users.
  • SapGuiCalendarFirstVisibleDate Function
    Scrolls to a date in the calendar and makes it visible.
  • SapGuiCalendarFocusDate Function
    Sets the focus to a specified date.
  • SapGuiCalendarSelectInterval Function
    Selects a date or a range of dates inside a calendar control.
  • SapGuiGetComboBoxEntry Function
    Retrieves the selected value of a combobox.
  • SapGuiContextMenuSelectItem Function
    Selects the specified cell in a SapGui grid control.
  • SapGuiContextMenuSelectItemByText Function
    Selects an item in a context menu.
  • SapGuiContextMenuSelectItemByPosition Function
    Selects an item in a context menu.
  • SapGuiGridDblClickCurrentCell Function
    Performs a double-click on the currently activated cell.
  • SapGuiTreeExpandNode Function
    Expands a specified node of a specified tree control.
  • SapGuiGetActiveWindowTitle Function
    Retrieves the title of the active window.
  • SapGuiGetCalendarFocusDate Function
    Retrieves the focused date of a calendar control.
  • SapGuiGridClick Function
    Clicks a cell of the grid control.
  • SapGuiGridClickCurrentCell Function
    Performs a simple click on the currently activated cell.
  • SapGuiGridContextMenu Function
    Opens a context menu for the currently selected cell.
  • SapGuiGridCurrentCellPressButton Function
    Emulates a button click in the currently selected cell of a grid.
  • SapGuiGridCurrentCellPressTotalRow Function
    Presses the total row button for the currently selected cell.
  • SapGuiGridDblClick Function
    Emulates a double-click in a cell of the grid.
  • SapGuiGridGetColumnTitles Function
    Returns a collection of strings that are used to display the title of a column.
  • SapGuiGridModifyCheckbox Function
    Checks a check box in a grid control.
  • SapGuiGridPressButton Function
    Clicks a button in a grid.
  • SapGuiGridPressColumnHeader Function
    Emulates a click on a column header of a grid.
  • SapGuiGridPressToolbarButton Function
    Emulates a click on a grid toolbar button.
  • SapGuiGridPressToolbarContextButton Function
    Emulates a virtual user opening a list of options by clicking on a context button.
  • SapGuiGridPressTotalRow Function
    Presses the total row button in a grid.
  • SapGuiGridScrollToRow Function
    Scrolls to the specified row of the SapGui grid control.
  • SapGuiGridSelectCell Function
    Selects the specified cell in a SapGui grid control.
  • SapGuiGridSelectContextMenu Function
    Selects an option from a context menu in a grid.
  • SapGuiGridSelectToolbarMenu Function
    Selects an option from a grid toolbar menu.
  • SapGuiGridSetCellData Function
    Writes data to the specified cell of a grid control.
  • SapGuiGridSetColumnWidth Function
    Sets the column width in a SapGui grid control to a specified value.
  • SapGuiIgnoreError Function
    Ignores SapGui errors.
  • SapGuiPressButton Function
    Performs a click on the specified SapGui button control.
  • SapGuiPressToolbarButton Function
    Presses a toolbar button.
  • SapGuiPressToolbarContextButton Function
    Presses the toolbar context button.
  • SapGuiSelectComboBoxEntry Function
    Selects an item in a SapGui combobox.
  • SapGuiSelectMenu Function
    Selects a menu from the SapGui menu bar.
  • SapGuiSelectRadioButton Function
    Selects the specifed SapGui radio button.
  • SapGuiSelectTab Function
    Activates the specified tab sheet inside a SapGui tab control.
  • SapGuiSelectToolbarMenuItem Function
    Selects a toolbar menu item.
  • SapGuiSelectToolbarMenuItemByText Function
    Selects a toolbar menu item using the text of the item.
  • SapGuiSelectTopNode Function
    Scrolls to a specified node in the SapGui tree control.
  • SapGuiSendVKey Function
    Sends a keyboard input event to the active window.
  • SapGuiSetCheckbox Function
    Checks or unchecks the specified SapGui check box.
  • SapGuiSetFileName Function
    Sets a file name that will be used to replace the next file selection using the Windows function GetOpenFileName.
  • SapGuiSetFocus Function
    Sets the focus to the specified control.
  • SapGuiSetOKCode Function
    Sets the text for a SapGui OK text field.
  • SapGuiSetText Function
    Enters text into a SapGui text field.
  • SapGuiTableGetRadioValue Function
    Checks whether a table cell's radio button is selected.
  • SapGuiTableGetRows Function
    Returns a collection of table rows for the specified table.
  • SapGuiTableGetRowSelected Function
    Returns the index of the current cell's row.
  • SapGuiTableGetRowCount Function
    Returns the number of rows for the specified table.
  • SapGuiTableGetText Function
    Returns the text of a specified table's cell.
  • SapGuiTableGetColumns Function
    Returns the collection of columns for the specified table.
  • SapGuiTableGetColumnCount Function
    Returns the number of columns for the specified table.
  • SapGuiTableIsCheckboxChecked Function
    Returns whether a check box in a table cell is checked.
  • SapGuiTablePressButton Function
    Presses a cell's button.
  • SapGuiTableSelectComboboxEntry Function
    Selects an entry from a cell's combobox.
  • SapGuiTableSelectRadioButton Function
    Select a cell's radio button.
  • SapGuiTableSelectRow Function
    Selects one row of a table.
  • SapGuiTableSetCheckbox Function
    Checks a cell's check box.
  • SapGuiTableSetFocusCell Function
    Sets the focus to a cell in a SapGui table control.
  • SapGuiTableSetText Function
    Sets text at the specified position in a SapGui table control.
  • SapGuiTreeChangeCheckbox Function
    Checks or unchecks a tree item's check box.
  • SapGuiTreeClickLink Function
    Clicks a tree's hyperlink.
  • SapGuiTreeCollapseNode Function
    Collapses a specified node of a specified tree control.
  • SapGuiTreeDblClickItem Function
    Performs a double click on the specified tree item.
  • SapGuiTreeDblClickNode Function
    Performs a double click on the specified node inside a SapGui tree control.
  • SapGuiTreeDefaultContextMenu Function
    Opens the default context menu for the tree.
  • SapGuiTreeGetColumnCol Function
    Returns the keys of all the items in the given column.
  • SapGuiTreeGetColumnHeaders Function
    Returns a collection of column headers for the specified tree.
  • SapGuiTreeGetColumnNames Function
    Returns a collection of column names for the specified tree.
  • SapGuiTreeGetItemText Function
    Returns the text of a tree item.
  • SapGuiTreeGetNodeChildrenCountByPath Function
    Returns the number of children of the node given by the path parameter.
  • SapGuiTreeGetNodeKeyByPath Function
    Returns the key of the node specified by the given path description.
  • SapGuiTreeGetNodesCol Function
    Returns the node keys of all the nodes in the tree.
  • SapGuiTreeGetNodeText Function
    Returns the text of a specified node of a SapGui tree control.
  • SapGuiTreeGetNodeTextByPath Function
    Returns the text of a node defined by the given path.
  • SapGuiTreeGetParent Function
    Returns the key of the parent node of the specified node in a SapGui tree control.
  • SapGuiTreeGetSubNodesCol Function
    Returns the keys of all subnodes of the node specified by the given key.
  • SapGuiTreeHeaderContextMenu Function
    Opens a context menu for a tree header.
  • SapGuiTreeItemContextMenu Function
    Opens a context menu for a tree item.
  • SapGuiTreeNodeContextMenu Function
    Opens a context menu for the specified tree node.
  • SapGuiTreePressButton Function
    Clicks a button in a SapGui tree.
  • SapGuiTreePressHeader Function
    Performs a click on the column header.
  • SapGuiTreePressKey Function
    Presses a keyboard key.
  • SapGuiTreeSelectColumn Function
    Selects a tree column.
  • SapGuiTreeSelectItem Function
    Selects an item from a SapGui tree control.
  • SapGuiTreeSelectNode Function
    Selects the specified node inside a SapGui tree control.
  • SapGuiTreeSetColumnWidth Function
    Sets the tree column width.
  • SapGuiTreeSetHierarchyWidth Function
    Sets the tree hierarchy width.
  • SapGuiTreeUnselectAll Function
    Cancels all selections in the tree.
  • SapGuiTreeUnselectColumn Function
    Unselects a tree column.
  • SapGuiTreeUnselectNode Function
    Unselects a tree node.
Parent topic: SAP Functions


SapGuiWindowAction Function

Action

Performs certain actions on the active window. The window can be closed, minimized, restored or maximized.

Include file

SapGui.bdh

Syntax

SapGuiWindowAction( in nAction : number,
                        sTimer : in string optional) : boolean;
Parameter | Description
nAction

The action to be performed on the active window. Available options are:

  • SAPGUI_WND_CLOSE. Closes the active window.
  • SAPGUI_WND_MAXIMIZE. Maximized the active window.
  • SAPGUI_WND_RESTORE. Restores the active window.
  • SAPGUI_WND_ICONIFY. Minimizes the active window.
sTimer | Timer name used for measurements.

Return value

  • true if successful
  • false otherwise

Example

transaction TMain
  var
    sId : string;
  begin

    // Connecting to SAP
    sId := SapGuiOpenConnection(" /SAP_CODEPAGE=1100 /FULLMENU lab77 00 /3");
    SapGuiSetActiveConnection(sId);
    SapGuiSetActiveSession("ses[0]");

    // SAP
    SapGuiSetActiveWindow("wnd[0]", "SAP", SAPGUI_MATCH_Exact);
    SapGuiWindowAction(SAPGUI_WND_MAXIMIZE);

    // Logon to SAP System
    // Before running a test you have to customize the password parameter!
    ThinkTime(5.3);
    SapGuiLogon("bcuser", "*******", "000", "");

    // Copyright
    SapGuiSetActiveWindow("wnd[1]", "Copyright", SAPGUI_MATCH_Exact);

    // Continue (Enter)
    SapGuiPressButton("tbar[0]/btn[0]", "Continue (Enter)");

    // SAP Easy Access
    SapGuiSetActiveWindow("wnd[0]", "SAP Easy Access", SAPGUI_MATCH_Exact);

    // Other menu
    SapGuiPressButton("tbar[1]/btn[17]", " Other menu");

    // Restrict Values
    SapGuiSetActiveWindow("wnd[1]", "Restrict Values", SAPGUI_MATCH_Exact);

    // Cancel (F12)
    SapGuiPressButton("tbar[0]/btn[12]", "Cancel (F12)");

    // SAP Easy Access
    SapGuiSetActiveWindow("wnd[0]", "SAP Easy Access", SAPGUI_MATCH_Exact);

    // Log off (Shift+F3)
    SapGuiPressButton("tbar[0]/btn[15]", "Log off (Shift+F3)");

    // Log Off
    SapGuiSetActiveWindow("wnd[1]", "Log Off", SAPGUI_MATCH_Exact);

    // Yes
    SapGuiPressButton("usr/btnSPOP-OPTION1", "Yes");
  end TMain;
Parent topic: Control Functions


SapGuiWindowResize Function

Action

Resizes the active window.

Include file

SapGui.bdh

Syntax

SapGuiWindowResize( in nWidth       : number,
                    in nHeight      : number,
                    in bThrowOnFail : boolean optional ) : boolean;
Parameter | Description
nWidth | New width to be set for the window.
nHeight | New height to be set for the window.
bThrowOnFail | If set to true, the window control will raise an exception in case resizing fails. Default value is false.

Return value

  • true if successful
  • false otherwise

Example

transaction TMain
  var
    sId : string;
  begin

    // Connecting to SAP
    sId := SapGuiOpenConnection( " /SAP_CODEPAGE=1100 /FULLMENU lab77 00 /3");
    SapGuiSetActiveConnection(sId);
    SapGuiSetActiveSession("ses[0]");

    // SAP
    SapGuiSetActiveWindow("wnd[0]", "SAP", SAPGUI_MATCH_Exact);
    SapGuiWindowResize(117, 28, false);

    // Logon to SAP System
    // Before running a test you have to customize the password parameter!
    ThinkTime(5.3);
    SapGuiLogon("bcuser", "*******", "000", "");
  end TMain;
Parent topic: Control Functions


SapGuiSetActiveWindow Function

Action

Sets the active window for the virtual users. Any subsequent SapGui calls will be performed on the active window. This function also allows window title verifications.

Include file

SapGui.bdh

Syntax

SapGuiSetActiveWindow( in sWindowId : string,
                       in sCaption  : string optional,
                       in nMatch    : number optional ) : boolean;
Parameter | Description
sWindowId | Id uniquely identifying the window to be set as the active one.
sCaption | Caption of the window. This parameter will be used to perform a window title verification. The caption may also be provided using wildcards or regular expressions. How the function will evaluate the caption has to be specified in the third parameter of the function.
nMatch

Method how to perform the title verification. Available options are:

  • SAPGUI_MATCH_Exact. The function will report an error unless the caption parameter exactly matches the current window title. This method is the default behaviour when omitting this parameter.
  • SAPGUI_MATCH_ExactNoCase. Performs a case insensitive window title verification
  • SAPGUI_MATCH_Wildcard. Performs a window title verification using wildcards. The search string may contain '*' which matches 0 to n characters. '?' will match exactly one character. Characters enclosed by square brackets ([ ]) will match one character from the set enclosed by the brackets.
  • SAPGUI_MATCH_WildcardNoCase. Same as the previous option but the comparison is performed case insensitive.
  • SAPGUI_MATCH_RegExp. The window title verification is performed using regular expressions. Specify a regualar expression for the caption parameter.

Return value

  • true if successful
  • false otherwise

Example

transaction TMain
  var
    sId : string;
  begin
    // Connecting to SAP
    sId := SapGuiOpenConnection(" /SAP_CODEPAGE=1100 /FULLMENU 10.5.2.198 0 /3");
    SapGuiSetActiveConnection(sId);
    SapGuiSetActiveSession("ses[0]");

    // SAP
    SapGuiSetActiveWindow("wnd[0]", "SAP", SAPGUI_MATCH_Exact);
    SapGuiSetActiveWindow("wnd[0]", "S.*P", SAPGUI_MATCH_RegExp);
    SapGuiSetActiveWindow("wnd[0]", "S?P", SAPGUI_MATCH_Wildcard);
    SapGuiWindowResize(117, 28, false);

    // Logon to SAP System
    // Before running a test you have to customize the password parameter!
    ThinkTime(5.3);
    SapGuiLogon("bcuser", "*******", "000", "");

    // Copyright
  end TMain;
Parent topic: Control Functions


SapGuiCalendarFirstVisibleDate Function

Action

Scrolls to a date in the calendar and makes it visible.

Include file

SapGui.bdh

Syntax

SapGuiCalendarFirstVisibleDate( in sControlId : stringallownull,
                                in sDate      : string,
                                in sTimer     : stringoptional ) : boolean;
Parameter | Description
sControlId | The calendar control's unique id.
sDate | The date field to be made visible. The date has to be specified in the following format YYYYMMDD (e.g. "20091031").
sTimer | Timer name for measurements.

Return value

  • true if successful
  • false otherwise

Example

transaction TMain
        var
        sConnID : string;
        begin// Connecting to SAP
        sConnID := SapGuiOpenConnection(" /SAP_CODEPAGE=1100 /FULLMENU 10.5.2.198 0 /3");

        SapGuiSetActiveConnection(sConnID);

        SapGuiSetActiveSession("ses[0]");

        // SAP
        SapGuiSetActiveWindow("wnd[0]", "SAP", SAPGUI_MATCH_Exact);

        SapGuiWindowAction(SAPGUI_WND_MAXIMIZE);

        // Logon to SAP System
        // Before running a test you have to customize the password parameter!
        SapGuiIgnoreError(SAPENGINE_STATUSBAR_CHANGED, SEVERITY_SUCCESS);
        ThinkTime(2.8);
        SapGuiLogon("ddic", "minisap", "000", "");
        // Copyright
        ThinkTime(2.1);
            SapGuiSetActiveWindow("wnd[1]", "Copyright", SAPGUI_MATCH_Exact);

        SapGuiPressButton("tbar[0]/btn[0]");

        // SAP Easy Access
            ThinkTime(9.9);
        SapGuiSetActiveWindow("wnd[0]", "SAP Easy Access", SAPGUI_MATCH_Exact);

        SapGuiSelectTopNode("usr/cntlIMAGE_CONTAINER/shellcont/shell/shellcont[0]/shell", "Favorites", "Favo", "TopNode\\Favorites");

        SapGuiCalendarFirstVisibleDate("usr/cntlCALE_CONTROL/shellcont/shell/shellcont[0]/shell", "20040809");

        end TMain;
Parent topic: Control Functions


SapGuiCalendarFocusDate Function

Action

Sets the focus to a specified date.

Include file

SapGui.bdh

Syntax

SapGuiCalendarFocusDate( in sControlId : stringallownull,
                         in sDate      : string,
                         in sTimer     : string optional) : boolean;
Parameter | Description
sControlId | The calendar control's unique id.
sDate | The date to be focused. The date has to be specified in the following format YYYYMMDD (e.g. "20091031").
sTimer | Timer name for measurements.

Return value

  • true if successful
  • false otherwise

Example

transaction TMain
        var
        sConnID : string;
        begin// Connecting to SAP
        sConnID := SapGuiOpenConnection(" /SAP_CODEPAGE=1100 /FULLMENU 10.5.2.198 0 /3");
        SapGuiSetActiveConnection(sConnID);

        SapGuiSetActiveSession("ses[0]");

        // SAP
        SapGuiSetActiveWindow("wnd[0]", "SAP", SAPGUI_MATCH_Exact);

        SapGuiWindowAction(SAPGUI_WND_MAXIMIZE);

        // Logon to SAP System// Before running a test you have to customize the password parameter!
        SapGuiIgnoreError(SAPENGINE_STATUSBAR_CHANGED, SEVERITY_SUCCESS);
        ThinkTime(2.8);
        SapGuiLogon("ddic", "minisap", "000", "");

        // Copyright
        ThinkTime(2.1);
        SapGuiSetActiveWindow("wnd[1]", "Copyright", SAPGUI_MATCH_Exact);

        SapGuiPressButton("tbar[0]/btn[0]");

        // SAP Easy Access
        ThinkTime(9.9);
        SapGuiSetActiveWindow("wnd[0]", "SAP Easy Access", SAPGUI_MATCH_Exact);

        // NodeName: Office
        // NodePath: 2\1
        SapGuiTreeExpandNode("usr/cntlIMAGE_CONTAINER/shellcont/shell/shellcont[0]/shell", "Office", "0000000003", "Expand\\Office");

        // NodeName: Appointment Calendar// NodePath: 2\1\3
        SapGuiTreeExpandNode("usr/cntlIMAGE_CONTAINER/shellcont/shell/shellcont[0]/shell", "Appointment Calendar", "0000000008",
          "Expand\\Appointment Calendar"
        );

        // NodeName: Owner
        // NodePath: 2\1\3\1
        SapGuiTreeSelectNode("usr/cntlIMAGE_CONTAINER/shellcont/shell/shellcont[0]/shell", "Owner", "0000000009", false, "SelNode\\Owner");

        // NodeName: Favorites// NodePath: 1
        SapGuiSelectTopNode("usr/cntlIMAGE_CONTAINER/shellcont/shell/shellcont[0]/shell", "Favorites", "Favo", "TopNode\\Favorites");

        // NodeName: Owner// NodePath: 2\1\3\1
        SapGuiTreeDblClickNode("usr/cntlIMAGE_CONTAINER/shellcont/shell/shellcont[0]/shell", "Owner", "0000000009", SapGuiTreeDblClickNode
        ("usr/cntlIMAGE_CONTAINER/shellcont/shell/shellcont[0]/shell", "Owner", "0000000009", "DblClNode\\Owner");
        // Grid Control Info: /app/con[0]/ses[0]/wnd[0]/usr/cntlCALE_CONTROL/shellcont/shell/shellcont[1]/shell/8 columns
        // -------------------------------------
            // 1: 1:Time
            // 2: 2:Monday
            // 3: 3:Tuesday
        // 4: 4:Wednesday
            // 5: 5:Thursday
        // 6: 6:Friday
            // 7: 7:Saturday
            // 8: 8:Sunday

        // Termine anzeigen: DDIC
        ThinkTime(9.3);
        SapGuiSetActiveWindow("wnd[0]", "Termine anzeigen: DDIC", SAPGUI_MATCH_Exact);

        ThinkTime(4.5);

        SapGuiCalendarFocusDate("usr/cntlCALE_CONTROL/shellcont/shell/shellcont[0]/shell", "20041203");
      end TMain;
Parent topic: Control Functions


SapGuiCalendarSelectInterval Function

Action

Selects a date or a range of dates inside a calendar control.

Include file

SapGui.bdh

Syntax

SapGuiCalendarSelectInterval( in sControlId : stringallownull,
                              in sInterval  : string,
                              in sTimer     : stringoptional ) : boolean;
Parameter | Description
sControlId | The calendar control's unique id.
sInterval | The interval to be selected.This interval has to be specified by two concatenated date strings (format YYYYMMDD) separated by a comma (e.g. "20091023,20091031").
sTimer | Timer name for measurements.

Return value

  • true if successful
  • false otherwise

Example

transaction TMain
  var
    sConnID : string;
  begin

    // Connecting to SAP
    sConnID := SapGuiOpenConnection(" /SAP_CODEPAGE=1100 /FULLMENU 10.5.2.198 0 /3");
    SapGuiSetActiveConnection(sConnID);
    SapGuiSetActiveSession("ses[0]");

    // SAP
    SapGuiSetActiveWindow("wnd[0]", "SAP", SAPGUI_MATCH_Exact);
    SapGuiWindowAction(SAPGUI_WND_MAXIMIZE);

    // Logon to SAP System// Before running a test you have to customize the password parameter!
    SapGuiIgnoreError(SAPENGINE_STATUSBAR_CHANGED, SEVERITY_SUCCESS);
    ThinkTime(2.8);
    SapGuiLogon("ddic", "minisap", "000", "");

    // Copyright
    ThinkTime(2.1);
    SapGuiSetActiveWindow("wnd[1]", "Copyright", SAPGUI_MATCH_Exact);
    SapGuiPressButton("tbar[0]/btn[0]");

    // SAP Easy Access
    ThinkTime(9.9);
    SapGuiSetActiveWindow("wnd[0]", "SAP Easy Access", SAPGUI_MATCH_Exact);
    SapGuiSelectTopNode("usr/cntlIMAGE_CONTAINER/shellcont/shell/shellcont[0]/shell", "Favorites", "Favo", "TopNode\\Favorites");
    SapGuiCalendarSelectInterval("usr/cntlCALE_CONTROL/shellcont/shell/shellcont[0]/shell", "20041203,20041203");
  end TMain;
Parent topic: Control Functions


SapGuiGetComboBoxEntry Function

Action

Retrieves the selected value of a combobox.

Include file

SapGui.bdh

Syntax

SapGuiGetComboBoxEntry( in sControl : string ) : string;
Parameter | Description
sControlId | The unique id of the control.

Return value

  • Selected entry on success.
  • Empty string otherwise.

Example

transaction TMain
      var
        sText : string;
        sConnID : string;

      begin// Connecting to SAP
        sConnID := SapGuiOpenConnection( " /SAP_CODEPAGE=1100 /FULLMENU 10.5.2.132 0 /3");

        SapGuiSetActiveConnection(sConnID);

        SapGuiSetActiveSession("ses[0]");

        // SAP
        SapGuiSetActiveWindow("wnd[0]", "SAP", SAPGUI_MATCH_ExactNoCase);

        SapGuiWindowAction(SAPGUI_WND_MAXIMIZE);

        SapGuiLogon("ddic", "*******", "000", "");

        sText := SapGuiGetComboBoxEntry("/usr/tab/combobox");
      end TMain;
Parent topic: Control Functions


SapGuiContextMenuSelectItem Function

Action

Selects an item of a context menu using the unique identifier of the item.

Include file

SapGui.bdh

Syntax

SapGuiContextMenuSelectItem( in sControl : stringallownull,
                             in sItem    : string,
                             in sTimer   : string optional ) : boolean;
Parameter | Description
sControlId | The context menu's unique id.
sItem | The menu item to be selected from the context menu.
sTimer | Timer name for measurements.

Return value

  • true if successful
  • false otherwise

Example

transaction TMain
  var
    sConnID : string;
  begin
    // Connecting to SAP
    sConnID := SapGuiOpenConnection(" /SAP_CODEPAGE=1100 /FULLMENU 10.5.2.198 0 /3");
    SapGuiSetActiveConnection(sConnID);
    SapGuiSetActiveSession("ses[0]");

    // SAP
    SapGuiSetActiveWindow("wnd[0]", "SAP", SAPGUI_MATCH_Exact);
    SapGuiWindowAction(SAPGUI_WND_MAXIMIZE);

    // Logon to SAP System// Before running a test you have to customize the password parameter!
    SapGuiIgnoreError(SAPENGINE_STATUSBAR_CHANGED, SEVERITY_SUCCESS);
    ThinkTime(3.3);
    SapGuiLogon("ddic", "*******", "000", "");

    // Copyright
    SapGuiSetActiveWindow("wnd[1]", "Copyright", SAPGUI_MATCH_Exact);
    SapGuiPressButton("tbar[0]/btn[0]");

    // SAP Easy AccessThinkTime(2.1);
    SapGuiSetActiveWindow("wnd[0]", "SAP Easy Access", SAPGUI_MATCH_Exact);

    // NodeName: Office// NodePath: 2\1
    SapGuiTreeSelectNode("usr/cntlIMAGE_CONTAINER/shellcont/shell/shellcont[0]/shell", "Office", "0000000003", false, "SelNode\\Office");

    // NodeName: Office
    // NodePath: 2\1
    SapGuiTreeNodeContextMenu("usr/cntlIMAGE_CONTAINER/shellcont/shell/shellcont[0]/shell", "Office", "0000000003", "NodeCtxt\\Office");
    SapGuiContextMenuSelectItem("usr/cntlIMAGE_CONTAINER/shellcont/shell/shellcont[0]/shell", "XXEXPD");
  end TMain;
Parent topic: Control Functions


SapGuiContextMenuSelectItemByText Function

Action

Selects an item of a context menu using the text of the item.

Include file

SapGui.bdh

Syntax

SapGuiContextMenuSelectItemByText( sControl : in string allownull,
                                   sText    : in string,
                                   sTimer   : in string optional) : boolean;
Parameter | Description
sControl | The context menu's unique ID
sText | The text of the item to be selected
sTimer | Timer name for measurements

Return value

  • true if successful
  • false otherwise

Example

transaction TMain
  var
  begin
    // Connecting to SAP
    gsConnID := SapGuiOpenConnection("   /SAP_CODEPAGE=1100  /FULLMENU  atlid-test1 00 /3 /UPDOWNLOAD_CP=2",
    "SapGuiOpenConnection");
    SapGuiSetActiveConnection(gsConnID);
    SapGuiSetActiveSession("ses[0]");

    // SAP
    SapGuiSetActiveWindow("wnd[0]", "SAP", SAPGUI_MATCH_ExactNoCase);
    SapGuiWindowAction(SAPGUI_WND_MAXIMIZE, "SapGuiWindowAction\\SAPGUI_WND_MAXIMIZE");

    // Logon to SAP System
    // Before running a test you have to customize the password parameter!
    ThinkTime(4.4);
    SapGuiLogon("bcuser", "*******", "001", "", "SapGuiLogon");

    // SAP Easy Access
    SapGuiIgnoreError(SAPENGINE_STATUSBAR_CHANGED, SEVERITY_SUCCESS);
    ThinkTime(2.1);
    SapGuiSetActiveWindow("wnd[0]", "SAP Easy Access", SAPGUI_MATCH_ExactNoCase);

    // NodeName: Office
    // NodePath: 2\1
    SapGuiTreeSelectNode("usr/cntlIMAGE_CONTAINER/shellcont/shell/shellcont[0]/shell", "Office", "0000000003", false,
    "SelNode\\Office");

    // NodeName: Office
    // NodePath: 2\1
    SapGuiTreeNodeContextMenu("usr/cntlIMAGE_CONTAINER/shellcont/shell/shellcont[0]/shell", "Office", "0000000003",
    "NodeCtxt\\Office");

    ThinkTime(9.9);
    SapGuiContextMenuSelectItemByText("usr/cntlIMAGE_CONTAINER/shellcont/shell/shellcont[0]/shell", "Open folder");

    // Log off
    ThinkTime(7.9);
    SapGuiSelectMenu("mbar/menu[4]/menu[12]", "SapGuiSelectMenu\\Log off");

    // Log Off
    SapGuiSetActiveWindow("wnd[1]", "Log Off", SAPGUI_MATCH_ExactNoCase);

    // Yes
    SapGuiPressButton("usr/btnSPOP-OPTION1", "SapGuiPressButton\\Yes");
  end TMain;
Parent topic: Control Functions


SapGuiContextMenuSelectItemByPosition Function

Action

Selects an item in a context menu by specifying the item's (zero-based) index.

Include file

SapGui.bdh

Syntax

SapGuiContextMenuSelectItemByPosition( sControl  : in string allownull,
                                       sPosition : in string,
                                       sTimer    : in string optional) : boolean;
Parameter | Description
sControl | The context menu's unique ID
sPosition | The menu item's index (zero-based) to be selected from the context menu
sTimer | Timer name for measurements

Return value

  • true if successful
  • false otherwise

Example

transaction TMain
  var
  begin
    // Connecting to SAP
    gsConnID := SapGuiOpenConnection("   /SAP_CODEPAGE=1100  /FULLMENU  atlid-test1 00 /3 /UPDOWNLOAD_CP=2",
    "SapGuiOpenConnection");
    SapGuiSetActiveConnection(gsConnID);
    SapGuiSetActiveSession("ses[0]");

    // SAP
    SapGuiSetActiveWindow("wnd[0]", "SAP", SAPGUI_MATCH_ExactNoCase);
    SapGuiWindowAction(SAPGUI_WND_MAXIMIZE, "SapGuiWindowAction\\SAPGUI_WND_MAXIMIZE");

    // Logon to SAP System
    // Before running a test you have to customize the password parameter!
    ThinkTime(4.4);
    SapGuiLogon("bcuser", "*******", "001", "", "SapGuiLogon");

    // SAP Easy Access
    SapGuiIgnoreError(SAPENGINE_STATUSBAR_CHANGED, SEVERITY_SUCCESS);
    ThinkTime(2.1);
    SapGuiSetActiveWindow("wnd[0]", "SAP Easy Access", SAPGUI_MATCH_ExactNoCase);

    // NodeName: Office
    // NodePath: 2\1
    SapGuiTreeSelectNode("usr/cntlIMAGE_CONTAINER/shellcont/shell/shellcont[0]/shell", "Office", "0000000003", false,
    "SelNode\\Office");

    // NodeName: Office
    // NodePath: 2\1
    SapGuiTreeNodeContextMenu("usr/cntlIMAGE_CONTAINER/shellcont/shell/shellcont[0]/shell", "Office", "0000000003",
    "NodeCtxt\\Office");

    ThinkTime(9.9);
    SapGuiContextMenuSelectItemByPosition("usr/cntlIMAGE_CONTAINER/shellcont/shell/shellcont[0]/shell", "0");

    // Log off
    ThinkTime(7.9);
    SapGuiSelectMenu("mbar/menu[4]/menu[12]", "SapGuiSelectMenu\\Log off");

    // Log Off
    SapGuiSetActiveWindow("wnd[1]", "Log Off", SAPGUI_MATCH_ExactNoCase);

    // Yes
    SapGuiPressButton("usr/btnSPOP-OPTION1", "SapGuiPressButton\\Yes");
  end TMain;
Parent topic: Control Functions


SapGuiGridDblClickCurrentCell Function

Action

Performs a double-click on the currently activated cell.

Include file

SapGui.bdh

Syntax

SapGuiGridClickCurrentCell( in sControlId : string allownull,
                            in sTimer     : string optional) : boolean;
Parameter | Description
sControlId | The cell's unique id.
sTimer | Timer name for measurements.

Return value

  • true if successful
  • false otherwise

Example

    transaction TMain
      var
        sConnID : string;
      begin
        // Connecting to SAP
        sConnID := SapGuiOpenConnection(" /SAP_CODEPAGE=1100 /FULLMENU 10.5.2.198 0 /3");

        SapGuiSetActiveConnection(sConnID);

        SapGuiSetActiveSession("ses[0]");

        //SAP
        SapGuiSetActiveWindow("wnd[0]", "SAP", SAPGUI_MATCH_Exact);

        SapGuiWindowAction(SAPGUI_WND_MAXIMIZE);

        // Logon to SAP System// Before running a test you have to customize the password parameter!
        SapGuiIgnoreError(SAPENGINE_STATUSBAR_CHANGED, SEVERITY_SUCCESS);
        ThinkTime(2.8);
        SapGuiLogon("ddic", "minisap", "000", "");

        // Copyright
        ThinkTime(2.1);
        SapGuiSetActiveWindow("wnd[1]", "Copyright", SAPGUI_MATCH_Exact);

        SapGuiPressButton("tbar[0]/btn[0]");

        // SAP Easy Access
        ThinkTime(9.9);
        SapGuiSetActiveWindow("wnd[0]", "SAP Easy Access", SAPGUI_MATCH_Exact);

        // NodeName: Office// NodePath: 2\1
        SapGuiTreeExpandNode("usr/cntlIMAGE_CONTAINER/shellcont/shell/shellcont[0]/shell", "Office", "0000000003", "Expand\\Office");

        // NodeName: Appointment Calendar// NodePath: 2\1\3
        SapGuiTreeExpandNode("usr/cntlIMAGE_CONTAINER/shellcont/shell/shellcont[0]/shell", "Appointment Calendar", "0000000008",
        "Expand\\Appointment Calendar");

        // NodeName: Owner// NodePath: 2\1\3\1
        SapGuiTreeSelectNode("usr/cntlIMAGE_CONTAINER/shellcont/shell/shellcont[0]/shell", "Owner", "0000000009", false, "SelNode\\Owner");

        // NodeName: Favorites// NodePath: 1
        SapGuiSelectTopNode("usr/cntlIMAGE_CONTAINER/shellcont/shell/shellcont[0]/shell", "Favorites", "Favo", "TopNode\\Favorites");

        // NodeName: Owner// NodePath: 2\1\3\1
        SapGuiTreeDblClickNode("usr/cntlIMAGE_CONTAINER/shellcont/shell/shellcont[0]/shell", "Owner", "0000000009", "DblClNode\\Owner");

        // Grid Control Info: /app/con[0]/ses[0]/wnd[0]/usr/cntlCALE_CONTROL/shellcont/shell/shellcont[1]/shell/8 columns
        // -------------------------------------
            // 1: 1:Time
        // 2: 2:Monday
        // 3: 3:Tuesday
        // 4: 4:Wednesday
        // 5: 5:Thursday
        // 6: 6:Friday
            // 7: 7:Saturday
        // 8: 8:Sunday

        // Termine anzeigen: DDIC
        ThinkTime(9.3);
        SapGuiSetActiveWindow("wnd[0]", "Termine anzeigen: DDIC", SAPGUI_MATCH_Exact);

        ThinkTime(2.0);
        SapGuiCalendarFirstVisibleDate("usr/cntlCALE_CONTROL/shellcont/shell/shellcont[0]/shell", "20040802");

        SapGuiGridSelectCell("usr/cntlCALE_CONTROL/shellcont/shell/shellcont[1]/shell", 5, " 2");

        SapGuiGridDblClickCurrentCell("usr/cntlCALE_CONTROL/shellcont/shell/shellcont[1]/shell");
      end TMain;
Parent topic: Control Functions


SapGuiTreeExpandNode Function

Action

Expands a specified node of a specified tree control.

Include file

SapGui.bdh

Syntax

SapGuiTreeExpandNode( in sControlId : string allownull,
                      in sNodeName  : string,
                      in sNode      : string,
                      in sTimer     : string optional ) : boolean;
Parameter | Description
sControlId | The tree's unique id.
sNodeName | The name of the node to be expanded. Silk Performer will try to look up the node by matching the node name. If it cannot find the node by the name or if the name is not unique, specify the node id in the third parameter.
sNode | The node id identifying the node.
sTimer | Timer name used for measurements.

Return value

  • true if successful
  • false otherwise

Example

transaction TMain
 var
    sConnID : string;
  begin
    // Connecting to SAP
    sConnID := SapGuiOpenConnection(" /SAP_CODEPAGE=1100 /FULLMENU 10.5.2.198 0 /3");
    SapGuiSetActiveConnection(sConnID);
    SapGuiSetActiveSession("ses[0]");

    // SAP
    SapGuiSetActiveWindow("wnd[0]", "SAP", SAPGUI_MATCH_Exact);
    SapGuiWindowAction(SAPGUI_WND_MAXIMIZE);

    // Logon to SAP System
    // Before running a test you have to customize the password parameter!
    SapGuiIgnoreError(SAPENGINE_STATUSBAR_CHANGED, SEVERITY_SUCCESS);
    ThinkTime(3.2);
    SapGuiLogon("ddic", "minisap", "000", "");

    // Copyright
    ThinkTime(2.2);
    SapGuiSetActiveWindow("wnd[1]", "Copyright", SAPGUI_MATCH_Exact);
    SapGuiPressButton("tbar[0]/btn[0]");

    // SAP Easy Access
    ThinkTime(3.8);
    SapGuiSetActiveWindow("wnd[0]", "SAP Easy Access", SAPGUI_MATCH_Exact);

    // NodeName: Office
    // NodePath: 2\1
    SapGuiTreeExpandNode("usr/cntlIMAGE_CONTAINER/shellcont/shell/shellcont[0]/shell", "Office", "0000000003", "Expand\\Office");
  end TMain;
Parent topic: Control Functions


SapGuiGetActiveWindowTitle Function

Action

Retrieves the title of the active window.

Include file

SapGui.bdh

Syntax

SapGetGetActiveWindowTitle( ) : string;

Return value

  • The title of the active window on success.
  • Empty string otherwise.

Example

transaction TMain
  var
    sText : string;
    sConnID : string;
  begin
    // Connecting to SAP
    sConnID := SapGuiOpenConnection( " /SAP_CODEPAGE=1100 /FULLMENU 10.5.2.132 0 /3");
    SapGuiSetActiveConnection(sConnID);
    SapGuiSetActiveSession("ses[0]");

    // SAP
    SapGuiSetActiveWindow("wnd[0]", "SAP", SAPGUI_MATCH_ExactNoCase);
    SapGuiWindowAction(SAPGUI_WND_MAXIMIZE);
    SapGuiLogon("ddic", "*******", "000", "");
    sText := SapGuiGetActiveWindowTitle();
  end TMain;
Parent topic: Control Functions


SapGuiGetCalendarFocusDate Function

Action

Retrieves the focused date of a calendar control.

Include file

SapGui.bdh

Syntax

SapGuiGetCalendarFocusDate( in sControlId : string ) : string;

Parameter | Description
sControlId | The unique id of a calendar control.

Return value

  • Focused date on success.
  • Empty string otherwise.

Example

transaction TMain
  var
    sText : string;
    sConnID : string;
  begin

    // Connecting to SAP
    sConnID := SapGuiOpenConnection(     " /SAP_CODEPAGE=1100 /FULLMENU 10.5.2.132 0 /3");
    SapGuiSetActiveConnection(sConnID);
    SapGuiSetActiveSession("ses[0]");

    // SAP
    SapGuiSetActiveWindow("wnd[0]", "SAP", SAPGUI_MATCH_ExactNoCase);
    SapGuiWindowAction(SAPGUI_WND_MAXIMIZE);
    SapGuiLogon("ddic", "*******", "000", "");
    sText := SapGuiGetCalendarFocusDate("/usr/tab/cal");
  end TMain;
Parent topic: Control Functions


SapGuiGridClick Function

Action

Clicks a cell of the grid control.

Include file

SapGui.bdh

Syntax

SapGuiGridClick( in sControlId : string allownull,
                 in nRow       : number,
                 in sCol       : string,
                 in sTimer     : string optional ) : boolean;
Parameter | Description
sControlId | The grid's unique id.
nRow | The cell's row index.
sCol | The cell's column id.
sTimer | Timer name used for measurements.

Return value

  • true if successful
  • false otherwise

Example

transaction TMain
  var
    bCheck  : boolean;
    sConnID : string;
  begin
    // Connecting to SAP
    sConnID := SapGuiOpenConnection( " /SAP_CODEPAGE=1100 /FULLMENU 10.5.2.132 0 /3");

    SapGuiSetActiveConnection(sConnID);
    SapGuiSetActiveSession("ses[0]");

    // SAP
    SapGuiSetActiveWindow("wnd[0]", "SAP", SAPGUI_MATCH_ExactNoCase);
    SapGuiWindowAction(SAPGUI_WND_MAXIMIZE);
    SapGuiLogon("ddic", "*******", "000", "");
    bCheck:= SapGuiGridClick("/usr/tab/grid", 0, "COL00203");
  end TMain;
Parent topic: Control Functions


SapGuiGridClickCurrentCell Function

Action

Performs a simple click on the currently activated cell.

Include file

SapGui.bdh

Syntax

SapGuiGridClickCurrentCell( in sControlId : string allownull,
                            in sTimer     : string optional ) : boolean;

Parameter | Description
sControlId | The cell's unique id.
sTimer | Timer name for measurements.

Return value

  • true if successful
  • false otherwise

Example

transaction TMain
  var
    sConnID : string;
  begin

    // Connecting to SAP
    sConnID := SapGuiOpenConnection(" /SAP_CODEPAGE=1100 /FULLMENU 10.5.2.198 0 /3");
    SapGuiSetActiveConnection(sConnID);
    SapGuiSetActiveSession("ses[0]");
    // SAP

    SapGuiSetActiveWindow("wnd[0]", "SAP", SAPGUI_MATCH_Exact);
    SapGuiWindowAction(SAPGUI_WND_MAXIMIZE);

    // Logon to SAP System

    // Before running a test you have to customize the password parameter!

    SapGuiIgnoreError(SAPENGINE_STATUSBAR_CHANGED, SEVERITY_SUCCESS);

    ThinkTime(2.8);

    SapGuiLogon("ddic", "minisap", "000", "");

    // Copyright

    ThinkTime(2.1);
    SapGuiSetActiveWindow("wnd[1]", "Copyright", SAPGUI_MATCH_Exact);
    SapGuiPressButton("tbar[0]/btn[0]");

    // SAP Easy Access
    ThinkTime(9.9);
    SapGuiSetActiveWindow("wnd[0]", "SAP Easy Access", SAPGUI_MATCH_Exact);

    // NodeName: Office

    // NodePath: 2\1    SapGuiTreeExpandNode( "usr/cntlIMAGE_CONTAINER/shellcont/shell/shellcont[0]/shell", "Office", "0000000003", "Expand\\Office");

    // NodeName: Appointment Calendar

    // NodePath: 2\1\3

    SapGuiTreeExpandNode( "usr/cntlIMAGE_CONTAINER/shellcont/shell/shellcont[0]/shell", "Appointment Calendar", "0000000008",
    "Expand\\Appointment alendar");

    // NodeName: Owner

    // NodePath: 2\1\3\1

    SapGuiTreeSelectNode("usr/cntlIMAGE_CONTAINER/shellcont/shell/shellcont[0]/shell", "Owner", "0000000009", false, "SelNode\\Owner");

    // NodeName: Favorites

    // NodePath: 1

    SapGuiSelectTopNode("usr/cntlIMAGE_CONTAINER/shellcont/shell/shellcont[0]/shell", "Favorites", "Favo", "TopNode\\Favorites");

    // NodeName: Owner

    // NodePath: 2\1\3\1

    SapGuiTreeDblClickNode("usr/cntlIMAGE_CONTAINER/shellcont/shell/shellcont[0]/shell", "Owner", "0000000009", "DblClNode\\Owner");
    // Grid Control Info: /app/con[0]/ses[0]/wnd[0]/usr/cntlCALE_CONTROL/shellcont/shell/shellcont[1]/shell/8 columns

    // -------------------------------------
    // 1: 1:Time
    // 2: 2:Monday
    // 3: 3:Tuesday
    // 4: 4:Wednesday
    // 5: 5:Thursday
    // 6: 6:Friday
    // 7: 7:Saturday
    // 8: 8:Sunday

    // Termine anzeigen: DDIC
    ThinkTime(9.3);
    SapGuiSetActiveWindow("wnd[0]", "Termine anzeigen: DDIC", SAPGUI_MATCH_Exact);

    ThinkTime(2.0);
    SapGuiCalendarFirstVisibleDate("usr/cntlCALE_CONTROL/shellcont/shell/shellcont[0]/shell", "20040802");
    SapGuiGridSelectCell("usr/cntlCALE_CONTROL/shellcont/shell/shellcont[1]/shell", 5, " 2");
    SapGuiGridClickCurrentCell("usr/cntlCALE_CONTROL/shellcont/shell/shellcont[1]/shell");

  end TMain;
Parent topic: Control Functions


SapGuiGridContextMenu Function

Action

Opens a context menu for the currently selected cell.

Include file

SapGui.bdh

Syntax

SapGuiGridContextMenu( in sControlId : string allownull,
                       in sTimer     : string optional ) : boolean;
Parameter | Description
sControlId | The cell's unique id.
sTimer | Timer name for measurements.

Return value

  • true if the function succeeds
  • false otherwise

Example

transaction TMain
  var
    sConnID : string;
  begin

    // Connecting to SAP
    sConnID := SapGuiOpenConnection(" /SAP_CODEPAGE=1100 /FULLMENU 10.5.2.198 0 /3");
    SapGuiSetActiveConnection(sConnID);
    SapGuiSetActiveSession("ses[0]");

    // SAP
    SapGuiSetActiveWindow("wnd[0]", "SAP", SAPGUI_MATCH_Exact);
    SapGuiWindowAction(SAPGUI_WND_MAXIMIZE);

    // Logon to SAP System
    // Before running a test you have to customize the password parameter!
    SapGuiIgnoreError(SAPENGINE_STATUSBAR_CHANGED, SEVERITY_SUCCESS);
    ThinkTime(2.8);
    SapGuiLogon("ddic", "minisap", "000", "");

    // Copyright
    ThinkTime(2.1);
    SapGuiSetActiveWindow("wnd[1]", "Copyright", SAPGUI_MATCH_Exact);
    SapGuiPressButton("tbar[0]/btn[0]");

    // SAP Easy Access
    ThinkTime(9.9);
    SapGuiSetActiveWindow("wnd[0]", "SAP Easy Access", SAPGUI_MATCH_Exact);

    // NodeName: Office
    // NodePath: 2\1
    SapGuiTreeExpandNode("usr/cntlIMAGE_CONTAINER/shellcont/shell/shellcont[0]/shell",
    "Office", "0000000003", "Expand\\Office");

    // NodeName: Appointment Calendar
    // NodePath: 2\1\3
    SapGuiTreeExpandNode("usr/cntlIMAGE_CONTAINER/shellcont/shell/shellcont[0]/shell",
    "Appointment Calendar", "0000000008", "Expand\\Appointment Calendar");

    // NodeName: Owner
    // NodePath: 2\1\3\1
    SapGuiTreeSelectNode("usr/cntlIMAGE_CONTAINER/shellcont/shell/shellcont[0]/shell",
    "Owner", "0000000009", false, "SelNode\\Owner");

    // NodeName: Favorites
    // NodePath: 1
    SapGuiSelectTopNode("usr/cntlIMAGE_CONTAINER/shellcont/shell/shellcont[0]/shell",
    "Favorites", "Favo", "TopNode\\Favorites");

    // NodeName: Owner
    // NodePath: 2\1\3\1
    SapGuiTreeDblClickNode("usr/cntlIMAGE_CONTAINER/shellcont/shell/shellcont[0]/shell",
    "Owner", "0000000009", "DblClNode\\Owner");

    // Grid Control Info: /app/con[0]/ses[0]/wnd[0]/usr/cntlCALE_CONTROL/shellcont/shell/shellcont[1]/shell/8 columns

    // -------------------------------------

    // 1: 1:Time

    // 2: 2:Monday

    // 3: 3:Tuesday

    // 4: 4:Wednesday

    // 5: 5:Thursday

    // 6: 6:Friday

    // 7: 7:Saturday

    // 8: 8:Sunday

    // Termine anzeigen: DDIC
    ThinkTime(9.3);
    SapGuiSetActiveWindow("wnd[0]", "Termine anzeigen: DDIC", SAPGUI_MATCH_Exact);
    ThinkTime(7.4);
    SapGuiCalendarFirstVisibleDate("usr/cntlCALE_CONTROL/shellcont/shell/shellcont[0]/shell", "20040802");
    SapGuiGridScrollToRow("usr/cntlCALE_CONTROL/shellcont/shell/shellcont[1]/shell",12);
    SapGuiGridDblClickCurrentCell("usr/cntlCALE_CONTROL/shellcont/shell/shellcont[1]/shell");

    // Terminkalender: Create Appointment
    ThinkTime(10.1);
    SapGuiSetActiveWindow("wnd[1]", "Terminkalender: Create Appointment",SAPGUI_MATCH_Exact);
    SapGuiPressButton("tbar[0]/btn[12]");

    // Termine anzeigen: DDIC
    ThinkTime(2.3);
    SapGuiSetActiveWindow("wnd[0]", "Termine anzeigen: DDIC", SAPGUI_MATCH_Exact);
    SapGuiGridSelectCell("usr/cntlCALE_CONTROL/shellcont/shell/shellcont[1]/shell", 13, " 2");
    SapGuiIgnoreError(SAPENGINE_STATUSBAR_CHANGED, SEVERITY_SUCCESS);
    SapGuiGridContextMenu("usr/cntlCALE_CONTROL/shellcont/shell/shellcont[1]/shell");
    ThinkTime(2.1);
  end TMain;
Parent topic: Control Functions


SapGuiGridCurrentCellPressButton Function

Action

Emulates a button click in the currently selected cell of a grid.

Include file

SapGui.bdh

Syntax

SapGuiGridCurrentCellPressButton( in sControlId : string allownull,
                                  in sTimer     : string optional ) : boolean;
Parameter | Description
sControlId | The grid control's unique id.
sTimer | Timer name used for measurements.

Return value

  • true if successful
  • false otherwise

Example

transaction TMain
  var
    sConnID : string;
  begin
    // Connecting to SAP
    sConnID := SapGuiOpenConnection( " /SAP_CODEPAGE=1100 /FULLMENU 10.5.2.132 0 /3");

    SapGuiSetActiveConnection(sConnID);

    SapGuiSetActiveSession("ses[0]");

    // SAP
    SapGuiSetActiveWindow("wnd[0]", "SAP", SAPGUI_MATCH_ExactNoCase);

    SapGuiWindowAction(SAPGUI_WND_MAXIMIZE);

    SapGuiLogon("ddic", "*******", "000", "");
    SapGuiGridCurrentCellPressButton("/usr/tab/grid");
  end TMain;
Parent topic: Control Functions


SapGuiGridCurrentCellPressTotalRow Function

Action

Presses the total row button for the currently selected cell.

Include file

SapGui.bdh

Syntax

SapGuiGridCurrentCellPressTotalRow( in sControlId : string allownull,
                                    in sTimer     : string optional ) : boolean;
Parameter | Description
sControlId | The grid control's unique id.
sTimer | Timer name for measurements.

Return value

  • true if successful
  • false otherwise

Example

transaction TMain
  var
    sText   : boolean;
    sConnID : string;
  begin
    // Connecting to SAP
    sConnID := SapGuiOpenConnection(" /SAP_CODEPAGE=1100 /FULLMENU 10.5.2.132 0 /3");

    SapGuiSetActiveConnection(sConnID);

    SapGuiSetActiveSession("ses[0]");

    // SAP
    SapGuiSetActiveWindow("wnd[0]", "SAP", SAPGUI_MATCH_ExactNoCase);

    SapGuiWindowAction(SAPGUI_WND_MAXIMIZE);

    SapGuiLogon("ddic", "*******", "000", "");
    bCheck := SapGuiGridCurrentCellPressTotalRow("/usr/tab/grid" );
  end TMain;
Parent topic: Control Functions


SapGuiGridDblClick Function

Action

Emulates a double-click in a cell of the grid.

Include file

SapGui.bdh

Syntax

SapGuiGridDblClick( in sControlId : string allownull,
                    in nRow       : number,
                    in sCol       : string,
                    in sTimer     : string optional ) : boolean;
Parameter | Description
sControlId | The cell's unique id.
nRow | The cell's row.
sCol | The cell's column id.
sTimer | Timer name used for measurements.

Return value

  • true if successful
  • false otherwise

Example

transaction TMain
  var
    bCheck  : boolean;
    sConnID : string;
  begin
    // Connecting to SAP
    sConnID := SapGuiOpenConnection( " /SAP_CODEPAGE=1100 /FULLMENU 10.5.2.132 0 /3");

    SapGuiSetActiveConnection(sConnID);

    SapGuiSetActiveSession("ses[0]");

    // SAP
    SapGuiSetActiveWindow("wnd[0]", "SAP", SAPGUI_MATCH_ExactNoCase);

    SapGuiWindowAction(SAPGUI_WND_MAXIMIZE);

    SapGuiLogon("ddic", "*******", "000", "");
    bCheck := SapGuiGridDblClick("/usr/tab/chgrid", 0, "COL002" );
  end TMain;
Parent topic: Control Functions


SapGuiGridGetColumnTitles Function

Action

Returns a collection of strings that are used to display the title of a column. The grid control chooses the appropriate title according to the width of the column.

Include file

SapGui.bdh

Syntax

SapGuiGridGetColumnTitles( sControl  : in string allownull,
                           sColumn   : in string,
                           nIterator : out number) : boolean;
Parameter | Description
sControl | The unique ID of the grid control
sColumn | The column's identifier for which to retrieve the titles
nIterator | This parameter will be assigned a handle to the iterator

Return value

  • true if successful
  • false otherwise

Example

transaction TMain
  var
    nIterator : number;
    sColumn   : string;
    nType     : number;
  begin
    // Connecting to SAP
    gsConnID := SapGuiOpenConnection("/SAP_CODEPAGE=1100  /FULLMENU  atlis-minisap 00 /3 /UPDOWNLOAD_CP=2",
    "SapGuiOpenConnection");

    SapGuiSetActiveConnection(gsConnID);

    SapGuiSetActiveSession("ses[0]");

    // SAP
    SapGuiSetActiveWindow("wnd[0]", "SAP", SAPGUI_MATCH_ExactNoCase);

    SapGuiWindowAction(SAPGUI_WND_MAXIMIZE, "SapGuiWindowAction\\SAPGUI_WND_MAXIMIZE");

    // Logon to SAP System
    // Before running a test you have to customize the password parameter!
    ThinkTime(5.8);
    SapGuiLogon("bcuser", "minisap", "001", "", "SapGuiLogon");

    // SAP Easy Access
    SapGuiIgnoreError(SAPENGINE_STATUSBAR_CHANGED, SEVERITY_SUCCESS);
    SapGuiSetActiveWindow("wnd[0]", "SAP Easy Access", SAPGUI_MATCH_ExactNoCase);

    // Grid Control Info: /app/con[0]/ses[0]/wnd[0]/usr/cntlBCALVC_TOOLBAR_D100_C1/shellcont/shell/ 15 columns
    // -------------------------------------
    // 1: CARRID:ID
    // 2: CONNID:No.
    // 3: COUNTRYFR:Cty
    // 4: CITYFROM:Depart. city
    // 5: AIRPFROM:Airport
    // 6: COUNTRYTO:Cty
    // 7: CITYTO:Arrival city
    // 8: AIRPTO:Apt
    // 9: FLTIME:Flght time
    // 10: DEPTIME:Departure
    // 11: ARRTIME:Arrival
    // 12: DISTANCE:Distance
    // 13: DISTID:Dis.
    // 14: FLTYPE:Charter
    // 15: PERIOD:Day(s)

    SapGuiGridGetColumnTitles("usr/cntlBCALVC_TOOLBAR_D100_C1/shellcont/shell", "CONNID", nIterator);
    while SapGuiIteratorHasMore(nIterator) do
      SapGuiIteratorFetchNext(nIterator);
      SapGuiIteratorGetValue(nIterator, sColumn, nType);
      Print(sColumn);
    end;
    SapGuiIteratorRelease(nIterator);

  end TMain;
Parent topic: Control Functions


SapGuiGridModifyCheckbox Function

Action

Checks a check box in a grid control.

Include file

SapGui.bdh

Syntax

SapGuiGridModifyCheckbox( in sControlId : string allownull,
                          in nRow       : number,
                          in sCol       : string,
                          in bChecked   : boolean ) : boolean;
Parameter | Description
sControlId | The grid control's unique id.
nRow | The cell's row
sCol | The column id of the cell.
bChecked | If this parameter is "true", the checkbox will be checked.

Return value

  • true if successful
  • false otherwise

Example

transaction TMain
  var
    sConnID : string;
  begin
    // Connecting to SAP
    sConnID := SapGuiOpenConnection( " /SAP_CODEPAGE=1100 /FULLMENU 10.5.2.132 0 /3");

    SapGuiSetActiveConnection(sConnID);

    SapGuiSetActiveSession("ses[0]");

    // SAP
    SapGuiSetActiveWindow("wnd[0]", "SAP", SAPGUI_MATCH_ExactNoCase);

    SapGuiWindowAction(SAPGUI_WND_MAXIMIZE);

    SapGuiLogon("ddic", "*******", "000", "");
    SapGuiGridModifyCheckbox("/usr/tab/chk", 0, "COL03", true );
  end TMain;
Parent topic: Control Functions


SapGuiGridPressButton Function

Action

Clicks a button in a grid.

Include file

SapGui.bdh

Syntax

SapGuiGridPressButton( in sControlId : string allownull,
                       in nRow       : number,
                       in sCol       : string,
                       in sTimer     : string optional ) : boolean;
Parameter | Description
sControlId | The grid's unique id.
nRow | The cell's row.
sCol | The id of the column.
sTimer | Timer name used for measurements.

Return value

  • true if successful
  • false otherwise

Example

transaction TMain
  var
    bCheck : boolean;
    sConnID : string;
  begin
    // Connecting to SAP
    sConnID := SapGuiOpenConnection( " /SAP_CODEPAGE=1100 /FULLMENU 10.5.2.132 0 /3");

    SapGuiSetActiveConnection(sConnID);

    SapGuiSetActiveSession("ses[0]");

    // SAP
    SapGuiSetActiveWindow("wnd[0]", "SAP", SAPGUI_MATCH_ExactNoCase);

    SapGuiWindowAction(SAPGUI_WND_MAXIMIZE);

    SapGuiLogon("ddic", "*******", "000", "");
    bCheck := SapGuiGridPressButton("/usr/tab/cgrid", 0, "COL002");
  end TMain;
Parent topic: Control Functions


SapGuiGridPressColumnHeader Function

Action

Emulates a click on a column header of a grid.

Include file

SapGui.bdh

Syntax

SapGuiGridPressColumnHeader( in sControlId : stringallownull,
                             in sCol       : string,
                             in sTimer     : string optional) : boolean;
Parameter | Description
sControlId | The control's unique id.
sCol | The column's id.
sTimer | Timer name used for measurements.

Return value

  • true if successful
  • false otherwise

Example

transaction TMain
  var
    bCheck : boolean;
    sConnID : string;
  begin
    // Connecting to SAP
    sConnID := SapGuiOpenConnection( " /SAP_CODEPAGE=1100 /FULLMENU 10.5.2.132 0 /3");

    SapGuiSetActiveConnection(sConnID);

    SapGuiSetActiveSession("ses[0]");

    // SAP
    SapGuiSetActiveWindow("wnd[0]", "SAP", SAPGUI_MATCH_ExactNoCase);

    SapGuiWindowAction(SAPGUI_WND_MAXIMIZE);

    SapGuiLogon("ddic", "*******", "000", "");
    bCheck := SapGuiGridPressColumnHeader("/usr/tab/ch", "OOFOCOLUMN");
  end TMain;
Parent topic: Control Functions


SapGuiGridPressToolbarButton Function

Action

Emulates a click on a grid toolbar button.

Include file

SapGui.bdh

Syntax

SapGuiGridPressToolbarButton( in sControlId : string allownull,
                              in sButton    : string,
                              in sTimer     : string optional ) : boolean;
Parameter | Description
sControlId | The grid control's unique id.
sButton | The button's id.
sTimer | Timer name for measurements.

Return value

  • true if successful
  • false otherwise

Example

transaction TMain
  var
    bCheck : boolean;
    sConnID : string;
  begin
    // Connecting to SAP
    sConnID := SapGuiOpenConnection( " /SAP_CODEPAGE=1100 /FULLMENU 10.5.2.132 0 /3");

    SapGuiSetActiveConnection(sConnID);

    SapGuiSetActiveSession("ses[0]");

    // SAP
    SapGuiSetActiveWindow("wnd[0]", "SAP", SAPGUI_MATCH_ExactNoCase);
    SapGuiWindowAction(SAPGUI_WND_MAXIMIZE);

    SapGuiLogon("ddic", "*******", "000", "");
    bCheck := SapGuiGridPressToolbarButton("/usr/tab/gr", "btn");
  end TMain;
Parent topic: Control Functions


SapGuiGridPressToolbarContextButton Function

Action

Emulates a virtual user opening a list of options by clicking on a context button.

Include file

SapGui.bdh

Syntax

SapGuiGridPressToolbarContextButton( in sControlId : string allownull,
                                     in sButton    : string,
                                     in sTimer     : string optional ) : boolean;
Parameter | Description
sControlId | The grid control's unique id.
sButton | The id of the button.
sTimer | Timer name for measurements.

Return value

  • true if successful
  • false otherwise

Example

transaction TMain
  var
    bCheck : boolean;
    sConnID : string;
  begin
    // Connecting to SAP
    sConnID := SapGuiOpenConnection( " /SAP_CODEPAGE=1100 /FULLMENU 10.5.2.132 0 /3");

    SapGuiSetActiveConnection(sConnID);

    SapGuiSetActiveSession("ses[0]");

    // SAP
    SapGuiSetActiveWindow("wnd[0]", "SAP", SAPGUI_MATCH_ExactNoCase);

    SapGuiWindowAction(SAPGUI_WND_MAXIMIZE);

    SapGuiLogon("ddic", "*******", "000", "");
    bCheck := SapGuiGridPressToolbarContextButton("/usr/tab/gr", "btid");
  end TMain;
Parent topic: Control Functions


SapGuiGridPressTotalRow Function

Action

Presses the total row button in a grid. This function may either expand or collapse the row.

Include file

SapGui.bdh

Syntax

SapGuiGridScrollToRow( in sControlId : string allownull,
                       in nRow       : number,
                       in sTimer     : string optional ) : boolean;
Parameter | Description
sControlId | The grid control's unique id.
nRow | Specifies the row to be expanded or collapsed
sTimer | Timer name for measurements.

Return value

  • true if successful
  • false otherwise

Example

transaction TMain
  var
    bCheck : boolean;
    sConnID : string;
  begin
    // Connecting to SAP
    sConnID := SapGuiOpenConnection( " /SAP_CODEPAGE=1100 /FULLMENU 10.5.2.132 0 /3");

    SapGuiSetActiveConnection(sConnID);

    SapGuiSetActiveSession("ses[0]");

    // SAP
    SapGuiSetActiveWindow("wnd[0]", "SAP", SAPGUI_MATCH_ExactNoCase);

    SapGuiWindowAction(SAPGUI_WND_MAXIMIZE);

    SapGuiLogon("ddic", "*******", "000", "");
    bCheck := SapGuiGridPressTotalRow("/usr/tab/cgrid", 3);
  end TMain;
Parent topic: Control Functions


SapGuiGridScrollToRow Function

Action

Scrolls to the specified row of the SapGui grid control.

Include file

SapGui.bdh

Syntax

SapGuiGridScrollToRow( in sControlId : string allownull,
                       in nRow       : number,
                       in sTimer     : string optional ) : boolean;
Parameter | Description
sControlId | The grid control's unique id.
nRow | Specifies the row where the function should scroll to.
sTimer | Timer name for measurements.

Return value

  • true if successful
  • false otherwise

Example

transaction TMain
  var
    sConnID : string;
  begin
    // Connecting to SAP
    sConnID := SapGuiOpenConnection(" /SAP_CODEPAGE=1100 /FULLMENU 10.5.2.198 0 /3");

    SapGuiSetActiveConnection(sConnID);

    SapGuiSetActiveSession("ses[0]");

    // SAP
    SapGuiSetActiveWindow("wnd[0]", "SAP", SAPGUI_MATCH_Exact);

    SapGuiWindowAction(SAPGUI_WND_MAXIMIZE);

    // Logon to SAP System
    // Before running a test you have to customize the password parameter!
    SapGuiIgnoreError(SAPENGINE_STATUSBAR_CHANGED, SEVERITY_SUCCESS);
    ThinkTime(2.8);
    SapGuiLogon("ddic", "minisap", "000", "");

    // Copyright
    ThinkTime(2.1);
    SapGuiSetActiveWindow("wnd[1]", "Copyright", SAPGUI_MATCH_Exact);

    SapGuiPressButton("tbar[0]/btn[0]");

    // SAP Easy Access
    ThinkTime(9.9);
    SapGuiSetActiveWindow("wnd[0]", "SAP Easy Access", SAPGUI_MATCH_Exact);

    // NodeName: Office
    // NodePath: 2\1
    SapGuiTreeExpandNode("usr/cntlIMAGE_CONTAINER/shellcont/shell/shellcont[0]/shell",
    "Office", "0000000003", "Expand\\Office");

    // NodeName: Telephone Integration
    // NodePath: 2\1\2
    SapGuiTreeExpandNode("usr/cntlIMAGE_CONTAINER/shellcont/shell/shellcont[0]/shell",
    "Telephone Integration", "0000000005", "Expand\\Telephone Integration");

    // NodeName: Appointment Calendar
    // NodePath: 2\1\3
    SapGuiTreeExpandNode("usr/cntlIMAGE_CONTAINER/shellcont/shell/shellcont[0]/shell",
    "Appointment Calendar", "0000000008", "Expand\\Appointment Calendar");

    // NodeName: Owner
    // NodePath: 2\1\3\1
    SapGuiTreeSelectNode("usr/cntlIMAGE_CONTAINER/shellcont/shell/shellcont[0]/shell",
    "Owner", "0000000009", false,"SelNode\\Owner");

    // NodeName: Favorites
    // NodePath: 1
    SapGuiSelectTopNode("usr/cntlIMAGE_CONTAINER/shellcont/shell/shellcont[0]/shell",
    "Favorites", "Favo", "TopNode\\Favorites");

    // NodeName: Owner
    // NodePath: 2\1\3\1
    SapGuiTreeDblClickNode("usr/cntlIMAGE_CONTAINER/shellcont/shell/shellcont[0]/shell",
    "Owner", "0000000009", "DblClNode\\Owner");
    // Grid Control Info: /app/con[0]/ses[0]/wnd[0]/usr/cntlCALE_CONTROL/shellcont/shell/shellcont[1]/shell/8 columns
    // -------------------------------------
    // 1: 1:Time
    // 2: 2:Monday
    // 3: 3:Tuesday
    // 4: 4:Wednesday
    // 5: 5:Thursday
    // 6: 6:Friday
    // 7: 7:Saturday
    // 8: 8:Sunday

    // Termine anzeigen: DDIC
    ThinkTime(9.3);
    SapGuiSetActiveWindow("wnd[0]", "Termine anzeigen: DDIC",SAPGUI_MATCH_Exact);

    ThinkTime(3.9);
    SapGuiCalendarFirstVisibleDate("usr/cntlCALE_CONTROL/shellcont/shell/shellcont[0]/shell","20040802");

    SapGuiGridSelectCell("usr/cntlCALE_CONTROL/shellcont/shell/shellcont[1]/shell", 9, " 3");

    SapGuiGridContextMenu("usr/cntlCALE_CONTROL/shellcont/shell/shellcont[1]/shell");

    ThinkTime(20.6);
    SapGuiGridScrollToRow("usr/cntlCALE_CONTROL/shellcont/shell/shellcont[1]/shell", 0);

  end TMain;
Parent topic: Control Functions


SapGuiGridSelectCell Function

Action

Selects the specified cell in a SapGui grid control.

Include file

SapGui.bdh

Syntax

SapGuiGridSelectCell( in sControlId : string allownull,
                      in nRow       : number,
                      in sCol       : string,
                      in sTimer     : string optional ) : boolean;
Parameter | Description
sControlId | The grid control's unique id.
nRow | Specifies the row where the function should scroll to.
sCol | The id of the column.
sTimer | Timer name for measurements.

Return value

  • true if successful
  • false otherwise

Example

transaction TMain
  var
    sConnID : string;
  begin
    // Connecting to SAP
    gsConnID := SapGuiOpenConnection(" /SAP_CODEPAGE=1100 /FULLMENU 10.5.2.198 0 /3");

    SapGuiSetActiveConnection(sConnID);

    SapGuiSetActiveSession("ses[0]");

    // SAP
    SapGuiSetActiveWindow("wnd[0]", "SAP", SAPGUI_MATCH_Exact);

    SapGuiWindowAction(SAPGUI_WND_MAXIMIZE);

    // Logon to SAP System
    // Before running a test you have to customize the password parameter!
    SapGuiIgnoreError(SAPENGINE_STATUSBAR_CHANGED, SEVERITY_SUCCESS);
    ThinkTime(2.3);
    SapGuiLogon("ddic", "*******", "000", "");

    // Copyright
    SapGuiSetActiveWindow("wnd[1]", "Copyright", SAPGUI_MATCH_Exact);

    SapGuiPressButton("tbar[0]/btn[0]");

    // SAP Easy Access
    ThinkTime(6.3);
    SapGuiSetActiveWindow("wnd[0]", "SAP Easy Access", SAPGUI_MATCH_Exact);

    // NodeName: Office
    // NodePath: 2\1
    SapGuiTreeExpandNode("usr/cntlIMAGE_CONTAINER/shellcont/shell/shellcont[0]/shell",
    "Office", "0000000003", "Expand\\Office");

    // NodeName: Telephone Integration
    // NodePath: 2\1\2
    SapGuiTreeExpandNode("usr/cntlIMAGE_CONTAINER/shellcont/shell/shellcont[0]/shell",
    "Telephone Integration", "0000000005", "Expand\\Telephone Integration");

    // NodeName: Appointment Calendar
    // NodePath: 2\1\3
    SapGuiTreeExpandNode("usr/cntlIMAGE_CONTAINER/shellcont/shell/shellcont[0]/shell",
    "Appointment Calendar", "0000000008", "Expand\\Appointment Calendar");

    // NodeName: Owner
    // NodePath: 2\1\3\1
    SapGuiTreeSelectNode("usr/cntlIMAGE_CONTAINER/shellcont/shell/shellcont[0]/shell",
    "Owner", "0000000009", false, "SelNode\\Owner");

    // NodeName: Favorites
    // NodePath: 1
    SapGuiSelectTopNode("usr/cntlIMAGE_CONTAINER/shellcont/shell/shellcont[0]/shell",
    "Favorites", "Favo", "TopNode\\Favorites") ;

    // NodeName: Owner
    // NodePath: 2\1\3\1
    SapGuiTreeDblClickNode("usr/cntlIMAGE_CONTAINER/shellcont/shell/shellcont[0]/shell",
    "Owner", "0000000009", "DblClNode\\Owner");
    // Grid Control Info: /app/con[0]/ses[0]/wnd[0]/usr/cntlCALE_CONTROL/shellcont/shell/shellcont[1]/shell/8 columns
    // -------------------------------------
    // 1: 1:Time
    // 2: 2:Monday
    // 3: 3:Tuesday
    // 4: 4:Wednesday
    // 5: 5:Thursday
    // 6: 6:Friday
    // 7: 7:Saturday
    // 8: 8:Sunday

    // Display appointments: DDIC
    SapGuiSetActiveWindow("wnd[0]", " Display appointments: DDIC", SAPGUI_MATCH_Exact);

    ThinkTime(3.9);
    SapGuiCalendarFirstVisibleDate("usr/cntlCALE_CONTROL/shellcont/shell/shellcont[0]/shell","20040802");

    SapGuiGridSelectCell("usr/cntlCALE_CONTROL/shellcont/shell/shellcont[1]/shell", 9, " 3");

    SapGuiGridContextMenu("usr/cntlCALE_CONTROL/shellcont/shell/shellcont[1]/shell");

    ThinkTime(20.6);
    SapGuiGridScrollToRow("usr/cntlCALE_CONTROL/shellcont/shell/shellcont[1]/shell", 0);
  end TMain;
Parent topic: Control Functions


SapGuiGridSelectContextMenu Function

Action

Selects an option from a context menu in a grid.

Include file

SapGui.bdh

Syntax

SapGuiGridSelectContextMenu( in sControlId : string allownull,
                             in sFunction  : string,
                             in sTimer     : string optional ) : boolean;
Parameter | Description
sControlId | The grid control's unique id.
sFunction | The id of the item to be selected.
sTimer | Timer name for measurements.

Return value

  • true if successful
  • false otherwise

Example

transaction TMain
  var
    bCheck : boolean;
    sConnID : string;
  begin
    // Connecting to SAP
    sConnID := SapGuiOpenConnection( " /SAP_CODEPAGE=1100 /FULLMENU 10.5.2.132 0 /3");

    SapGuiSetActiveConnection(sConnID);

    SapGuiSetActiveSession("ses[0]");

    // SAP
    SapGuiSetActiveWindow("wnd[0]", "SAP", SAPGUI_MATCH_ExactNoCase);

    SapGuiWindowAction(SAPGUI_WND_MAXIMIZE);

    SapGuiLogon("ddic", "*******", "000", "");
    bCheck := SapGuiGridSelectContextMenu("/usr/tab/cbgrid", "CODE");
  end TMain;
Parent topic: Control Functions


SapGuiGridSelectToolbarMenu Function

Action

Selects an option from a grid toolbar menu.

Include file

SapGui.bdh

Syntax

SapGuiGridSelectToolbarMenu( in sControl  : string allownull,
                             in sFunction : string,
                             in sTimer    : string optional ) : boolean;
Parameter | Description
sControlId | The grid control's unique id.
sFunction | Id for the selected menu.
sTimer | Timer name for measurements.

Return value

  • true if successful
  • false otherwise

Example

transaction TMain
  var
    bCheck : boolean;
    sConnID : string;
  begin
    // Connecting to SAP
    sConnID := SapGuiOpenConnection( " /SAP_CODEPAGE=1100 /FULLMENU 10.5.2.132 0 /3");
    SapGuiSetActiveConnection(sConnID);
    SapGuiSetActiveSession("ses[0]");

    // SAP
    SapGuiSetActiveWindow("wnd[0]", "SAP", SAPGUI_MATCH_ExactNoCase);
    SapGuiWindowAction(SAPGUI_WND_MAXIMIZE);
    SapGuiLogon("ddic", "*******", "000", "");
    bCheck := SapGuiGridSelectToolbarMenu("/usr/tab/grid", "FUNCODE");
  end TMain;
Parent topic: Control Functions


SapGuiGridSetCellData Function

Action

Writes data to the specified cell of a grid control.

Include file

SapGui.bdh

Syntax

SapGuiGridSetCellData( in sControlId : string allownull,
                       in nRow       : number,
                       in sCol       : string,
                       in sVal       : string,
                       in sTimer     : string optional ) : boolean;
Parameter | Description
sControlId | The grid control's unique id.
nRow | Specifies the row where the function should scroll to.
sCol | The id of the column.
sVal | The value to be set for the specified cell.
sTimer | Timer name used for measurements.

Return value

  • true if successful
  • false otherwise

Example

transaction TMain
  var
    bCheck : boolean;
    sConnID : string;
  begin

    // Connecting to SAP
    sConnID := SapGuiOpenConnection( " /SAP_CODEPAGE=1100 /FULLMENU 10.5.2.132 0 /3");
    SapGuiSetActiveConnection(sConnID);
    SapGuiSetActiveSession("ses[0]");

    // SAP
    SapGuiSetActiveWindow("wnd[0]", "SAP", SAPGUI_MATCH_ExactNoCase);
    SapGuiWindowAction(SAPGUI_WND_MAXIMIZE);
    SapGuiLogon("ddic", "*******", "000", "");
    bCheck := SapGuiGridSetCellData("/usr/tab/grid", 0, "OOBBA", "Value" );
  end TMain;
Parent topic: Control Functions


SapGuiGridSetColumnWidth Function

Action

Sets the column width in a SapGui grid control to a specified value.

Include file

SapGui.bdh

Syntax

SapGuiGridSetColumnWidth( in sControl : string allownull,
                          in sCol     : string,
                          in nWidth   : number,
                          in sTimer   : string optional ) : boolean;
Parameter | Description
sControlId | The grid control's unique id.
sCol | The id of the column.
nWidth | The new width of the column.
sTimer | Timer name used for measurements.

Return value

  • true if successful
  • false otherwise

Example

transaction TMain
  var
    bCheck : boolean;
    sConnID : string;
  begin

    // Connecting to SAP
    sConnID := SapGuiOpenConnection( " /SAP_CODEPAGE=1100 /FULLMENU 10.5.2.132 0 /3");
    SapGuiSetActiveConnection(sConnID);
    SapGuiSetActiveSession("ses[0]");

    // SAP
    SapGuiSetActiveWindow("wnd[0]", "SAP", SAPGUI_MATCH_ExactNoCase);
    SapGuiWindowAction(SAPGUI_WND_MAXIMIZE);
    SapGuiLogon("ddic", "*******", "000", "");
    bCheck := SapGuiGridSetColumnWidth("/usr/tab/grid", "OOBOO", 234 );
  end TMain;
Parent topic: Control Functions


SapGuiIgnoreError Function

Action

Ignores SapGui errors. It is scripted by the Silk Performer Recorder for ignoring errors that are indicated in the SapGui status bar during recording. Although this function is only scripted in this case it can also be applied to ignore any SapGui error.

Include file

SapGui.bdh

Syntax

SapGuiIgnoreError( in nError    : number,
                   in nSeverity : number optional := SEVERITY_SUCCESS );
Parameter | Description
nError | The error to be ignored in the next SapGui function call.
nSeverity Optional: Severity of the error that is raised if the verification fails. Can be one of the following values:
  • SEVERITY_SUCCESS: (Default) Success; no error (numerical value: 0)
  • SEVERITY_INFORMATIONAL: Informational; no error (numerical value: 1)
  • SEVERITY_WARNING: Warning; no error (numerical value: 2)
  • SEVERITY_ERROR: Error; simulation continues (numerical value: 3)
  • SEVERITY_TRANS_EXIT: Error; the active transaction is aborted (numerical value: 4)
  • SEVERITY_PROCESS_EXIT: Error; the simulation is aborted (numerical value: 5)

Example

transaction TMain
  var
    sConnID : string;
  begin

    // Connecting to SAP
    sConnID := SapGuiOpenConnection(" /SAP_CODEPAGE=1100 /FULLMENU 10.5.2.198 0 /3");
    SapGuiSetActiveConnection(sConnID);
    SapGuiSetActiveSession("ses[0]");

    // SAP
    SapGuiSetActiveWindow("wnd[0]", "SAP", SAPGUI_MATCH_Exact);
    SapGuiWindowAction(SAPGUI_WND_MAXIMIZE);

    // Logon to SAP System
    // Before running a test you have to customize the password parameter!
    SapGuiIgnoreError(SAPENGINE_STATUSBAR_CHANGED, SEVERITY_ERROR);
    ThinkTime(2.8);
    SapGuiLogon("ddic", "minisap", "000", "");

    // Copyright
    SapGuiSetActiveWindow("wnd[1]", "Copyright", SAPGUI_MATCH_Exact);
    SapGuiPressButton("tbar[0]/btn[0]");

  end TMain;
Parent topic: Control Functions


SapGuiPressButton Function

Action

Performs a click on the specified SapGui button control.

Include file

SapGui.bdh

Syntax

SapGuiPressButton( in sControlId : string allownull,
                   in sTimer     : string optional ) : boolean;
Parameter | Description
sControlId | The uniquely identifying id of a button control.
sTimer | Timer name used for measurements.

Return value

  • true if successful
  • false otherwise

Example

transaction TMain
  var
    sId : string;
  begin
    // Connecting to SAP
    sId := SapGuiOpenConnection(" /SAP_CODEPAGE=1100 /FULLMENU lab77 00 /3");

    SapGuiSetActiveConnection(sId);

    SapGuiSetActiveSession("ses[0]");

    // SAP
    SapGuiSetActiveWindow("wnd[0]", "SAP", SAPGUI_MATCH_Exact);

    SapGuiWindowResize(117, 28, false);

    // Logon to SAP System
    // Before running a test you have to customize the password parameter!
    ThinkTime(5.3);
    SapGuiLogon("bcuser", "*******", "000", "");

    // Copyright
    SapGuiSetActiveWindow("wnd[1]", "Copyright", SAPGUI_MATCH_Exact);

    // Continue (Enter)
    SapGuiPressButton("tbar[0]/btn[0]", "Continue (Enter)");

    // SAP Easy Access
    SapGuiSetActiveWindow("wnd[0]", "SAP Easy Access", SAPGUI_MATCH_Exact);

    // Other menu
    SapGuiPressButton("tbar[1]/btn[17]", " Other menu");

    // Restrict Values
    SapGuiSetActiveWindow("wnd[1]", "Restrict Values", SAPGUI_MATCH_Exact);

    // Cancel (F12)
    SapGuiPressButton("tbar[0]/btn[12]", "Cancel (F12)");

    // SAP Easy Access
    SapGuiSetActiveWindow("wnd[0]", "SAP Easy Access", SAPGUI_MATCH_Exact);

    // Log off (Shift+F3)
    SapGuiPressButton("tbar[0]/btn[15]", "Log off (Shift+F3)");

    // Log Off
    SapGuiSetActiveWindow("wnd[1]", "Log Off", SAPGUI_MATCH_Exact);

    // Yes
    SapGuiPressButton("usr/btnSPOP-OPTION1", "Yes");
  end TMain;
Parent topic: Control Functions


SapGuiPressToolbarButton Function

Action

Presses a toolbar button.

Include file

SapGui.bdh

Syntax

SapGuiPressToolbarButton( in sControlId : string allownull,
                          in sButtonId  : string,
                          in sTimer     : string optional ) : boolean;
Parameter | Description
sControlId | The toolbar's unique id.
sButtonId | The button's id.
sTimer | Timer name for measurements.

Return value

  • true if successful
  • false otherwise

Example

transaction TMain
  var
    bCheck : boolean;
    sConnID : string;
  begin
    // Connecting to SAP
    sConnID := SapGuiOpenConnection( " /SAP_CODEPAGE=1100 /FULLMENU 10.5.2.132 0 /3");

    SapGuiSetActiveConnection(sConnID);

    SapGuiSetActiveSession("ses[0]");

    // SAP
    SapGuiSetActiveWindow("wnd[0]", "SAP", SAPGUI_MATCH_ExactNoCase);

    SapGuiWindowAction(SAPGUI_WND_MAXIMIZE);

    SapGuiLogon("ddic", "*******", "000", "");
    bCheck := SapGuiPressToolbarButton("/usr/tab/tbar", "btn" );
  end TMain;
Parent topic: Control Functions


SapGuiPressToolbarContextButton Function

Action

Presses the toolbar context button.

Include file

SapGui.bdh

Syntax

SapGuiGridPressToolbarContextButton( in sControlId : string allownull,
                                     in sButton    : string,
                                     in sTimer     : string optional ) : boolean;
Parameter | Description
sControlId | The toolbar's unique id.
sButton | The button's id.
sTimer | Timer name for measurements.

Return value

  • true if successful
  • false otherwise

Example

transaction TMain
  var
    bCheck : boolean;
    sConnID : string;
  begin
    // Connecting to SAP
    sConnID := SapGuiOpenConnection( " /SAP_CODEPAGE=1100 /FULLMENU 10.5.2.132 0 /3");

    SapGuiSetActiveConnection(sConnID);

    SapGuiSetActiveSession("ses[0]");

    // SAP
    SapGuiSetActiveWindow("wnd[0]", "SAP", SAPGUI_MATCH_ExactNoCase);

    SapGuiWindowAction(SAPGUI_WND_MAXIMIZE);

    SapGuiLogon("ddic", "*******", "000", "");
    bCheck := SapGuiPressToolbarContextButton("/usr/tab/tbab", "Btns2");
  end TMain;
Parent topic: Control Functions


SapGuiSelectComboBoxEntry Function

Action

Selects an item in a SapGui combobox.

Include file

SapGui.bdh

Syntax

SapGuiSelectComboBoxEntry( in sControlId : string allownull,
                           in sEntry     : string,
                           in sTimer     : string optional ) : boolean;
Parameter | Description
sControlId | The uniquely identifying id of a combobox.
Sentry | The value to be selected from the combobox.
sTimer | Timer name used for measurements.

Return value

  • true if successful
  • false otherwise

Example

transaction TMain
  var
    sConnID : string;
  begin
    // Connecting to SAP
    sConnID := SapGuiOpenConnection(" /SAP_CODEPAGE=1100 /FULLMENU 10.5.2.198 0 /3");
    SapGuiSetActiveConnection(sConnID);
    SapGuiSetActiveSession("ses[0]");

    // SAP
    SapGuiSetActiveWindow("wnd[0]", "SAP", SAPGUI_MATCH_Exact);
    SapGuiWindowAction(SAPGUI_WND_MAXIMIZE);

    // Logon to SAP System
    // Before running a test you have to customize the password parameter!
    SapGuiIgnoreError(SAPENGINE_STATUSBAR_CHANGED, SEVERITY_SUCCESS);
    ThinkTime(2.8);
    SapGuiLogon("ddic", "minisap", "000", "");

    // Copyright
    ThinkTime(2.1);
    SapGuiSetActiveWindow("wnd[1]", "Copyright", SAPGUI_MATCH_Exact);
    SapGuiPressButton("tbar[0]/btn[0]");

    // SAP Easy Access
    ThinkTime(3.8);
    SapGuiSetActiveWindow("wnd[0]", "Display Document: No address for SAP user in SAPoffice !", SAPGUI_MATCH_Exact);
    SapGuiSelectTab("usr/tabsSO33_TAB1/tabpTAB2");
    ThinkTime(4.0);
    SapGuiSelectTab("usr/tabsSO33_TAB1/tabpTAB3");
    ThinkTime(4.5);
    SapGuiTreeSetHierarchyWidth( "usr/tabsSO33_TAB1/tabpTAB3/ssubSUB1:SAPLSO09:0150/cntlSPLITTER/shellcont/shell/shellcont[0]/shell", 250);
    SapGuiSelectTab("usr/tabsSO33_TAB1/tabpTAB2");
    ThinkTime(9.0);
    SapGuiSelectComboBoxEntry("usr/tabsSO33_TAB1/tabpTAB2/ssubSUB1:SAPLSO33:1200/cmbSOS33-OBJPRI", "510", "High");
    SapGuiSetFocus("usr/tabsSO33_TAB1/tabpTAB2/ssubSUB1:SAPLSO33:1200/cmbSOS33-OBJPRI");
    SapGuiPressButton("tbar[0]/btn[15]");

    // Grid Control Info:
    // /app/con[0]/ses[0]/wnd[0]/usr/cntlSINWP_CONTAINER/shellcont/shell/shellcont[1]/shell/shellcont[0]/shell/9 columns
    // -------------------------------------
    // 1: STATSO:Message attributes
    // 2: OBJTP:Type
    // 3: OBJDES:Title
    // 4: ATTACH:Attachments
    // 5: CRADR:Author
    // 6: INDAT:Date received
    // 7: SNDCP:Copy
    // 8: RESUB:Resubmission
    // 9: RECCNT:Recipient

    // Business Workplace von DDIC
    ThinkTime(8.8);
    SapGuiSetActiveWindow("wnd[0]", "Business Workplace von DDIC", SAPGUI_MATCH_Exact);
    SapGuiPressButton("tbar[0]/btn[15]");

    // SAP Easy Access
    SapGuiSetActiveWindow("wnd[0]", "SAP Easy Access", SAPGUI_MATCH_Exact);
    ThinkTime(2.3);
    SapGuiPressButton("tbar[0]/btn[15]");

    // Log Off
    ThinkTime(2.0);
    SapGuiSetActiveWindow("wnd[1]", "Log Off", SAPGUI_MATCH_Exact);

    // Yes
    SapGuiPressButton("usr/btnSPOP-OPTION1", "Yes");
  end TMain;
Parent topic: Control Functions


SapGuiSelectMenu Function

Action

Selects a menu from the SapGui menu bar.

Include file

SapGui.bdh

Syntax

SapGuiSelectMenu( in sControlId : string allownull,
                  in sTimer     : string optional ) : boolean;
Parameter | Description
sControlId | The uniquely identifying id of a menu item.
sTimer | Timer name used for measurements.

Return value

  • true if successful
  • false otherwise

Example

transaction TMain
  var
    sConnId : string;
  begin
    // Connecting to SAP
    sConnID := SapGuiOpenConnection(" /SAP_CODEPAGE=1100 /FULLMENU 10.5.2.198 0 /3");
    SapGuiSetActiveConnection(sConnID);
    SapGuiSetActiveSession("ses[0]");

    // SAP
    SapGuiSetActiveWindow("wnd[0]", "SAP", SAPGUI_MATCH_Exact);
    SapGuiWindowAction(SAPGUI_WND_MAXIMIZE);

    // Logon to SAP System
    // Before running a test you have to customize the password parameter!
    SapGuiIgnoreError(SAPENGINE_STATUSBAR_CHANGED, SEVERITY_SUCCESS);
    ThinkTime(2.9);
    SapGuiLogon("ddic", "*******", "000", "");

    // Copyright
    SapGuiSetActiveWindow("wnd[1]", "Copyright", SAPGUI_MATCH_Exact);
    SapGuiPressButton("tbar[0]/btn[0]");

    // SAP Easy Access
    ThinkTime(17.0);
    SapGuiSetActiveWindow("wnd[0]", "SAP Easy Access", SAPGUI_MATCH_Exact);
    SapGuiSelectMenu("mbar/menu[3]/menu[0]");

    // System administration information
    ThinkTime(6.5);
    SapGuiSetActiveWindow("wnd[1]", "System administration information", SAPGUI_MATCH_Exact);
    SapGuiPressButton("tbar[0]/btn[12]");
  end TMain;
Parent topic: Control Functions


SapGuiSelectRadioButton Function

Action

Selects the specifed SapGui radio button.

Include file

SapGui.bdh

Syntax

SapGuiSelectRadioButton( in sControlId : string allownull,
                         in sTimer     : string optional ) : boolean;
Parameter | Description
sControlId | The uniquely identifying id of a radio button control.
sTimer | Timer name used for measurements.

Return value

  • true if successful
  • false otherwise

Example

transaction TMain
  var
    sConnId : string;
  begin
    // Connecting to SAP
    sConnID := SapGuiOpenConnection(" /SAP_CODEPAGE=1100 /FULLMENU 10.5.2.198 0 /3");
    SapGuiSetActiveConnection(sConnID);
    SapGuiSetActiveSession("ses[0]");

    // SAP
    SapGuiSetActiveWindow("wnd[0]", "SAP", SAPGUI_MATCH_Exact);
    SapGuiWindowAction(SAPGUI_WND_MAXIMIZE);

    // Logon to SAP System
    // Before running a test you have to customize the password parameter!
    SapGuiIgnoreError(SAPENGINE_STATUSBAR_CHANGED, SEVERITY_SUCCESS);
    ThinkTime(2.9);
    SapGuiLogon("ddic", "*******", "000", "");

    // Copyright
    SapGuiPressButton("tbar[1]/btn[28]");

    // Mappenselektion
    ThinkTime(4.0);
    SapGuiSetActiveWindow("wnd[1]", "Mappenselektion", SAPGUI_MATCH_Exact);
    SapGuiSelectRadioButton("usr/radSOS06-S_FOLPRV", "Private");
    SapGuiSetFocus("usr/radSOS06-S_FOLPRV");
    SapGuiPressButton("tbar[0]/btn[12]");
  end TMain;
Parent topic: Control Functions


SapGuiSelectTab Function

Action

Activates the specified tab sheet inside a SapGui tab control.

Include file

SapGui.bdh

Syntax

SapGuiSelectTab( in sControlId : string allownull,
                 in sTimer     : string optional ) : boolean;
Parameter | Description
sControlId | The uniquely identifying id of the tab sheet to be activated.
sTimer | Timer name used for measurements.

Return value

  • true if successful
  • false otherwise

Example

transaction TMain
  var
    sConnId : string;
  begin
    // Connecting to SAP
    sConnID := SapGuiOpenConnection(" /SAP_CODEPAGE=1100 /FULLMENU 10.5.2.198 0 /3");
    SapGuiSetActiveConnection(sConnID);
    SapGuiSetActiveSession("ses[0]");

    // SAP
    SapGuiSetActiveWindow("wnd[0]", "SAP", SAPGUI_MATCH_Exact);
    SapGuiWindowAction(SAPGUI_WND_MAXIMIZE);

    // Logon to SAP System
    // Before running a test you have to customize the password parameter!
    SapGuiIgnoreError(SAPENGINE_STATUSBAR_CHANGED, SEVERITY_SUCCESS);
    ThinkTime(2.9);
    SapGuiLogon("ddic", "*******", "000", "");

    // Other menu
    SapGuiIgnoreError(SAPENGINE_STATUSBAR_CHANGED, SEVERITY_SUCCESS);
    ThinkTime(2.4);
    SapGuiPressButton("tbar[1]/btn[17]", " Other menu");

    // Wertebereich einschränken
    ThinkTime(3.2);
    SapGuiSetActiveWindow("wnd[1]", "Wertebereich einschränken", SAPGUI_MATCH_Exact);
    SapGuiSelectTab("usr/tabsG_SELONETABSTRIP/tabpTAB001");
    SapGuiSelectTab("usr/tabsG_SELONETABSTRIP/tabpTAB002");
  end TMain;
Parent topic: Control Functions


SapGuiSelectToolbarMenuItem Function

Action

Selects a toolbar menu item.

Include file

SapGui.bdh

Syntax

SapGuiSelectToolbarMenuItem( in sControlId : string allownull,
                             in sMenuId    : string,
                             in sTimer     : string optional ) :  boolean;
Parameter | Description
sControlId | The toolbar's unique id.
sMenuId | The id of the menu item.
sTimer | Timer name for measurements.

Return value

  • true if successful
  • false otherwise

Example

transaction TMain
  var
    bCheck : boolean;
    sConnID : string;
  begin
    // Connecting to SAP
    sConnID := SapGuiOpenConnection( " /SAP_CODEPAGE=1100 /FULLMENU 10.5.2.132 0 /3");
    SapGuiSetActiveConnection(sConnID);
    SapGuiSetActiveSession("ses[0]");

    // SAP
    SapGuiSetActiveWindow("wnd[0]", "SAP", SAPGUI_MATCH_ExactNoCase);
    SapGuiWindowAction(SAPGUI_WND_MAXIMIZE);
    SapGuiLogon("ddic", "*******", "000", "");
    bCheck := SapGuiSelectToolbarMenuItem("/usr/tab/tbar", "OBI");
  end TMain;
Parent topic: Control Functions


SapGuiSelectToolbarMenuItemByText Function

Action

Selects a toolbar menu item using the text of the item.

Include file

SapGui.bdh

Syntax

SapGuiSelectToolbarMenuItemByText( in sControlId : string allownull,
                                   in sMenuText  : string,
                                   in sTimer     : string optional ) : boolean;
Parameter | Description
sControlId | The toolbar's unique id.
sMenuText | The label of the menu item.
sTimer | Timer name for measurements.

Return value

  • true if successful
  • false otherwise

Example

transaction TMain
  var
    bCheck : boolean;
    sConnID : string;
  begin
    // Connecting to SAP
    sConnID := SapGuiOpenConnection( " /SAP_CODEPAGE=1100 /FULLMENU 10.5.2.132 0 /3");
    SapGuiSetActiveConnection(sConnID);
    SapGuiSetActiveSession("ses[0]");

    // SAP
    SapGuiSetActiveWindow("wnd[0]", "SAP", SAPGUI_MATCH_ExactNoCase);
    SapGuiWindowAction(SAPGUI_WND_MAXIMIZE);
    SapGuiLogon("ddic", "*******", "000", "");
    bCheck := SapGuiSelectToolbarMenuItemByText("/usr/tab/tbar", "Label");
  end TMain;
Parent topic: Control Functions


SapGuiSelectTopNode Function

Action

Scrolls to a specified node in the SapGui tree control.

Include file

SapGui.bdh

Syntax

SapGuiSelectTopNode( in sControlId : string allownull,
                     in sNodeName  : string,
                     in sTopNode   : string,
                     in sTimer     : string optional ) : boolean;
Parameter | Description
sControlId | The tree's unique id.
sNodeName | The name of the node to be expanded. Silk Performer will try to look up the node by matching the node name. If it cannot find the node by the name or if the name is not unique, specify the node id in the third parameter.
sNode | The node id identifying the node.
sTimer | Timer name used for measurements.

Return value

  • true if successful
  • false otherwise

Example

transaction TMain
  var
    sConnID : string;
  begin
    // Connecting to SAP
    sConnID := SapGuiOpenConnection(" /SAP_CODEPAGE=1100 /FULLMENU 10.5.2.198 0 /3");
    SapGuiSetActiveConnection(sConnID);
    SapGuiSetActiveSession("ses[0]");

    // SAP
    SapGuiSetActiveWindow("wnd[0]", "SAP", SAPGUI_MATCH_Exact);
    SapGuiWindowAction(SAPGUI_WND_MAXIMIZE);

    // Logon to SAP System
    // Before running a test you have to customize the password parameter!
    SapGuiIgnoreError(SAPENGINE_STATUSBAR_CHANGED, SEVERITY_SUCCESS);
    ThinkTime(3.3);
    SapGuiLogon("ddic", "*******", "000", "");

    // Copyright
    SapGuiSetActiveWindow("wnd[1]", "Copyright", SAPGUI_MATCH_Exact);
    SapGuiPressButton("tbar[0]/btn[0]");

    // SAP Easy Access
    ThinkTime(3.9);
    SapGuiSetActiveWindow("wnd[0]", "SAP Easy Access", SAPGUI_MATCH_Exact);

    // NodeName: Office
    // NodePath: 2\1
    SapGuiTreeExpandNode("usr/cntlIMAGE_CONTAINER/shellcont/shell/shellcont[0]/shell", "Office",
    "0000000003", "Expand\\Office");

    // NodeName: Workplace
    // NodePath: 2\1\1
    SapGuiTreeSelectNode("usr/cntlIMAGE_CONTAINER/shellcont/shell/shellcont[0]/shell", "Workplace",
    "0000000004", false, "SelNode\\Workplace");

    // NodeName: Favorites
    // NodePath: 1
    SapGuiSelectTopNode("usr/cntlIMAGE_CONTAINER/shellcont/shell/shellcont[0]/shell", "Favorites",
    "Favo", "TopNode\\Favorites");

    // NodeName: Workplace
    // NodePath: 2\1\1
    SapGuiTreeDblClickNode("usr/cntlIMAGE_CONTAINER/shellcont/shell/shellcont[0]/shell", "Workplace",
    "0000000004", "DblClNode\\Workplace");
    // Grid Control Info:
    // /app/con[0]/ses[0]/wnd[0]/usr/cntlSINWP_CONTAINER/shellcont/shell/shellcont[1]/shell/shellcont[0]/shell/0 columns
    // -------------------------------------

    // Business Workplace von DDIC
    ThinkTime(2.6);
    SapGuiSetActiveWindow("wnd[0]", "Business Workplace von DDIC", SAPGUI_MATCH_Exact);
    SapGuiPressButton("tbar[0]/btn[15]");

    // SAP Easy Access
    SapGuiSetActiveWindow("wnd[0]", "SAP Easy Access", SAPGUI_MATCH_Exact);

    // NodeName: Office
    // NodePath: 2\1
    ThinkTime(2.2);
    SapGuiTreeSelectNode("usr/cntlIMAGE_CONTAINER/shellcont/shell/shellcont[0]/shell", "Office",
    "0000000003", false, "SelNode\\Office");

    // NodeName: Office
    // NodePath: 2\1
  end TMain;
Parent topic: Control Functions


SapGuiSendVKey Function

Action

Sends a keyboard input event to the active window.

Include file

SapGui.bdh

Syntax

SapGuiSendVKey( in nKey : number) : boolean;
Parameter Description
nKey

The ordinal number of the key that should be sent to the active window. These are predefined constants for keys that can be sent to the active window:

  • SAPGUI_VKEY_ENTER
  • SAPGUI_VKEY_HELP
  • SAPGUI_VKEY_F2
  • SAPGUI_VKEY_BACK
  • SAPGUI_VKEY_F4
  • SAPGUI_VKEY_CANCEL
  • SAPGUI_VKEY_PAGEUP
  • SAPGUI_VKEY_PAGEDOWN

Otherwise pass the ordinal number of the keyboard event to be sent.

Return value

  • true if successful
  • false otherwise

Example

transaction TMain
  var
    sConnID : string;
  begin
    // Connecting to SAP
    sConnID := SapGuiOpenConnection(" /SAP_CODEPAGE=1100 /FULLMENU 10.5.2.198 0 /3");
    SapGuiSetActiveConnection(sConnID);
    SapGuiSetActiveSession("ses[0]");

    // SAP
    SapGuiSetActiveWindow("wnd[0]", "SAP", SAPGUI_MATCH_Exact);
    SapGuiWindowAction(SAPGUI_WND_MAXIMIZE);
    ThinkTime(2.8);
    SapGuiSetText("usr/txtRSYST-BNAME", "ddic");

    // Logon to SAP System
    // Before running a test you have to customize the password parameter!
    SapGuiSetText("usr/pwdRSYST-BCODE", "********");
    SapGuiSetFocus("usr/pwdRSYST-BCODE");

    // caretPosition
    SapGuiSetProperty("usr/pwdRSYST-BCODE", "caretPosition", "7");
    SapGuiIgnoreError(SAPENGINE_STATUSBAR_CHANGED, SEVERITY_SUCCESS);
    SapGuiSendVKey(SAPGUI_VKEY_ENTER);

    // Copyright
    SapGuiSetActiveWindow("wnd[1]", "Copyright", SAPGUI_MATCH_Exact);
    SapGuiPressButton("tbar[0]/btn[0]");
  end TMain;
Parent topic: Control Functions


SapGuiSetCheckbox Function

Action

Checks or unchecks the specified SapGui check box.

Include file

SapGui.bdh

Syntax

SapGuiSetCheckbox( in sControlId : string allownull,
                   in bChecked   : boolean,
                   in sTimer     : string optional ) : boolean;
Parameter | Description
sControlId | The uniquely identifying id of a check box control.
bChecked | Specifies, whether to check or uncheck the check box
sTimer | Timer name used for measurements.

Return value

  • true if successful
  • false otherwise

Example

transaction TMain
  var
    sConnID : string;
  begin
    // Connecting to SAP
    sConnID := SapGuiOpenConnection(" /SAP_CODEPAGE=1100 /FULLMENU 10.5.2.198 0 /3");
    SapGuiSetActiveConnection(sConnID);
    SapGuiSetActiveSession("ses[0]");

    // SAP
    SapGuiSetActiveWindow("wnd[0]", "SAP", SAPGUI_MATCH_Exact);
    SapGuiWindowAction(SAPGUI_WND_MAXIMIZE);

    // Logon to SAP System
    // Before running a test you have to customize the password parameter!
    SapGuiIgnoreError(SAPENGINE_STATUSBAR_CHANGED, SEVERITY_SUCCESS);
    ThinkTime(2.2);
    SapGuiLogon("ddic", "*******", "000", "");

    // Copyright
    ThinkTime(2.6);
    SapGuiSetActiveWindow("wnd[1]", "Copyright", SAPGUI_MATCH_Exact);
    SapGuiPressButton("tbar[0]/btn[0]");

    // SAP Easy Access
    ThinkTime(9.2);
    SapGuiSetActiveWindow("wnd[0]", "SAP Easy Access", SAPGUI_MATCH_Exact);

    // Other menu
    SapGuiIgnoreError(SAPENGINE_STATUSBAR_CHANGED, SEVERITY_SUCCESS);
    SapGuiPressButton("tbar[1]/btn[17]", " Other menu");
    // StatusBar(Msg/Id/Type/No): The search help for could not be initialized (CNTL error)/27051464/S/002

    // Wertebereich einschränken
    ThinkTime(8.5);
    SapGuiSetActiveWindow("wnd[1]", "Wertebereich einschränken", SAPGUI_MATCH_Exact);
    SapGuiSetFocus("usr/tabsG_SELONETABSTRIP/tabpTAB002/ssubSUBSCR_PRESEL:SAPLSDH4:0220/chkG_SELPOP_STATE-BUTTON");
    SapGuiSetCheckbox("usr/tabsG_SELONETABSTRIP/tabpTAB002/ssubSUBSCR_PRESEL:SAPLSDH4:0220/chkG_SELPOP_STATE-BUTTON",
    true, "No restriction");
    ThinkTime(2.1);
    SapGuiPressButton("tbar[0]/btn[12]");
  end TMain;
Parent topic: Control Functions


SapGuiSetFileName Function

Action

Sets a file name that will be used to replace the next file selection using the Windows function GetOpenFileName.

Include file

SapGui.bdh

Syntax

SapGuiSetFileName( in  sFileName : string allownull ): boolean;
Parameter | Description
sFileName | The file name to be used.

Return value

  • true if successful
  • false otherwise

Example

transaction TMain
  var
    sId : string;
  begin
    // Connecting to SAP
    sId := SapGuiOpenConnection(" /SAP_CODEPAGE=1100 /FULLMENU lab77 00 /3");

    SapGuiSetActiveConnection(sId);

    SapGuiSetActiveSession("ses[0]");

    // SAP
    SapGuiSetActiveWindow("wnd[0]", "SAP", SAPGUI_MATCH_Exact);

    SapGuiWindowResize(117, 28, false);

    // Logon to SAP System
    // Before running a test you have to customize the password parameter!
    ThinkTime(5.3);
    SapGuiLogon("bcuser", "*******", "000", "");

                …

    SapGuiIgnoreError(SAPENGINE_STATUSBAR_CHANGED, SEVERITY_SUCCESS);
    ThinkTime(2.9);
    SapGuiSetFileName("C:\\Temp\\file.text");
    SapGuiPressButton("tbar[1]/btn[39]", "SapGuiPressButton\\btn[39]");
    // StatusBar(Msg/Id/Type/No): Attachment created/98314464/S/182

                …

    // Log Off
    SapGuiSetActiveWindow("wnd[1]", "Log Off", SAPGUI_MATCH_Exact);

    // Yes
    SapGuiPressButton("usr/btnSPOP-OPTION1", "Yes");
  end TMain;
Parent topic: Control Functions


SapGuiSetFocus Function

Action

Sets the focus to the specified control.

Include file

SapGui.bdh

Syntax

SapGuiSetFocus( in sControlId : string allownull,
                in sTimer     : string optional ) :  boolean;
Parameter | Description
sControlId | The id of the control that should gain the focus.
sTimer | Timer name used for measurements.

Return value

  • true if successful
  • false otherwise

Example

transaction TMain
  var
    sConnID : string;
  begin
    // Connecting to SAP
    sConnID := SapGuiOpenConnection(" /SAP_CODEPAGE=1100 /FULLMENU 10.5.2.198 0 /3");
    SapGuiSetActiveConnection(sConnID);
    SapGuiSetActiveSession("ses[0]");

    // SAP
    SapGuiSetActiveWindow("wnd[0]", "SAP", SAPGUI_MATCH_Exact);
    SapGuiWindowAction(SAPGUI_WND_MAXIMIZE);

    // Logon to SAP System
    // Before running a test you have to customize the password parameter!
    SapGuiIgnoreError(SAPENGINE_STATUSBAR_CHANGED, SEVERITY_SUCCESS);
    ThinkTime(3.8);
    SapGuiLogon("ddic", "*******", "000", "");

    // Copyright
    SapGuiSetActiveWindow("wnd[1]", "Copyright", SAPGUI_MATCH_Exact);
    SapGuiPressButton("tbar[0]/btn[0]");

    // SAP Easy Access
    ThinkTime(4.0);
    SapGuiSetActiveWindow("wnd[0]", "SAP Easy Access", SAPGUI_MATCH_Exact);

    // NodeName: Office
    // NodePath: 2\1
    SapGuiTreeExpandNode("usr/cntlIMAGE_CONTAINER/shellcont/shell/shellcont[0]/shell", "Office",
    "0000000003", "Expand\\Office");

    // NodeName: Workplace
    // NodePath: 2\1\1
    SapGuiTreeSelectNode("usr/cntlIMAGE_CONTAINER/shellcont/shell/shellcont[0]/shell", "Workplace",
    "0000000004", false,"SelNode\\Workplace");

    // NodeName: Favorites
    // NodePath: 1
    SapGuiSelectTopNode("usr/cntlIMAGE_CONTAINER/shellcont/shell/shellcont[0]/shell", "Favorites",
    "Favo", "TopNode\\Favorites");

    // NodeName: Workplace
    // NodePath: 2\1\1
    SapGuiTreeDblClickNode("usr/cntlIMAGE_CONTAINER/shellcont/shell/shellcont[0]/shell", "Workplace",
    "0000000004", "DblClNode\\Workplace");
    // Grid Control Info:
    // /app/con[0]/ses[0]/wnd[0]/usr/cntlSINWP_CONTAINER/shellcont/shell/shellcont[1]/shell/shellcont[0]/shell/0 columns
    // -------------------------------------

    // Business Workplace von DDIC
    ThinkTime(3.2);
    SapGuiSetActiveWindow("wnd[0]", "Business Workplace von DDIC", SAPGUI_MATCH_Exact);

    // Find folder
    ThinkTime(3.6);
    SapGuiPressButton("tbar[1]/btn[17]", " Find folder");

    // Folder Selection
    ThinkTime(50.2);
    SapGuiSetActiveWindow("wnd[1]", "Folder Selection", SAPGUI_MATCH_Exact);
    SapGuiSetText("usr/ctxtSOS06-S_FOLNAM", "d");
    SapGuiSetFocus("usr/txtSOS06-S_FOLDES");

    // caretPosition
    SapGuiSetProperty("usr/txtSOS06-S_FOLDES", "caretPosition", "0");
    SapGuiPressButton("tbar[0]/btn[12]");
  end TMain;
Parent topic: Control Functions


SapGuiSetOKCode Function

Action

Sets the text for a SapGui OK text field. These text fields are normally used to execute a SAP transaction.

Include file

SapGui.bdh

Syntax

SapGuiSetOKCode( in sControlId : string allownull,
                 in sOKCode    : string,
                 in sTimer     : string optional ) : boolean;
Parameter | Description
sControlId | The id of the Ok textfield.
sOKCode | Text to be set for the ok textfield. Normally, this will be the name of a SAP transaction.
sTimer | Timer name used for measurements.

Return value

  • true if successful
  • false otherwise

Example

transaction TMain
  var
    sConnId : string;
  begin
    // Connecting to SAP
    sConnID := SapGuiOpenConnection(" /SAP_CODEPAGE=1100 /FULLMENU 10.5.2.198 0 /3");
    SapGuiSetActiveConnection(sConnID);
    SapGuiSetActiveSession("ses[0]");

    // SAP
    SapGuiSetActiveWindow("wnd[0]", "SAP", SAPGUI_MATCH_Exact);
    SapGuiWindowAction(SAPGUI_WND_MAXIMIZE);

    // Logon to SAP System
    // Before running a test you have to customize the password parameter!
    SapGuiIgnoreError(SAPENGINE_STATUSBAR_CHANGED, SEVERITY_SUCCESS);
    ThinkTime(3.0);
    SapGuiLogon("ddic", "*******", "000", "");

    // Copyright
    SapGuiSetActiveWindow("wnd[1]", "Copyright", SAPGUI_MATCH_Exact);
    SapGuiPressButton("tbar[0]/btn[0]");

    // SAP Easy Access
    ThinkTime(7.1);
    SapGuiSetActiveWindow("wnd[0]", "SAP Easy Access", SAPGUI_MATCH_Exact);
    SapGuiSetOKCode("tbar[0]/okcd", "rz11");
    SapGuiSendVKey(SAPGUI_VKEY_ENTER);

    // Maintain Profile Parameters
    SapGuiSetActiveWindow("wnd[0]", "Maintain Profile Parameters", SAPGUI_MATCH_Exact);
  end TMain;
Parent topic: Control Functions


SapGuiSetText Function

Action

Enters text into a SapGui text field.

Include file

SapGui.bdh

Syntax

SapGuiSetText( in sControlId : string allownull,
               in sText      : string,
               in sTimer     : string optional ) : boolean;
Parameter | Description
sControlId | The uniquely identifying id of a text control.
sText | Text to be entered into the textfield.
sTimer | Timer name used for measurements.

Return value

  • true if successful
  • false otherwise

Example

transaction TMain
  var
    sConnID : string;
  begin
    // Connecting to SAP
    sConnID := SapGuiOpenConnection(" /SAP_CODEPAGE=1100 /FULLMENU 10.5.2.198 0 /3");
    SapGuiSetActiveConnection(sConnID);
    SapGuiSetActiveSession("ses[0]");

    // SAP
    SapGuiSetActiveWindow("wnd[0]", "SAP", SAPGUI_MATCH_Exact);
    SapGuiWindowAction(SAPGUI_WND_MAXIMIZE);
    ThinkTime(2.8);
    SapGuiSetText("usr/txtRSYST-BNAME", "ddic");

    // Logon to SAP System
    // Before running a test you have to customize the password parameter!
    SapGuiSetText("usr/pwdRSYST-BCODE", "********");
    SapGuiSetFocus("usr/pwdRSYST-BCODE");

    // caretPosition
    SapGuiSetProperty("usr/pwdRSYST-BCODE", "caretPosition", "7");
    SapGuiIgnoreError(SAPENGINE_STATUSBAR_CHANGED, SEVERITY_SUCCESS);
    SapGuiSendVKey(SAPGUI_VKEY_ENTER);

    //Copyright
    SapGuiSetActiveWindow("wnd[1]", "Copyright", SAPGUI_MATCH_Exact);
    SapGuiPressButton("tbar[0]/btn[0]");
  end TMain;
Parent topic: Control Functions


SapGuiTableGetRadioValue Function

Action

Checks whether a table cell's radio button is selected.

Include file

SapGui.bdh

Syntax

SapGuiTableGetRadioValue( in sControlId : string;
                          in nRow       : number;
                          in nCol       : number ) : boolean;
Parameter | Description
sControlId | The unique id of the control.
nRow | The cell's row
nCol | The cell's column.

Return value

  • true if the radio button is selected.
  • false otherwise

Example

transaction TMain
  var
    sText : string;
    sConnID : string;
  begin
    // Connecting to SAP
    sConnID := SapGuiOpenConnection( " /SAP_CODEPAGE=1100 /FULLMENU 10.5.2.132 0 /3");
    SapGuiSetActiveConnection(sConnID);
    SapGuiSetActiveSession("ses[0]");

    // SAP
    SapGuiSetActiveWindow("wnd[0]", "SAP", SAPGUI_MATCH_ExactNoCase);
    SapGuiWindowAction(SAPGUI_WND_MAXIMIZE);
    SapGuiLogon("ddic", "*******", "000", "");
    sText := SapGuiTableGetRadioValue("/usr/tab/mytable", 0, 0 );
  end TMain;
Parent topic: Control Functions


SapGuiTableGetRows Function

Action

This function returns a collection of table rows for the specified table. Each element of the collection is of type GuiTableRow.

Include file

SapGui.bdh

Syntax

SapGuiTableGetRows( in  sControlId : string,
                    out nIterator  : number ) : boolean;
Parameter | Description
sControlId | The control’s unique id.
nIterator | This parameter will be assigned the collection iterator

Return value

  • true if successful
  • false otherwise

Example

transaction TMain
  var
    sConnID   : string;
    i         : number;
    nIterator : number;
    nType     : number;
    nObject   : number;
    bRet      : boolean;
    sStr1, sStr2 : string;
  begin
    // Connecting to SAP
    sConnID := SapGuiOpenConnection(" /SAP_CODEPAGE=1100 /FULLMENU 10.5.2.198 0 /3");
    SapGuiSetActiveConnection(sConnID);
    SapGuiSetActiveSession("ses[0]");

    // SAP
    SapGuiSetActiveWindow("wnd[0]", "SAP", SAPGUI_MATCH_Exact);
    SapGuiWindowAction(SAPGUI_WND_MAXIMIZE);

    // Logon to SAP System
    SapGuiIgnoreError(SAPENGINE_STATUSBAR_CHANGED, SEVERITY_SUCCESS);
    ThinkTime(2.8);
    SapGuiLogon("ddic", "minisap", "000", "");

    // Copyright
    ThinkTime(2.1);
    SapGuiSetActiveWindow("wnd[1]", "Copyright", SAPGUI_MATCH_Exact);
    SapGuiPressButton("tbar[0]/btn[0]");

    // SAP Easy Access
    ThinkTime(9.9);
    SapGuiSetActiveWindow("wnd[0]", "SAP Easy Access", SAPGUI_MATCH_Exact);
    SapGuiTableGetRows("table[0]", nIterator);
    while
      (SapGuiIteratorHasMore(nIterator)) do
      SapGuiIteratorFetchNext(nIterator);
      SapGuiIteratorGetObject(nIterator, nObject);
      SapGuiObjectGetType(nObject, sStr1, sStr2);
    if sStr1 = "GuiTableRow"then
      Print("GuiTableRow");
      end;
      SapGuiObjectFree(nObject);
    end;
    SapGuiIteratorRelease(nIterator);
end TMain;
Parent topic: Control Functions


SapGuiTableGetRowSelected Function

Action

Returns the index of the current cell's row.

Include file

SapGui.bdh

Syntax

SapGuiTableGetRowSelected( in sControlId : string ) : number;
Parameter | Description
sControlId | The unique id of the control.

Return value

  • index of the selected row on success
  • -1 otherwise

Example

transaction TMain
  var
    nRowIx  : number;
    sConnID : string;
  begin
    // Connecting to SAP
    sConnID := SapGuiOpenConnection( " /SAP_CODEPAGE=1100 /FULLMENU 10.5.2.132 0 /3");
    SapGuiSetActiveConnection(sConnID);
    SapGuiSetActiveSession("ses[0]");

    // SAP
    SapGuiSetActiveWindow("wnd[0]", "SAP", SAPGUI_MATCH_ExactNoCase);
    SapGuiWindowAction(SAPGUI_WND_MAXIMIZE);
    SapGuiLogon("ddic", "*******", "000", "");
    nRowIx := SapGuiTableGetRowSelected("/usr/tab/grid23");
  end TMain
Parent topic: Control Functions


SapGuiTableGetRowCount Function

Action

Returns the number of rows for the specified table.

Include file

SapGui.bdh

Syntax

SapGuiTableGetRowCount( in sControlId : string;
                        in nRows      : number ) : boolean;
Parameter | Description
sControlId | The unique id of the control.
nRows | The parameter will be assigned the number of rows on success.

Return value

  • true if the radio button is selected.
  • false otherwise

Example

transaction TMain
  var
    nRows : number;
  begin
    // Connecting to SAP
    sConnID := SapGuiOpenConnection( " /SAP_CODEPAGE=1100 /FULLMENU 10.5.2.132 0 /3");
    SapGuiSetActiveConnection("/app/con[0]");
    SapGuiSetActiveSession("ses[0]");

    // SAP
    SapGuiSetActiveWindow("wnd[0]", "SAP", SAPGUI_MATCH_Exact);
    SapGuiWindowResize(117, 28, false);
    SapGuiLogon("bcuser", "*******", "000", "");
    SapGuiTableGetRowCount("tables/SapTable", nRows);
  end TMain;
Parent topic: Control Functions


SapGuiTableGetText Function

Action

This function returns the text of a specified table's cell.

Include file

SapGui.bdh

Syntax

SapGuiTableGetText( in sControlId : string;
                    in nRow       : number;
                    in nCol       : number ) : string;
Parameter | Description
sControlId | The unique id of the control.
nRow | The cell's row.
nCol | The cell's column.

Return value

  • Text on success.
  • Empty string otherwise.

Example

transaction TMain
  var
    sText : string;
    sConnID : string;
  begin
    // Connecting to SAP
    sConnID := SapGuiOpenConnection( " /SAP_CODEPAGE=1100 /FULLMENU 10.5.2.132 0 /3");
    SapGuiSetActiveConnection(sConnID);
    SapGuiSetActiveSession("ses[0]");

    // SAP
    SapGuiSetActiveWindow("wnd[0]", "SAP", SAPGUI_MATCH_ExactNoCase);
    SapGuiWindowAction(SAPGUI_WND_MAXIMIZE);
    SapGuiLogon("ddic", "*******", "000", "");
    sText := SapGuiTableGetText("/usr/tab/table2", 0, 0 );
  end TMain;
Parent topic: Control Functions


SapGuiTableGetColumns Function

Action

This function returns the collection of columns for the specified table. Each entry in the collection is of type GuiTableColumn.

Include file

SapGui.bdh

Syntax

SapGuiTableGetColumns( in  sControlId : string,
                       out nIterator  : number ) : boolean;
Parameter | Description
sControlId | The control’s unique id.
nIterator | This parameter will be assigned the collection iterator.

Return value

  • true if successful
  • false otherwise

Example

transaction TMain
  var
    sConnID   : string;
    i         : number;
   nIterator : number;
    nType     : number;
    nObject   : number;
    bRet      : boolean;
    sStr1, sStr2 : string;
  begin
    // Connecting to SAP
    sConnID := SapGuiOpenConnection(" /SAP_CODEPAGE=1100 /FULLMENU 10.5.2.198 0 /3");
    SapGuiSetActiveConnection(sConnID);
    SapGuiSetActiveSession("ses[0]");

    // SAP
    SapGuiSetActiveWindow("wnd[0]", "SAP", SAPGUI_MATCH_Exact);
    SapGuiWindowAction(SAPGUI_WND_MAXIMIZE);

    // Logon to SAP System
    SapGuiIgnoreError(SAPENGINE_STATUSBAR_CHANGED, SEVERITY_SUCCESS);
    ThinkTime(2.8);
    SapGuiLogon("ddic", "minisap", "000", "");

    // Copyright
    ThinkTime(2.1);
    SapGuiSetActiveWindow("wnd[1]", "Copyright", SAPGUI_MATCH_Exact);
    SapGuiPressButton("tbar[0]/btn[0]");

    // SAP Easy Access
    ThinkTime(9.9);
    SapGuiSetActiveWindow("wnd[0]", "SAP Easy Access", SAPGUI_MATCH_Exact);
    SapGuiTableGetColumns("table[0]", nIterator);
    while
      (SapGuiIteratorHasMore(nIterator)) do
      SapGuiIteratorFetchNext(nIterator);
      SapGuiIteratorGetObject(nIterator, nObject);
      SapGuiObjectGetType(nObject, sStr1, sStr2);
    if sStr1 = "GuiTableColumn"then
      Print("GuiTableColumn");
    end;
      SapGuiObjectFree(nObject);
    end;
      SapGuiIteratorRelease(nIterator);
  end TMain;
Parent topic: Control Functions


SapGuiTableGetColumnCount Function

Action

Returns the number of columns for the specified table.

Include file

SapGui.bdh

Syntax

SapGuiTableGetColumnCount( in sControlId : string;
                           in nCols      : number ) : boolean;
Parameter | Description
sControlId | The unique id of the control.
nCols | The parameter will be assigned the number of columns on success.

Return value

  • true if the radio button is selected.
  • false otherwise

Example

transaction TMain
  var
    nCols : number;
  begin
    // Connecting to SAP
    sConnID := SapGuiOpenConnection( " /SAP_CODEPAGE=1100 /FULLMENU 10.5.2.132 0 /3");
    SapGuiSetActiveConnection("/app/con[0]");
    SapGuiSetActiveSession("ses[0]");

    // SAP
    SapGuiSetActiveWindow("wnd[0]", "SAP", SAPGUI_MATCH_Exact);
    SapGuiWindowResize(117, 28, false);
    SapGuiLogon("bcuser", "*******", "000", "");
    SapGuiTableGetColumnCount("tables/SapTable", nCols);
  end TMain;
Parent topic: Control Functions


SapGuiTableIsCheckboxChecked Function

Action

This function returns whether a check box in a table cell is checked.

Include file

SapGui.bdh

Syntax

SapGuiTableIsCheckboxChecked( in sControlId : string;
                              in nRow       : number;
                              in nCol       : number ) : boolean;
Parameter | Description
sControlId | The unique id of the control.
nRow | The cell's row.
nCol | The cell's column.

Return value

  • true if the check box is checked
  • false otherwise

Example

transaction TMain
  var
    bCheck : boolean;
    sConnID : string;
  begin
    // Connecting to SAP
    sConnID := SapGuiOpenConnection( " /SAP_CODEPAGE=1100 /FULLMENU 10.5.2.132 0 /3");
    SapGuiSetActiveConnection(sConnID);
    SapGuiSetActiveSession("ses[0]");

    // SAP
    SapGuiSetActiveWindow("wnd[0]", "SAP", SAPGUI_MATCH_ExactNoCase);
    SapGuiWindowAction(SAPGUI_WND_MAXIMIZE);
    SapGuiLogon("ddic", "*******", "000", "");
    bCheck := SapGuiTableIsCheckboxChecked("/usr/tab/table23", 0, 0 );
  end TMain;
Parent topic: Control Functions


SapGuiTablePressButton Function

Action

Presses a cell's button.

Include file

SapGui.bdh

Syntax

SapGuiTablePressButton( in sControl : string allownull,
                        in nRow     : number,
                        in nCol     : number,
                        in sTimer   : string optional ) : boolean;
Parameter | Description
sControlId | The table's unique id.
nRow | The row where to set the value
nCol | The column where to set the value
sTimer | Timer name for measurements.

Return value

  • true if successful
  • false otherwise

Example

transaction TMain
  var
    bCheck : boolean;
    sConnID : string;
  begin
    // Connecting to SAP
    sConnID := SapGuiOpenConnection( " /SAP_CODEPAGE=1100 /FULLMENU 10.5.2.132 0 /3");
    SapGuiSetActiveConnection(sConnID);
    SapGuiSetActiveSession("ses[0]");

    // SAP
    SapGuiSetActiveWindow("wnd[0]", "SAP", SAPGUI_MATCH_ExactNoCase);
    SapGuiWindowAction(SAPGUI_WND_MAXIMIZE);
    SapGuiLogon("ddic", "*******", "000", "");
    bCheck := SapGuiTablePressButton("/usr/tab/tablecontrol", 0, 0 );
  end TMain;
Parent topic: Control Functions


SapGuiTableSelectComboboxEntry Function

Action

Selects an entry from a cell's combobox.

Include file

SapGui.bdh

Syntax

SapGuiTableSelectComboBoxEntry( in sControl : string allownull,
                                in nRow     : number,
                                in nCol     : number,
                                in sValue   : string,
                                in sTimer   : string optional ) : boolean;
Parameter | Description
sControlId | The context menu's unique id.
nRow | The cell's row.
nCol | The cell's column.
sValue | The value to be selected for the combobox.
sTimer | Timer name for measurements.

Return value

  • true if successful
  • false otherwise

Example

transaction TMain
  var
    sConnID : string;
  begin
    // Connecting to SAP
    sConnID := SapGuiOpenConnection( " /SAP_CODEPAGE=1100 /FULLMENU 10.5.2.132 0 /3");
    SapGuiSetActiveConnection(sConnID);
    SapGuiSetActiveSession("ses[0]");

    // SAP
    SapGuiSetActiveWindow("wnd[0]", "SAP", SAPGUI_MATCH_ExactNoCase);
    SapGuiWindowAction(SAPGUI_WND_MAXIMIZE);
    SapGuiLogon("ddic", "*******", "000", "");
    SapGuiTableSelectComboboxEntry("/usr/tab/table", 0, 0, "SelectedValue" );
  end TMain;
Parent topic: Control Functions


SapGuiTableSelectRadioButton Function

Action

Select a cell's radio button.

Include file

SapGui.bdh

Syntax

SapGuiTableSelectRadioButton( in sControl : string allownull,
                              in nRow     : number,
                              in nCol     : number,
                              in sTimer   : string optional ) : boolean;
Parameter | Description
sControlId | The context menu's unique id.
nRow | The cell's row.
nCol | The cell's column.
sTimer | Timer name for measurements.

Return value

  • true if successful
  • false otherwise

Example

transaction TMain
  var
    bCheck : boolean;
    sConnID : string;
  begin
    // Connecting to SAP
    sConnID := SapGuiOpenConnection( " /SAP_CODEPAGE=1100 /FULLMENU 10.5.2.132 0 /3");
    SapGuiSetActiveConnection(sConnID);
    SapGuiSetActiveSession("ses[0]");

    // SAP
    SapGuiSetActiveWindow("wnd[0]", "SAP", SAPGUI_MATCH_ExactNoCase);
    SapGuiWindowAction(SAPGUI_WND_MAXIMIZE);
    SapGuiLogon("ddic", "*******", "000", "");
    bCheck := SapGuiTableSelectRadioButton("/usr/tab/roundtable", 0, 0);
  end TMain;
Parent topic: Control Functions


SapGuiTableSelectRow Function

Action

Selects one row of a table.

Include file

SapGui.bdh

Syntax

SapGuiTableSelectRow( in sControl : string allownull,
                      in nRow     : number,
                      in bSelect  : boolean,
                      in sTimer   : string optional ) : boolean;
Parameter | Description
sControlId | The table's unique id.
nRow | The row where to set the value
bSelect | Set this parameter to "true" to select the row. Set this parameter to "false" to unselect the row.
sTimer | Timer name for measurements.

Return value

  • true if successful
  • false otherwise

Example

transaction TMain
  var
    bCheck : boolean;
    sConnID : string;
  begin
    // Connecting to SAP
    sConnID := SapGuiOpenConnection( " /SAP_CODEPAGE=1100 /FULLMENU 10.5.2.132 0 /3");
    SapGuiSetActiveConnection(sConnID);
    SapGuiSetActiveSession("ses[0]");

    // SAP
    SapGuiSetActiveWindow("wnd[0]", "SAP", SAPGUI_MATCH_ExactNoCase);
    SapGuiWindowAction(SAPGUI_WND_MAXIMIZE);
    SapGuiLogon("ddic", "*******", "000", "");
    bCheck := SapGuiTableSelectRow("/usr/tab/table", 0, true);
  end TMain;
Parent topic: Control Functions


SapGuiTableSetCheckbox Function

Action

Checks a cell's check box.

Include file

SapGui.bdh

Syntax

SapGuiTableSetCheckBox( in sControl : string allownull,
                        in nRow     : number,
                        in nCol     : number,
                        in bCheck   : boolean,
                        in sTimer   : string optional ): boolean;
Parameter | Description
sControlId | The table's unique id.
nRow | The row where to set the value
nCol | The column where to set the value
bCheck | Set this parameter to "true" in order to check the checkbox.
sTimer | Timer name for measurements.

Return value

  • true if successful
  • false otherwise

Example:

transaction TMain
  var
    bCheck : boolean;
    sConnID : string;
  begin
    // Connecting to SAP
    sConnID := SapGuiOpenConnection(  " /SAP_CODEPAGE=1100 /FULLMENU 10.5.2.132 0 /3");
    SapGuiSetActiveConnection(sConnID);
    SapGuiSetActiveSession("ses[0]");

    // SAP
    SapGuiSetActiveWindow("wnd[0]", "SAP", SAPGUI_MATCH_ExactNoCase);
    SapGuiWindowAction(SAPGUI_WND_MAXIMIZE);
    SapGuiLogon("ddic", "*******", "000", "");
    bCheck := SapGuiTableSetCheckbox("/usr/tab/table", 0, 0, true );
  end TMain;
Parent topic: Control Functions


SapGuiTableSetFocusCell Function

Action

Sets the focus to a cell in a SapGui table control.

Include file

SapGui.bdh

Syntax

SapGuiTableSetFocusCell( in sControl : string allownull,
                         in nRow     : number,
                         in nCol     : number,
                         in sTimer   : string optional ) : boolean;
Parameter | Description
sControlId | The table's unique id.
nRow | The row where to set the value
nCol | The column where to set the value
sTimer | Timer name for measurements.

Return value

  • true if successful
  • false otherwise

Example

transaction TMain
  var
    sConnID : string;
  begin
    // Connecting to SAP
    sConnID := SapGuiOpenConnection(" /SAP_CODEPAGE=1100 /FULLMENU 10.5.2.198 0 /3");
    SapGuiSetActiveConnection(sConnID);
    SapGuiSetActiveSession("ses[0]");

    // SAP
    SapGuiSetActiveWindow("wnd[0]", "SAP", SAPGUI_MATCH_Exact);
    SapGuiWindowAction(SAPGUI_WND_MAXIMIZE);

    // Logon to SAP System
    // Before running a test you have to customize the password parameter!
    SapGuiIgnoreError(SAPENGINE_STATUSBAR_CHANGED, SEVERITY_SUCCESS);
    ThinkTime(3.4);
    SapGuiLogon("ddic", "*******", "000", "");
    SapGuiPressButton("usr/btn%_AUTOTEXT005", " Simulate inbound call");

    // Daten des Anrufs eingeben
    ThinkTime(22.6);
    SapGuiSetActiveWindow("wnd[1]", "Daten des Anrufs eingeben", SAPGUI_MATCH_Exact);
    SapGuiTableSetText("usr/tblSAPLPHOAD102_ADDITIONAL", 0, 3, "asdf");
    SapGuiTableSetFocusCell("usr/tblSAPLPHOAD102_ADDITIONAL", 1, 2, "D102_ADD_DATA-KEYNAME");

    // caretPosition
  end TMain;
Parent topic: Control Functions


SapGuiTableSetText Function

Action

Sets text at the specified position in a SapGui table control.

Include file

SapGui.bdh

Syntax

SapGuiTableSetText( in sControl : string allownull,
                    in nRow     : number,
                    in nCol     : number,
                    in sValue   : string,
                    in sTimer   : string optional ) : boolean;
Parameter | Description
sControlId | The table's unique id.
nRow | The row where to set the value
nCol | The column where to set the value
sValue | The value to be set at the specified position.
sTimer | Timer name for measurements.

Return value

  • true if successful
  • false otherwise

Example

transaction TMain
  var
    sConnID : string;
  begin
    // Connecting to SAP
    sConnID := SapGuiOpenConnection(" /SAP_CODEPAGE=1100 /FULLMENU 10.5.2.198 0 /3");
    SapGuiSetActiveConnection(sConnID);
    SapGuiSetActiveSession("ses[0]");

    // SAP
    SapGuiSetActiveWindow("wnd[0]", "SAP", SAPGUI_MATCH_Exact);
    SapGuiWindowAction(SAPGUI_WND_MAXIMIZE);

    // Logon to SAP System
    // Before running a test you have to customize the password parameter!
    SapGuiIgnoreError(SAPENGINE_STATUSBAR_CHANGED, SEVERITY_SUCCESS);
    ThinkTime(3.4);
    SapGuiLogon("ddic", "*******", "000", "");
    SapGuiPressButton("usr/btn%_AUTOTEXT005", " Simulate inbound call");

    // Daten des Anrufs eingeben
    ThinkTime(22.6);
    SapGuiSetActiveWindow("wnd[1]", "Daten des Anrufs eingeben", SAPGUI_MATCH_Exact);
    SapGuiTableSetText("usr/tblSAPLPHOAD102_ADDITIONAL", 0, 0, "asdf");
  end TMain;
Parent topic: Control Functions


SapGuiTreeChangeCheckbox Function

Action

Checks or unchecks a tree item's check box.

Include file

SapGui.bdh

Syntax

SapGuiTreeChangeCheckBox( in sControlId : string allownull,
                          in sNodeName  : string,
                          in sNode      : string,
                          in sItemName  : string,
                          in bChecked   : boolean,
                          in sTimer     : string optional ) : boolean;
Parameter | Description
sControlId | The tree's unique id.
sNodeName | The name of the node for which the check box will be changed. Silk Performer will try to look up the node by matching the node name. If it cannot find the node by the name or if the name is not unique, specify the node id in the third parameter.
sNode | The node id identifying the node.
sItemName | The item's name.
bChecked | Set this parameter to true in order to check the check box. False otherwise.
sTimer | Timer name used for measurements.

Return value

  • true if successful
  • false otherwise

Example

transaction TMain
  var
    sConnID : string;
  begin
    // Connecting to SAP
    sConnID := SapGuiOpenConnection( " /SAP_CODEPAGE=1100 /FULLMENU 10.5.2.132 0 /3");
    SapGuiSetActiveConnection(sConnID);
    SapGuiSetActiveSession("ses[0]");

    // SAP
    SapGuiSetActiveWindow("wnd[0]", "SAP", SAPGUI_MATCH_ExactNoCase);
    SapGuiWindowAction(SAPGUI_WND_MAXIMIZE);
    SapGuiLogon("ddic", "*******", "000", "");
    SapGuiTreeChangeCheckbox("/usr/tab/tree", "NODENAME", "NODEID", "ITEM", false );
  end TMain;
Parent topic: Control Functions


SapGuiTreeClickLink Function

Action

Clicks a tree's hyperlink.

Include file

SapGui.bdh

Syntax

SapGuiTreeClickLink( in sControlId : string allownull,
                     in sNodeName  : string,
                     in sNode      : string,
                     in sItemName  : string,
                     in sTimer     : string optional ) : boolean;
Parameter | Description
sControlId | The tree's unique id.
sNodeName | The name of the node for which the hyperlink should be clicked. Silk Performer will try to look up the node by matching the node name. If it cannot find the node by the name or if the name is not unique, specify the node id in the third parameter.
sNode | The node id identifying the node.
sItemName | The name of the tree item.
sTimer | Timer name used for measurements.

Return value

  • true if successful
  • false otherwise

Example

transaction TMain
 var
    bCheck : boolean;
    sConnID : string;
  begin
    // Connecting to SAP
    sConnID := SapGuiOpenConnection( " /SAP_CODEPAGE=1100 /FULLMENU 10.5.2.132 0 /3");
    SapGuiSetActiveConnection(sConnID);
    SapGuiSetActiveSession("ses[0]");

    // SAP
    SapGuiSetActiveWindow("wnd[0]", "SAP", SAPGUI_MATCH_ExactNoCase);
    SapGuiWindowAction(SAPGUI_WND_MAXIMIZE);
    SapGuiLogon("ddic", "*******", "000", "");
    bCheck := SapGuiTreeClickLink("/usr/tab/tree", "NODENAME", "NODEID", "ITEM");
  end TMain;
Parent topic: Control Functions


SapGuiTreeCollapseNode Function

Action

Collapses a specified node of a specified tree control.

Include file

SapGui.bdh

Syntax

SapGuiTreeCollapseNode( in sControlId : string allownull,
                        in sNodeName  : string,
                        in sNode      : string,
                        in sTimer     : string optional ) : boolean;
Parameter | Description
sControlId | The tree's unique id.
sNodeName | The name of the node to be collapsed. Silk Performer will try to look up the node by matching the node name. If it cannot find the node by the name or if the name is not unique, specify the node id in the third parameter.
sNode | The node id identifying the node.
sTimer | Timer name used for measurements.

Return value

  • true if successful
  • false otherwise

Example

transaction TMain
  var
    sConnID : string;
  begin
    // Connecting to SAP
    sConnID := SapGuiOpenConnection(" /SAP_CODEPAGE=1100 /FULLMENU 10.5.2.198 0 /3");
    SapGuiSetActiveConnection(sConnID);
    SapGuiSetActiveSession("ses[0]");

    // SAP
    SapGuiSetActiveWindow("wnd[0]", "SAP", SAPGUI_MATCH_Exact);
    SapGuiWindowAction(SAPGUI_WND_MAXIMIZE);

    // Logon to SAP System
    // Before running a test you have to customize the password parameter!
    SapGuiIgnoreError(SAPENGINE_STATUSBAR_CHANGED, SEVERITY_SUCCESS);
    ThinkTime(3.3);
    SapGuiLogon("ddic", "*******", "000", "");

    // Copyright
    SapGuiSetActiveWindow("wnd[1]", "Copyright", SAPGUI_MATCH_Exact);
    SapGuiPressButton("tbar[0]/btn[0]");

    // SAP Easy Access
    ThinkTime(3.9);
    SapGuiSetActiveWindow("wnd[0]", "SAP Easy Access", SAPGUI_MATCH_Exact);

    // NodeName: Office
    // NodePath: 2\1
    SapGuiTreeExpandNode("usr/cntlIMAGE_CONTAINER/shellcont/shell/shellcont[0]/shell", "Office", "0000000003", "Expand\\Office");

    // NodeName: Workplace
    // NodePath: 2\1\1
    SapGuiTreeSelectNode("usr/cntlIMAGE_CONTAINER/shellcont/shell/shellcont[0]/shell",
    "Workplace", "0000000004", false, "SelNode\\Workplace");

    // NodeName: Favorites
    // NodePath: 1
    SapGuiSelectTopNode("usr/cntlIMAGE_CONTAINER/shellcont/shell/shellcont[0]/shell",
    "Favorites", "Favo", "TopNode\\Favorites");

    // NodeName: Workplace
    // NodePath: 2\1\1
    SapGuiTreeDblClickNode("usr/cntlIMAGE_CONTAINER/shellcont/shell/shellcont[0]/shell", "Workplace", "0000000004", "DblClNode\\Workplace");
    // Grid Control Info:
    // /app/con[0]/ses[0]/wnd[0]/usr/cntlSINWP_CONTAINER/shellcont/shell/shellcont[1]/shell/shellcont[0]/shell/0 columns
    // -------------------------------------

    // Business Workplace von DDIC
    ThinkTime(2.6);
    SapGuiSetActiveWindow("wnd[0]", "Business Workplace von DDIC", SAPGUI_MATCH_Exact);
    SapGuiPressButton("tbar[0]/btn[15]");

    // SAP Easy Access
    SapGuiSetActiveWindow("wnd[0]", "SAP Easy Access", SAPGUI_MATCH_Exact);

    // NodeName: Office
    // NodePath: 2\1
    ThinkTime(2.2);
    SapGuiTreeSelectNode("usr/cntlIMAGE_CONTAINER/shellcont/shell/shellcont[0]/shell",
    "Office", "0000000003", false, "SelNode\\Office");

    // NodeName: Office
    // NodePath: 2\1
    SapGuiTreeCollapseNode("usr/cntlIMAGE_CONTAINER/shellcont/shell/shellcont[0]/shell",
    "Office", "0000000003", "Collapse\\Office");

    // NodeName: Cross-Application Components
    // NodePath: 2\2
    SapGuiTreeExpandNode("usr/cntlIMAGE_CONTAINER/shellcont/shell/shellcont[0]/shell",
    "Cross-Application Components", "0000000020", "Expand\\Cross-Application Components");

    // NodeName: ALE Distribution Units
    // NodePath: 2\2\1
    SapGuiTreeExpandNode("usr/cntlIMAGE_CONTAINER/shellcont/shell/shellcont[0]/shell",
    "ALE Distribution Units", "0000000021", "Expand\\ALE Distribution Units");

    // NodeName: Favorites
    // NodePath: 1
    SapGuiSelectTopNode("usr/cntlIMAGE_CONTAINER/shellcont/shell/shellcont[0]/shell", "Favorites", "Favo", "TopNode\\Favorites");

    // NodeName: UPS Cockpit
    // NodePath: 2\2\1\1
    ThinkTime(3.1);
    SapGuiTreeSelectNode("usr/cntlIMAGE_CONTAINER/shellcont/shell/shellcont[0]/shell",
    "UPS Cockpit", "0000000075", false, "SelNode\\UPS Cockpit");

    // NodeName: UPS Cockpit
    // NodePath: 2\2\1\1
    SapGuiTreeDblClickNode("usr/cntlIMAGE_CONTAINER/shellcont/shell/shellcont[0]/shell",
    "UPS Cockpit", "0000000075", "DblClNode\\UPS Cockpit");

    // ALE - Distribution - Cockpit
    ThinkTime(3.6);
    SapGuiSetActiveWindow("wnd[0]", "ALE - Distribution - Cockpit", SAPGUI_MATCH_Exact);
  end TMain;
Parent topic: Control Functions


SapGuiTreeDblClickItem Function

Action

Performs a double click on the specified tree item.

Include file

SapGui.bdh

Syntax

SapGuiTreeDblClickItem( in sControlId : string allownull,
                        in sNodeName  : string,
                        in sNode      : string,
                        in sItemName  : string,
                        in sTimer     : string optional ) : boolean;
Parameter | Description
sControlId | The tree's unique id.
sNodeName | The name of the node for which the double click should be performed. Silk Performer will try to look up the node by matching the node name. If it cannot find the node by the name or if the name is not unique, specify the node id in the third parameter.
sNode | The node id identifying the node.
sItemName | The name of the tree item.
sTimer | Timer name used for measurements.

Return value

  • true if successful
  • false otherwise

Example

transaction TMain
  var
    sText : string;
  begin
    // Connecting to SAP
    sConnID := SapGuiOpenConnection( " /SAP_CODEPAGE=1100 /FULLMENU 10.5.2.132 0 /3");
    SapGuiSetActiveConnection(sConnID);
    SapGuiSetActiveSession("ses[0]");

    // SAP
    SapGuiSetActiveWindow("wnd[0]", "SAP", SAPGUI_MATCH_ExactNoCase);
    SapGuiWindowAction(SAPGUI_WND_MAXIMIZE);
    SapGuiLogon("ddic", "*******", "000", "");
    SapGuiTreeDblClickItem("/usr/tab/gtree", "NODENAME", "NODEID", "ITEM");
  end TMain;
Parent topic: Control Functions


SapGuiTreeDblClickNode Function

Action

Performs a double-click on the specified node inside a SapGui tree control.

Include file

SapGui.bdh

Syntax

SapGuiTreeDblClickNode( in sControlId : string allownull,
                        in sNodeName  : string,
                        in sNode      : string,
                        in sTimer     : string optional ) : boolean;
Parameter | Description
sControlId | The tree's unique id.
sNodeName | The name of the node for which the double click should be performed. Silk Performer will try to look up the node by matching the node name. If it cannot find the node by the name or if the name is not unique, specify the node id in the third parameter.
sNode | The node id identifying the node.
sTimer | Timer name used for measurements.

Return value

  • true if successful
  • false otherwise

Example

transaction TMain
   var
    sConnID : string;
  begin
    // Connecting to SAP
    sConnID := SapGuiOpenConnection(" /SAP_CODEPAGE=1100 /FULLMENU 10.5.2.198 0 /3");
    SapGuiSetActiveConnection(sConnID);
    SapGuiSetActiveSession("ses[0]");

    // SAP
    SapGuiSetActiveWindow("wnd[0]", "SAP", SAPGUI_MATCH_Exact);
    SapGuiWindowAction(SAPGUI_WND_MAXIMIZE);

    // Logon to SAP System
    // Before running a test you have to customize the password parameter!
    SapGuiIgnoreError(SAPENGINE_STATUSBAR_CHANGED, SEVERITY_SUCCESS);
    ThinkTime(3.3);
    SapGuiLogon("ddic", "*******", "000", "");

    // Copyright
    SapGuiSetActiveWindow("wnd[1]", "Copyright", SAPGUI_MATCH_Exact);
    SapGuiPressButton("tbar[0]/btn[0]");

    // SAP Easy Access
    ThinkTime(3.9);
    SapGuiSetActiveWindow("wnd[0]", "SAP Easy Access", SAPGUI_MATCH_Exact);

    // NodeName: Office
    // NodePath: 2\1
    SapGuiTreeExpandNode("usr/cntlIMAGE_CONTAINER/shellcont/shell/shellcont[0]/shell",
    "Office", "0000000003", "Expand\\Office");

    // NodeName: Workplace
    // NodePath: 2\1\1
    SapGuiTreeSelectNode("usr/cntlIMAGE_CONTAINER/shellcont/shell/shellcont[0]/shell", "Workplace", "0000000004",
    false, "SelNode\\Workplace");

    // NodeName: Favorites
    // NodePath: 1
    SapGuiSelectTopNode("usr/cntlIMAGE_CONTAINER/shellcont/shell/shellcont[0]/shell",
    "Favorites", "Favo", "TopNode\\Favorites");

    // NodeName: Workplace
    // NodePath: 2\1\1
    SapGuiTreeDblClickNode("usr/cntlIMAGE_CONTAINER/shellcont/shell/shellcont[0]/shell", "Workplace",
    "0000000004", "DblClNode\\Workplace");

    // Grid Control Info:
    // /app/con[0]/ses[0]/wnd[0]/usr/cntlSINWP_CONTAINER/shellcont/shell/shellcont[1]/shell/shellcont[0]/shell/0 columns
    // -------------------------------------

    // Business Workplace von DDIC
    ThinkTime(2.6);
    SapGuiSetActiveWindow("wnd[0]", "Business Workplace von DDIC", SAPGUI_MATCH_Exact);
    SapGuiPressButton("tbar[0]/btn[15]");

    // SAP Easy Access
    SapGuiSetActiveWindow("wnd[0]", "SAP Easy Access", SAPGUI_MATCH_Exact);

    // NodeName: Office
    // NodePath: 2\1
    ThinkTime(2.2);
    SapGuiTreeSelectNode("usr/cntlIMAGE_CONTAINER/shellcont/shell/shellcont[0]/shell", "Office", "0000000003",
    false, "SelNode\\Office");

    // NodeName: Office
    // NodePath: 2\1
    SapGuiTreeCollapseNode("usr/cntlIMAGE_CONTAINER/shellcont/shell/shellcont[0]/shell", "Office", "0000000003",
    "Collapse\\Office");

    // NodeName: Cross-Application Components
    // NodePath: 2\2
    SapGuiTreeExpandNode("usr/cntlIMAGE_CONTAINER/shellcont/shell/shellcont[0]/shell", "Cross-Application Components",
    "0000000020", "Expand\\Cross-Application Components");

    // NodeName: ALE Distribution Units
    // NodePath: 2\2\1
    SapGuiTreeExpandNode("usr/cntlIMAGE_CONTAINER/shellcont/shell/shellcont[0]/shell", "ALE Distribution Units",
    "0000000021", "Expand\\ALE Distribution Units");

    // NodeName: Favorites
    // NodePath: 1
    SapGuiSelectTopNode("usr/cntlIMAGE_CONTAINER/shellcont/shell/shellcont[0]/shell", "Favorites", "Favo",
    "TopNode\\Favorites");

    // NodeName: UPS Cockpit
    // NodePath: 2\2\1\1
    ThinkTime(3.1);
    SapGuiTreeSelectNode("usr/cntlIMAGE_CONTAINER/shellcont/shell/shellcont[0]/shell", "UPS Cockpit", "0000000075",
    false, "SelNode\\UPS Cockpit");

    // NodeName: UPS Cockpit
    // NodePath: 2\2\1\1
    SapGuiTreeDblClickNode("usr/cntlIMAGE_CONTAINER/shellcont/shell/shellcont[0]/shell", "UPS Cockpit",
    "0000000075", "DblClNode\\UPS Cockpit");

    // ALE - Distribution - Cockpit
    ThinkTime(3.6);
    SapGuiSetActiveWindow("wnd[0]", "ALE - Distribution - Cockpit", SAPGUI_MATCH_Exact);
  end TMain;
Parent topic: Control Functions


SapGuiTreeDefaultContextMenu Function

Action

Opens the default context menu for the tree.

Include file

SapGui.bdh

Syntax

SapGuiTreeDefaultContextMenu( in sControlId : string allownull,
                              in sTimer     : string optional ) : boolean;
Parameter | Description
sControlId | The tree's unique id.
sTimer | Timer name used for measurements.

Return value

  • true if successful
  • false otherwise

Example

transaction TMain
  var
    sConnID : string;
  begin
    // Connecting to SAP
    sConnID := SapGuiOpenConnection( " /SAP_CODEPAGE=1100 /FULLMENU 10.5.2.132 0 /3");
    SapGuiSetActiveConnection(sConnID);
    SapGuiSetActiveSession("ses[0]");

    // SAP
    SapGuiSetActiveWindow("wnd[0]", "SAP", SAPGUI_MATCH_ExactNoCase);
    SapGuiWindowAction(SAPGUI_WND_MAXIMIZE);
    SapGuiLogon("ddic", "*******", "000", "");
    SapGuiTreeDefaultContextMenu("/usr/tab/chk1");
  end TMain;
Parent topic: Control Functions


SapGuiTreeGetColumnCol Function

Action

Returns the keys of all the items in the given column.

Include file

SapGui.bdh

Syntax

SapGuiTreeGetColumnCol( in  sControlId  : string,
                        in  sColumnName : string,
                        out nIterator   : number ) : boolean;
Parameter | Description
sControlId | The control’s unique id.
sColumnName | The column to be queried for keys.
nIterator | This parameter will be assigned the collection iterator.

Return value

  • true if successful
  • false otherwise

Example

transaction TMain
 var
    sConnID   : string;
    i         : number;
    nIterator : number;
    nType     : number;
    nObject   : number;
    bRet      : boolean;
    sStr1, sStr2 : string;
 begin
    // Connecting to SAP
    sConnID := SapGuiOpenConnection(" /SAP_CODEPAGE=1100 /FULLMENU 10.5.2.198 0 /3");
    SapGuiSetActiveConnection(sConnID);
    SapGuiSetActiveSession("ses[0]");

    // SAP
    SapGuiSetActiveWindow("wnd[0]", "SAP", SAPGUI_MATCH_Exact);
    SapGuiWindowAction(SAPGUI_WND_MAXIMIZE);

    // Logon to SAP System
    SapGuiIgnoreError(SAPENGINE_STATUSBAR_CHANGED, SEVERITY_SUCCESS);
    ThinkTime(2.8);
    SapGuiLogon("ddic", "minisap", "000", "");

    // Copyright
    ThinkTime(2.1);
    SapGuiSetActiveWindow("wnd[1]", "Copyright", SAPGUI_MATCH_Exact);
    SapGuiPressButton("tbar[0]/btn[0]");

    // SAP Easy Access
    ThinkTime(9.9);
    SapGuiSetActiveWindow("wnd[0]", "SAP Easy Access",SAPGUI_MATCH_Exact);
    SapGuiTreeGetColumnCol("tree[0]", "col1", nIterator);
    while (SapGuiIteratorHasMore(nIterator)) do
      SapGuiIteratorFetchNext(nIterator);
      SapGuiIteratorGetValue(nIterator, sValue, nType);
      Print(string(nType) + " " + sValue);
    end;
    SapGuiIteratorRelease(nIterator);
  end TMain;
Parent topic: Control Functions


SapGuiTreeGetColumnHeaders Function

Action

Returns a collection of column headers for the specified tree.

Include file

SapGui.bdh

Syntax

SapGuiTreeGetColumnHeaders( in  sControlId : string,
                            out nIterator  : number ) : boolean;
Parameter | Description
sControlId | The control’s unique id.
nIterator | This parameter will be assigned a collection iterator for the column headers.

Return value

  • true if successful
  • false otherwise

Example

transaction TMain
  var
    sConnID   : string;
    i         : number;
    nIterator : number;
    nType     : number;
    nObject   : number;
    bRet      : boolean;
    sStr1, sStr2 : string;
  begin
    // Connecting to SAP
    sConnID := SapGuiOpenConnection(" /SAP_CODEPAGE=1100 /FULLMENU 10.5.2.198 0 /3");
    SapGuiSetActiveConnection(sConnID);
    SapGuiSetActiveSession("ses[0]");

    // SAP
    SapGuiSetActiveWindow("wnd[0]", "SAP", SAPGUI_MATCH_Exact);
    SapGuiWindowAction(SAPGUI_WND_MAXIMIZE);

    // Logon to SAP System
    SapGuiIgnoreError(SAPENGINE_STATUSBAR_CHANGED, SEVERITY_SUCCESS);
    ThinkTime(2.8);
    SapGuiLogon("ddic", "minisap", "000", "");

    // Copyright
    ThinkTime(2.1);
    SapGuiSetActiveWindow("wnd[1]", "Copyright", SAPGUI_MATCH_Exact);
    SapGuiPressButton("tbar[0]/btn[0]");

    // SAP Easy Access
    ThinkTime(9.9);
    SapGuiSetActiveWindow("wnd[0]", "SAP Easy Access", SAPGUI_MATCH_Exact);
    SapGuiTreeGetColumnHeaders("tree[0]", nIterator);
    while (SapGuiIteratorHasMore(nIterator)) do
      SapGuiIteratorFetchNext(nIterator);
      SapGuiIteratorGetValue(nIterator, sValue, nType);
      Print(string(nType) + " " + sValue);
    end;
    SapGuiIteratorRelease(nIterator);
  end TMain;
Parent topic: Control Functions


SapGuiTreeGetColumnNames Function

Action

Returns a collection of column names for the specified tree.

Include file

SapGui.bdh

Syntax

SapGuiTreeGetColumnNames( in  sControlId : string,
                          out nIterator  : number ) : boolean;
Parameter | Description
sControlId | The control’s unique id.
nIterator | This parameter will be assigned a collection iterator for the column names.

Return value

  • true if successful
  • false otherwise

Example

transaction TMain
  var
    sConnID   : string;
    i         : number;
    nIterator : number;
    nType     : number;
    nObject   : number;
    bRet      : boolean;
    sStr1, sStr2 : string;
  begin
    // Connecting to SAP
    sConnID := SapGuiOpenConnection(" /SAP_CODEPAGE=1100 /FULLMENU 10.5.2.198 0 /3");
    SapGuiSetActiveConnection(sConnID);
    SapGuiSetActiveSession("ses[0]");

    // SAP
    SapGuiSetActiveWindow("wnd[0]", "SAP", SAPGUI_MATCH_Exact);
    SapGuiWindowAction(SAPGUI_WND_MAXIMIZE);

    // Logon to SAP System
    SapGuiIgnoreError(SAPENGINE_STATUSBAR_CHANGED, SEVERITY_SUCCESS);
    ThinkTime(2.8);
    SapGuiLogon("ddic", "minisap", "000", "");

    // Copyright
    ThinkTime(2.1);
    SapGuiSetActiveWindow("wnd[1]", "Copyright", SAPGUI_MATCH_Exact);
    SapGuiPressButton("tbar[0]/btn[0]");

    // SAP Easy Access
    ThinkTime(9.9);
    SapGuiSetActiveWindow("wnd[0]", "SAP Easy Access", SAPGUI_MATCH_Exact);
    SapGuiTreeGetColumnNames("wnd[0]", nIterator);
    while (SapGuiIteratorHasMore(nIterator)) do
      SapGuiIteratorFetchNext(nIterator);
      SapGuiIteratorGetValue(nIterator, sValue, nType);
      Print(string(nType) + " " + sValue);
    end;
    SapGuiIteratorRelease(nIterator);
  end TMain;
Parent topic: Control Functions


SapGuiTreeGetItemText Function

Action

Returns the text of a tree item.

Include file

SapGui.bdh

Syntax

SapGuiTreeGetItemText( in sControlId : string;
                       in sNode      : string;
                       in sItem      : string ) : string;
Parameter | Description
sControlId | The unique id of the control.
sNode | Identifier for the node.
sItem | Identifier for the treeitem.

Return value

  • Tree item text on success.
  • Empty string otherwise.

Example

transaction TMain
  var
    sText : string;
    sConnID : string;
  begin
    // Connecting to SAP
    sConnID := SapGuiOpenConnection( " /SAP_CODEPAGE=1100 /FULLMENU 10.5.2.132 0 /3");
    SapGuiSetActiveConnection(sConnID);
    SapGuiSetActiveSession("ses[0]");

    // SAP
    SapGuiSetActiveWindow("wnd[0]", "SAP", SAPGUI_MATCH_ExactNoCase);
    SapGuiWindowAction(SAPGUI_WND_MAXIMIZE);
    SapGuiLogon("ddic", "*******", "000", "");
    sText := SapGuiTreeGetItemText("/usr/tab/mytree", "OBJEII", "SITEM");
  end TMain;
Parent topic: Control Functions


SapGuiTreeGetNodeChildrenCountByPath Function

Action

Returns the number of children of the node given by the path parameter.

Include file

SapGui.bdh

Syntax

SapGuiTreeGetNodeChildrenCountByPath( in  sControlId : string,
                                      in  sPath      : string,
                                      out nCount     : number ) : boolean;
Parameter | Description
sControlId | The control’s unique id.
sPath | The path to the node.
nCount | This parameter will be assigned the number of children.

Return value

  • true if successful
  • false otherwise

Example

transaction TMain
  var
    sConnID   : string;
    i         : number;
    nIterator : number;
    nType     : number;
    nObject   : number;
    bRet      : boolean;
    sStr1, sStr2 : string;
  begin
    // Connecting to SAP
    sConnID := SapGuiOpenConnection(" /SAP_CODEPAGE=1100 /FULLMENU 10.5.2.198 0 /3");
    SapGuiSetActiveConnection(sConnID);
    SapGuiSetActiveSession("ses[0]");

    // SAP
    SapGuiSetActiveWindow("wnd[0]", "SAP", SAPGUI_MATCH_Exact);
    SapGuiWindowAction(SAPGUI_WND_MAXIMIZE);

    // Logon to SAP System
    SapGuiIgnoreError(SAPENGINE_STATUSBAR_CHANGED, SEVERITY_SUCCESS);
    ThinkTime(2.8);
    SapGuiLogon("ddic", "minisap", "000", "");

    // Copyright
    ThinkTime(2.1);
    SapGuiSetActiveWindow("wnd[1]", "Copyright", SAPGUI_MATCH_Exact);
    SapGuiPressButton("tbar[0]/btn[0]");

    // SAP Easy Access
    ThinkTime(9.9);
    SapGuiSetActiveWindow("wnd[0]", "SAP Easy Access", SAPGUI_MATCH_Exact);
    SapGuiTreeGetNodeChildrenCountByPath("tree[0]", "2/1/2", i);
  end TMain;
Parent topic: Control Functions


SapGuiTreeGetNodeKeyByPath Function

Action

Returns the key of the node specified by the given path description.

Include file

SapGui.bdh

Syntax

SapGuiTreeGetNodeKeyByPath( in  sControlId : string,
                            in  sPath      : string,
                            out sNodeKey   : string ) : boolean;
Parameter | Description
sControlId | The control’s unique id
sPath | The path of the node.
sNodeKey | This parameter will be assigned the node key.

Return value

  • true if successful
  • false otherwise

Example

transaction TMain
  var
    sConnID   : string;
    i         : number;
    nIterator : number;
    nType     : number;
    nObject   : number;
    bRet      : boolean;
    sStr1, sStr2 : string;
  begin
    // Connecting to SAP
    sConnID := SapGuiOpenConnection(" /SAP_CODEPAGE=1100 /FULLMENU 10.5.2.198 0 /3");
    SapGuiSetActiveConnection(sConnID);
    SapGuiSetActiveSession("ses[0]");

    // SAP
    SapGuiSetActiveWindow("wnd[0]", "SAP", SAPGUI_MATCH_Exact);
    SapGuiWindowAction(SAPGUI_WND_MAXIMIZE);

    // Logon to SAP System
    SapGuiIgnoreError(SAPENGINE_STATUSBAR_CHANGED, SEVERITY_SUCCESS);
    ThinkTime(2.8);
    SapGuiLogon("ddic", "minisap", "000", "");

    // Copyright
    ThinkTime(2.1);
    SapGuiSetActiveWindow("wnd[1]", "Copyright", SAPGUI_MATCH_Exact);
    SapGuiPressButton("tbar[0]/btn[0]");

    // SAP Easy Access
    ThinkTime(9.9);
    SapGuiSetActiveWindow("wnd[0]", "SAP Easy Access", SAPGUI_MATCH_Exact);
    SapGuiTreeGetNodeKeyByPath("tree[0]", "2\\1\\2", sValue);
  end TMain;
Parent topic: Control Functions


SapGuiTreeGetNodesCol Function

Action

Returns the node keys of all the nodes in the tree.

Include file

SapGui.bdh

Syntax

SapGuiTreeGetNodesCol( in  sControlId : string,
                       out nIterator  : number ) : boolean;
Parameter | Description
sControlId | The control’s unique id.
nIterator | This parameter will be assigned a collection iterator for the nodes in the tree.

Return value

  • true if successful
  • false otherwise

Example

transaction TMain
  var
    sConnID   : string;
    i         : number;
    nIterator : number;
    nType     : number;
    nObject   : number;
    bRet      : boolean;
    sStr1, sStr2 : string;
  begin
    // Connecting to SAP
    sConnID := SapGuiOpenConnection(" /SAP_CODEPAGE=1100 /FULLMENU 10.5.2.198 0 /3");
    SapGuiSetActiveConnection(sConnID);
    SapGuiSetActiveSession("ses[0]");

    // SAP
    SapGuiSetActiveWindow("wnd[0]", "SAP", SAPGUI_MATCH_Exact);
    SapGuiWindowAction(SAPGUI_WND_MAXIMIZE);

    // Logon to SAP System
    SapGuiIgnoreError(SAPENGINE_STATUSBAR_CHANGED, SEVERITY_SUCCESS);
    ThinkTime(2.8);
    SapGuiLogon("ddic", "minisap", "000", "");

    // Copyright
    ThinkTime(2.1);
    SapGuiSetActiveWindow("wnd[1]", "Copyright", SAPGUI_MATCH_Exact);
    SapGuiPressButton("tbar[0]/btn[0]");

    // SAP Easy Access
    ThinkTime(9.9);
    SapGuiSetActiveWindow("wnd[0]", "SAP Easy Access", SAPGUI_MATCH_Exact);
    SapGuiTreeGetNodesCol("tree[0]", nIterator);
    while (SapGuiIteratorHasMore(nIterator)) do
      SapGuiIteratorFetchNext(nIterator);
      SapGuiIteratorGetValue(nIterator, sValue, nType);
      Print(string(nType) + " " + sValue);
    end;
    SapGuiIteratorRelease(nIterator);
  end TMain;
Parent topic: Control Functions


SapGuiTreeGetNodeText Function

Action

Returns the text of a specified node of a SapGui tree control.

Include file

SapGui.bdh

Syntax

SapGuiTreeGetNodeText( in sControlId : string;
                       in sNode      : string ) : string;
Parameter | Description
sControlId | The unique id of the control.
sNode | Identifier of the node.

Return value

  • Node text on success.
  • Empty string otherwise.

Example

transaction TMain
  var
    sConnID : string;
    sText   : string;
    sConnID : string;
  begin
    // Connecting to SAP
    sConnID := SapGuiOpenConnection( " /SAP_CODEPAGE=1100 /FULLMENU 10.5.2.132 0 /3");
    SapGuiSetActiveConnection(sConnID);
    SapGuiSetActiveSession("ses[0]");

    // SAP
    SapGuiSetActiveWindow("wnd[0]", "SAP", SAPGUI_MATCH_ExactNoCase);
    SapGuiWindowAction(SAPGUI_WND_MAXIMIZE);
    SapGuiLogon("ddic", "*******", "000", "");
    sText := SapGuiTreeGetNodeText("/usr/tab/mytree", "OOOBJOE")
  end TMain;
Parent topic: Control Functions


SapGuiTreeGetNodeTextByPath Function

Action

Returns the text of a node defined by the given path.

Include file

SapGui.bdh

Syntax

SapGuiTreeGetNodeTextByPath( in  sControlId : string,
                             in  sPath      : string,
                             out sNodeText  : string ) : boolean;
Parameter | Description
sControlId | The control’s unique id.
sPath | The path to the node.
sNodeText | This parameter will be assigned the node text.

Return value

  • true if successful
  • false otherwise

Example

transaction TMain
  var
    sConnID   : string;
    i         : number;
    nIterator : number;
    nType     : number;
    nObject   : number;
    bRet      : boolean;
    sStr1, sStr2 : string;
  begin
    // Connecting to SAP
    sConnID := SapGuiOpenConnection(" /SAP_CODEPAGE=1100 /FULLMENU 10.5.2.198 0 /3");
    SapGuiSetActiveConnection(sConnID);
    SapGuiSetActiveSession("ses[0]");

    // SAP
    SapGuiSetActiveWindow("wnd[0]", "SAP", SAPGUI_MATCH_Exact);
    SapGuiWindowAction(SAPGUI_WND_MAXIMIZE);

    // Logon to SAP System
    SapGuiIgnoreError(SAPENGINE_STATUSBAR_CHANGED, SEVERITY_SUCCESS);
    ThinkTime(2.8);
    SapGuiLogon("ddic", "minisap", "000", "");

    // Copyright
    ThinkTime(2.1);
    SapGuiSetActiveWindow("wnd[1]", "Copyright", SAPGUI_MATCH_Exact);
    SapGuiPressButton("tbar[0]/btn[0]");

    // SAP Easy Access
    ThinkTime(9.9);
    SapGuiSetActiveWindow("wnd[0]", "SAP Easy Access", SAPGUI_MATCH_Exact);
    SapGuiTreeGetNodeTextByPath("tree[0]", "2/1/2", sValue);
  end TMain;
Parent topic: Control Functions


SapGuiTreeGetParent Function

Action

Returns the key of the parent node of the specified node in a SapGui tree control.

Include file

SapGui.bdh

Syntax

SapGuiTreeGetParent( in  sControlId : string,
                     in  sNodeKey   : string, out sParentKey : string ) : boolean;
Parameter | Description
sControlId | The control’s unique id.
sNodeKey | The node to be queried for its parent key.
sParentKey | This parameter will be assigned the key of the parent node.

Return value

  • true if successful
  • false otherwise

Example

transaction TMain
  var
    sConnID   : string;
    i         : number;
    nIterator : number;
    nType     : number;
    nObject   : number;
    bRet      : boolean;
    sStr1, sStr2 : string;
  begin
    // Connecting to SAP
    sConnID := SapGuiOpenConnection(" /SAP_CODEPAGE=1100 /FULLMENU 10.5.2.198 0 /3");
    SapGuiSetActiveConnection(sConnID);
    SapGuiSetActiveSession("ses[0]");

    // SAP
    SapGuiSetActiveWindow("wnd[0]", "SAP", SAPGUI_MATCH_Exact);
    SapGuiWindowAction(SAPGUI_WND_MAXIMIZE);

    // Logon to SAP System
    SapGuiIgnoreError(SAPENGINE_STATUSBAR_CHANGED, SEVERITY_SUCCESS);
    ThinkTime(2.8);
    SapGuiLogon("ddic", "minisap", "000", "");

    // Copyright
    ThinkTime(2.1);
    SapGuiSetActiveWindow("wnd[1]", "Copyright", SAPGUI_MATCH_Exact);
    SapGuiPressButton("tbar[0]/btn[0]");

    // SAP Easy Access
    ThinkTime(9.9);
    SapGuiSetActiveWindow("wnd[0]", "SAP Easy Access", SAPGUI_MATCH_Exact);
    SapGuiTreeGetParent("tree[0]", "212542", sValue);
  end TMain;
Parent topic: Control Functions


SapGuiTreeGetSubNodesCol Function

Action

Returns the keys of all subnodes of the node specified by the given key.

Include file

SapGui.bdh

Syntax

SapGuiTreeGetSubNodesCol( in  sControlId : string,
                          in  sNodeKey   : number,
                          out nIterator  : number ) : boolean;
Parameter | Description
sControlId | The control’s unique id.
sNodeKey | The key of the node.
nIterator | This parameter will be assigned the a collection iterator for the node's subnodes.

Return value

  • true if successful
  • false otherwise

Example

transaction TMain
  var
    sConnID   : string;
    i         : number;
    nIterator : number;
    nType     : number;
    nObject   : number;
    bRet      : boolean;
    sStr1, sStr2 : string;
  begin
    // Connecting to SAP
    sConnID := SapGuiOpenConnection(" /SAP_CODEPAGE=1100 /FULLMENU 10.5.2.198 0 /3");
    SapGuiSetActiveConnection(sConnID);
    SapGuiSetActiveSession("ses[0]");

    // SAP
    SapGuiSetActiveWindow("wnd[0]", "SAP", SAPGUI_MATCH_Exact);
    SapGuiWindowAction(SAPGUI_WND_MAXIMIZE);

    // Logon to SAP System
    SapGuiIgnoreError(SAPENGINE_STATUSBAR_CHANGED, SEVERITY_SUCCESS);
    ThinkTime(2.8);
    SapGuiLogon("ddic", "minisap", "000", "");

    // Copyright
    ThinkTime(2.1);
    SapGuiSetActiveWindow("wnd[1]", "Copyright", SAPGUI_MATCH_Exact);
    SapGuiPressButton("tbar[0]/btn[0]");

    // SAP Easy Access
    ThinkTime(9.9);
    SapGuiSetActiveWindow("wnd[0]", "SAP Easy Access", SAPGUI_MATCH_Exact);
    SapGuiTreeGetSubNodesCol("tree[0]", "000564", nIterator);
    while (SapGuiIteratorHasMore(nIterator)) do
      SapGuiIteratorFetchNext(nIterator);
      SapGuiIteratorGetValue(nIterator, sValue, nType);
      Print(string(nType) + " " + sValue);
    end;
    SapGuiIteratorRelease(nIterator);
  end TMain;
Parent topic: Control Functions


SapGuiTreeHeaderContextMenu Function

Action

Opens a context menu for a tree header.

Include file

SapGui.bdh

Syntax

SapGuiTreeHeaderContextMenu( in sControlId  : string allownull,
                             in sHeaderName : string,
                             in sTimer      : string optional ) : boolean;
Parameter | Description
sControlId | The control's unique id.
sHeaderName | The name of the tree header.
sTimer | Timer name used for measurements.

Return value

  • true if successful
  • false otherwise

Example

transaction TMain
  var
    sConnID : string;
  begin
    // Connecting to SAP
    sConnID := SapGuiOpenConnection( " /SAP_CODEPAGE=1100 /FULLMENU 10.5.2.132 0 /3");
    SapGuiSetActiveConnection(sConnID);
    SapGuiSetActiveSession("ses[0]");

    // SAP
    SapGuiSetActiveWindow("wnd[0]", "SAP", SAPGUI_MATCH_ExactNoCase);
    SapGuiWindowAction(SAPGUI_WND_MAXIMIZE);
    SapGuiLogon("ddic", "*******", "000", "");
    SapGuiTreeHeaderContextMenu("/usr/tab/tree", "header");
  end TMain;
Parent topic: Control Functions


SapGuiTreeItemContextMenu Function

Action

Opens a context menu for a tree item.

Include file

SapGui.bdh

Syntax

SapGuiTreeItemContextMenu( in sControlId : string allownull,
                           in sNodeName  : string,
                           in sNode      : string,
                           in sItemName  : string,
                           in sTimer     : string optional ) : boolean;
Parameter | Description
sControlId | The tree's unique id.
sNodeName | The name of the node for which the context menu should be opened. Silk Performer will try to look up the node by matching the node name. If it cannot find the node by the name or if the name is not unique, specify the node id in the third parameter.
sNode | The node id identifying the node.
sItemName | The name of the tree item.
sTimer | Timer name used for measurements.

Return value

  • true if successful
  • false otherwise

Example

transaction TMain
  var
    sConnID : string;
  begin
    // Connecting to SAP
    sConnID := SapGuiOpenConnection( " /SAP_CODEPAGE=1100 /FULLMENU 10.5.2.132 0 /3");
    SapGuiSetActiveConnection(sConnID);
    SapGuiSetActiveSession("ses[0]");

    // SAP
    SapGuiSetActiveWindow("wnd[0]", "SAP", SAPGUI_MATCH_ExactNoCase);
    SapGuiWindowAction(SAPGUI_WND_MAXIMIZE);
    SapGuiLogon("ddic", "*******", "000", "");
    SapGuiTreeItemContextMenu("/usr/tag/metre", "NODENAME", "NODEID", "ITEM");
  end TMain;
Parent topic: Control Functions


SapGuiTreeNodeContextMenu Function

Action

Opens a context menu for the specified tree node.

Include file

SapGui.bdh

Syntax

SapGuiTreeNodeContextMenu( in sControlId : string allownull,
                           in sNodeName  : string,
                           in sNode      : string,
                           in sTimer     : string optional ) : boolean;
Parameter | Description
sControlId | The tree's unique ID.
sNodeName | The name of the node for which the context menu should be opened. Silk Performer will try to look up the node by matching the node name. If it cannot find the node by the name or if the name is not unique, specify the node id in the third parameter.
sNode | The node id identifying the node.
sTimer | Timer name used for measurements.

Return value

  • true if successful
  • false otherwise

Example

transaction TMain
  var
    sConnID : string;
  begin
    // Connecting to SAP
    sConnID := SapGuiOpenConnection( " /SAP_CODEPAGE=1100 /FULLMENU /H/195.61.176.22/H/194.117.106.130/S/3297/H/cpce601 13 /3");
    SapGuiSetActiveConnection(sConnID);
    SapGuiSetActiveSession("ses[0]");

    // SAP R/3
    SapGuiSetActiveWindow("wnd[0]", "SAP R/3", SAPGUI_MATCH_Exact);
    SapGuiWindowAction(SAPGUI_WND_MAXIMIZE);

    // Logon to SAP System
    // Before running a test you have to customize the password parameter!
    SapGuiIgnoreError(SAPENGINE_STATUSBAR_CHANGED, SEVERITY_SUCCESS);
    ThinkTime(2.6);
    SapGuiLogon("sapuser", "****", "850", "");

    // System Messages
    ThinkTime(7.0);
    SapGuiSetActiveWindow("wnd[1]", "System Messages", SAPGUI_MATCH_Exact);
    SapGuiPressButton("tbar[0]/btn[0]");

    // SAP Easy Access - User menu for Partner #999999
    ThinkTime(102.6);
    SapGuiSetActiveWindow("wnd[0]", "SAP Easy Access - User menu for Partner #999999", SAPGUI_MATCH_Exact);

    // NodeName: User menu for Partner #999999
    // NodePath: 2
    SapGuiTreeSelectNode("usr/cntlIMAGE_CONTAINER/shellcont/shell/shellcont[0]/shell", "User menu for Partner #999999",
    "Root", false, "SelNode\\User menu for Partner #999999");

    // NodeName: User menu for Partner #999999
    // NodePath: 2
    SapGuiTreeDblClickNode("usr/cntlIMAGE_CONTAINER/shellcont/shell/shellcont[0]/shell", "User menu for Partner #999999",
    "Root", "DblClNode\\User menu for Partner #999999");

    // NodeName: Favorites
    // NodePath: 1
    ThinkTime(11.1);
    SapGuiTreeSelectNode("usr/cntlIMAGE_CONTAINER/shellcont/shell/shellcont[0]/shell", "Favorites", "Favo", false,
    "SelNode\\Favorites");

    // NodeName: Favorites
    // NodePath: 1
    SapGuiTreeDblClickNode("usr/cntlIMAGE_CONTAINER/shellcont/shell/shellcont[0]/shell", "Favorites", "Favo", "DblClNode\\Favorites");

    // NodeName: Office
    // NodePath: 2\1
    ThinkTime(11.5);
    SapGuiTreeExpandNode("usr/cntlIMAGE_CONTAINER/shellcont/shell/shellcont[0]/shell", "Office", "0000000005", "Expand\\Office");

    // NodeName: Telephone Integration
    // NodePath: 2\1\2
    SapGuiTreeExpandNode("usr/cntlIMAGE_CONTAINER/shellcont/shell/shellcont[0]/shell", "Telephone Integration",
    "0000000007", "Expand\\Telephone Integration");

    // NodeName: Own Telephone Number
    // NodePath: 2\1\2\1
    SapGuiTreeSelectNode("usr/cntlIMAGE_CONTAINER/shellcont/shell/shellcont[0]/shell", "Own Telephone Number", "0000000008",
    false, "SelNode\\Own Telephone Number");

    // NodeName: Favorites
    // NodePath: 1
    SapGuiSelectTopNode("usr/cntlIMAGE_CONTAINER/shellcont/shell/shellcont[0]/shell", "Favorites", "Favo", "TopNode\\Favorites");

    // NodeName: Own Telephone Number
    // NodePath: 2\1\2\1
    SapGuiTreeNodeContextMenu("usr/cntlIMAGE_CONTAINER/shellcont/shell/shellcont[0]/shell", "Own Telephone Number", "0000000008" ,
    "NodeCtxt\\Own Telephone Number");

    SapGuiIgnoreError(SAPENGINE_STATUSBAR_CHANGED, SEVERITY_SUCCESS);
    ThinkTime(5.6);
    SapGuiContextMenuSelectItem("usr/cntlIMAGE_CONTAINER/shellcont/shell/shellcont[0]/shell", "XXECK1");

    // StatusBar(Msg/Id/Type/No): No documentation exists for program RSPHSPHD/26363088/S/035
  end TMain;
Parent topic: Control Functions


SapGuiTreePressButton Function

Action

Clicks a button in a SapGui tree.

Include file

SapGui.bdh

Syntax

SapGuiTreePressButton( in sControlId : string allownull,
                       in sNodeName  : string,
                       in sNode      : string,
                       in sItemName  : string,
                       in sTimer     : string optional ) : boolean;
Parameter | Description
sControlId | The tree's unique id.
sNodeName | The name of the node for which its button should be clicked. Silk Performer will try to look up the node by matching the node name. If it cannot find the node by the name or if the name is not unique, specify the node id in the third parameter.
sNode | The node id identifying the node.
sItem | The name of the item.
sTimer | Timer name used for measurements.

Return value

  • true if successful
  • false otherwise

Example

transaction TMain
  var
    sText : string;
  begin
    // Connecting to SAP
    sConnID := SapGuiOpenConnection( " /SAP_CODEPAGE=1100 /FULLMENU 10.5.2.132 0 /3");
    SapGuiSetActiveConnection(sConnID);
    SapGuiSetActiveSession("ses[0]");

    // SAP
    SapGuiSetActiveWindow("wnd[0]", "SAP", SAPGUI_MATCH_ExactNoCase);
    SapGuiWindowAction(SAPGUI_WND_MAXIMIZE);
    SapGuiLogon("ddic", "*******", "000", "");
    SapGuiTreePressButton("/usr/tab/mtr", "NODENAME", "NODE", "ITEM");
  end TMain;
Parent topic: Control Functions


SapGuiTreePressHeader Function

Action

Performs a click on the column header.

Include file

SapGui.bdh

Syntax

SapGuiTreePressHeader( in sControlId : string allownull,
                       in sHeader    : string,
                       in sTimer     : string optional ) : boolean;
Parameter | Description
sControlId | The tree's unique id.
sHeader | The name of the header.
sTimer | Timer name used for measurements.

Return value

  • true if successful
  • false otherwise

Example

transaction TMain
  var
    sConnID : string;
  begin
    // Connecting to SAP
    sConnID := SapGuiOpenConnection( " /SAP_CODEPAGE=1100 /FULLMENU 10.5.2.132 0 /3");
    SapGuiSetActiveConnection(sConnID);
    SapGuiSetActiveSession("ses[0]");

    // SAP
    SapGuiSetActiveWindow("wnd[0]", "SAP", SAPGUI_MATCH_ExactNoCase);
    SapGuiWindowAction(SAPGUI_WND_MAXIMIZE);
    SapGuiLogon("ddic", "*******", "000", "");
    SapGuiTreePressHeader("/usr/tab/ctree", "HEADER1");
  end TMain;
Parent topic: Control Functions


SapGuiTreePressKey Function

Action

Presses a keyboard key.

Include file

SapGui.bdh

Syntax

SapGuiTreePressKey( in sControlId : string allownull,
                    in sKey       : string,
                    in sTimer     : string optional ) : boolean;
Parameter | Description
sControlId | The tree's unique id.
sKey | The key pressed.
sTimer | Timer name used for measurements.

Return value

  • true if successful
  • false otherwise

Example

transaction TMain
  var
    sText : string;
  begin
    // Connecting to SAP
    sConnID := SapGuiOpenConnection( " /SAP_CODEPAGE=1100 /FULLMENU 10.5.2.132 0 /3");
    SapGuiSetActiveConnection(sConnID);
    SapGuiSetActiveSession("ses[0]");

    // SAP
    SapGuiSetActiveWindow("wnd[0]", "SAP", SAPGUI_MATCH_ExactNoCase);
    SapGuiWindowAction(SAPGUI_WND_MAXIMIZE);
    SapGuiLogon("ddic", "*******", "000", "");
    SapGuiTreePressKey("/usr/tab/mtree", "A");
  end TMain;
Parent topic: Control Functions


SapGuiTreeSelectColumn Function

Action

Selects a tree column.

Include file

SapGui.bdh

Syntax

SapGuiTreeSelectColumn( in sControlId : string allownull,
                        in sColumn    : string,
                        in sTimer     : string optional ) : boolean;
Parameter | Description
sControlId | The tree's unique id.
sColumn | The identifier of the column.
sTimer | Timer name used for measurements.

Return value

  • true if successful
  • false otherwise

Example

transaction TMain
  var
    sText : string;
  begin
    // Connecting to SAP
    sConnID := SapGuiOpenConnection( " /SAP_CODEPAGE=1100 /FULLMENU 10.5.2.132 0 /3");
    SapGuiSetActiveConnection(sConnID);
    SapGuiSetActiveSession("ses[0]");

    // SAP
    SapGuiSetActiveWindow("wnd[0]", "SAP", SAPGUI_MATCH_ExactNoCase);
    SapGuiWindowAction(SAPGUI_WND_MAXIMIZE);
    SapGuiLogon("ddic", "*******", "000", "");
    SapGuiTreeSelectColumn("/usr/tab/mtree", "COLUNN2" );
  end TMain;
Parent topic: Control Functions


SapGuiTreeSelectItem Function

Action

Selects an item from a SapGui tree control.

Include file

SapGui.bdh

Syntax

SapGuiTreeSelectItem( in sControlId : string allownull,
                      in sNodeName  : string,
                      in sNode      : string,
                      in sItemName  : string,
                      in sTimer     : string optional ) : boolean;
Parameter | Description
sControlId | The tree's unique id.
sNodeName | The name of the node. Silk Performer will try to look up the node by matching the node name. If it cannot find the node by the name or if the name is not unique, specify the node id in the third parameter.
sNode | The node id identifying the node.
sItemName | The item to be selected.
sTimer | Timer name used for measurements.

Return value

  • true if successful
  • false otherwise

Example

transaction TMain
  var
    sText : string;
  begin
    // Connecting to SAP
    sConnID := SapGuiOpenConnection( " /SAP_CODEPAGE=1100 /FULLMENU 10.5.2.132 0 /3");
    SapGuiSetActiveConnection(sConnID);
    SapGuiSetActiveSession("ses[0]");

    // SAP
    SapGuiSetActiveWindow("wnd[0]", "SAP", SAPGUI_MATCH_ExactNoCase);
    SapGuiWindowAction(SAPGUI_WND_MAXIMIZE);
    SapGuiLogon("ddic", "*******", "000", "");
    SapGuiTreeSelectItem("/usr/tab/mtree", "THENODE", "TREEITEM");
  end TMain;
Parent topic: Control Functions


SapGuiTreeSelectNode Function

Action

Selects the specified node inside a SapGui tree control.

Include file

SapGui.bdh

Syntax

SapGuiTreeSelectNode( in sControlId   : string allownull,
                      in sNodeName    : string,
                      in sNode        : string,
                      in bMultiselect : boolean optional,
                      in sTimer       : string optional ) : boolean;
Parameter | Description
sControlId | The tree's unique id.
sNodeName | The name of the node to be expanded. Silk Performer will try to look up the node by matching the node name. If it cannot find the node by the name or if the name is not unique, specify the node id in the third parameter.
sNode | The node id identifying the node.
bMultiselect | Specify, whether select more tree nodes. Set this parameter to "true", if more than one node should be selected.
sTimer | Timer name used for measurements.

Return value

  • true if successful
  • false otherwise

Example

transaction TMain
  var
    sConnID : string;
  begin
    // Connecting to SAP
    sConnID := SapGuiOpenConnection(" /SAP_CODEPAGE=1100 /FULLMENU 10.5.2.198 0 /3");
    SapGuiSetActiveConnection(sConnID);
    SapGuiSetActiveSession("ses[0]");

    // SAP
    SapGuiSetActiveWindow("wnd[0]", "SAP", SAPGUI_MATCH_Exact);
    SapGuiWindowAction(SAPGUI_WND_MAXIMIZE);

    // Logon to SAP System
    // Before running a test you have to customize the password parameter!
    SapGuiIgnoreError(SAPENGINE_STATUSBAR_CHANGED, SEVERITY_SUCCESS);
    ThinkTime(3.3);
    SapGuiLogon("ddic", "*******", "000", "");

    // Copyright
    SapGuiSetActiveWindow("wnd[1]", "Copyright", SAPGUI_MATCH_Exact);
    SapGuiPressButton("tbar[0]/btn[0]");

    // SAP Easy Access
    ThinkTime(3.9);
    SapGuiSetActiveWindow("wnd[0]", "SAP Easy Access", SAPGUI_MATCH_Exact);

    // NodeName: Office
    // NodePath: 2\1
    SapGuiTreeExpandNode("usr/cntlIMAGE_CONTAINER/shellcont/shell/shellcont[0]/shell", "Office",
    "0000000003", "Expand\\Office");

    // NodeName: Workplace
    // NodePath: 2\1\1
    SapGuiTreeSelectNode("usr/cntlIMAGE_CONTAINER/shellcont/shell/shellcont[0]/shell", "Workplace",
    "0000000004", false, "SelNode\\Workplace");

    // NodeName: Favorites
    // NodePath: 1
    SapGuiSelectTopNode("usr/cntlIMAGE_CONTAINER/shellcont/shell/shellcont[0]/shell", "Favorites",
    "Favo", "TopNode\\Favorites");

    // NodeName: Workplace
    // NodePath: 2\1\1
    SapGuiTreeDblClickNode("usr/cntlIMAGE_CONTAINER/shellcont/shell/shellcont[0]/shell", "Workplace",
    "0000000004", "DblClNode\\Workplace");
    // Grid Control Info:
    // /app/con[0]/ses[0]/wnd[0]/usr/cntlSINWP_CONTAINER/shellcont/shell/shellcont[1]/shell/shellcont[0]/shell/0 columns
    // -------------------------------------

    // Business Workplace von DDIC
    ThinkTime(2.6);
    SapGuiSetActiveWindow("wnd[0]", "Business Workplace von DDIC", SAPGUI_MATCH_Exact);
    SapGuiPressButton("tbar[0]/btn[15]");

    // SAP Easy Access
    SapGuiSetActiveWindow("wnd[0]", "SAP Easy Access", SAPGUI_MATCH_Exact);

    // NodeName: Office
    // NodePath: 2\1
    ThinkTime(2.2);
    SapGuiTreeSelectNode("usr/cntlIMAGE_CONTAINER/shellcont/shell/shellcont[0]/shell", "Office",
    "0000000003", false, "SelNode\\Office");

    // NodeName: Office
    // NodePath: 2\1
  end TMain;
Parent topic: Control Functions


SapGuiTreeSetColumnWidth Function

Action

Sets the tree column width.

Include file

SapGui.bdh

Syntax

SapGuiTreeSetColumnWidth( in sControlId : string allownull,
                          in sColumn    : string,
                          in nWidth     : number,
                          in sTimer     : string optional ) : boolean;
Parameter | Description
sControlId | The tree's unique id.
sColumn | The identifier for the column.
nWidth | The width to be set.
sTimer | Timer name used for measurements.

Return value

  • true if successful
  • false otherwise

Example

transaction TMain
  var
    bCheck : boolean;
    sConnID : string;
  begin
    // Connecting to SAP
    sConnID := SapGuiOpenConnection( " /SAP_CODEPAGE=1100 /FULLMENU 10.5.2.132 0 /3");
    SapGuiSetActiveConnection(sConnID);
    SapGuiSetActiveSession("ses[0]");

    // SAP
    SapGuiSetActiveWindow("wnd[0]", "SAP", SAPGUI_MATCH_ExactNoCase);
    SapGuiWindowAction(SAPGUI_WND_MAXIMIZE);
    SapGuiLogon("ddic", "*******", "000", "");
    bCheck := SapGuiTreeSetColumnWidth("/usr/tab/mtree", "OBIDU", 233 );
  end TMain;
Parent topic: Control Functions


SapGuiTreeSetHierarchyWidth Function

Action

Sets the tree hierarchy width.

Include file

SapGui.bdh

Syntax

SapGuiTreeSetHierarchyWidth( in sControlId : string allownull,
                             in nWidth     : number,
                             in sTimer     : string optional ) : boolean;
Parameter | Description
sControlId | The tree's unique id.
nWidth | The width to be set.
sTimer | Timer name used for measurements.

Return value

  • true if successful
  • false otherwise

Example

transaction TMain
  var
    bCheck : boolean;
    sConnID : string;
  begin
    // Connecting to SAP
    sConnID := SapGuiOpenConnection( " /SAP_CODEPAGE=1100 /FULLMENU 10.5.2.132 0 /3");
    SapGuiSetActiveConnection(sConnID);
    SapGuiSetActiveSession("ses[0]");

    // SAP
    SapGuiSetActiveWindow("wnd[0]", "SAP", SAPGUI_MATCH_ExactNoCase);
    SapGuiWindowAction(SAPGUI_WND_MAXIMIZE);
    SapGuiLogon("ddic", "*******", "000", "");
    bCheck := SapGuiTreeSetHierarchyWidth("/usr/tab/mtree", 232 );
  end TMain;
Parent topic: Control Functions


SapGuiTreeUnselectAll Function

Action

Cancels all selections in the tree.

Include file

SapGui.bdh

Syntax

SapGuiTreeUnselectAll( in sControlId : string allownull,
                       in sTimer     : string optional ) : boolean;
Parameter | Description
sControlId | The tree's unique id.
sTimer | Timer name used for measurements.

Return value

  • true if successful
  • false otherwise

Example

transaction TMain
  var
    bCheck : boolean;
    sConnID : string;
  begin
    // Connecting to SAP
    sConnID := SapGuiOpenConnection( " /SAP_CODEPAGE=1100 /FULLMENU 10.5.2.132 0 /3");
    SapGuiSetActiveConnection(sConnID);
    SapGuiSetActiveSession("ses[0]");

    // SAP
    SapGuiSetActiveWindow("wnd[0]", "SAP", SAPGUI_MATCH_ExactNoCase);
    SapGuiWindowAction(SAPGUI_WND_MAXIMIZE);
    SapGuiLogon("ddic", "*******", "000", "");
    bCheck := SapGuiTreeUnselectAll("/usr/tab/mtree");
  end TMain;
Parent topic: Control Functions


SapGuiTreeUnselectColumn Function

Action

Unselects a tree column.

Include file

SapGui.bdh

Syntax

SapGuiTreeUnselectColumn( in sControlId : string allownull,
                          in sColumn    : string,
                          in sTimer     : string optional ) : boolean;
Parameter | Description
sControlId | The tree's unique id.
sColumn | Identifier for the column to be unselected.
sTimer | Timer name used for measurements.

Return value

  • true if successful
  • false otherwise

Example

transaction TMain
  var
    sConnID : string;
  begin
    // Connecting to SAP
    sConnID := SapGuiOpenConnection( " /SAP_CODEPAGE=1100 /FULLMENU 10.5.2.132 0 /3");
    SapGuiSetActiveConnection(sConnID);
    SapGuiSetActiveSession("ses[0]");

    // SAP
    SapGuiSetActiveWindow("wnd[0]", "SAP", SAPGUI_MATCH_ExactNoCase);
    SapGuiWindowAction(SAPGUI_WND_MAXIMIZE);
    SapGuiLogon("ddic", "*******", "000", "");
    SapGuiTreeUnselectColumn("/usr/tab/tree", "COL894");
  end TMain;
Parent topic: Control Functions


SapGuiTreeUnselectNode Function

Action

Unselects a tree node.

Include file

SapGui.bdh

Syntax

SapGuiTreeUnselectNode( in sControlId : string allownull,
                        in sNodeName  : string,
                        in sNode      : string,
                        in sTimer     : string optional ) : boolean;
Parameter | Description
sControlId | The tree's unique id.
sNodeName | The name of the node to be unselected. Silk Performer will try to look up the node by matching the node name. If it cannot find the node by the name or if the name is not unique, specify the node id in the third parameter.
sNode | The node id identifying the node.
sTimer | Timer name used for measurements.

Return value

  • true if successful
  • false otherwise

Example

transaction TMain
  var
    sConnID : string;
  begin
    // Connecting to SAP
    sConnID := SapGuiOpenConnection( " /SAP_CODEPAGE=1100 /FULLMENU 10.5.2.132 0 /3");
    SapGuiSetActiveConnection(sConnID);
    SapGuiSetActiveSession("ses[0]");

    // SAP
    SapGuiSetActiveWindow("wnd[0]", "SAP", SAPGUI_MATCH_ExactNoCase);
    SapGuiWindowAction(SAPGUI_WND_MAXIMIZE);
    SapGuiLogon("ddic", "*******", "000", "");
    SapGuiTreeUnselectNode("/usr/tab/mtree", "OBJEJLKS" );
  end TMain;
Parent topic: Control Functions


Logging Functions

  • SapGuiLogControlInformation Function
    Logs the current control tree to the TrueLog.
Parent topic: SAP Functions


SapGuiLogControlInformation Function

Action

This function logs the current control tree to the TrueLog. During load tests with TrueLog-On-Error enabled, it is recommended that you use the profile setting “Log control information on error” rather than “Log control information in TrueLog.” TrueLogs-On-Error will then only contain the control values of windows in which errors have been raised. To have additional control information included in TrueLogs-On-Error, use the following method to log the control information of the active window.

Include file

SapGui.bdh

Syntax

SapGuiLogControlInformation( ): boolean;

Return value

  • true if successful
  • false otherwise

Example

transaction TMain
  var
    sConnID : string;
  begin

    // Connecting to SAP
    sConnID := SapGuiOpenConnection(" /SAP_CODEPAGE=1100 /FULLMENU 10.5.2.198 0 /3");
    SapGuiSetActiveConnection(sConnID);    SapGuiSetActiveSession("ses[0]");

    // SAP
    SapGuiSetActiveWindow("wnd[0]", "SAP", SAPGUI_MATCH_Exact);
    SapGuiWindowAction(SAPGUI_WND_MAXIMIZE);

    // ensures that – in case of an error – the control tree of the logon screen is included in the TrueLog
    SapGuiLogControlInformation();

    // Logon to SAP System

    // Before running a test you must customize the password parameter!
    SapGuiIgnoreError(SAPENGINE_STATUSBAR_CHANGED, SEVERITY_SUCCESS);
    ThinkTime(2.8);
    SapGuiLogon("ddic", "minisap", "000", "");

    // SAP Easy Access
    ThinkTime(9.9);
    SapGuiSetActiveWindow("wnd[0]", "SAP Easy Access", SAPGUI_MATCH_Exact);
  end TMain;
Parent topic: Logging Functions


Parsing Functions

  • SapGuiGetOkCode Function
    Retrieves text of the OK code text field.
  • SapGuiGetStatusBarText Function
    Retrieves the current text of the SapGui status bar.
  • SapGuiGetStatusBarType Function
    Retrieves the current type of the status bar control.
  • SapGuiGetText Function
    Retrieves the text of a label or edit control.
  • SapGuiIsCheckboxChecked Function
    Determines whether a SapGui check box control is checked.
  • SapGuiIsRadioButtonSelected Function
    Determines whether a specified radio button is selected.
  • SapGuiIsTabSelected Function
    Determines whether a specified tab is active.
  • SapGuiGridGetCellData Function
    Returns the value of a specified cell from a grid control.
  • SapGuiGridGetColumnCount Function
    Counts the number of columns of a SapGui grid control.
  • SapGuiGridGetColumnName Function
    Retrieves the name of a specified column of a SapGui grid control.
  • SapGuiGridGetColumnOrder Function
    Returns an iterator to a collection that contains all the column identifiers in the order in which they are currently displayed.
  • SapGuiGridGetCurrentCellColumn Function
    Returns the name of the current cell's column.
  • SapGuiGridGetCurrentCellRow Function
    Returns the name of the current cell's row.
  • SapGuiGridGetRowCount Function
    Returns the number of rows of a SapGui grid control.
  • SapGuiGridGetSelectedCells Function
    Collection of selected cells contains strings, each of which has the format “<index of the row>,<column identifier>”, such as “0,CARRID”.
  • SapGuiGridGetSelectedColumns Function
    Selected columns are available as a collection of strings.
  • SapGuiGridIsCheckboxChecked Function
    Determines whether grid cell's check box is checked.
  • SapGuiObjectFree Function
    Frees the memory that was allocated for a handle.
  • SapGuiObjectGetBoolean Function
    Reads the return value of a previous SapGuiObjectInvokeMethod call and provides it as type boolean.
  • SapGuiObjectGetCollection Function
    Reads the return value of a previous function call and returns it as a collection iterator.
  • SapGuiObjectGetControlId Function
    Provides the control id of a SAPGUI object.
  • SapGuiObjectGetLong Function
    Reads the return value of a previous call of the SapGuiObjectInvokeMethod function.
  • SapGuiObjectGetProperty Function
    Reads an object’s property.
  • SapGuiObjectGetPropertyBoolean Function
    Reads an object’s property.
  • SapGuiObjectGetPropertyLong Function
    Reads an object’s property.
  • SapGuiObjectGetObject Function
    Reads the return value of a pior call to SapGuiObjectInvokeMethod.
  • SapGuiObjectGetPropertyObject Function
    Reads an object’s property where the value to be read is an object.
  • SapGuiObjectGetString Function
    Reads the return value of a previous SapGuiObjectInvokeMethod call and provides it as a string.
  • SapGuiObjectGetType Function
    Returns the “type” and the “subtype” property of a SAPGUI object.
  • SapGuiObjectSetBoolean Function
    Pushes a parameter of type boolean onto the parameter stack for the next SapGuiObjectInvokeMethod call.
  • SapGuiObjectSetLong Function
    Pushes a parameter of type long onto the parameter stack for the next SapGuiObjectInvokeMethod function call.
  • SapGuiObjectSetObject Function
    Pushes an object onto the parameter stack for the next method invocation with SapGuiObjectInvokeMethod.
  • SapGuiObjectSetProperty Function
    Sets an object’s property.
  • SapGuiObjectSetPropertyObject Function
    Sets an object’s property which is of type object.
  • SapGuiObjectSetString Function
    Pushes a variable of type string onto the parameter stack for the next call of SapGuiObjectInvokeMethod call.
  • SapGuiIteratorFetchNext Function
    Moves the iterator to the next position.
  • SapGuiObjectInvokeMethod Function
    Invokes a method for the passed object.
  • SapGuiIteratorHasMore Function
    Determines whether there are more entries in a collection.
  • SapGuiIteratorRelease Function
    Frees the resources that were allocated for an iterator.
  • SapGuiIteratorGetCount Function
    Determines the number of elements in a collection.
  • SapGuiIteratorGetObject Function
    Provides the value of the iterator’s current position.
  • SapGuiIteratorGetObjectAt Function
    Reads and provides the value of a collection at a specified position.
  • SapGuiIteratorGetValue Function
    Provides the value of the iterator’s current position.
  • SapGuiIteratorGetValueAt Function
    Reads and provides the value of a collection at a specified position.
  • SapGuiGetCollection Function
    Reads the return value of a previous SapGuiInvokeMethod or SapGuiGetProperty call and provides it as a collection iterator.
  • SapGuiGetComboboxEntries Function
    Provides an iterator for the combobox entries.
  • SapGuiGetHandleFromControlId Function
    Returns a handle for the control specified.
  • SapGuiGetPropertyCollection Function
    Reads the return value of a previous call of SapGuiInvokeMethod and provides the value as a collection.
Parent topic: SAP Functions


SapGuiGetOkCode Function

Action

This function retrieves text of the OK code text field.

Include file

SapGui.bdh

Syntax

SapGuiGetOkCode( ) : string;

Return value

  • Text of the OK code textfield on success.
  • Empty string otherwise.

Example

transaction TMain
  var
    sText : string;
    sConnID : string;
  begin// Connecting to SAP
    sConnID := SapGuiOpenConnection(" /SAP_CODEPAGE=1100 /FULLMENU 10.5.2.132 0 /3");

    SapGuiSetActiveConnection(sConnID);

    SapGuiSetActiveSession("ses[0]");

    // SAP
    SapGuiSetActiveWindow("wnd[0]", "SAP", SAPGUI_MATCH_ExactNoCase);

    SapGuiWindowAction(SAPGUI_WND_MAXIMIZE);

    SapGuiLogon("ddic", "*******", "000", "");
    sText := SapGuiGetOkCode();
  end TMain;
Parent topic: Parsing Functions


SapGuiGetStatusBarText Function

Action

This function retrieves the current text of the SapGui status bar.

Include file

SapGui.bdh

Syntax

SapGuiGetStatusBarText() : string;

Return value

  • Text of the status bar.
  • Empty string otherwise.

Example

transaction TMain
  var
    sText : string;
    sConnID : string;
  begin

    // Connecting to SAP
    sConnID := SapGuiOpenConnection( " /SAP_CODEPAGE=1100 /FULLMENU 10.5.2.132 0 /3");
    SapGuiSetActiveConnection(sConnID);
    SapGuiSetActiveSession("ses[0]");

    // SAP
    SapGuiSetActiveWindow("wnd[0]", "SAP", SAPGUI_MATCH_ExactNoCase);
    SapGuiWindowAction(SAPGUI_WND_MAXIMIZE);
    SapGuiLogon("ddic", "*******", "000", "");
    sText := SapGuiGetStatusBarText();
  end TMain;
Parent topic: Parsing Functions


SapGuiGetStatusBarType Function

Action

This function retrieves the current type of the status bar message.

Include file

SapGui.bdh

Syntax

SapGuiGetStatusBarType() : string;

Return value

  • Type of the status bar control (for example, "GuiStatusbar").
  • Empty string otherwise.

Example

transaction TMain
  var
    sText : string;
    sConnID : string;
  begin
    // Connecting to SAP
    sConnID := SapGuiOpenConnection( " /SAP_CODEPAGE=1100 /FULLMENU 10.5.2.132 0 /3");
    SapGuiSetActiveConnection(sConnID);
    SapGuiSetActiveSession("ses[0]");

    // SAP
    SapGuiSetActiveWindow("wnd[0]", "SAP", SAPGUI_MATCH_ExactNoCase);
    SapGuiWindowAction(SAPGUI_WND_MAXIMIZE);
    SapGuiLogon("ddic", "*******", "000", "");
    sText := SapGuiGetStatusBarType();
  end TMain;
Parent topic: Parsing Functions


SapGuiGetText Function

Action

This function retrieves the text of a label or edit control.

Include file

SapGui.bdh

Syntax

SapGuiGetText( in sControlId : string ) : string;
Parameter | Description
sControlId | Unique id of the label or edit field.

Return value

  • Text of the control.
  • Empty string otherwise.

Example

transaction TMain
  var
    sText : string;
    sConnID : string;
  begin
    // Connecting to SAP
    sConnID := SapGuiOpenConnection( " /SAP_CODEPAGE=1100 /FULLMENU 10.5.2.132 0 /3");

    SapGuiSetActiveConnection(sConnID);
    SapGuiSetActiveSession("ses[0]");

    // SAP
    SapGuiSetActiveWindow("wnd[0]", "SAP", SAPGUI_MATCH_ExactNoCase);
    SapGuiWindowAction(SAPGUI_WND_MAXIMIZE);
    SapGuiLogon("ddic", "*******", "000", "");
    sText := SapGuiGetText("/tbar[1]/btn[48]");
    Print(sText);
  end TMain;
Parent topic: Parsing Functions


SapGuiIsCheckboxChecked Function

Action

This function determines whether a SapGui check box control is checked.

Include file

SapGui.bdh

Syntax

SapGuiIsCheckboxChecked( in sControlId : string ) : boolean;
Parameter | Description
sControlId | The unique id of the control.

Return value

  • true if the check box is checked
  • false otherwise

Example

transaction TMain
  var
    bCheck : boolean;
    sConnID : string;
  begin

    // Connecting to SAP
    sConnID := SapGuiOpenConnection( " /SAP_CODEPAGE=1100 /FULLMENU 10.5.2.132 0 /3");
    SapGuiSetActiveConnection(sConnID);
    SapGuiSetActiveSession("ses[0]");

    // SAP
    SapGuiSetActiveWindow("wnd[0]", "SAP", SAPGUI_MATCH_ExactNoCase);
    SapGuiWindowAction(SAPGUI_WND_MAXIMIZE);
    SapGuiLogon("ddic", "*******", "000", "");
    bCheck := SapGuiIsCheckboxChecked("/usr/tab/chk1");
  end TMain;
Parent topic: Parsing Functions


SapGuiIsRadioButtonSelected Function

Action

This function determines whether a specified radio button is selected.

Include file

SapGui.bdh

Syntax

SapGuiIsRadioButtonSelected( in sControlId : string ) : boolean;
Parameter | Description
sControlId | The unique id of the control.

Return value

  • true if the radio button is selected
  • false otherwise

Example

transaction TMain
  var
    bSel : boolean;
    sConnID : string;
  begin

    // Connecting to SAP
    sConnID := SapGuiOpenConnection( " /SAP_CODEPAGE=1100 /FULLMENU 10.5.2.132 0 /3");
    SapGuiSetActiveConnection(sConnID);
    SapGuiSetActiveSession("ses[0]");

    // SAP
    SapGuiSetActiveWindow("wnd[0]", "SAP", SAPGUI_MATCH_ExactNoCase);
    SapGuiWindowAction(SAPGUI_WND_MAXIMIZE);
    SapGuiLogon("ddic", "*******", "000", "");
    bSel := SapGuiIsRadioButtonSelected("/usr/tab/radio1");
  end TMain;
Parent topic: Parsing Functions


SapGuiIsTabSelected Function

Action

This function determines whether a specified tab is active.

Include file

SapGui.bdh

Syntax

SapGuiIsTabSelected( in sControlId : string ) : boolean;
Parameter | Description
sControlId | The unique id of the control.

Return value

  • true if the tab is selected
  • false otherwise

Example

transaction TMain
  var
    bSel : boolean;
    sConnID : string;
  begin

    // Connecting to SAP
    sConnID := SapGuiOpenConnection( " /SAP_CODEPAGE=1100 /FULLMENU 10.5.2.132 0 /3");
    SapGuiSetActiveConnection(sConnID);
    SapGuiSetActiveSession("ses[0]");

    // SAP
    SapGuiSetActiveWindow("wnd[0]", "SAP", SAPGUI_MATCH_ExactNoCase);
    SapGuiWindowAction(SAPGUI_WND_MAXIMIZE);
    SapGuiLogon("ddic", "*******", "000", "");
    bSel := SapGuiIsTabSelected("/usr/tab/pag1");
  end TMain;
Parent topic: Parsing Functions


SapGuiGridGetCellData Function

Action

This function returns the value of a specified cell from a grid control.

Include file

SapGui.bdh

Syntax

SapGuiGridGetCellData( in sControlId : string;
                       in nRow       : number;
                       in sCol       : string ) : string;
Parameter | Description
sControlId | The unique id of the control.
nRow | The cell's row. The first row is 1.
sCol | The cell's column. All valid column names of the table which can be passed as sCol parameter are recorded as comments in the script.

Return value

  • Selected entry on success.
  • Empty string otherwise.

Example

transaction TMain
  var
    sText  : string;
    sConnID : string;
  begin

    // Connecting to SAP
    sConnID := SapGuiOpenConnection( " /SAP_CODEPAGE=1100 /FULLMENU 10.5.2.132 0 /3");

    SapGuiSetActiveConnection(sConnID);

    SapGuiSetActiveSession("ses[0]");

    // SAP
    SapGuiSetActiveWindow("wnd[0]", "SAP", SAPGUI_MATCH_ExactNoCase);

    SapGuiWindowAction(SAPGUI_WND_MAXIMIZE);

    SapGuiLogon("ddic", "*******", "000", "");
    sText := SapGuiGridGetCellData("/usr/tab/grid23", 2, "OOBJW" );
  end TMain;

Parent topic: Parsing Functions


SapGuiGridGetColumnCount Function

Action

This functions counts the number of columns of a SapGui grid control.

Include file

SapGui.bdh

Syntax

SapGuiGridGetColumnCount( in     csControlId : string,
                          in out iCount      : number ) : boolean;
Parameter | Description
sControlId | The unique id of the grid
iCount | The value to be assigned the number of columns.

Return value

  • true if successful

  • false otherwise

Example

transaction TMain
  var
    iCount  : number;
    sConnID : string;
  begin
    // Connecting to SAP
    sConnID := SapGuiOpenConnection( " /SAP_CODEPAGE=1100 /FULLMENU 10.5.2.132 0 /3");

    SapGuiSetActiveConnection(sConnID);

    SapGuiSetActiveSession("ses[0]");

    // SAP
    SapGuiSetActiveWindow("wnd[0]", "SAP", SAPGUI_MATCH_ExactNoCase);

    SapGuiWindowAction(SAPGUI_WND_MAXIMIZE);

    SapGuiLogon("ddic", "*******", "000", "");
    SapGuiIgnoreError(SAPENGINE_STATUSBAR_CHANGED, SEVERITY_SUCCESS);
    SapGuiSetActiveWindow("wnd[0]", "SAP Easy Access", SAPGUI_MATCH_ExactNoCase);

    SapGuiSelectTopNode( "usr/cntlSINWP_CONTAINER/shellcont/shell/shellcont[0]/shell", "Workplace: DDIC", " 1", "TopNode\\Workplace: DDIC");

    ThinkTime(16.8);
    SapGuiGridSelectCell( "usr/cntlSINWP_CONTAINER/shellcont/shell/shellcont[1]/shell/shellcont[0]/shell", 1, "OBJDES");
    SapGuiGridGetColumnCount( "usr/cntlSINWP_CONTAINER/shellcont/shell/shellcont[1]/shell/shellcont[0]/shell" , iCount);
  end TMain;
Parent topic: Parsing Functions


SapGuiGridGetColumnName Function

Action

This function retrieves the name of a specified column of a SapGui grid control.

Include file

SapGui.bdh

Syntax

SapGuiGridGetColumnName( in  csControlId : string,
                         in  iCol        : number,
                         out sVal        : string) : boolean;
Parameter | Description
sControlId | The unique id of the grid.
iCol | The based index of the column. The first column is 0. Note that the index does not necessarily reflect the displayed order of the column. Call SapGuiGridGetColumnOrder to get the diplayed order of columns.
sVal | The parameter will be assigned the name of the column.

Return value

  • true if successful
  • false otherwise

Example

transaction TMain
  var
    iCol     : number;
    sConnID  : string;
    sColName : string;

  begin
    // Connecting to SAP
    sConnID := SapGuiOpenConnection( " /SAP_CODEPAGE=1100 /FULLMENU 10.5.2.132 0 /3");

    SapGuiSetActiveConnection(sConnID);
    SapGuiSetActiveSession("ses[0]");

    // SAP
    SapGuiSetActiveWindow("wnd[0]", "SAP", SAPGUI_MATCH_ExactNoCase);
    SapGuiWindowAction(SAPGUI_WND_MAXIMIZE);
    SapGuiLogon("ddic", "*******", "000", "");
    SapGuiIgnoreError(SAPENGINE_STATUSBAR_CHANGED, SEVERITY_SUCCESS);
    SapGuiSetActiveWindow("wnd[0]", "SAP Easy Access", SAPGUI_MATCH_ExactNoCase);
    SapGuiSelectTopNode( "usr/cntlSINWP_CONTAINER/shellcont/shell/shellcont[0]/shell", "Workplace: DDIC", " 1", "TopNode\\Workplace: DDIC");

    ThinkTime(16.8);
    SapGuiGridSelectCell( "usr/cntlSINWP_CONTAINER/shellcont/shell/shellcont[1]/shell/shellcont[0]/shell", 1, "OBJDES");

    // Write the name of 3rd column into sColName
    SapGuiGridGetColumnName( "usr/cntlSINWP_CONTAINER/shellcont/shell/shellcont[1]/shell/shellcont[0]/shell" , 2, sColName);

  end TMain;
Parent topic: Parsing Functions
Related reference
SapGuiGridGetColumnOrder Function


SapGuiGridGetColumnOrder Function

Action

This function returns an iterator to a collection that contains all the column identifiers in the order in which they are currently displayed.

Include file

SapGui.bdh

Syntax

SapGuiGridGetColumnOrder( in  sControlId : string allownull,
                          out nItertor   : number ) : boolean;
Parameter | Description
sControlId | The control’s unique id.
nIterator | This parameter will be assigned a handle to the collection iterator.

Return value

  • true if successful

  • false otherwise

Example

transaction TMain
  var
    sConnID   : string;
    sValue    : string;
    nIterator : number;
    nType     : number;
  begin

    // Connecting to SAP
    sConnID := SapGuiOpenConnection(" /SAP_CODEPAGE=1100 /FULLMENU 10.5.2.198 0 /3");
    SapGuiSetActiveConnection(sConnID);
    SapGuiSetActiveSession("ses[0]");

    // SAP
    SapGuiSetActiveWindow("wnd[0]", "SAP", SAPGUI_MATCH_Exact);
    SapGuiWindowAction(SAPGUI_WND_MAXIMIZE);

    // Logon to SAP System
    SapGuiIgnoreError(SAPENGINE_STATUSBAR_CHANGED, SEVERITY_SUCCESS);
    ThinkTime(2.8);
    SapGuiLogon("ddic", "minisap", "000", "");

    // Copyright
    ThinkTime(2.1);
    SapGuiSetActiveWindow("wnd[1]", "Copyright", SAPGUI_MATCH_Exact);
    SapGuiPressButton("tbar[0]/btn[0]");

    // SAP Easy Access
    ThinkTime(9.9);
    SapGuiSetActiveWindow("wnd[0]", "SAP Easy Access", SAPGUI_MATCH_Exact);
    SapGuiGridGetColumnOrder("usr/tblRSDEMO02TC_COLS/txtDEMO_CPROP-GROUP4", nIterator);
    while SapGuiIteratorHasMore(nIterator) do
      SapGuiIteratorFetchNext(nIterator);
      SapGuiIteratorGetValue(nIterator, sValue, nType);
      Print(sValue);
    end;
    SapGuiIteratorRelease(nIterator);
  end TMain;
Parent topic: Parsing Functions


SapGuiGridGetCurrentCellColumn Function

Action

This function returns the name of the current cell's column.

Include file

SapGui.bdh

Syntax

SapGuiGridGetCurrentCellColumn( in sControlId : string) : string;
Parameter | Description
sControlId | The unique id of the control.

Return value

  • Column name on success.

  • Empty string otherwise.

Example

transaction TMain
  var
    sText  : string;
    sConnID : string;
  begin
    // Connecting to SAP
    sConnID := SapGuiOpenConnection( " /SAP_CODEPAGE=1100 /FULLMENU 10.5.2.132 0 /3");

    SapGuiSetActiveConnection(sConnID);

    SapGuiSetActiveSession("ses[0]");

    // SAP
    SapGuiSetActiveWindow("wnd[0]", "SAP", SAPGUI_MATCH_ExactNoCase);

    SapGuiWindowAction(SAPGUI_WND_MAXIMIZE);

    SapGuiLogon("ddic", "*******", "000", "");
    sText := SapGuiGridGetCurrentCellColumn("/usr/tab/grid23" );
  end TMain;
Parent topic: Parsing Functions


SapGuiGridGetCurrentCellRow Function

Action

This function returns the name of the current cell's row.

Include file

SapGui.bdh

Syntax

SapGuiGridGetCurrentCellRow( in sControlId : string ) : string;
Parameter | Description
sControlId | The unique id of the control.

Return value

  • Row index (0-based) as string on success.
  • Empty string otherwise.

Example

transaction TMain
  var
    sText  : string;
    sConnID : string;
  begin
    // Connecting to SAP
    sConnID := SapGuiOpenConnection( " /SAP_CODEPAGE=1100 /FULLMENU 10.5.2.132 0 /3");

    SapGuiSetActiveConnection(sConnID);

    SapGuiSetActiveSession("ses[0]");

    // SAP
    SapGuiSetActiveWindow("wnd[0]", "SAP", SAPGUI_MATCH_ExactNoCase);

    SapGuiWindowAction(SAPGUI_WND_MAXIMIZE);

    SapGuiLogon("ddic", "*******", "000", "");
    sText := SapGuiGridGetCurrentCellRow("/usr/tab/grid23");
  end TMain;
Parent topic: Parsing Functions


SapGuiGridGetRowCount Function

Action

This function returns the number of rows of a SapGui grid control.

Include file

SapGui.bdh

Syntax

SapGuiGridGetRowCount( in    csControlId : string,
                       inout iCount      : number ) : boolean;
Parameter | Description
sControlId | The unique id of the grid
iCount | The value to be assigned the number of rows.

Return value

  • true if successful

  • false otherwise

Example

transaction TMain
  var
    iCount  : number;
    sConnID : string;
  begin
    // Connecting to SAP
    sConnID := SapGuiOpenConnection( " /SAP_CODEPAGE=1100 /FULLMENU 10.5.2.132 0 /3");

    SapGuiSetActiveConnection(sConnID);

    SapGuiSetActiveSession("ses[0]");

    // SAP
    SapGuiSetActiveWindow("wnd[0]", "SAP", SAPGUI_MATCH_ExactNoCase);

    SapGuiWindowAction(SAPGUI_WND_MAXIMIZE);

    SapGuiLogon("ddic", "*******", "000", "");
    SapGuiIgnoreError(SAPENGINE_STATUSBAR_CHANGED, SEVERITY_SUCCESS);
    SapGuiSetActiveWindow("wnd[0]", "SAP Easy Access", SAPGUI_MATCH_ExactNoCase);

    SapGuiSelectTopNode( "usr/cntlSINWP_CONTAINER/shellcont/shell/shellcont[0]/shell", "Workplace: DDIC", " 1", "TopNode\\Workplace: DDIC");

    ThinkTime(16.8);
    SapGuiGridSelectCell( "usr/cntlSINWP_CONTAINER/shellcont/shell/shellcont[1]/shell/shellcont[0]/shell", 1, "OBJDES");

    // Store the number of rows in iCount
    SapGuiGridGetRowCount( "usr/cntlSINWP_CONTAINER/shellcont/shell/shellcont[1]/shell/shellcont[0]/shell" , iCount);
  end TMain;
Parent topic: Parsing Functions


SapGuiGridGetSelectedCells Function

Action

The collection of selected cells contains strings, each of which has the format “<index of the row>,<column identifier>”, such as “0,CARRID”.

Include file

SapGui.bdh

Syntax

SapGuiGridGetSelectedCells( in  sControlId : string allownull,
                            out nIterator  : number ) : boolean;
Parameter | Description
sControlId | The controls’s unique id.
nIterator | This parameter will be assigned the handle to the collection iterator.

Return value

  • true if successful

  • false otherwise

Example

transaction TMain
  var
    sConnID       : string;
    nIterator     : number;
    sSelectedCell : string;
    nType         : number;
  begin
    // Connecting to SAP
    sConnID := SapGuiOpenConnection(" /SAP_CODEPAGE=1100 /FULLMENU 10.5.2.198 0 /3");

    SapGuiSetActiveConnection(sConnID);

    SapGuiSetActiveSession("ses[0]");

    // SAP
    SapGuiSetActiveWindow("wnd[0]", "SAP", SAPGUI_MATCH_Exact);

    SapGuiWindowAction(SAPGUI_WND_MAXIMIZE);

    // Logon to SAP System
    SapGuiIgnoreError(SAPENGINE_STATUSBAR_CHANGED, SEVERITY_SUCCESS);
    ThinkTime(2.8);
    SapGuiLogon("ddic", "minisap", "000", "");
    // Copyright
    ThinkTime(2.1);
    SapGuiSetActiveWindow("wnd[1]", "Copyright", SAPGUI_MATCH_Exact);

    SapGuiPressButton("tbar[0]/btn[0]");

    // SAP Easy Access
    ThinkTime(9.9);
    SapGuiSetActiveWindow("wnd[0]", "SAP Easy Access", SAPGUI_MATCH_Exact);

    SapGuiGridGetSelectedCells("usr/tblRSDEMO02TC_COLS/txtDEMO_CPROP-GROUP4", nIterator);
    while SapGuiIteratorHasMore(nIterator) do
      SapGuiIteratorFetchNext(nIterator);
      SapGuiIteratorGetValue(nIterator, sSelectedCell, nType);
      Print(sSelectedCell);
    end;

    SapGuiIteratorRelease(nIterator);

  end TMain;
Parent topic: Parsing Functions


SapGuiGridGetSelectedColumns Function

Action

The selected columns are available as a collection of strings.

Include file

SapGui.bdh

Syntax

SapGuiGridGetSelectedColumns( in  sControlId : string allownull,
                              out nIterator  : number ) : boolean;
Parameter | Description
sControlId | The control’s unique id.
nIterator | This parameter will be assigned a handle to the iterator.

Return value

  • true if successful

  • false otherwise

Example

transaction TMain
  var
    sConnID   : string;
    nIterator : number;
    sColumn   : string;
    nType     : number;
  begin
    // Connecting to SAP
    sConnID := SapGuiOpenConnection(" /SAP_CODEPAGE=1100 /FULLMENU 10.5.2.198 0 /3");

    SapGuiSetActiveConnection(sConnID);

    SapGuiSetActiveSession("ses[0]");

    // SAP
    SapGuiSetActiveWindow("wnd[0]", "SAP", SAPGUI_MATCH_Exact);

    SapGuiWindowAction(SAPGUI_WND_MAXIMIZE);

    // Logon to SAP System
    SapGuiIgnoreError(SAPENGINE_STATUSBAR_CHANGED, SEVERITY_SUCCESS);
    ThinkTime(2.8);
    SapGuiLogon("ddic", "minisap", "000", "");
    // Copyright
    ThinkTime(2.1);
    SapGuiSetActiveWindow("wnd[1]", "Copyright", SAPGUI_MATCH_Exact);

    SapGuiPressButton("tbar[0]/btn[0]");

    // SAP Easy Access
    ThinkTime(9.9);
    SapGuiSetActiveWindow("wnd[0]", "SAP Easy Access", SAPGUI_MATCH_Exact);
    SapGuiGridGetSelectedColumns("usr/tblRSDEMO02TC_COLS/txtDEMO_CPROP-GROUP4", nIterator);
    while SapGuiIteratorHasMore(nIterator) do
    SapGuiIteratorFetchNext(nIterator);
    SapGuiIteratorGetValue(nIterator, sColumn, nType);
    Print(sColumn);
  end;

    SapGuiIteratorRelease(nIterator);
  end TMain;
Parent topic: Parsing Functions


SapGuiGridIsCheckboxChecked Function

Action

This function determines whether grid cell's check box is checked.

Include file

SapGui.bdh

Syntax

SapGuiGridIsCheckboxChecked( in sControlId : string;
                             in nRow       : number;
                             in sCol       : string ) : boolean;
Parameter | Description
sControlId | The unique id of the control.
nRow | The row of the cell.
sCol | The column of the cell.

Return value

  • true if successful
  • false otherwise

Example

transaction TMain
  var
    bChecked : boolean;
    sConnID : string;
  begin
    // Connecting to SAP
    sConnID := SapGuiOpenConnection( " /SAP_CODEPAGE=1100 /FULLMENU 10.5.2.132 0 /3");

    SapGuiSetActiveConnection(sConnID);

    SapGuiSetActiveSession("ses[0]");

    // SAP
    SapGuiSetActiveWindow("wnd[0]", "SAP", SAPGUI_MATCH_ExactNoCase);

    SapGuiWindowAction(SAPGUI_WND_MAXIMIZE);

    SapGuiLogon("ddic", "*******", "000", "");
    bChecked := SapGuiGridIsCheckboxChecked("/usr/tab/grid23", 0, 0 );
  end TMain;
Parent topic: Parsing Functions


SapGuiObjectFree Function

Action

Frees the memory that was allocated for a handle.

Include file

SapGui.bdh

Syntax

SapGuiObjectFree( inout nObject : number );
Parameter | Description
nObject | The handle to be freed.

Example

transaction TMain
  var
    sConnID   : string;
    i         : number;
    nIterator : number;
    nType     : number;
    nObject   : number;
    bRet      : boolean;
    sStr1, sStr2 : string;
  begin

    // Connecting to SAP
    sConnID := SapGuiOpenConnection(" /SAP_CODEPAGE=1100 /FULLMENU 10.5.2.198 0 /3");
    SapGuiSetActiveConnection(sConnID);
    SapGuiSetActiveSession("ses[0]");

    // SAP
    SapGuiSetActiveWindow("wnd[0]", "SAP", SAPGUI_MATCH_Exact);
    SapGuiWindowAction(SAPGUI_WND_MAXIMIZE);

    // Logon to SAP System
    SapGuiIgnoreError(SAPENGINE_STATUSBAR_CHANGED, SEVERITY_SUCCESS);
    ThinkTime(2.8);
    SapGuiLogon("ddic", "minisap", "000", "");

    // Copyright
    ThinkTime(2.1);
    SapGuiSetActiveWindow("wnd[1]", "Copyright", SAPGUI_MATCH_Exact);
    SapGuiPressButton("tbar[0]/btn[0]");

    // SAP Easy Access
    ThinkTime(9.9);
    SapGuiSetActiveWindow("wnd[0]", "SAP Easy Access", SAPGUI_MATCH_Exact);
    SapGuiGetPropertyCollection("wnd[0]", "Children", nIterator);

    while (SapGuiIteratorHasMore(nIterator)) do
      SapGuiIteratorFetchNext(nIterator);
      SapGuiIteratorGetObject(nIterator, nObject);
      SapGuiObjectGetType(nObject, sStr1, sStr2);
      Print(sStr1 + ", " + sStr2);
      SapGuiObjectFree(nObject);
    end;

    SapGuiIteratorRelease(nIterator);
  end TMain;
Parent topic: Parsing Functions


SapGuiObjectGetBoolean Function

Action

This function reads the return value of a previous SapGuiObjectInvokeMethod call and provides it as type boolean.

Include file

SapGui.bdh

Syntax

SapGuiObjectGetBoolean( in  nObject : number,
                        out bParam  : boolean ) : boolean;
Parameter | Description
nObject | The handle to the object.
bParam | This parameter will be assigned the value.

Return value

  • true if successful
  • false otherwise

Example

transaction TMain
  var
    sConnID   : string;
    i         : number;
    nIterator : number;
    nObject   : number;
    bRet      : boolean;
    sStr1, sStr2 : string;
  begin

    // Connecting to SAP
    sConnID := SapGuiOpenConnection(" /SAP_CODEPAGE=1100 /FULLMENU 10.5.2.198 0 /3");
    SapGuiSetActiveConnection(sConnID);
    SapGuiSetActiveSession("ses[0]");

    // SAP
    SapGuiSetActiveWindow("wnd[0]", "SAP", SAPGUI_MATCH_Exact);
    SapGuiWindowAction(SAPGUI_WND_MAXIMIZE);

    // Logon to SAP System
    SapGuiIgnoreError(SAPENGINE_STATUSBAR_CHANGED, SEVERITY_SUCCESS);
    ThinkTime(2.8);
    SapGuiLogon("ddic", "minisap", "000", "");

    // Copyright
    ThinkTime(2.1);
    SapGuiSetActiveWindow("wnd[1]", "Copyright", SAPGUI_MATCH_Exact);
    SapGuiPressButton("tbar[0]/btn[0]");

    // SAP Easy Access
    ThinkTime(9.9);
    SapGuiSetActiveWindow("wnd[0]", "SAP Easy Access", SAPGUI_MATCH_Exact);
    SapGuiGetPropertyCollection("wnd[0]", "Children", nIterator);
    while (SapGuiIteratorHasMore(nIterator)) do
      SapGuiIteratorFetchNext(nIterator);
      SapGuiIteratorGetObject(nIterator, nObject);
      SapGuiObjectSetBoolean(nObject, true);
      SapGuiObjectInvokeMethod(nObject, "method");
      SapGuiObjectGetBoolean(nObject, bRet);
      Print(string(bRet));
      SapGuiObjectFree(nObject);
    end;

    SapGuiIteratorRelease(nIterator);
  end TMain;
Parent topic: Parsing Functions


SapGuiObjectGetCollection Function

Action

This function reads the return value of a previous function call and returns it as a collection iterator.

Include file

SapGui.bdh

Syntax

SapGuiObjectGetCollection( in  nObject   : number,
                           out nIterator : number ) : boolean;
Parameter | Description
nObject | The handle to the object.
nIterator | This parameter will be assigned the handle to a collection iterator.

Return value

  • true if successful
  • false otherwise

Example

transaction TMain
  var
    sConnID    : string;
    i          : number;
    nIterator, nIt2 : number;
    nType      : number;
    nObject    : number;
    bRet       : boolean;
    sStr1, sStr2 : string;
  begin
    // Connecting to SAP
    sConnID := SapGuiOpenConnection(" /SAP_CODEPAGE=1100 /FULLMENU 10.5.2.198 0 /3");
    SapGuiSetActiveConnection(sConnID);
    SapGuiSetActiveSession("ses[0]");

    // SAP
    SapGuiSetActiveWindow("wnd[0]", "SAP", SAPGUI_MATCH_Exact);
    SapGuiWindowAction(SAPGUI_WND_MAXIMIZE);

      // Logon to SAP System
    SapGuiIgnoreError(SAPENGINE_STATUSBAR_CHANGED, SEVERITY_SUCCESS);
    ThinkTime(2.8);
    SapGuiLogon("ddic", "minisap", "000", "");

    // Copyright
    ThinkTime(2.1);
    SapGuiSetActiveWindow("wnd[1]", "Copyright", SAPGUI_MATCH_Exact);
    SapGuiPressButton("tbar[0]/btn[0]");

    // SAP Easy Access
    ThinkTime(9.9);
    SapGuiSetActiveWindow("wnd[0]", "SAP Easy Access", SAPGUI_MATCH_Exact);
    SapGuiGetPropertyCollection("wnd[0]", "Children", nIterator);

    while (SapGuiIteratorHasMore(nIterator)) do
      SapGuiIteratorFetchNext(nIterator);
      SapGuiIteratorGetObject(nIterator, nObject);
      SapGuiObjectSetBoolean(nObject, true);
      SapGuiObjectInvokeMethod(nObject, "method");
      SapGuiObjectGetCollection(nObject, nIt2);

            // use nIt2 here
      SapGuiIteratorRelease(nIt2);
      SapGuiObjectFree(nObject);
    end;

    SapGuiIteratorRelease(nIterator);
  end TMain;
Parent topic: Parsing Functions


SapGuiObjectGetControlId Function

Action

This function provides the control id of a SAPGUI object.

Include file

SapGui.bdh

Syntax

SapGuiObjectGetControlId( in  nObject    : number,
                          out sControlId : string ) : boolean;
Parameter | Description
nObject | The handle to the object.
sControlId | This parameter will be assigned the control id.

Return value

  • true if successful
  • false otherwise

Example

transaction TMain
  var
    sConnID   : string;
    i         : number;
    nIterator : number;
    nType     : number;
    nObject   : number;
    bRet      : boolean;
    sStr1, sStr2 : string;
  begin

    // Connecting to SAP
    sConnID := SapGuiOpenConnection(" /SAP_CODEPAGE=1100 /FULLMENU 10.5.2.198 0 /3");
    SapGuiSetActiveConnection(sConnID);
    SapGuiSetActiveSession("ses[0]");

    // SAP
    SapGuiSetActiveWindow("wnd[0]", "SAP", SAPGUI_MATCH_Exact);
    SapGuiWindowAction(SAPGUI_WND_MAXIMIZE);

    // Logon to SAP System
    SapGuiIgnoreError(SAPENGINE_STATUSBAR_CHANGED, SEVERITY_SUCCESS);
    ThinkTime(2.8);
    SapGuiLogon("ddic", "minisap", "000", "");

    // Copyright
    ThinkTime(2.1);
    SapGuiSetActiveWindow("wnd[1]", "Copyright", SAPGUI_MATCH_Exact);
    SapGuiPressButton("tbar[0]/btn[0]");

    // SAP Easy Access
    ThinkTime(9.9);
    SapGuiSetActiveWindow("wnd[0]", "SAP Easy Access", SAPGUI_MATCH_Exact);
    SapGuiGetPropertyCollection("wnd[0]", "Children", nIterator);

    while (SapGuiIteratorHasMore(nIterator)) do
      SapGuiIteratorFetchNext(nIterator);
      SapGuiIteratorGetObject(nIterator, nObject);
      SapGuiObjectGetControlId(nObject, sStr1);
      SapGuiObjectFree(nObject);
      Print(sStr1);
    end;

    SapGuiIteratorRelease(nIterator);
  end TMain;
Parent topic: Parsing Functions


SapGuiObjectGetLong Function

Action

This function reads the return value of a previous call of the SapGuiObjectInvokeMethod function.

Include file

SapGui.bdh

Syntax

SapGuiObjectGetLong( in  nObject : number,
                     out nVal    : number ) : boolean;
Parameter | Description
nObject | The handle to the object.
nVal | This parameter will be assigned the return value.

Return value

  • true if successful
  • false otherwise

Example

transaction TMain
  var
    sConnID   : string;
    i         : number;
    nIterator : number;
    nType     : number;
    nObject   : number;
    bRet      : boolean;
  begin

    // Connecting to SAP
    sConnID := SapGuiOpenConnection(" /SAP_CODEPAGE=1100 /FULLMENU 10.5.2.198 0 /3");
    SapGuiSetActiveConnection(sConnID);
    SapGuiSetActiveSession("ses[0]");

    // SAP
    SapGuiSetActiveWindow("wnd[0]", "SAP", SAPGUI_MATCH_Exact);
    SapGuiWindowAction(SAPGUI_WND_MAXIMIZE);

    // Logon to SAP System
    SapGuiIgnoreError(SAPENGINE_STATUSBAR_CHANGED, SEVERITY_SUCCESS);
    ThinkTime(2.8);
    SapGuiLogon("ddic", "minisap", "000", "");

    // Copyright
    ThinkTime(2.1);
    SapGuiSetActiveWindow("wnd[1]", "Copyright", SAPGUI_MATCH_Exact);
    SapGuiPressButton("tbar[0]/btn[0]");

    // SAP Easy Access
    ThinkTime(9.9);
    SapGuiSetActiveWindow("wnd[0]", "SAP Easy Access", SAPGUI_MATCH_Exact);
    SapGuiGetPropertyCollection("wnd[0]", "Children", nIterator);

    while (SapGuiIteratorHasMore(nIterator)) do
      SapGuiIteratorFetchNext(nIterator);
      SapGuiIteratorGetObject(nIterator, nObject);
      SapGuiObjectSetBoolean(nObject, true);
      SapGuiObjectInvokeMethod(nObject, "method");
      SapGuiObjectGetLong(nObject, i);
      SapGuiObjectFree(nObject);
      Print(string(i));
    end;

    SapGuiIteratorRelease(nIterator);
  end TMain;
Parent topic: Parsing Functions


SapGuiObjectGetProperty Function

Action

This function reads an object’s property.

Include file

SapGui.bdh

Syntax

SapGuiObjectGetProperty( in  nObject   : number,
                         in  sProperty : string,
                         out sValue    : string ) : boolean;
Parameter | Description
nObject | The handle to the object.
sProperty | The property to be read.
sValue | The string value of the property.

Return value

  • true if successful
  • false otherwise

Example

transaction TMain
  var
    sConnID   : string;
    i         : number;
    nIterator : number;
    nType     : number;
    nObject   : number;
    bRet      : boolean;
    sStr1, sStr2 : string;
  begin

    // Connecting to SAP
    sConnID := SapGuiOpenConnection(" /SAP_CODEPAGE=1100 /FULLMENU 10.5.2.198 0 /3");
    SapGuiSetActiveConnection(sConnID);
    SapGuiSetActiveSession("ses[0]");

    // SAP
    SapGuiSetActiveWindow("wnd[0]", "SAP", SAPGUI_MATCH_Exact);
    SapGuiWindowAction(SAPGUI_WND_MAXIMIZE);

    // Logon to SAP System
    SapGuiIgnoreError(SAPENGINE_STATUSBAR_CHANGED, SEVERITY_SUCCESS);
    ThinkTime(2.8);
    SapGuiLogon("ddic", "minisap", "000", "");

    // Copyright
    ThinkTime(2.1);
    SapGuiSetActiveWindow("wnd[1]", "Copyright", SAPGUI_MATCH_Exact);
    SapGuiPressButton("tbar[0]/btn[0]");

    // SAP Easy Access
    ThinkTime(9.9);
    SapGuiSetActiveWindow("wnd[0]", "SAP Easy Access", SAPGUI_MATCH_Exact);
    SapGuiGetPropertyCollection("wnd[0]", "Children", nIterator);

    while (SapGuiIteratorHasMore(nIterator)) do
      SapGuiIteratorFetchNext(nIterator);
      SapGuiIteratorGetObject(nIterator, nObject);
      SapGuiObjectSetBoolean(nObject, true);
      SapGuiObjectInvokeMethod(nObject, "method");
      SapGuiObjectGetBoolean(nObject, bRet);
      SapGuiObjectGetProperty(nObject, "sProp", sStr2);
      SapGuiObjectFree(nObject);
      Print(sStr2);
    end;

    SapGuiIteratorRelease(nIterator);
  end TMain;
Parent topic: Parsing Functions


SapGuiObjectGetPropertyBoolean Function

Action

This function reads an object’s property.

Include file

SapGui.bdh

Syntax

SapGuiObjectGetPropertyBoolean( in  nObject   : number,
                                in  sProperty : string,
                                out bValue    : boolean ) : boolean;
Parameter | Description
nObject | The handle to the object.
sProperty | The property to be read.
bValue | This parameter will be assigned the value of the property.

Return value

  • true if successful
  • false otherwise

Example

transaction TMain
  var
    sConnID   : string;
    i         : number;
    nIterator : number;
    nType     : number;
    nObject   : number;
    bRet      : boolean;
    sStr1, sStr2 : string;
  begin

    // Connecting to SAP
    sConnID := SapGuiOpenConnection(" /SAP_CODEPAGE=1100 /FULLMENU 10.5.2.198 0 /3");
    SapGuiSetActiveConnection(sConnID);
    SapGuiSetActiveSession("ses[0]");

    // SAP
    SapGuiSetActiveWindow("wnd[0]", "SAP", SAPGUI_MATCH_Exact);
    SapGuiWindowAction(SAPGUI_WND_MAXIMIZE);

    // Logon to SAP System
    SapGuiIgnoreError(SAPENGINE_STATUSBAR_CHANGED, SEVERITY_SUCCESS);
    ThinkTime(2.8);
    SapGuiLogon("ddic", "minisap", "000", "");
    // Copyright
    ThinkTime(2.1);
    SapGuiSetActiveWindow("wnd[1]", "Copyright", SAPGUI_MATCH_Exact);
    SapGuiPressButton("tbar[0]/btn[0]");

    // SAP Easy Access
    ThinkTime(9.9);
    SapGuiSetActiveWindow("wnd[0]", "SAP Easy Access", SAPGUI_MATCH_Exact);
    SapGuiGetPropertyCollection("wnd[0]", "Children", nIterator);

    while (SapGuiIteratorHasMore(nIterator)) do
      SapGuiIteratorFetchNext(nIterator);
      SapGuiIteratorGetObject(nIterator, nObject);
      SapGuiObjectSetBoolean(nObject, true);
      SapGuiObjectInvokeMethod(nObject, "method");
      SapGuiObjectGetBoolean(nObject, bRet);
      SapGuiObjectGetPropertyBoolean(nObject, "boolProp", bRet);
      SapGuiObjectFree(nObject);
      Print(string(bRet));
    end;

    SapGuiIteratorRelease(nIterator);
  end TMain;
Parent topic: Parsing Functions


SapGuiObjectGetPropertyLong Function

Action

This function reads an object’s property.

Include file

SapGui.bdh

Syntax

SapGuiObjectGetPropertyLong( in  nObject   : number,
                             in  sProperty : string,
                             out lVal      : number ) : boolean;
Parameter | Description
nObject | The handle to the object.
sProperty | The property to be read.
lVal | This parameter will be assigned the property value.

Return value

  • true if successful
  • false otherwise

Example

transaction TMain
  var
    sConnID   : string;
    i         : number;
    nIterator : number;
    nType     : number;
    nObject   : number;
    bRet      : boolean;
    sStr1, sStr2 : string;
  begin
    // Connecting to SAP
    sConnID := SapGuiOpenConnection(" /SAP_CODEPAGE=1100 /FULLMENU 10.5.2.198 0 /3");
    SapGuiSetActiveConnection(sConnID);
    SapGuiSetActiveSession("ses[0]");

    // SAP
    SapGuiSetActiveWindow("wnd[0]", "SAP", SAPGUI_MATCH_Exact);
    SapGuiWindowAction(SAPGUI_WND_MAXIMIZE);

    // Logon to SAP System
    SapGuiIgnoreError(SAPENGINE_STATUSBAR_CHANGED, SEVERITY_SUCCESS);
    ThinkTime(2.8);
    SapGuiLogon("ddic", "minisap", "000", "");

    // Copyright
    ThinkTime(2.1);
    SapGuiSetActiveWindow("wnd[1]", "Copyright", SAPGUI_MATCH_Exact);
    SapGuiPressButton("tbar[0]/btn[0]");

    // SAP Easy Access
    ThinkTime(9.9);
    SapGuiSetActiveWindow("wnd[0]", "SAP Easy Access", SAPGUI_MATCH_Exact);
    SapGuiGetPropertyCollection("wnd[0]", "Children", nIterator);

    while (SapGuiIteratorHasMore(nIterator)) do
      SapGuiIteratorFetchNext(nIterator);
      SapGuiIteratorGetObject(nIterator, nObject);
      SapGuiObjectSetBoolean(nObject, true);
      SapGuiObjectInvokeMethod(nObject, "method");
      SapGuiObjectGetBoolean(nObject, bRet);
      SapGuiObjectGetPropertyLong(nObject, "method", i);
      SapGuiObjectFree(nObject);
      Print(string(i));
    end;

    SapGuiIteratorRelease(nIterator);
  end TMain;
Parent topic: Parsing Functions


SapGuiObjectGetObject Function

Action

This function reads the return value of a pior call to SapGuiObjectInvokeMethod.

Include file

SapGui.bdh

Syntax

SapGuiObjectGetObject( in  nObject    : number,
                       out nObjectOut : number ) : boolean;
Parameter | Description
nObject | The handle to the object
nObjectOut | The return value of the previous SapGuiObjectInvokeMethod call.

Return value

  • true if successful
  • false otherwise

Example

transaction TMain
  var
    sConnID   : string;
    i         : number;
    nIterator : number;
    nType     : number;
    nObject   : number;
    nObject2  : number;
    bRet      : boolean;
    sStr1, sStr2 : string;
  begin
    // Connecting to SAP
    sConnID := SapGuiOpenConnection(" /SAP_CODEPAGE=1100 /FULLMENU 10.5.2.198 0 /3");
    SapGuiSetActiveConnection(sConnID);
    SapGuiSetActiveSession("ses[0]");

    // SAP
    SapGuiSetActiveWindow("wnd[0]", "SAP", SAPGUI_MATCH_Exact);
    SapGuiWindowAction(SAPGUI_WND_MAXIMIZE);

    // Logon to SAP System
    SapGuiIgnoreError(SAPENGINE_STATUSBAR_CHANGED, SEVERITY_SUCCESS);
    ThinkTime(2.8);
    SapGuiLogon("ddic", "minisap", "000", "");

    // Copyright
    ThinkTime(2.1);
    SapGuiSetActiveWindow("wnd[1]", "Copyright", SAPGUI_MATCH_Exact);
    SapGuiPressButton("tbar[0]/btn[0]");

    // SAP Easy Access
    ThinkTime(9.9);
    SapGuiSetActiveWindow("wnd[0]", "SAP Easy Access", SAPGUI_MATCH_Exact);
    SapGuiGetPropertyCollection("wnd[0]", "Children", nIterator);

    while (SapGuiIteratorHasMore(nIterator)) do
      SapGuiIteratorFetchNext(nIterator);
      SapGuiIteratorGetObject(nIterator, nObject);
      SapGuiObjectSetBoolean(nObject, true);
      SapGuiObjectInvokeMethod(nObject, "method");
      SapGuiObjectGetObject(nObject, nObject2);

            // use nObject2 here
      SapGuiObjectFree(nObject2);
      SapGuiObjectFree(nObject);
    end;

    SapGuiIteratorRelease(nIterator);
  end TMain;
Parent topic: Parsing Functions


SapGuiObjectGetPropertyObject Function

Action

This functions reads an object’s property where the value to be read is an object.

Include file

SapGui.bdh

Syntax

SapGuiObjectGetPropertyObject( in  nObject   : number,
                               in  sProperty : string,
                               out nOutProp  : number ) : boolean;
Parameter | Description
nObject | The handle to the object
sProperty | The name of the property to be read.
nOutProp | This parameter will be assigned the handle to the object read.

Return value

  • true if successful
  • false otherwise

Example

transaction TMain
  var
    sConnID   : string;
    i         : number;
    nIterator : number;
    nType     : number;
    nObject   : number;
    nObject2  : number;
    bRet      : boolean;
    sStr1, sStr2 : string;
  begin

    // Connecting to SAP
    sConnID := SapGuiOpenConnection(" /SAP_CODEPAGE=1100 /FULLMENU 10.5.2.198 0 /3");
    SapGuiSetActiveConnection(sConnID);
    SapGuiSetActiveSession("ses[0]");

    // SAP
    SapGuiSetActiveWindow("wnd[0]", "SAP", SAPGUI_MATCH_Exact);
    SapGuiWindowAction(SAPGUI_WND_MAXIMIZE);

    // Logon to SAP System
    SapGuiIgnoreError(SAPENGINE_STATUSBAR_CHANGED, SEVERITY_SUCCESS);
    ThinkTime(2.8);
    SapGuiLogon("ddic", "minisap", "000", "");

    // Copyright
    ThinkTime(2.1);
    SapGuiSetActiveWindow("wnd[1]", "Copyright", SAPGUI_MATCH_Exact);
    SapGuiPressButton("tbar[0]/btn[0]");

    // SAP Easy Access
    ThinkTime(9.9);
    SapGuiSetActiveWindow("wnd[0]", "SAP Easy Access", SAPGUI_MATCH_Exact);
    SapGuiGetPropertyCollection("wnd[0]", "Children", nIterator);

    while (SapGuiIteratorHasMore(nIterator)) do
      SapGuiIteratorFetchNext(nIterator);
      SapGuiIteratorGetObject(nIterator, nObject);
      SapGuiObjectSetBoolean(nObject, true);
      SapGuiObjectInvokeMethod(nObject, "method");
      SapGuiObjectGetBoolean(nObject, bRet);
      SapGuiObjectGetPropertyObject(nObject, "sProp", nObject2);

      // use nObject2 here
      SapGuiObjectFree(nObject2);
      SapGuiObjectFree(nObject);
    end;

    SapGuiIteratorRelease(nIterator);
  end TMain;
Parent topic: Parsing Functions


SapGuiObjectGetString Function

Action

Reads the return value of a previous SapGuiObjectInvokeMethod call and provides it as a string.

Include file

SapGui.bdh

Syntax

SapGuiObjectGetString( in  nObject : number,
                       out sRet    : string ) : boolean;
Parameter | Description
nObject | The handle to the object.
sRet | This parameter will be assigned the return value.

Return value

  • true if successful
  • false otherwise

Example

transaction TMain
  var
    sConnID   : string;
    i         : number;
    nIterator : number;
    nType     : number;
    nObject   : number;
    bRet      : boolean;
    sStr1, sStr2 : string;
  begin

    // Connecting to SAP
    sConnID := SapGuiOpenConnection(" /SAP_CODEPAGE=1100 /FULLMENU 10.5.2.198 0 /3");
    SapGuiSetActiveConnection(sConnID);
    SapGuiSetActiveSession("ses[0]");

    // SAP
    SapGuiSetActiveWindow("wnd[0]", "SAP", SAPGUI_MATCH_Exact);
    SapGuiWindowAction(SAPGUI_WND_MAXIMIZE);

    // Logon to SAP System
    SapGuiIgnoreError(SAPENGINE_STATUSBAR_CHANGED, SEVERITY_SUCCESS);
    ThinkTime(2.8);
    SapGuiLogon("ddic", "minisap", "000", "");

    // Copyright
    ThinkTime(2.1);
    SapGuiSetActiveWindow("wnd[1]", "Copyright", SAPGUI_MATCH_Exact);
    SapGuiPressButton("tbar[0]/btn[0]");

    // SAP Easy Access
    ThinkTime(9.9);
    SapGuiSetActiveWindow("wnd[0]", "SAP Easy Access", SAPGUI_MATCH_Exact);
    SapGuiGetPropertyCollection("wnd[0]", "Children", nIterator);

    while (SapGuiIteratorHasMore(nIterator)) do
      SapGuiIteratorFetchNext(nIterator);
      SapGuiIteratorGetObject(nIterator, nObject);
      SapGuiObjectSetBoolean(nObject, true);
      SapGuiObjectInvokeMethod(nObject, "method");
      SapGuiObjectGetString(nObject, sValue);
      SapGuiObjectFree(nObject);
      Print(sValue);
   end;

  SapGuiIteratorRelease(nIterator);
end TMain;
Parent topic: Parsing Functions


SapGuiObjectGetType Function

Action

This function returns the “type” and the “subtype” property of a SAPGUI object.

Include file

SapGui.bdh

Syntax

SapGuiObjectGetType( in  nObject  : number,
                     out sType    : string,
                     out sSubType : string ) : boolean;
Parameter | Description
nObject | The handle to the object.
sType | The parameter will be assigned the type property.
sSubType | The parameter will be assigned the subtype property.

Return value

  • true if successful
  • false otherwise

Example

transaction TMain
  var
    sConnID   : string;
    i         : number;
    nIterator : number;
    nType     : number;
    nObject   : number;
    bRet      : boolean;
    sStr1, sStr2 : string;
  begin

    // Connecting to SAP
    sConnID := SapGuiOpenConnection(" /SAP_CODEPAGE=1100 /FULLMENU 10.5.2.198 0 /3");
    SapGuiSetActiveConnection(sConnID);
    SapGuiSetActiveSession("ses[0]");

    // SAP
    SapGuiSetActiveWindow("wnd[0]", "SAP", SAPGUI_MATCH_Exact);
    SapGuiWindowAction(SAPGUI_WND_MAXIMIZE);

    // Logon to SAP System
    SapGuiIgnoreError(SAPENGINE_STATUSBAR_CHANGED, SEVERITY_SUCCESS);
    ThinkTime(2.8);
    SapGuiLogon("ddic", "minisap", "000", "");

    // Copyright
    ThinkTime(2.1);
    SapGuiSetActiveWindow("wnd[1]", "Copyright", SAPGUI_MATCH_Exact);
    SapGuiPressButton("tbar[0]/btn[0]");

    // SAP Easy Access
    ThinkTime(9.9);
    SapGuiSetActiveWindow("wnd[0]", "SAP Easy Access", SAPGUI_MATCH_Exact);
    SapGuiGetPropertyCollection("wnd[0]", "Children", nIterator);

    while (SapGuiIteratorHasMore(nIterator)) do
      SapGuiIteratorFetchNext(nIterator);
      SapGuiIteratorGetObject(nIterator, nObject);
      SapGuiObjectSetBoolean(nObject, true);
      SapGuiObjectInvokeMethod(nObject, "method");
      SapGuiObjectGetBoolean(nObject, bRet);
      SapGuiObjectGetType(nObject, sStr1, sStr2);
      SapGuiObjectFree(nObject);
      Print(sStr1 + " " + sStr2);
    end;

  SapGuiIteratorRelease(nIterator);
end TMain;
Parent topic: Parsing Functions


SapGuiObjectSetBoolean Function

Action

This function pushes a parameter of type boolean onto the parameter stack for the next SapGuiObjectInvokeMethod call.

Include file

SapGui.bdh

Syntax

SapGuiObjectSetBoolean( in nObject : number,
                        in bParam  : boolean ) : boolean;
Parameter | Description
nObject | The handle to the object.
bParam | The value to be pushed onto the parameter stack.

Return value

  • true if successful
  • false otherwise

Example

transaction TMain
  var
    sConnID   : string;
    i         : number;
    nIterator : number;
    nType     : number;
    nObject   : number;
    bRet      : boolean;
    sStr1, sStr2 : string;
  begin

    // Connecting to SAP
    sConnID := SapGuiOpenConnection(" /SAP_CODEPAGE=1100 /FULLMENU 10.5.2.198 0 /3");
    SapGuiSetActiveConnection(sConnID);
    SapGuiSetActiveSession("ses[0]");

    // SAP
    SapGuiSetActiveWindow("wnd[0]", "SAP", SAPGUI_MATCH_Exact);
    SapGuiWindowAction(SAPGUI_WND_MAXIMIZE);

    // Logon to SAP System
    SapGuiIgnoreError(SAPENGINE_STATUSBAR_CHANGED, SEVERITY_SUCCESS);
    ThinkTime(2.8);
    SapGuiLogon("ddic", "minisap", "000", "");
    // Copyright
    ThinkTime(2.1);
    SapGuiSetActiveWindow("wnd[1]", "Copyright", SAPGUI_MATCH_Exact);
    SapGuiPressButton("tbar[0]/btn[0]");

    // SAP Easy Access
    ThinkTime(9.9);
    SapGuiSetActiveWindow("wnd[0]", "SAP Easy Access", SAPGUI_MATCH_Exact);

    SapGuiGetPropertyCollection("wnd[0]", "Children", nIterator);

    while (SapGuiIteratorHasMore(nIterator)) do
      SapGuiIteratorFetchNext(nIterator);
      SapGuiIteratorGetObject(nIterator, nObject);
      SapGuiObjectSetBoolean(nObject, true);
      SapGuiObjectInvokeMethod(nObject, "method");
      SapGuiObjectGetBoolean(nObject, bRet);
      SapGuiObjectFree(nObject);
    end;

    SapGuiIteratorRelease(nIterator);
  end TMain;
Parent topic: Parsing Functions


SapGuiObjectSetLong Function

Action

Pushes a parameter of type long onto the parameter stack for the next SapGuiObjectInvokeMethod function call.

Include file

SapGui.bdh

Syntax

SapGuiObjectSetLong( in nObject : number,
                     in nVal    : number ) : boolean;
Parameter | Description
nObject | The handle to the object.
nVal | The parameter to be added to the parameter stack for the next call of the function SapGuiObjectInvokeMethod.

Return value

  • true if successful
  • false otherwise

Example

transaction TMain
  var
    sConnID   : string;
    i         : number;
    nIterator : number;
    nType     : number;
    nObject   : number;
    bRet      : boolean;
    sStr1, sStr2 : string;
  begin
    // Connecting to SAP
    sConnID := SapGuiOpenConnection(" /SAP_CODEPAGE=1100 /FULLMENU 10.5.2.198 0 /3");
    SapGuiSetActiveConnection(sConnID);
    SapGuiSetActiveSession("ses[0]");

    // SAP
    SapGuiSetActiveWindow("wnd[0]", "SAP", SAPGUI_MATCH_Exact);
    SapGuiWindowAction(SAPGUI_WND_MAXIMIZE);

    // Logon to SAP System
    SapGuiIgnoreError(SAPENGINE_STATUSBAR_CHANGED, SEVERITY_SUCCESS);
    ThinkTime(2.8);
    SapGuiLogon("ddic", "minisap", "000", "");

    // Copyright
    ThinkTime(2.1);
    SapGuiSetActiveWindow("wnd[1]", "Copyright", SAPGUI_MATCH_Exact);
    SapGuiPressButton("tbar[0]/btn[0]");

    // SAP Easy Access
    ThinkTime(9.9);
    SapGuiSetActiveWindow("wnd[0]", "SAP Easy Access", SAPGUI_MATCH_Exact);
    SapGuiGetPropertyCollection("wnd[0]", "Children", nIterator);

    while (SapGuiIteratorHasMore(nIterator)) do
      SapGuiIteratorFetchNext(nIterator);
      SapGuiIteratorGetObject(nIterator, nObject);
      SapGuiObjectSetLong(nObject, 56);
      SapGuiObjectInvokeMethod(nObject, "method");
      SapGuiObjectGetBoolean(nObject, bRet);
      SapGuiObjectFree(nObject);
    end;

    SapGuiIteratorRelease(nIterator);
  end TMain;
Parent topic: Parsing Functions


SapGuiObjectSetObject Function

Action

This function pushes an object onto the parameter stack for the next method invocation with SapGuiObjectInvokeMethod.

Include file

SapGui.bdh

Syntax

SapGuiObjectSetObject( in nObject   : number,
                       in nParamObj : number ) : boolean;
Parameter | Description
nObject | The handle to the object.
nParamObj | Handle to the object to be pushed onto the parameter stack.

Return value

  • true if successful
  • false otherwise

Example

transaction TMain
  var
    sConnID   : string;
    i         : number;
    nIterator : number;
    nType     : number;
    nObject   : number;
    nObjectParam : number;
    bRet      : boolean;
    sStr1, sStr2 : string;
  begin
    // Connecting to SAP
    sConnID := SapGuiOpenConnection(" /SAP_CODEPAGE=1100 /FULLMENU 10.5.2.198 0 /3");
    SapGuiSetActiveConnection(sConnID);
    SapGuiSetActiveSession("ses[0]");

    // SAP
    SapGuiSetActiveWindow("wnd[0]", "SAP", SAPGUI_MATCH_Exact);
    SapGuiWindowAction(SAPGUI_WND_MAXIMIZE);

    // Logon to SAP System
    SapGuiIgnoreError(SAPENGINE_STATUSBAR_CHANGED, SEVERITY_SUCCESS);
    ThinkTime(2.8);
    SapGuiLogon("ddic", "minisap", "000", "");

    // Copyright
    ThinkTime(2.1);
    SapGuiSetActiveWindow("wnd[1]", "Copyright", SAPGUI_MATCH_Exact);
    SapGuiPressButton("tbar[0]/btn[0]");

    // SAP Easy Access
    ThinkTime(9.9);
    SapGuiSetActiveWindow("wnd[0]", "SAP Easy Access", SAPGUI_MATCH_Exact);
    SapGuiGetPropertyCollection("wnd[0]", "Children", nIterator);

    while (SapGuiIteratorHasMore(nIterator)) do
      SapGuiIteratorFetchNext(nIterator);
      SapGuiIteratorGetObject(nIterator, nObject);
      SapGuiGetHandleFromControlId("wnd[0]", nObjectParam);
      SapGuiObjectSetObject(nObject, nObjectParam);
      SapGuiObjectInvokeMethod(nObject, "method");
      SapGuiObjectGetBoolean(nObject, bRet);
      SapGuiObjectFree(nObject);
    end;

    SapGuiIteratorRelease(nIterator);
  end TMain;
Parent topic: Parsing Functions


SapGuiObjectSetProperty Function

Action

This functions sets an object’s property.

Include file

SapGui.bdh

Syntax

SapGuiObjectSetProperty( in nObject   : number,
                         in sProperty : string,
                         in uValue    : union ) : boolean;
Parameter | Description
nObject | The objects handle.
sProperty | The name of the property to be set.
uValue | The value to be set. Only simple types are accepted. To set an object property use the function SapGuiObjectSetPropertyObject.

Return value

  • true if successful
  • false otherwise

Example

transaction TMain
  var
    sConnID   : string;
    i         : number;
    nIterator : number;
    nType     : number;
    nObject   : number;
    bRet      : boolean;
    sStr1, sStr2 : string;
  begin
    // Connecting to SAP
    sConnID := SapGuiOpenConnection(" /SAP_CODEPAGE=1100 /FULLMENU 10.5.2.198 0 /3");
    SapGuiSetActiveConnection(sConnID);
    SapGuiSetActiveSession("ses[0]");

    // SAP
    SapGuiSetActiveWindow("wnd[0]", "SAP", SAPGUI_MATCH_Exact);
    SapGuiWindowAction(SAPGUI_WND_MAXIMIZE);

    // Logon to SAP System
    SapGuiIgnoreError(SAPENGINE_STATUSBAR_CHANGED, SEVERITY_SUCCESS);
    ThinkTime(2.8);
    SapGuiLogon("ddic", "minisap", "000", "");
    // Copyright
    ThinkTime(2.1);
    SapGuiSetActiveWindow("wnd[1]", "Copyright", SAPGUI_MATCH_Exact);
    SapGuiPressButton("tbar[0]/btn[0]");

    // SAP Easy Access
    ThinkTime(9.9);
    SapGuiSetActiveWindow("wnd[0]", "SAP Easy Access", SAPGUI_MATCH_Exact);
    SapGuiGetHandleFromControlId("wnd[0]", nObject);
    SapGuiObjectSetProperty(nObject, "ButtonbarVisible", 0);
  end TMain;
Parent topic: Parsing Functions


SapGuiObjectSetPropertyObject Function

Action

This function sets an object’s property which is of type object.

Include file

SapGui.bdh

Syntax

SapGuiObjectSetPropertyObject( in nObject      : number,
                               in sProperty    : string,
                               in nParamObject : object ) : boolean;
Parameter | Description
nObject | The handle to the object.
sProperty | The name of the property to be set.
nParamObject | The handle of the object to be set.

Return value

  • true if successful
  • false otherwise

Example

transaction TMain
  var
    sConnID   : string;
    i : number;
    nIterator : number;
    nType     : number;
    nObject   : number;
    nObjectParam : number;
    bRet      : boolean;
    sStr1, sStr2 : string;
  begin
    // Connecting to SAP
    sConnID := SapGuiOpenConnection(" /SAP_CODEPAGE=1100 /FULLMENU 10.5.2.198 0 /3");
    SapGuiSetActiveConnection(sConnID);
    SapGuiSetActiveSession("ses[0]");

    // SAP
    SapGuiSetActiveWindow("wnd[0]", "SAP", SAPGUI_MATCH_Exact);
    SapGuiWindowAction(SAPGUI_WND_MAXIMIZE);

    // Logon to SAP System
    SapGuiIgnoreError(SAPENGINE_STATUSBAR_CHANGED, SEVERITY_SUCCESS);
    ThinkTime(2.8);
    SapGuiLogon("ddic", "minisap", "000", "");

    // Copyright
    ThinkTime(2.1);
    SapGuiSetActiveWindow("wnd[1]", "Copyright", SAPGUI_MATCH_Exact);
    SapGuiPressButton("tbar[0]/btn[0]");

    // SAP Easy Access
    ThinkTime(9.9);
    SapGuiSetActiveWindow("wnd[0]", "SAP Easy Access", SAPGUI_MATCH_Exact);
    SapGuiGetPropertyCollection("wnd[0]", "Children", nIterator);

    while (SapGuiIteratorHasMore(nIterator)) do
      SapGuiIteratorFetchNext(nIterator);
      SapGuiIteratorGetObject(nIterator, nObject);
      SapGuiGetHandleFromControlId("wnd[0]", nObjectParam);
      SapGuiObjectSetPropertyObject(nObject, "sProp", nObjectParam);
      SapGuiObjectFree(nObject);
    end;

    SapGuiIteratorRelease(nIterator);
  end TMain;
Parent topic: Parsing Functions


SapGuiObjectSetString Function

Action

This function pushes a variable of type string onto the parameter stack for the next call of SapGuiObjectInvokeMethod call.

Include file

SapGui.bdh

Syntax

SapGuiObjectSetString( in nObject : number,
                       in sParam  : string ) : boolean;
Parameter | Description
nObject | The handle to the object.
sParam | The parameter to be pushed onto the parameter stack.

Return value

  • true if successful
  • false otherwise

Example

transaction TMain
  var
      sConnID   : string;
      i         : number;
    nIterator : number;
    nType     : number;
    nObject   : number;
    bRet      : boolean;
    sStr1, sStr2 : string;
  begin

    // Connecting to SAP
    sConnID := SapGuiOpenConnection(" /SAP_CODEPAGE=1100 /FULLMENU 10.5.2.198 0 /3");
    SapGuiSetActiveConnection(sConnID);
    SapGuiSetActiveSession("ses[0]");

    // SAP
    SapGuiSetActiveWindow("wnd[0]", "SAP", SAPGUI_MATCH_Exact);
    SapGuiWindowAction(SAPGUI_WND_MAXIMIZE);

    // Logon to SAP System
    SapGuiIgnoreError(SAPENGINE_STATUSBAR_CHANGED, SEVERITY_SUCCESS);
    ThinkTime(2.8);
    SapGuiLogon("ddic", "minisap", "000", "");

    // Copyright
    ThinkTime(2.1);
    SapGuiSetActiveWindow("wnd[1]", "Copyright", SAPGUI_MATCH_Exact);
    SapGuiPressButton("tbar[0]/btn[0]");

    // SAP Easy Access
    ThinkTime(9.9);
    SapGuiSetActiveWindow("wnd[0]", "SAP Easy Access", SAPGUI_MATCH_Exact);

    SapGuiGetPropertyCollection("wnd[0]", "Children", nIterator);

    while (SapGuiIteratorHasMore(nIterator)) do
      SapGuiIteratorFetchNext(nIterator);
      SapGuiIteratorGetObject(nIterator, nObject);
      SapGuiObjectSetString(nObject, "sParam");
      SapGuiObjectInvokeMethod(nObject, "method");
      SapGuiObjectGetBoolean(nObject, bRet);
      SapGuiObjectFree(nObject);
    end;

    SapGuiIteratorRelease(nIterator);
  end TMain;
Parent topic: Parsing Functions


SapGuiIteratorFetchNext Function

Action

This function moves the iterator to the next position.

Include file

SapGui.bdh

Syntax

SapGuiIteratorFetchNext( in nIterator : number ) : boolean;
Parameter | Description
nIterator | The handle to the iterator.

Return value

  • true if successful
  • false otherwise

Example

transaction TMain
  var
    sConnID   : string;
    sKey      : string;
    sValue    : string;
    nIterator : number;
    nObject   : number;
  begin

    // Connecting to SAP
    sConnID := SapGuiOpenConnection(" /SAP_CODEPAGE=1100 /FULLMENU 10.5.2.198 0 /3");
    SapGuiSetActiveConnection(sConnID);
    SapGuiSetActiveSession("ses[0]");

    // SAP
    SapGuiSetActiveWindow("wnd[0]", "SAP", SAPGUI_MATCH_Exact);
    SapGuiWindowAction(SAPGUI_WND_MAXIMIZE);

    // Logon to SAP System
    SapGuiIgnoreError(SAPENGINE_STATUSBAR_CHANGED, SEVERITY_SUCCESS);
    ThinkTime(2.8);
    SapGuiLogon("ddic", "minisap", "000", "");

    // Copyright
    ThinkTime(2.1);
    SapGuiSetActiveWindow("wnd[1]", "Copyright", SAPGUI_MATCH_Exact);
    SapGuiPressButton("tbar[0]/btn[0]");

    // SAP Easy Access
    ThinkTime(9.9);
    SapGuiSetActiveWindow("wnd[0]", "SAP Easy Access", SAPGUI_MATCH_Exact);
    SapGuiGetComboboxEntries("usr/tblRSDEMO02TC_COLS/txtDEMO_CPROP-GROUP4", nIterator);
    while SapGuiIteratorHasMore(nIterator) do
      SapGuiIteratorFetchNext(nIterator);
      SapGuiIteratorGetObject(nIterator, nObject);
      SapGuiObjectGetProperty(nObject,"Key", sKey);
      SapGuiObjectGetProperty(nObject, "Value", sValue);
      SapGuiObjectFree(nObject);
    end;
    SapGuiIteratorRelease(nIterator);
  end TMain;
Parent topic: Parsing Functions
Related reference
SapGuiIteratorGetCount Function
SapGuiIteratorGetObjectAt Function
SapGuiIteratorGetObject Function
SapGuiIteratorGetValueAt Function
SapGuiIteratorGetValue Function
SapGuiIteratorHasMore Function
SapGuiIteratorRelease Function


SapGuiObjectInvokeMethod Function

Action

This functions invokes a method for the passed object. The parameter list has to be specified with prior calls of SapGuiObjectSet functions.

The return value of this function call can be fetched by calling one of the SapGuiObjectGet functions.

Include file

SapGui.bdh

Syntax

SapGuiObjectInvokeMethod( in nObject     : number,
                          in sMethodName : string ) : boolean;
Parameter | Description
nObject | The handle to the object.
sMethodName | The method to be called.

Return value

  • true if successful
  • false otherwise

Example

transaction TMain
  var
    sVal      : string;
    sConnID   : string;
    i         : number;
    nIterator : number;
    nType     : number;
    nObject   : number;
    bRet      : boolean;
  begin

    // Connecting to SAP
    sConnID := SapGuiOpenConnection(" /SAP_CODEPAGE=1100 /FULLMENU 10.5.2.198 0 /3");
    SapGuiSetActiveConnection(sConnID);
    SapGuiSetActiveSession("ses[0]");

    // SAP
    SapGuiSetActiveWindow("wnd[0]", "SAP", SAPGUI_MATCH_Exact);
    SapGuiWindowAction(SAPGUI_WND_MAXIMIZE);

    // Logon to SAP System
    SapGuiIgnoreError(SAPENGINE_STATUSBAR_CHANGED, SEVERITY_SUCCESS);
    ThinkTime(2.8);
    SapGuiLogon("ddic", "minisap", "000", "");

    // Copyright
    ThinkTime(2.1);
    SapGuiSetActiveWindow("wnd[1]", "Copyright", SAPGUI_MATCH_Exact);
    SapGuiPressButton("tbar[0]/btn[0]");

    // SAP Easy Access
    ThinkTime(9.9);
    SapGuiSetActiveWindow("wnd[0]", "SAP Easy Access", SAPGUI_MATCH_Exact);
    SapGuiGetPropertyCollection("wnd[0]", "Children", nIterator);

    while (SapGuiIteratorHasMore(nIterator)) do
      SapGuiIteratorFetchNext(nIterator);
      SapGuiIteratorGetObject(nIterator, nObject);
      SapGuiObjectSetBoolean(nObject, true);
      SapGuiObjectInvokeMethod(nObject, "method");
      SapGuiObjectGetBoolean(nObject, bRet);
      SapGuiObjectFree(nObject);
      Print(string(bRet));
    end;

    SapGuiIteratorRelease(nIterator);
  end TMain;
Parent topic: Parsing Functions
Related reference
SapGuiObjectGetBoolean Function
SapGuiObjectGetCollection Function
SapGuiObjectGetControlId Function
SapGuiObjectGetLong Function
SapGuiObjectGetObject Function
SapGuiObjectGetPropertyBoolean Function
SapGuiObjectGetProperty Function
SapGuiObjectGetPropertyLong Function
SapGuiObjectGetPropertyObject Function
SapGuiObjectGetString Function
SapGuiObjectGetType Function
SapGuiObjectSetBoolean Function
SapGuiObjectSetLong Function
SapGuiObjectSetObject Function
SapGuiObjectSetProperty Function
SapGuiObjectSetPropertyObject Function
SapGuiObjectSetString Function


SapGuiIteratorHasMore Function

Action

This function determines whether there are more entries in a collection. The handle has to be closed with SapGuiIteratorRelease, if it is no longer needed.

Include file

SapGui.bdh

Syntax

SapGuiIteratorHasMore( in nIterator : number ) : boolean;
Parameter | Description
nIterator | The handle to the iterator.

Return value

  • true if successful and more items are to be fetched.
  • false otherwise.

Example

transaction TMain
  var
    sConnID   : string;
    sKey      : string;
    sValue    : string;
    nIterator : number;
    nObject   : number;
  begin

    // Connecting to SAP
    sConnID := SapGuiOpenConnection(" /SAP_CODEPAGE=1100 /FULLMENU 10.5.2.198 0 /3");
    SapGuiSetActiveConnection(sConnID);
    SapGuiSetActiveSession("ses[0]");

    // SAP
    SapGuiSetActiveWindow("wnd[0]", "SAP", SAPGUI_MATCH_Exact);
    SapGuiWindowAction(SAPGUI_WND_MAXIMIZE);

    // Logon to SAP System
    SapGuiIgnoreError(SAPENGINE_STATUSBAR_CHANGED, SEVERITY_SUCCESS);
    ThinkTime(2.8);
    SapGuiLogon("ddic", "minisap", "000", "");

    // Copyright
    ThinkTime(2.1);
    SapGuiSetActiveWindow("wnd[1]", "Copyright", SAPGUI_MATCH_Exact);
    SapGuiPressButton("tbar[0]/btn[0]");

    // SAP Easy Access
    ThinkTime(9.9);
    SapGuiSetActiveWindow("wnd[0]", "SAP Easy Access", SAPGUI_MATCH_Exact);

    SapGuiGetComboboxEntries("usr/tblRSDEMO02TC_COLS/txtDEMO_CPROP-GROUP4", nIterator);
    whileSapGuiIteratorHasMore(nIterator) do
      SapGuiIteratorFetchNext(nIterator);
      SapGuiIteratorGetObject(nIterator, nObject);
      SapGuiObjectGetProperty(nObject,"Key", sKey);
      SapGuiObjectGetProperty(nObject, "Value", sValue);
      SapGuiObjectFree(nObject);
    end;
    SapGuiIteratorRelease(nIterator);
  end TMain;
Parent topic: Parsing Functions
Related reference
SapGuiIteratorFetchNext Function
SapGuiIteratorGetCount Function
SapGuiIteratorGetObjectAt Function
SapGuiIteratorGetObject Function
SapGuiIteratorGetValueAt Function
SapGuiIteratorGetValue Function
SapGuiIteratorRelease Function


SapGuiIteratorRelease Function

Action

This function frees the resources that were allocated for an iterator. This function has to be called for an iterator if the iterator is no longer needed.

Include file

SapGui.bdh

Syntax

SapGuiIteratorRelease( in nIterator : number );
Parameter | Description
nIterator | The handle to the iterator.

Example

transaction TMain
  var
    sConnID   : string;
    sKey      : string;
    sValue    : string;
    nIterator : number;
    nObject   : number;
  begin

    // Connecting to SAP
    sConnID := SapGuiOpenConnection(" /SAP_CODEPAGE=1100 /FULLMENU 10.5.2.198 0 /3");
    SapGuiSetActiveConnection(sConnID);
    SapGuiSetActiveSession("ses[0]");

    // SAP
    SapGuiSetActiveWindow("wnd[0]", "SAP", SAPGUI_MATCH_Exact);
    SapGuiWindowAction(SAPGUI_WND_MAXIMIZE);

    // Logon to SAP System
    SapGuiIgnoreError(SAPENGINE_STATUSBAR_CHANGED, SEVERITY_SUCCESS);
    ThinkTime(2.8);
    SapGuiLogon("ddic", "minisap", "000", "");

    // Copyright
    ThinkTime(2.1);
    SapGuiSetActiveWindow("wnd[1]", "Copyright", SAPGUI_MATCH_Exact);
    SapGuiPressButton("tbar[0]/btn[0]");

    // SAP Easy Access
    ThinkTime(9.9);
    SapGuiSetActiveWindow("wnd[0]", "SAP Easy Access", SAPGUI_MATCH_Exact);
    SapGuiGetComboboxEntries("usr/tblRSDEMO02TC_COLS/txtDEMO_CPROP-GROUP4", nIterator);
    while SapGuiIteratorHasMore(nIterator) do
      SapGuiIteratorFetchNext(nIterator);
      SapGuiIteratorGetObject(nIterator, nObject);
      SapGuiObjectGetProperty(nObject,"Key", sKey);
      SapGuiObjectGetProperty(nObject, "Value", sValue);
      SapGuiObjectFree(nObject);
    end;

    SapGuiIteratorRelease(nIterator);
  end TMain;
Parent topic: Parsing Functions
Related reference
SapGuiIteratorFetchNext Function
SapGuiIteratorGetCount Function
SapGuiIteratorGetObjectAt Function
SapGuiIteratorGetObject Function
SapGuiIteratorGetValueAt Function
SapGuiIteratorGetValue Function
SapGuiIteratorHasMore Function


SapGuiIteratorGetCount Function

Action

This function determines the number of elements in a collection.

Include file

SapGui.bdh

Syntax

SapGuiIteratorGetCount( in nIterator : number ) : number;
Parameter | Description
nIterator | The handle to the collection iterator.

Return value

  • the number of elements

Example

transaction TMain
  var
    sConnID   : string;
    i         : number;
    nIterator : number;
    nType     : number;
    nObject   : number;
    bRet      : boolean;
    sStr1, sStr2 : string;
  begin

    // Connecting to SAP
    sConnID := SapGuiOpenConnection(" /SAP_CODEPAGE=1100 /FULLMENU 10.5.2.198 0 /3");
    SapGuiSetActiveConnection(sConnID);
    SapGuiSetActiveSession("ses[0]");

    // SAP
    SapGuiSetActiveWindow("wnd[0]", "SAP", SAPGUI_MATCH_Exact);
    SapGuiWindowAction(SAPGUI_WND_MAXIMIZE);

    // Logon to SAP System
    SapGuiIgnoreError(SAPENGINE_STATUSBAR_CHANGED, SEVERITY_SUCCESS);
    ThinkTime(2.8);
    SapGuiLogon("ddic", "minisap", "000", "");

    // Copyright
    ThinkTime(2.1);
    SapGuiSetActiveWindow("wnd[1]", "Copyright", SAPGUI_MATCH_Exact);
    SapGuiPressButton("tbar[0]/btn[0]");

    // SAP Easy Access
    ThinkTime(9.9);
    SapGuiSetActiveWindow("wnd[0]", "SAP Easy Access", SAPGUI_MATCH_Exact);
    SapGuiGetPropertyCollection("wnd[0]", "Children", nIterator);
    i := SapGuiIteratorGetCount(nIterator);

       Print(string(i));

    SapGuiIteratorRelease(nIterator);
  end TMain;
Parent topic: Parsing Functions
Related reference
SapGuiIteratorFetchNext Function
SapGuiIteratorGetObjectAt Function
SapGuiIteratorGetObject Function
SapGuiIteratorGetValueAt Function
SapGuiIteratorGetValue Function
SapGuiIteratorHasMore Function
SapGuiIteratorRelease Function


SapGuiIteratorGetObject Function

Action

This function provides the value of the iterator’s current position. This function will provide a handle to the object at the current position, unless the object at the current position is of a simple type such as long or boolean or string. Then the function SapGuiIteratorGetValue has to be used. The returned object handle has to be freed by calling SapGuiObjectFree when no longer needed.

Include file

SapGui.bdh

Syntax

SapGuiIteratorGetObject( in  nIterator : number,
                         out nObject   : number ) : boolean;
Parameter | Description
nIterator | The handle to the collection iterator.
nObject | This parameter will be assigned the handle to the object.

Return value

  • true if successful
  • false otherwise

Example

transaction TMain
  var
    sConnID   : string;
    sKey      : string;
    sValue    : string;
    nIterator : number;
    nObject   : number;
    nType     : number;
  begin

    // Connecting to SAP
    sConnID := SapGuiOpenConnection(" /SAP_CODEPAGE=1100 /FULLMENU 10.5.2.198 0 /3");
    SapGuiSetActiveConnection(sConnID);
    SapGuiSetActiveSession("ses[0]");

    // SAP
    SapGuiSetActiveWindow("wnd[0]", "SAP", SAPGUI_MATCH_Exact);
    SapGuiWindowAction(SAPGUI_WND_MAXIMIZE);

    // Logon to SAP System
    SapGuiIgnoreError(SAPENGINE_STATUSBAR_CHANGED, SEVERITY_SUCCESS);
    ThinkTime(2.8);
    SapGuiLogon("ddic", "minisap", "000", "");

    // Copyright
    ThinkTime(2.1);
    SapGuiSetActiveWindow("wnd[1]", "Copyright", SAPGUI_MATCH_Exact);
    SapGuiPressButton("tbar[0]/btn[0]");

    // SAP Easy Access
    ThinkTime(9.9);
    SapGuiSetActiveWindow("wnd[0]", "SAP Easy Access", SAPGUI_MATCH_Exact);
    SapGuiGetComboboxEntries("usr/tblRSDEMO02TC_COLS/txtDEMO_CPROP-GROUP4", nIterator);
    while SapGuiIteratorHasMore(nIterator) do
      SapGuiIteratorFetchNext(nIterator);
      SapGuiIteratorGetValue(nIterator, sValue, nType);
      if (nType = SAPGUI_VT_DISPATCH) then
        SapGuiIteratorGetObject(nIterator, nObject);
        SapGuiObjectGetProperty(nObject,"Key", sKey);
        SapGuiObjectGetProperty(nObject, "Value", sValue);
        SapGuiObjectFree(nObject);
      end;
    end;

   SapGuiIteratorRelease(nIterator);
  end TMain;
Parent topic: Parsing Functions
Related reference
SapGuiIteratorFetchNext Function
SapGuiIteratorGetCount Function
SapGuiIteratorGetObjectAt Function
SapGuiIteratorGetValueAt Function
SapGuiIteratorGetValue Function
SapGuiIteratorHasMore Function
SapGuiIteratorRelease Function
SapGuiObjectFree Function


SapGuiIteratorGetObjectAt Function

Action

This functions reads and provides the value of a collection at a specified position. This function has to be used if the expected value is not of a simple type but a complex one.

For simple types the function SapGuiIteratorGetValueAt has to be used. The returned object handle has to be freed by calling SapGuiObjectFree when no longer needed.

Include file

SapGui.bdh

Syntax

SapGuiIteratorGetObjectAt( in  nIterator : number,
                           in  nPos      : number,
                           out nObj      : number ) : boolean;
Parameter | Description
nIterator | The handle to the collection iterator
nPos | The position of the value to be read.
nObj | This parameter will be assigned the handle of the object to be read.

Return value

  • true if successful
  • false otherwise

Example

transaction TMain
  var
    sConnID       : string;
    i             : number;
    nIterator     : number;
    nType         : number;
    nObject, nObj : number;
    bRet          : boolean;
    sStr1, sStr2  : string;
  begin

    // Connecting to SAP
    sConnID := SapGuiOpenConnection(" /SAP_CODEPAGE=1100 /FULLMENU 10.5.2.198 0 /3");
    SapGuiSetActiveConnection(sConnID);
    SapGuiSetActiveSession("ses[0]");

    // SAP
    SapGuiSetActiveWindow("wnd[0]", "SAP", SAPGUI_MATCH_Exact);
    SapGuiWindowAction(SAPGUI_WND_MAXIMIZE);

    // Logon to SAP System
    SapGuiIgnoreError(SAPENGINE_STATUSBAR_CHANGED, SEVERITY_SUCCESS);
    ThinkTime(2.8);
    SapGuiLogon("ddic", "minisap", "000", "");

    // Copyright
    ThinkTime(2.1);
    SapGuiSetActiveWindow("wnd[1]", "Copyright", SAPGUI_MATCH_Exact);
    SapGuiPressButton("tbar[0]/btn[0]");

    // SAP Easy Access
    ThinkTime(9.9);
    SapGuiSetActiveWindow("wnd[0]", "SAP Easy Access", SAPGUI_MATCH_Exact);
    SapGuiGetPropertyCollection("wnd[0]", "Children", nIterator);
    SapGuiIteratorGetObjectAt(nIterator, 0, nObj);
    SapGuiObjectFree(nObj);
    SapGuiIteratorRelease(nIterator);
  end TMain;
Parent topic: Parsing Functions
Related reference
SapGuiIteratorFetchNext Function
SapGuiIteratorGetCount Function
SapGuiIteratorGetObject Function
SapGuiIteratorGetValueAt Function
SapGuiIteratorGetValue Function
SapGuiIteratorHasMore Function
SapGuiIteratorRelease Function
SapGuiObjectFree Function


SapGuiIteratorGetValue Function

Action

This function provides the value of the iterator’s current position. It will only return the value of simple data types such as long, boolean and strings. Use SapGuiIteratorGetObject for getting a handle to complex types.

Include file

SapGui.bdh

Syntax

SapGuiIteratorGetValue( in  nIterator : number,
                        out sValue    : string,
                        out nType     : number ) : boolean;
Parameter | Description
nIterator | The handle to the iterator
sValue | This parameter will be assigned the value at the iterator’s current position
nType
The type of the property. The value may be one of the following:
  • SAPGUI_VT_BSTR: The value is of type string.
  • SAPGUI_VT_DISPATCH: The value is of type object. To get a handle to the object use SapGuiIteratorGetObject.
  • SAPGUI_VT_NULL: The value is NULL.
  • SAPGUI_VT_I4: The value if of type long.
  • SAPGUI_VT_BOOL: The value is of type boolean.

Return value

  • true if successful
  • false otherwise

Example

transaction TMain
  var
    sConnID   : string;
    sKey      : string;
    sValue    : string;
    nIterator : number;
    nObject   : number;
    nType     : number;
  begin

    // Connecting to SAP
    sConnID := SapGuiOpenConnection(" /SAP_CODEPAGE=1100 /FULLMENU 10.5.2.198 0 /3");
    SapGuiSetActiveConnection(sConnID);
    SapGuiSetActiveSession("ses[0]");

    // SAP
    SapGuiSetActiveWindow("wnd[0]", "SAP", SAPGUI_MATCH_Exact);
    SapGuiWindowAction(SAPGUI_WND_MAXIMIZE);

    // Logon to SAP System
    SapGuiIgnoreError(SAPENGINE_STATUSBAR_CHANGED, SEVERITY_SUCCESS);
    ThinkTime(2.8);
    SapGuiLogon("ddic", "minisap", "000", "");

    // Copyright
    ThinkTime(2.1);
    SapGuiSetActiveWindow("wnd[1]", "Copyright", SAPGUI_MATCH_Exact);
    SapGuiPressButton("tbar[0]/btn[0]");

    // SAP Easy Access
    ThinkTime(9.9);
    SapGuiSetActiveWindow("wnd[0]", "SAP Easy Access", SAPGUI_MATCH_Exact);
    SapGuiGetComboboxEntries("usr/tblRSDEMO02TC_COLS/txtDEMO_CPROP-GROUP4", nIterator);
    while SapGuiIteratorHasMore(nIterator) do
      SapGuiIteratorFetchNext(nIterator);
      SapGuiIteratorGetValue(nIterator, sValue, nType);
      if (nType = SAPGUI_VT_DISPATCH) then
        SapGuiIteratorGetObject(nIterator, nObject);
        SapGuiObjectGetProperty(nObject,"Key", sKey);
        SapGuiObjectGetProperty(nObject, "Value", sValue);
        SapGuiObjectFree(nObject);
      end;
    end;
    SapGuiIteratorRelease(nIterator);
  end TMain;
Parent topic: Parsing Functions
Related reference
SapGuiIteratorFetchNext Function
SapGuiIteratorGetCount Function
SapGuiIteratorGetObjectAt Function
SapGuiIteratorGetObject Function
SapGuiIteratorGetValueAt Function
SapGuiIteratorHasMore Function
SapGuiIteratorRelease Function


SapGuiIteratorGetValueAt Function

Action

This functions reads and provides the value of a collection at a specified position. It will only return the value of simple data types such as long, boolean and strings. Use SapGuiIteratorGetObjectAt for getting a handle to complex types.

Include file

SapGui.bdh

Syntax

SapGuiIteratorGetValueAt( in  nIterator : number,
                          in  nPos      : number,
                          out sValue    : string,
                          out nType     : number ) : boolean;
Parameter | Description
nIterator | The handle to the collection iterator.
nPos | The position of the value to be read
sValue | The string representation of the value
nType
The type of the property. The value may be one of the following:
  • SAPGUI_VT_BSTR: The value is of type string.
  • SAPGUI_VT_DISPATCH: The value is of type object. To get a handle to the object use SapGuiIteratorGetObject.
  • SAPGUI_VT_NULL: The value is NULL.
  • SAPGUI_VT_I4: The value if of type long.
  • SAPGUI_VT_BOOL: The value is of type boolean.

Return value

  • true if successful
  • false otherwise

Example

transaction TMain
  var
    sConnID   : string;
    i         : number;
    nIterator : number;
    nType     : number;
    nObject   : number;
    bRet      : boolean;
    sStr1, sStr2 : string;
  begin

    // Connecting to SAP
    sConnID := SapGuiOpenConnection(" /SAP_CODEPAGE=1100 /FULLMENU 10.5.2.198 0 /3");
    SapGuiSetActiveConnection(sConnID);
    SapGuiSetActiveSession("ses[0]");

    // SAP
    SapGuiSetActiveWindow("wnd[0]", "SAP", SAPGUI_MATCH_Exact);
    SapGuiWindowAction(SAPGUI_WND_MAXIMIZE);

    // Logon to SAP System
    SapGuiIgnoreError(SAPENGINE_STATUSBAR_CHANGED, SEVERITY_SUCCESS);
    ThinkTime(2.8);
    SapGuiLogon("ddic", "minisap", "000", "");

    // Copyright
    ThinkTime(2.1);
    SapGuiSetActiveWindow("wnd[1]", "Copyright", SAPGUI_MATCH_Exact);
    SapGuiPressButton("tbar[0]/btn[0]");

    // SAP Easy Access
    ThinkTime(9.9);
    SapGuiSetActiveWindow("wnd[0]", "SAP Easy Access", SAPGUI_MATCH_Exact);
    SapGuiGetPropertyCollection("wnd[0]", "Children", nIterator);
    SapGuiIteratorGetValueAt(nIterator, 0, sValue, nType);

    SapGuiIteratorRelease(nIterator);
  end TMain;
Parent topic: Parsing Functions
Related reference
SapGuiIteratorFetchNext Function
SapGuiIteratorGetCount Function
SapGuiIteratorGetObjectAt Function
SapGuiIteratorGetObject Function
SapGuiIteratorGetValue Function
SapGuiIteratorHasMore Function
SapGuiIteratorRelease Function


SapGuiGetCollection Function

Action

This function reads the return value of a previous SapGuiInvokeMethod call and provides it as a collection iterator.

The returned collection iterator has to be released after usage by calling SapGuiIteratorRelease.

Include file

SapGui.bdh

Syntax

SapGuiGetCollection( inout nIterator : number ) : boolean;
Parameter | Description
nIterator | This parameter will be assigned the collection iterator.

Return value

  • true if successful
  • false otherwise

Example

transaction TMain
  var
    sConnID   : string;
    i         : number;
    nIterator : number;
    nType     : number;
    nObject   : number;
    bRet      : boolean;
    sStr1, sStr2 : string;
  begin

    // Connecting to SAP
    sConnID := SapGuiOpenConnection(" /SAP_CODEPAGE=1100 /FULLMENU 10.5.2.198 0 /3");

    SapGuiSetActiveConnection(sConnID);

    SapGuiSetActiveSession("ses[0]");

    // SAP
    SapGuiSetActiveWindow("wnd[0]", "SAP", SAPGUI_MATCH_Exact);

    SapGuiWindowAction(SAPGUI_WND_MAXIMIZE);

    // Logon to SAP System
    SapGuiIgnoreError(SAPENGINE_STATUSBAR_CHANGED, SEVERITY_SUCCESS);
    ThinkTime(2.8);
    SapGuiLogon("ddic", "minisap", "000", "");

    // SAP Easy Access
    ThinkTime(9.9);
    SapGuiSetActiveWindow("wnd[0]", "SAP Easy Access", SAPGUI_MATCH_Exact);

    SapGuiGetProperty("wnd[0]", "Children");
    SapGuiGetCollection(nIterator);

    // nIterator now contains the iterator which the SapGuiGetProperty() call returned

    // Code using the iterator
    i := SapGuiIteratorGetCount(nIterator);
  while (SapGuiIteratorHasMore(nIterator)) do
    SapGuiIteratorFetchNext(nIterator);
    SapGuiIteratorGetObject(nIterator, nObject);
    sStr1 := "";
    sStr2 := "";
    SapGuiObjectGetType(nObject, sStr1, sStr2);
    SapGuiObjectFree(nObject);
    Print(sStr1 + " " + sStr2);
  end;

    SapGuiIteratorRelease(nIterator); // necessary to avoid a resource leak
  end TMain;
Parent topic: Parsing Functions
Related reference
SapGuiIteratorFetchNext Function
SapGuiIteratorGetCount Function
SapGuiIteratorGetObjectAt Function
SapGuiIteratorGetObject Function
SapGuiIteratorGetValueAt Function
SapGuiIteratorGetValue Function
SapGuiIteratorHasMore Function
SapGuiIteratorRelease Function


SapGuiGetComboboxEntries Function

Action

This functions provides an iterator for the combobox entries. All members of the collection are of type GuiComboBoxEntry and have just two properties, key and value, both of type string.

Include file

SapGui.bdh

Syntax

SapGuiGetComboboxEntries( in  sControlId : string allownull,
                          out nIterator  : number ) : boolean;
Parameter | Description
sControlId | The control’s unique id.
nIterator | This parameter will be assigned a handle to the collection iterator.

Return value

  • true if successful
  • false otherwise

Example

transaction TMain
  var
    sConnID   : string;
    sKey      : string;
    sValue    : string;
    nIterator : number;
    nObject   : number;
  begin
    // Connecting to SAP
    sConnID := SapGuiOpenConnection(" /SAP_CODEPAGE=1100 /FULLMENU 10.5.2.198 0 /3");
    SapGuiSetActiveConnection(sConnID);
    SapGuiSetActiveSession("ses[0]");

    // SAP
    SapGuiSetActiveWindow("wnd[0]", "SAP", SAPGUI_MATCH_Exact);
    SapGuiWindowAction(SAPGUI_WND_MAXIMIZE);

    // Logon to SAP System
    SapGuiIgnoreError(SAPENGINE_STATUSBAR_CHANGED, SEVERITY_SUCCESS);
    ThinkTime(2.8);
    SapGuiLogon("ddic", "minisap", "000", "");

    // Copyright
    ThinkTime(2.1);
    SapGuiSetActiveWindow("wnd[1]", "Copyright", SAPGUI_MATCH_Exact);
    SapGuiPressButton("tbar[0]/btn[0]");

    // SAP Easy Access
    ThinkTime(9.9);
    SapGuiSetActiveWindow("wnd[0]", "SAP Easy Access", SAPGUI_MATCH_Exact);
    SapGuiGetComboboxEntries("usr/tblRSDEMO02TC_COLS/txtDEMO_CPROP-GROUP4", nIterator);
    while SapGuiIteratorHasMore(nIterator) do
    SapGuiIteratorFetchNext(nIterator);
    SapGuiIteratorGetObject(nIterator, nObject);
    SapGuiObjectGetProperty(nObject,"Key", sKey);
    SapGuiObjectGetProperty(nObject, "Value", sValue);
    SapGuiObjectFree(nObject);
    end;

    SapGuiIteratorRelease(nIterator);

  end TMain;

Parent topic: Parsing Functions
Related reference
SapGuiIteratorRelease Function


SapGuiGetHandleFromControlId Function

Action

This function returns a handle for the control specified. The returned handle has to be free by calling SapGuiObjectFree.

Include file

SapGui.bdh

Syntax

SapGuiGetHandleFromControlId( in  sControlId : string,
                              out nObject    : number ) : boolean;
Parameter | Description
sControlId | The control’s unique id.
nObject | This parameter will be assigned the handle to the object.

Return value

  • true if successful
  • false otherwise

Example

transaction TMain
  var
    sConnID   : string;
    i         : number;
    nIterator : number;
    nType     : number;
    nObj      : number;
    bRet      : boolean;
    sStr1, sStr2 : string;
  begin
    // Connecting to SAP
    sConnID := SapGuiOpenConnection(" /SAP_CODEPAGE=1100 /FULLMENU 10.5.2.198 0 /3");
    SapGuiSetActiveConnection(sConnID);
    SapGuiSetActiveSession("ses[0]");

    // SAP
    SapGuiSetActiveWindow("wnd[0]", "SAP", SAPGUI_MATCH_Exact);
    SapGuiWindowAction(SAPGUI_WND_MAXIMIZE);

    // Logon to SAP System
    SapGuiIgnoreError(SAPENGINE_STATUSBAR_CHANGED, SEVERITY_SUCCESS);
    ThinkTime(2.8);
    SapGuiLogon("ddic", "minisap", "000", "");

    // Copyright
    ThinkTime(2.1);
    SapGuiSetActiveWindow("wnd[1]", "Copyright", SAPGUI_MATCH_Exact);
    SapGuiPressButton("tbar[0]/btn[0]");

    // SAP Easy Access
    ThinkTime(9.9);
    SapGuiSetActiveWindow("wnd[0]", "SAP Easy Access", SAPGUI_MATCH_Exact);
    SapGuiGetHandleFromControlId("wnd[0]", nObj);

    // Here nObj can be used.
    // That means be passed as parameter to all SapGuiObject... functions
    SapGuiObjectFree(nObj); // Don't forget to free the object handle!
  end TMain;
Parent topic: Parsing Functions
Related reference
SapGuiObjectFree Function
SapGuiObjectGetBoolean Function
SapGuiObjectGetCollection Function
SapGuiObjectGetControlId Function
SapGuiObjectGetLong Function
SapGuiObjectGetObject Function
SapGuiObjectGetPropertyBoolean Function
SapGuiObjectGetProperty Function
SapGuiObjectGetPropertyLong Function
SapGuiObjectGetPropertyObject Function
SapGuiObjectGetString Function
SapGuiObjectGetType Function
SapGuiObjectInvokeMethod Function
SapGuiObjectSetBoolean Function
SapGuiObjectSetLong Function
SapGuiObjectSetObject Function
SapGuiObjectSetProperty Function
SapGuiObjectSetPropertyObject Function
SapGuiObjectSetString Function


SapGuiGetPropertyCollection Function

Action

This function reads the return value of a previous call of SapGuiInvokeMethod and provides the value as a collection.

Include file

SapGui.bdh

Syntax

SapGuiGetPropertyCollection( in  sControlId : string,
                             in  sProperty  : string,
                             out nIterator  : number ) : boolean;
Parameter | Description
sControlId | The control’s unique id.
sProperty | The name of the property to be read.
nIterator | This parameter will be assigned the handle to the collection iterator.

Return value

  • true if successful
  • false otherwise

Example

transaction TMain
  var
    sConnID   : string;
    i         : number;
    nIterator : number;
    nType     : number;
    nObject   : number;
    bRet      : boolean;
    sStr1, sStr2 : string;
  begin

    // Connecting to SAP
    sConnID := SapGuiOpenConnection(" /SAP_CODEPAGE=1100 /FULLMENU 10.5.2.198 0 /3");
    SapGuiSetActiveConnection(sConnID);
    SapGuiSetActiveSession("ses[0]");

    // SAP
    SapGuiSetActiveWindow("wnd[0]", "SAP", SAPGUI_MATCH_Exact);
    SapGuiWindowAction(SAPGUI_WND_MAXIMIZE);

    // Logon to SAP System
    SapGuiIgnoreError(SAPENGINE_STATUSBAR_CHANGED, SEVERITY_SUCCESS);
    ThinkTime(2.8);
    SapGuiLogon("ddic", "minisap", "000", "");

    // Copyright
    ThinkTime(2.1);
    SapGuiSetActiveWindow("wnd[1]", "Copyright", SAPGUI_MATCH_Exact);
    SapGuiPressButton("tbar[0]/btn[0]");

    // SAP Easy Access
    ThinkTime(9.9);
    SapGuiSetActiveWindow("wnd[0]", "SAP Easy Access", SAPGUI_MATCH_Exact);
    SapGuiGetPropertyCollection("wnd[0]", "Children", nIterator);
  while (SapGuiIteratorHasMore(nIterator)) do
    SapGuiIteratorFetchNext(nIterator);
    SapGuiIteratorGetObject(nIterator, nObject);
    SapGuiObjectSetBoolean(nObject, true);
    SapGuiObjectInvokeMethod(nObject, "method");
    SapGuiObjectGetBoolean(nObject, bRet);
    SapGuiObjectGetType(nObject, sStr1, sStr2);
    SapGuiObjectFree(nObject);
    Print(string(nType) + " " + sValue);
  end;
    SapGuiIteratorRelease(nIterator);
  end TMain;
Parent topic: Parsing Functions
Related reference
SapGuiIteratorFetchNext Function
SapGuiIteratorGetCount Function
SapGuiIteratorGetObjectAt Function
SapGuiIteratorGetObject Function
SapGuiIteratorGetValueAt Function
SapGuiIteratorGetValue Function
SapGuiIteratorHasMore Function
SapGuiIteratorRelease Function


Verifying Functions

  • SapGuiVerifyCalendarFocusDate Function
    Verifies whether a specified date is focused in a calendar control.
  • SapGuiVerifyCheckbox Function
    Verifies a SapGui check box control.
  • SapGuiVerifyComboboxEntry Function
    Verifies whether an entry in a combobox is selected.
  • SapGuiVerifyGridCellData Function
    Verifies the content of a specified cell of a SapGui grid.
  • SapGuiVerifyGridCheckboxChecked Function
    Verifies the row of the current cell of a SapGui grid control.
  • SapGuiVerifyGridCurrentCellColumn Function
    Verifies the column of the current cell of a SapGui grid control.
  • SapGuiVerifyGridCurrentCellRow Function
    Verifies the row of the current cell of a SapGui grid control.
  • SapGuiVerifyObjectAvailability Function
    Verifies whether a SapGui control exists and can be accessed during a test run.
  • SapGuiVerifyPropertyBoolean Function
    Verifies a property of type Boolean for any SapGui control.
  • SapGuiVerifyPropertyByte Function
    Verifies a property of type byte for any SapGui control.
  • SapGuiVerifyPropertyDouble Function
    Verifies a property of type Double for any SapGui control.
  • SapGuiVerifyPropertyFloat Function
    Verifies a property of type Float for any SapGui control.
  • SapGuiVerifyPropertyLong Function
    Verifies a property of type Long for any SapGui control.
  • SapGuiVerifyPropertyShort Function
    Verifies a property of type Short for any SapGui control.
  • SapGuiVerifyPropertyString Function
    Verifies a property of type string for any SapGui control.
  • SapGuiVerifyRadioValue Function
    Verifies a SapGui radio button control.
  • SapGuiVerifyStatusBarText Function
    Verifies the current statusbar text of the SapGui application.
  • SapGuiVerifyTableCheckbox Function
    Verifies whether a check box in a table cell is checked.
  • SapGuiVerifyTableRadioValue Function
    Verifies whether a radio button in a table cell is selected.
  • SapGuiVerifyTableRowSelected Function
    Verifies whether a check box in a table cell is checked.
  • SapGuiVerifyTableText Function
    Verifies the text of a table cell.
  • SapGuiVerifyTabSelected Function
    Verifies whether a tab is currently the selected one inside a tab control.
  • SapGuiVerifyTextValue Function
    Verifies the value of a SapGui text control.
  • SapGuiVerifyTreeCheckbox Function
    Verifies a SapGui check box attached to an item in a SapGui tree.
  • SapGuiVerifyTreeItemText Function
    Verifies the text of an item in a SapGui tree control.
  • SapGuiVerifyTreeNodeText Function
    Verifies the text of a node in a SapGui tree control.
  • SapGuiVerifyWindowAvailability Function
    Verifies whether a SapGui window exists and can be accessed during a test run.
Parent topic: SAP Functions


SapGuiVerifyCalendarFocusDate Function

Action

This function verifies whether a specified date is focused in a calendar control.

Include file

SapGui.bdh

Syntax

SapGuiVerifyCalendarFocusDate( in sControlId : string,
                               in sDate      : string,
                               in nOptions   : number optional,
                               in nSeverity  : number optional := SEVERITY_ERROR ) : boolean;
Parameter | Description
sControlId | The unique id of the calendar
sDate | The date to be verified.
nOptions

This parameter specifies the type of check to be performed. Available options are:

  • SAPGUI_VERIFY_EQUAL. Verifies, whether the state of the checkbox's state is equal to the value specified in the second parameter.
  • SAPGUI_VERIFY_NOT_EQUAL. Verifies, whether the checkbox's state is not equal to the value specified in the second parameter.
nSeverity Optional: Severity of the error that is raised if the verification fails. Can be one of the following values:
  • SEVERITY_SUCCESS: Success; no error (numerical value: 0)
  • SEVERITY_INFORMATIONAL: Informational; no error (numerical value: 1)
  • SEVERITY_WARNING: Warning; no error (numerical value: 2)
  • SEVERITY_ERROR: (Default) Error; simulation continues (numerical value: 3)
  • SEVERITY_TRANS_EXIT: Error; the active transaction is aborted (numerical value: 4)
  • SEVERITY_PROCESS_EXIT: Error; the simulation is aborted (numerical value: 5)

Return value

  • true if successful
  • false otherwise

Example

transaction TMain
  var
    sConnID : string;
  begin
    // Connecting to SAP
    sConnID := SapGuiOpenConnection( " /SAP_CODEPAGE=1100 /FULLMENU 10.5.2.132 0 /3");
    SapGuiSetActiveConnection(sConnID);
    SapGuiSetActiveSession("ses[0]");

    // SAP
    SapGuiSetActiveWindow("wnd[0]", "SAP", SAPGUI_MATCH_ExactNoCase);
    SapGuiWindowAction(SAPGUI_WND_MAXIMIZE);

    // Logon to SAP System
    // Before running a test you have to customize the password parameter!
    ThinkTime(2.3);
    SapGuiLogon("ddic", "*******", "000", "");

    // SAP Easy Access
    SapGuiIgnoreError(SAPENGINE_STATUSBAR_CHANGED, SEVERITY_SUCCESS);
    SapGuiSetActiveWindow("wnd[0]", "SAP Easy Access", SAPGUI_MATCH_ExactNoCase);
    SapGuiSetActiveWindow("wnd[0]", "Termine anzeigen: DDIC", SAPGUI_MATCH_ExactNoCase);
    SapGuiCalendarFocusDate( "usr/cntlCALE_CONTROL/shellcont/shell/shellcont[0]/shell", "20041105");
    SapGuiVerifyCalendarFocusDate( "usr/cntlCALE_CONTROL/shellcont/shell/shellcont[0]/shell", "20041105", SAPGUI_VERIFY_EQUAL, SEVERITY_ERROR);
  end TMain;
Parent topic: Verifying Functions


SapGuiVerifyCheckbox Function

Action

This function verifies a SapGui check box control. It can be used to ensure whether a checkbox is checked or not checked.

Include file

SapGui.bdh

Syntax

SapGuiVerifyCheckbox( in sControlId : string,
                      in bValue     : boolean,
                      in nOptions   : number optional,
                      in nSeverity  : number optional := SEVERITY_ERROR ) : boolean;
Parameter | Description
sControlId | The unique id of a checkbox control
bValue | This parameter is set to "true" if the check as specified in the third parameter results in success. Otherwise it is set to "false".
nOptions

This parameter specifies the type of check to be performed. Available options are:

  • SAPGUI_VERIFY_EQUAL. Verifies, whether the state of the checkbox's state is equal to the value specified in the second parameter.
  • SAPGUI_VERIFY_NOT_EQUAL. Verifies, whether the checkbox's state is not equal to the value specified in the second parameter.
nSeverity Optional: Severity of the error that is raised if the verification fails. Can be one of the following values:
  • SEVERITY_SUCCESS: Success; no error (numerical value: 0)
  • SEVERITY_INFORMATIONAL: Informational; no error (numerical value: 1)
  • SEVERITY_WARNING: Warning; no error (numerical value: 2)
  • SEVERITY_ERROR: (Default) Error; simulation continues (numerical value: 3)
  • SEVERITY_TRANS_EXIT: Error; the active transaction is aborted (numerical value: 4)
  • SEVERITY_PROCESS_EXIT: Error; the simulation is aborted (numerical value: 5)

Return value

  • true if successful
  • false otherwise

Example

transaction TMain
  var
    sConnID : string;
  begin
    // Connecting to SAP
    sConnID := SapGuiOpenConnection( " /SAP_CODEPAGE=1100 /FULLMENU 10.5.2.132 0 3");
    SapGuiSetActiveConnection(sConnID);
    SapGuiSetActiveSession("ses[0]");

    // SAP
    SapGuiSetActiveWindow("wnd[0]", "SAP", SAPGUI_MATCH_ExactNoCase);
    SapGuiWindowAction(SAPGUI_WND_MAXIMIZE);

    // Logon to SAP System
    // Before running a test you have to customize the password parameter!
    ThinkTime(2.3);
    SapGuiLogon("ddic", "*******", "000", "");

    // SAP Easy Access
    SapGuiIgnoreError(SAPENGINE_STATUSBAR_CHANGED, SEVERITY_SUCCESS);
    SapGuiSetActiveWindow("wnd[0]", "SAP Easy Access", SAPGUI_MATCH_ExactNoCase);

    // Other menu
    SapGuiIgnoreError(SAPENGINE_STATUSBAR_CHANGED, SEVERITY_SUCCESS);
    ThinkTime(5.9);
    SapGuiPressButton("tbar[1]/btn[17]", " Other menu");

    // Wertebereich einschränken
    ThinkTime(2.7);
    SapGuiSetActiveWindow("wnd[1]", "Wertebereich einschränken", SAPGUI_MATCH_ExactNoCase);
    SapGuiSetFocus("usr/tabsG_SELONETABSTRIP/tabpTAB002/chkG_SELPOP_STATE-BUTTON");
    SapGuiSetCheckbox("usr/tabsG_SELONETABSTRIP/220/chkG_SELPOP_STATE-BUTTON", true, "No restriction");
    SapGuiVerifyCheckbox( "/usr/tabsG_SELONETABSTRIP/DH4:0220/chkG_SELPOP_STATE-BUTTON", true, SAPGUI_VERIFY_EQUAL, SEVERITY_ERROR);
  end TMain;
Parent topic: Verifying Functions


SapGuiVerifyComboboxEntry Function

Action

This function verifies whether an entry in a combobox is selected.

Include file

SapGui.bdh

Syntax

SapGuiVerifyComboboxEntry( in sControlId : string,
                           in sValue     : string,
                           in nOptions   : number optional,
                           in nSeverity  : number optional := SEVERITY_ERROR ) : boolean;
Parameter | Description
sControlId | The unique id of the tab.
sValue | The value to be verified for the combobox.
nOptions

This parameter specifies the type of check to be performed. Available options are:

  • SAPGUI_VERIFY_EQUAL. Verifies, whether the state of the checkbox's state is equal to the value specified in the second parameter.
  • SAPGUI_VERIFY_NOT_EQUAL. Verifies, whether the checkbox's state is not equal to the value specified in the second parameter.
nSeverity Optional: Severity of the error that is raised if the verification fails. Can be one of the following values:
  • SEVERITY_SUCCESS: Success; no error (numerical value: 0)
  • SEVERITY_INFORMATIONAL: Informational; no error (numerical value: 1)
  • SEVERITY_WARNING: Warning; no error (numerical value: 2)
  • SEVERITY_ERROR: (Default) Error; simulation continues (numerical value: 3)
  • SEVERITY_TRANS_EXIT: Error; the active transaction is aborted (numerical value: 4)
  • SEVERITY_PROCESS_EXIT: Error; the simulation is aborted (numerical value: 5)

Return value

  • true if successful
  • false otherwise

Example

transaction TMain
  var
    sText : string;
    sConnID : string;
  begin
    // Connecting to SAP
    sConnID := SapGuiOpenConnection( " /SAP_CODEPAGE=1100 /FULLMENU 10.5.2.132 0 /3");
    SapGuiSetActiveConnection(sConnID);
    SapGuiSetActiveSession("ses[0]");

    // SAP
    SapGuiSetActiveWindow("wnd[0]", "SAP", SAPGUI_MATCH_ExactNoCase);
    SapGuiWindowAction(SAPGUI_WND_MAXIMIZE);

    // Logon to SAP System
    // Before running a test you have to customize the password parameter!
    ThinkTime(2.0);
    SapGuiLogon("ddic", "minisap", "000", "");
    SapGuiVerifyComboboxEntry("/usr/tabsG_SELONETABSTRIP/combo2/", "Entry", SAPGUI_VERIFY_EQUAL, SEVERITY_ERROR);
  end TMain;
Parent topic: Verifying Functions


SapGuiVerifyGridCellData Function

Action

This function verifies the content of a specified cell of a SapGui grid.

Include file

SapGui.bdh

Syntax

SapGuiVerifyGridCellData( in sControlId : string,
                          in nRow       : number,
                          in sCol       : string,
                          in sValue     : string,
                          in nOptions   : number optional,
                          in nSeverity  : number optional := SEVERITY_ERROR ) : boolean;
Parameter | Description
sControlId | The unique id of the table.
nRow | The row of the cell to be verified.
sCol | The column of the cell to be verified.
sValue | The value to be verified.
nOptions

This parameter specifies the type of check to be performed. Available options are:

  • SAPGUI_VERIFY_EQUAL. Verifies, whether the state of the checkbox's state is equal to the value specified in the second parameter.
  • SAPGUI_VERIFY_NOT_EQUAL. Verifies, whether the checkbox's state is not equal to the value specified in the second parameter.
nSeverity Optional: Severity of the error that is raised if the verification fails. Can be one of the following values:
  • SEVERITY_SUCCESS: Success; no error (numerical value: 0)
  • SEVERITY_INFORMATIONAL: Informational; no error (numerical value: 1)
  • SEVERITY_WARNING: Warning; no error (numerical value: 2)
  • SEVERITY_ERROR: (Default) Error; simulation continues (numerical value: 3)
  • SEVERITY_TRANS_EXIT: Error; the active transaction is aborted (numerical value: 4)
  • SEVERITY_PROCESS_EXIT: Error; the simulation is aborted (numerical value: 5)

Return value

  • true if successful
  • false otherwise

Example

transaction TMain
  var
    sConnID : string;
  begin
    // Connecting to SAP
    sConnID := SapGuiOpenConnection( " /SAP_CODEPAGE=1100 /FULLMENU 10.5.2.132 0 /3");
    SapGuiSetActiveConnection(sConnID);
    SapGuiSetActiveSession("ses[0]");

    // SAP
    SapGuiSetActiveWindow("wnd[0]", "SAP", SAPGUI_MATCH_ExactNoCase);
    SapGuiWindowAction(SAPGUI_WND_MAXIMIZE);

    // Logon to SAP System
    // Before running a test you have to customize the password parameter!
    ThinkTime(2.3);
    SapGuiLogon("ddic", "*******", "000", "");

    // SAP Easy Access
    SapGuiIgnoreError(SAPENGINE_STATUSBAR_CHANGED, SEVERITY_SUCCESS);
    SapGuiSetActiveWindow("wnd[0]", "SAP Easy Access", SAPGUI_MATCH_ExactNoCase);

    // NodeName: Workplace: DDIC
    // NodePath: 1
    SapGuiSelectTopNode( "usr/cntlSINWP_CONTAINER/shellcont/shell/shellcont[0]/shell", "Workplace: DDIC", " 1", "TopNode\\Workplace: DDIC");
    ThinkTime(16.8);
    SapGuiGridSelectCell( "usr/cntlSINWP_CONTAINER/shellcont/shell/shellcont[1]/shell/shellcont[0]/shell", 1, "OBJDES");
    SapGuiVerifyGridCellData( "usr/cntlSINWP_CONTAINER/shellcont/shell/shellcont[1]/shell/shellcont[0]/shell", 1, "OBJDES", "value");
  end TMain;
Parent topic: Verifying Functions


SapGuiVerifyGridCheckboxChecked Function

Action

This function verifies the row of the current cell of a SapGui grid control.

Include file

SapGui.bdh

Syntax

SapGuiVerifyGridCheckboxChecked( in sControlId : string,
                                 in nRow       : number,
                                 in sCol       : string,
                                 in bChecked   : boolean,
                                 in nOptions   : number optional,
                                 in nSeverity  : number optional := SEVERITY_ERROR ) : boolean;
Parameter | Description
sControlId | The unique id of the table.
nRow | The row of the cell to be verified.
sCol | The column of the cell to be verified.
bChecked | Value to be compared according to the rules specified in the 'nOptions' parameter.
nOptions

This parameter specifies the type of check to be performed. Available options are:

  • SAPGUI_VERIFY_EQUAL. Verifies, whether the state of the checkbox's state is equal to the value specified in the second parameter.
  • SAPGUI_VERIFY_NOT_EQUAL. Verifies, whether the checkbox's state is not equal to the value specified in the second parameter.
nSeverity Optional: Severity of the error that is raised if the verification fails. Can be one of the following values:
  • SEVERITY_SUCCESS: Success; no error (numerical value: 0)
  • SEVERITY_INFORMATIONAL: Informational; no error (numerical value: 1)
  • SEVERITY_WARNING: Warning; no error (numerical value: 2)
  • SEVERITY_ERROR: (Default) Error; simulation continues (numerical value: 3)
  • SEVERITY_TRANS_EXIT: Error; the active transaction is aborted (numerical value: 4)
  • SEVERITY_PROCESS_EXIT: Error; the simulation is aborted (numerical value: 5)

Return value

  • true if successful
  • false otherwise

Example

transaction TMain
  var
    sConnID : string;
  begin
    // Connecting to SAP
    sConnID := SapGuiOpenConnection( " /SAP_CODEPAGE=1100 /FULLMENU 10.5.2.132 0 /3");
    SapGuiSetActiveConnection(sConnID);
    SapGuiSetActiveSession("ses[0]");

    // SAP
    SapGuiSetActiveWindow("wnd[0]", "SAP", SAPGUI_MATCH_ExactNoCase);
    SapGuiWindowAction(SAPGUI_WND_MAXIMIZE);

    // Logon to SAP System
    // Before running a test you have to customize the password parameter!
    ThinkTime(2.3);
    SapGuiLogon("ddic", "*******", "000", "");

    // SAP Easy Access
    SapGuiIgnoreError(SAPENGINE_STATUSBAR_CHANGED, SEVERITY_SUCCESS);
    SapGuiSetActiveWindow("wnd[0]", "SAP Easy Access", SAPGUI_MATCH_ExactNoCase);

    // NodeName: Workplace: DDIC
    // NodePath: 1
    SapGuiSelectTopNode( "usr/cntlSINWP_CONTAINER/shellcont/shell/shellcont[0]/shell", "Workplace: DDIC", " 1", "TopNode\\Workplace: DDIC");
    ThinkTime(16.8);
    SapGuiGridSelectCell( "usr/cntlSINWP_CONTAINER/shellcont/shell/shellcont[1]/shell/shellcont[0]/shell", 1, "OBJDES");
    SapGuiVerifyGridCheckboxChecked ( "usr/cntlSINWP_CONTAINER/shellcont/shell/shellcont[1]/shell/shellcont[0]/shell", 1, "OBJDES", true, SAPGUI_VERIFY_EQUAL, SEVERITY_ERROR);
  end TMain;
Parent topic: Verifying Functions


SapGuiVerifyGridCurrentCellColumn Function

Action

This function verifies the column of the current cell of a SapGui grid control.

Include file

SapGui.bdh

Syntax

SapGuiVerifyGridCurrentCellColumn( in sControlId : string,
                                   in sColumn    : string,
                                   in nOptions   : number optional,
                                   in nSeverity  : number optional := SEVERITY_ERROR ) : boolean;
Parameter | Description
sControlId | The unique id of the table.
sColumn | The column to be verified as the active one.
nOptions This parameter specifies the type of check to be performed. Available options are:
  • SAPGUI_VERIFY_EQUAL. Verifies, whether the state of the checkbox's state is equal to the value specified in the second parameter.
  • SAPGUI_VERIFY_NOT_EQUAL. Verifies, whether the checkbox's state is not equal to the value specified in the second parameter.
nSeverity Optional: Severity of the error that is raised if the verification fails. Can be one of the following values:
  • SEVERITY_SUCCESS: Success; no error (numerical value: 0)
  • SEVERITY_INFORMATIONAL: Informational; no error (numerical value: 1)
  • SEVERITY_WARNING: Warning; no error (numerical value: 2)
  • SEVERITY_ERROR: (Default) Error; simulation continues (numerical value: 3)
  • SEVERITY_TRANS_EXIT: Error; the active transaction is aborted (numerical value: 4)
  • SEVERITY_PROCESS_EXIT: Error; the simulation is aborted (numerical value: 5)

Return value

  • true if successful
  • false otherwise

Example

transaction TMain
  var
    sConnID : string;
  begin
    // Connecting to SAP
    sConnID := SapGuiOpenConnection( " /SAP_CODEPAGE=1100 /FULLMENU 10.5.2.132 0 /3");
    SapGuiSetActiveConnection(sConnID);
    SapGuiSetActiveSession("ses[0]");

    // SAP
    SapGuiSetActiveWindow("wnd[0]", "SAP", SAPGUI_MATCH_ExactNoCase);
    SapGuiWindowAction(SAPGUI_WND_MAXIMIZE);

    // Logon to SAP System
    // Before running a test you have to customize the password parameter!
    ThinkTime(2.3);
    SapGuiLogon("ddic", "*******", "000", "");

    // SAP Easy Access
    SapGuiIgnoreError(SAPENGINE_STATUSBAR_CHANGED, SEVERITY_SUCCESS);
    SapGuiSetActiveWindow("wnd[0]", "SAP Easy Access", SAPGUI_MATCH_ExactNoCase);

    // NodeName: Workplace: DDIC
    // NodePath: 1
    SapGuiSelectTopNode( "usr/cntlSINWP_CONTAINER/shellcont/shell/shellcont[0]/shell", "Workplace: DDIC", " 1", "TopNode\\Workplace: DDIC");
    ThinkTime(16.8);
    SapGuiGridSelectCell( "usr/cntlSINWP_CONTAINER/shellcont/shell/shellcont[1]/shell/shellcont[0]/shell", 1, "OBJDES");
    SapGuiVerifyGridCurrentCellColumn ("usr/cntlSINWP_CONTAINER/shellcont/shell/shellcont[1]/shell/shellcont[0]/shell", "OBJDES", SAPGUI_VERIFY_EQUAL, SEVERITY_ERROR);
  end TMain;
Parent topic: Verifying Functions


SapGuiVerifyGridCurrentCellRow Function

Action

This function verifies the row of the current cell of a SapGui grid control.

Include file

SapGui.bdh

Syntax

SapGuiVerifyGridCurrentCellRow( in sControlId : string,
                                in nRow       : number,
                                in nOptions   : number optional,
                                in nSeverity  : number optional := SEVERITY_ERROR ) : boolean;
Parameter | Description
sControlId | The unique id of the table.
nRow | The row to be verified as the active one.
nOptions This parameter specifies the type of check to be performed. Available options are:
  • SAPGUI_VERIFY_EQUAL. Verifies, whether the state of the checkbox's state is equal to the value specified in the second parameter.
  • SAPGUI_VERIFY_NOT_EQUAL. Verifies, whether the checkbox's state is not equal to the value specified in the second parameter.
nSeverity Optional: Severity of the error that is raised if the verification fails. Can be one of the following values:
  • SEVERITY_SUCCESS: Success; no error (numerical value: 0)
  • SEVERITY_INFORMATIONAL: Informational; no error (numerical value: 1)
  • SEVERITY_WARNING: Warning; no error (numerical value: 2)
  • SEVERITY_ERROR: (Default) Error; simulation continues (numerical value: 3)
  • SEVERITY_TRANS_EXIT: Error; the active transaction is aborted (numerical value: 4)
  • SEVERITY_PROCESS_EXIT: Error; the simulation is aborted (numerical value: 5)

Return value

  • true if successful
  • false otherwise

Example

transaction TMain
  var
    sConnID : string;
  begin
    // Connecting to SAP
    sConnID := SapGuiOpenConnection( " /SAP_CODEPAGE=1100 /FULLMENU 10.5.2.132 0 /3");
    SapGuiSetActiveConnection(sConnID);
    SapGuiSetActiveSession("ses[0]");

    // SAP
    SapGuiSetActiveWindow("wnd[0]", "SAP", SAPGUI_MATCH_ExactNoCase);
    SapGuiWindowAction(SAPGUI_WND_MAXIMIZE);

    // Logon to SAP System
    // Before running a test you have to customize the password parameter!
    ThinkTime(2.3);
    SapGuiLogon("ddic", "*******", "000", "");

    // SAP Easy Access
    SapGuiIgnoreError(SAPENGINE_STATUSBAR_CHANGED, SEVERITY_SUCCESS);
    SapGuiSetActiveWindow("wnd[0]", "SAP Easy Access", SAPGUI_MATCH_ExactNoCase);

    // NodeName: Workplace: DDIC
    // NodePath: 1
    SapGuiSelectTopNode( "usr/cntlSINWP_CONTAINER/shellcont/shell/shellcont[0]/shell", "Workplace: DDIC", " 1", "TopNode\\Workplace: DDIC");
    ThinkTime(16.8);
    SapGuiGridSelectCell( "usr/cntlSINWP_CONTAINER/shellcont/shell/shellcont[1]/shell/shellcont[0]/shell", 1, "OBJDES");
    SapGuiVerifyGridCurrentCellRow ( "usr/cntlSINWP_CONTAINER/shellcont/shell/shellcont[1]/shell/shellcont[0]/shell", 1, SAPGUI_VERIFY_EQUAL, SEVERITY_ERROR);
  end TMain;
Parent topic: Verifying Functions


SapGuiVerifyObjectAvailability Function

Action

Verifies whether a SapGui control exists and can be accessed during a test run.

Include file

SapGui.bdh

Syntax

SapGuiVerifyObjectAvailability( in sControlId    : string,
                                in bAbsolutePath : boolean optional,
                                in nSeverity     : number optional  := SEVERITY_ERROR ) : boolean;
Parameter | Description
sControlId | The unique id of the SapGui control.
bAbsolutePath | If set to true, the id of the control has to be specified using the absolute path. This includes the connection, session, window and control id. Otherwise the verification will be performed looking up the control in the active session.
nSeverity Optional: Severity of the error that is raised if the verification fails. Can be one of the following values:
  • SEVERITY_SUCCESS: Success; no error (numerical value: 0)
  • SEVERITY_INFORMATIONAL: Informational; no error (numerical value: 1)
  • SEVERITY_WARNING: Warning; no error (numerical value: 2)
  • SEVERITY_ERROR: (Default) Error; simulation continues (numerical value: 3)
  • SEVERITY_TRANS_EXIT: Error; the active transaction is aborted (numerical value: 4)
  • SEVERITY_PROCESS_EXIT: Error; the simulation is aborted (numerical value: 5)

Return value

  • true if successful
  • false otherwise

Example

transaction TMain
  var
    sText : string;
    sConnID : string;
  begin
    // Connecting to SAP
    sConnID := SapGuiOpenConnection( " /SAP_CODEPAGE=1100 /FULLMENU 10.5.2.132 0 /3");
    SapGuiSetActiveConnection(sConnID);
    SapGuiSetActiveSession("ses[0]");

    // SAP
    SapGuiSetActiveWindow("wnd[0]", "SAP", SAPGUI_MATCH_ExactNoCase);
    SapGuiWindowAction(SAPGUI_WND_MAXIMIZE);

    // Logon to SAP System
    // Before running a test you have to customize the password parameter!
    ThinkTime(2.0);
    SapGuiLogon("ddic", "minisap", "000", "");
    SapGuiVerifyObjectAvailability("tab[0]/btn1", false, SEVERITY_ERROR);
  end TMain;
Parent topic: Verifying Functions


SapGuiVerifyPropertyBoolean Function

Action

This function verifies a property of type Boolean for any SapGui control.

Include file

SapGui.bdh

Syntax

SapGuiVerifyPropertyBoolean( in sControlId : string,
                             in sName      : string,
                             in bValue     : boolean,
                             in nOptions   : number optional,
                             in nSeverity  : number optional := SEVERITY_ERROR ) : boolean;
Parameter | Description
sControlId | The unique Id of the control.
sName | The name of the property
bValue | The value to be verified.
nOptions

This parameter specifies the type of check to be performed. Available options are:

  • SAPGUI_VERIFY_EQUAL. Verifies, whether the state of the checkbox's state is equal to the value specified in the second parameter.
  • SAPGUI_VERIFY_NOT_EQUAL. Verifies, whether the checkbox's state is not equal to the value specified in the second parameter.
nSeverity Optional: Severity of the error that is raised if the verification fails. Can be one of the following values:
  • SEVERITY_SUCCESS: Success; no error (numerical value: 0)
  • SEVERITY_INFORMATIONAL: Informational; no error (numerical value: 1)
  • SEVERITY_WARNING: Warning; no error (numerical value: 2)
  • SEVERITY_ERROR: (Default) Error; simulation continues (numerical value: 3)
  • SEVERITY_TRANS_EXIT: Error; the active transaction is aborted (numerical value: 4)
  • SEVERITY_PROCESS_EXIT: Error; the simulation is aborted (numerical value: 5)

Return value

  • true if successful
  • false otherwise
Parent topic: Verifying Functions
Related reference
SapGuiVerifyPropertyLong Function
SapGuiVerifyPropertyString Function
SapGuiVerifyPropertyShort Function
SapGuiVerifyPropertyByte Function
SapGuiVerifyPropertyFloat Function
SapGuiVerifyPropertyDouble Function


SapGuiVerifyPropertyByte Function

Action

This function verifies a property of type byte for any SapGui control.

Include file

SapGui.bdh

Syntax

SapGuiVerifyPropertyByte(  in sControlId : string,
                           in sName      : string,
                           in nValue     : number,
                           in nOptions   : number optional,
                           in nSeverity  : number optional := SEVERITY_ERROR ) : boolean;
Parameter | Description
sControlId | The unique ID of the control.
sName | The name of the property.
nValue | The value to be verified.
nOptions

This parameter specifies the type of check to be performed. Available options are:

  • SAPGUI_VERIFY_EQUAL. Verifies, whether the state of the checkbox's state is equal to the value specified in the second parameter.
  • SAPGUI_VERIFY_NOT_EQUAL. Verifies, whether the checkbox's state is not equal to the value specified in the second parameter.
nSeverity Optional: Severity of the error that is raised if the verification fails. Can be one of the following values:
  • SEVERITY_SUCCESS: Success; no error (numerical value: 0)
  • SEVERITY_INFORMATIONAL: Informational; no error (numerical value: 1)
  • SEVERITY_WARNING: Warning; no error (numerical value: 2)
  • SEVERITY_ERROR: (Default) Error; simulation continues (numerical value: 3)
  • SEVERITY_TRANS_EXIT: Error; the active transaction is aborted (numerical value: 4)
  • SEVERITY_PROCESS_EXIT: Error; the simulation is aborted (numerical value: 5)

Return value

  • true if successful
  • false otherwise
Parent topic: Verifying Functions
Related reference
SapGuiVerifyPropertyBoolean Function
SapGuiVerifyPropertyLong Function
SapGuiVerifyPropertyString Function
SapGuiVerifyPropertyShort Function
SapGuiVerifyPropertyFloat Function
SapGuiVerifyPropertyDouble Function


SapGuiVerifyPropertyDouble Function

Action

This function verifies a property of type Double for any SapGui control.

Include file

SapGui.bdh

Syntax

SapGuiVerifyPropertyDouble( in sControlId : string,
                            in sName      : string,
                            in fValue     : float,
                            in nOptions   : number optional,
                            in nSeverity  : number optional := SEVERITY_ERROR ) : boolean;
Parameter | Description
sControlId | The unique of the control.
sName | The name of the property
fValue | The value to be verified.
nOptions

This parameter specifies the type of check to be performed. Available options are:

  • SAPGUI_VERIFY_EQUAL. Verifies, whether the state of the checkbox's state is equal to the value specified in the second parameter.
  • SAPGUI_VERIFY_NOT_EQUAL. Verifies, whether the checkbox's state is not equal to the value specified in the second parameter.
nSeverity Optional: Severity of the error that is raised if the verification fails. Can be one of the following values:
  • SEVERITY_SUCCESS: Success; no error (numerical value: 0)
  • SEVERITY_INFORMATIONAL: Informational; no error (numerical value: 1)
  • SEVERITY_WARNING: Warning; no error (numerical value: 2)
  • SEVERITY_ERROR: (Default) Error; simulation continues (numerical value: 3)
  • SEVERITY_TRANS_EXIT: Error; the active transaction is aborted (numerical value: 4)
  • SEVERITY_PROCESS_EXIT: Error; the simulation is aborted (numerical value: 5)

Return value

  • true if successful
  • false otherwise
Parent topic: Verifying Functions
Related reference
SapGuiVerifyPropertyBoolean Function
SapGuiVerifyPropertyLong Function
SapGuiVerifyPropertyString Function
SapGuiVerifyPropertyShort Function
SapGuiVerifyPropertyByte Function
SapGuiVerifyPropertyFloat Function


SapGuiVerifyPropertyFloat Function

Action

This function verifies a property of type Float for any SapGui control.

Include file

SapGui.bdh

Syntax

SapGuiVerifyPropertyFloat( in sControlId : string,
                           in sName      : string,
                           in fValue     : float,
                           in nOptions   : number optional,
                           in nSeverity  : number optional := SEVERITY_ERROR ) : boolean;
Parameter | Description
sControlId | The unique of the control.
sName | The name of the property
fValue | The value to be verified.
nOptions

This parameter specifies the type of check to be performed. Available options are:

  • SAPGUI_VERIFY_EQUAL. Verifies, whether the state of the checkbox's state is equal to the value specified in the second parameter.
  • SAPGUI_VERIFY_NOT_EQUAL. Verifies, whether the checkbox's state is not equal to the value specified in the second parameter.
nSeverity Optional: Severity of the error that is raised if the verification fails. Can be one of the following values:
  • SEVERITY_SUCCESS: Success; no error (numerical value: 0)
  • SEVERITY_INFORMATIONAL: Informational; no error (numerical value: 1)
  • SEVERITY_WARNING: Warning; no error (numerical value: 2)
  • SEVERITY_ERROR: (Default) Error; simulation continues (numerical value: 3)
  • SEVERITY_TRANS_EXIT: Error; the active transaction is aborted (numerical value: 4)
  • SEVERITY_PROCESS_EXIT: Error; the simulation is aborted (numerical value: 5)

Return value

  • true if successful
  • false otherwise
Parent topic: Verifying Functions
Related reference
SapGuiVerifyPropertyBoolean Function
SapGuiVerifyPropertyLong Function
SapGuiVerifyPropertyString Function
SapGuiVerifyPropertyShort Function
SapGuiVerifyPropertyByte Function
SapGuiVerifyPropertyDouble Function


SapGuiVerifyPropertyLong Function

Action

This function verifies a property of type Long for any SapGui control.

Include file

SapGui.bdh

Syntax

SapGuiVerifyPropertyLong( in sControlId : string,
                          in sName      : string,
                          in nValue     : number,
                          in nOptions   : number optional,
                          in nSeverity  : number optional := SEVERITY_ERROR ) : boolean;
Parameter | Description
sControlId | The unique Id of the control.
sName | The name of the property
nValue | The value to be verified.
nOptions This parameter specifies the type of check to be performed. Available options are:
  • SAPGUI_VERIFY_EQUAL. Verifies, whether the state of the checkbox's state is equal to the value specified in the second parameter.
  • SAPGUI_VERIFY_NOT_EQUAL. Verifies, whether the checkbox's state is not equal to the value specified in the second parameter.
nSeverity Optional: Severity of the error that is raised if the verification fails. Can be one of the following values:
  • SEVERITY_SUCCESS: Success; no error (numerical value: 0)
  • SEVERITY_INFORMATIONAL: Informational; no error (numerical value: 1)
  • SEVERITY_WARNING: Warning; no error (numerical value: 2)
  • SEVERITY_ERROR: (Default) Error; simulation continues (numerical value: 3)
  • SEVERITY_TRANS_EXIT: Error; the active transaction is aborted (numerical value: 4)
  • SEVERITY_PROCESS_EXIT: Error; the simulation is aborted (numerical value: 5)

Return value

  • true if successful
  • false otherwise
Parent topic: Verifying Functions
Related reference
SapGuiVerifyPropertyBoolean Function
SapGuiVerifyPropertyString Function
SapGuiVerifyPropertyShort Function
SapGuiVerifyPropertyByte Function
SapGuiVerifyPropertyFloat Function
SapGuiVerifyPropertyDouble Function


SapGuiVerifyPropertyShort Function

Action

This function verifies a property of type Short for any SapGui control.

Include file

SapGui.bdh

Syntax

SapGuiVerifyPropertyShort( in sControlId : string,
                           in sName      : string,
                           in nValue     : number,
                           in nOptions   : number optional,
                           in nSeverity  : number optional := SEVERITY_ERROR ) : boolean;
Parameter | Description
sControlId | The unique Id of the control.
sName | The name of the property
nValue | The value to be verified.
nOptions

This parameter specifies the type of check to be performed. Available options are:

  • SAPGUI_VERIFY_EQUAL. Verifies, whether the state of the checkbox's state is equal to the value specified in the second parameter.
  • SAPGUI_VERIFY_NOT_EQUAL. Verifies, whether the checkbox's state is not equal to the value specified in the second parameter.
nSeverity Optional: Severity of the error that is raised if the verification fails. Can be one of the following values:
  • SEVERITY_SUCCESS: Success; no error (numerical value: 0)
  • SEVERITY_INFORMATIONAL: Informational; no error (numerical value: 1)
  • SEVERITY_WARNING: Warning; no error (numerical value: 2)
  • SEVERITY_ERROR: (Default) Error; simulation continues (numerical value: 3)
  • SEVERITY_TRANS_EXIT: Error; the active transaction is aborted (numerical value: 4)
  • SEVERITY_PROCESS_EXIT: Error; the simulation is aborted (numerical value: 5)

Return value

  • true if successful
  • false otherwise
Parent topic: Verifying Functions
Related reference
SapGuiVerifyPropertyBoolean Function
SapGuiVerifyPropertyLong Function
SapGuiVerifyPropertyString Function
SapGuiVerifyPropertyByte Function
SapGuiVerifyPropertyFloat Function
SapGuiVerifyPropertyDouble Function


SapGuiVerifyPropertyString Function

Action

This function verifies a property of type string for any SapGui control.

Include file

SapGui.bdh

Syntax

SapGuiVerifyPropertyString( in sControlId : string,
                            in sName      : string,
                            in sValue     : string,
                            in nOptions   : number optional,
                            in nSeverity  : number optional := SEVERITY_ERROR ) : boolean;
Parameter | Description
sControlId | The unique Id of the control.
sName | The name of the property
sValue | The value to be verified.
nOptions

This parameter specifies the type of check to be performed. Available options are:

  • SAPGUI_VERIFY_EQUAL. Verifies, whether the state of the checkbox's state is equal to the value specified in the second parameter.
  • SAPGUI_VERIFY_NOT_EQUAL. Verifies, whether the checkbox's state is not equal to the value specified in the second parameter.
nSeverity Optional: Severity of the error that is raised if the verification fails. Can be one of the following values:
  • SEVERITY_SUCCESS: Success; no error (numerical value: 0)
  • SEVERITY_INFORMATIONAL: Informational; no error (numerical value: 1)
  • SEVERITY_WARNING: Warning; no error (numerical value: 2)
  • SEVERITY_ERROR: (Default) Error; simulation continues (numerical value: 3)
  • SEVERITY_TRANS_EXIT: Error; the active transaction is aborted (numerical value: 4)
  • SEVERITY_PROCESS_EXIT: Error; the simulation is aborted (numerical value: 5)

Return value

  • true if successful
  • false otherwise
Parent topic: Verifying Functions
Related reference
SapGuiVerifyPropertyBoolean Function
SapGuiVerifyPropertyLong Function
SapGuiVerifyPropertyShort Function
SapGuiVerifyPropertyByte Function
SapGuiVerifyPropertyFloat Function
SapGuiVerifyPropertyDouble Function


SapGuiVerifyRadioValue Function

Action

This function verifies a SapGui radio button control. It can be used to ensure whether a radio button is checked or not checked.

Include file

SapGui.bdh

Syntax

SapGuiVerifyRadioValue( in sControlId : string,
                        in bValue     : boolean,
                        in nOptions   : number optional,
                        in nSeverity  : number optional := SEVERITY_ERROR ) : boolean;
Parameter | Description
sControlId | The unique id of a checkbox control
bValue | This parameter is set to "true" if the check as specified in the third parameter results in success. Otherwise it is set to "false".
nOptions This parameter specifies the type of check to be performed. Available options are:
  • SAPGUI_VERIFY_EQUAL. Verifies, whether the state of the checkbox's state is equal to the value specified in the second parameter.
  • SAPGUI_VERIFY_NOT_EQUAL. Verifies, whether the checkbox's state is not equal to the value specified in the second parameter.
nSeverity Optional: Severity of the error that is raised if the verification fails. Can be one of the following values:
  • SEVERITY_SUCCESS: Success; no error (numerical value: 0)
  • SEVERITY_INFORMATIONAL: Informational; no error (numerical value: 1)
  • SEVERITY_WARNING: Warning; no error (numerical value: 2)
  • SEVERITY_ERROR: (Default) Error; simulation continues (numerical value: 3)
  • SEVERITY_TRANS_EXIT: Error; the active transaction is aborted (numerical value: 4)
  • SEVERITY_PROCESS_EXIT: Error; the simulation is aborted (numerical value: 5)

Return value

  • true if successful
  • false otherwise

Example

transaction TMain
  var
    sConnID : string;
  begin
    // Connecting to SAP
    sConnID := SapGuiOpenConnection( " /SAP_CODEPAGE=1100 /FULLMENU 10.5.2.132 0 /3");
    SapGuiSetActiveConnection(sConnID);
    SapGuiSetActiveSession("ses[0]");

    // SAP
    SapGuiSetActiveWindow("wnd[0]", "SAP", SAPGUI_MATCH_ExactNoCase);
    SapGuiWindowAction(SAPGUI_WND_MAXIMIZE);

    // Logon to SAP System
    // Before running a test you have to customize the password parameter!
    ThinkTime(2.3);
    SapGuiLogon("ddic", "*******", "000", "");

    // SAP Easy Access
    SapGuiIgnoreError(SAPENGINE_STATUSBAR_CHANGED, SEVERITY_SUCCESS);
    SapGuiSetActiveWindow("wnd[0]", "SAP Easy Access", SAPGUI_MATCH_ExactNoCase);

    SapGuiIgnoreError(SAPENGINE_STATUSBAR_CHANGED, SEVERITY_SUCCESS);
    ThinkTime(5.9);
    SapGuiPressButton("tbar[1]/btn[17]", " Other menu");
    ThinkTime(2.7);
    SapGuiSetActiveWindow("wnd[1]", "Wertebereich einschränken", SAPGUI_MATCH_ExactNoCase);
    SapGuiSetFocus("usr/tabsG_SELONETABSTRIP/tabpTAB002/chkG_SELPOP_STATE-BUTTON");
    SapGuiSetCheckbox("usr/tabsG_SELONETABSTRIP/220/chkG_SELPOP_STATE-BUTTON", true, "No restriction");
    SapGuiVerifyRadioValue( "/usr/tabsG_SELONETABSTRIP/DH4:0220/chkG_SELPOP_RADIO-BUTTON", true, SAPGUI_VERIFY_EQUAL, SEVERITY_ERROR);
  end TMain;
Parent topic: Verifying Functions


SapGuiVerifyStatusBarText Function

Action

This function verifies the current statusbar text of the SapGui application.

Include file

SapGui.bdh

Syntax

SapGuiVerifyStatusBarText( in sValue    : string,
                           in nOptions  : number optional,
                           in nSeverity : number optional := SEVERITY_ERROR ) : boolean;
Parameter | Description
sValue | Value to be compared with the current statusbar text.
nOptions This parameter specifies the type of check to be performed. Available options are:
  • SAPGUI_VERIFY_EQUAL. Verifies, whether the state of the checkbox's state is equal to the value specified in the second parameter.
  • SAPGUI_VERIFY_NOT_EQUAL. Verifies, whether the checkbox's state is not equal to the value specified in the second parameter.
nSeverity Optional: Severity of the error that is raised if the verification fails. Can be one of the following values:
  • SEVERITY_SUCCESS: Success; no error (numerical value: 0)
  • SEVERITY_INFORMATIONAL: Informational; no error (numerical value: 1)
  • SEVERITY_WARNING: Warning; no error (numerical value: 2)
  • SEVERITY_ERROR: (Default) Error; simulation continues (numerical value: 3)
  • SEVERITY_TRANS_EXIT: Error; the active transaction is aborted (numerical value: 4)
  • SEVERITY_PROCESS_EXIT: Error; the simulation is aborted (numerical value: 5)

Return value

  • true if successful
  • false otherwise

Example

transaction TMain
  var
  begin
    // Connecting to SAP
    sConnID := SapGuiOpenConnection( " /SAP_CODEPAGE=1100 /FULLMENU 10.5.2.132 0 /3");
    SapGuiSetActiveConnection(sConnID);
    SapGuiSetActiveSession("ses[0]");

    // SAP
    SapGuiSetActiveWindow("wnd[0]", "SAP", SAPGUI_MATCH_ExactNoCase);
    SapGuiWindowAction(SAPGUI_WND_MAXIMIZE);

    // Logon to SAP System
    // Before running a test you have to customize the password parameter!
    ThinkTime(2.0);
    SapGuiLogon("ddic", "minisap", "000", "");
    SapGuiVerifyStatusBarText("verification", SAPGUI_VERIFY_EQUAL, SEVERITY_ERROR);
  end TMain;
Parent topic: Verifying Functions


SapGuiVerifyTableCheckbox Function

Action

This function verifies whether a check box in a table cell is checked.

Include file

SapGui.bdh

Syntax

SapGuiVerifyTableCheckbox( in sControlId : string,
                           in nRow       : number,
                           in nCol       : number,
                           in bValue     : boolean,
                           in nOptions   : number optional,
                           in nSeverity  : number optional := SEVERITY_ERROR ) : boolean;
Parameter | Description
sControlId | The unique id of the table.
nRow | The row of the cell to be verified.
nCol | The column of the cell to be verified.
bValue | The value to be verified.
nOptions

This parameter specifies the type of check to be performed. Available options are:

  • SAPGUI_VERIFY_EQUAL. Verifies, whether the state of the checkbox's state is equal to the value specified in the second parameter.
  • SAPGUI_VERIFY_NOT_EQUAL. Verifies, whether the checkbox's state is not equal to the value specified in the second parameter.
nSeverity Optional: Severity of the error that is raised if the verification fails. Can be one of the following values:
  • SEVERITY_SUCCESS: Success; no error (numerical value: 0)
  • SEVERITY_INFORMATIONAL: Informational; no error (numerical value: 1)
  • SEVERITY_WARNING: Warning; no error (numerical value: 2)
  • SEVERITY_ERROR: (Default) Error; simulation continues (numerical value: 3)
  • SEVERITY_TRANS_EXIT: Error; the active transaction is aborted (numerical value: 4)
  • SEVERITY_PROCESS_EXIT: Error; the simulation is aborted (numerical value: 5)

Return value

  • true if successful
  • false otherwise

Example

transaction TMain
  var
    sConnID : string;
  begin
    sConnID := SapGuiOpenConnection( " /SAP_CODEPAGE=1100 /FULLMENU 10.5.2.132 0 /3");
    SapGuiSetActiveConnection(sConnID);
    SapGuiSetActiveSession("ses[0]");
    SapGuiSetActiveWindow("wnd[0]", "SAP", SAPGUI_MATCH_ExactNoCase);
    SapGuiWindowAction(SAPGUI_WND_MAXIMIZE);
    ThinkTime(4.3);
    SapGuiLogon("ddic", "*******", "000", "");
    SapGuiIgnoreError(SAPENGINE_STATUSBAR_CHANGED, SEVERITY_SUCCESS);
    ThinkTime(2.4);
    SapGuiSetActiveWindow("wnd[0]", "SAP Easy Access", SAPGUI_MATCH_ExactNoCase);
    SapGuiTreeExpandNode("usr/cntlIMAGE_CONTAINER/shellcont/shell/shellcont[0]/shell""Office", "0000000003", "Expand\\Office");

    // NodeName: Telephone Integration
    // NodePath: 2\1\2
    SapGuiTreeExpandNode("usr/cntlIMAGE_CONTAINER/shellcont/shell/shellcont[0]/shell", "Telephone Integration", "0000000005", "Expand\\Telephone Integration");

    // NodeName: Extended Settings
    // NodePath: 2\1\2\2
    SapGuiTreeSelectNode("usr/cntlIMAGE_CONTAINER/shellcont/shell/shellcont[0]/shell", "Extended Settings",  "0000000007", false, "SelNode\\Extended Settings");

    // NodeName: Favorites
    // NodePath: 1
    SapGuiSelectTopNode("usr/cntlIMAGE_CONTAINER/shellcont/shell/shellcont[0]/shell", "Favorites", "Favo", "TopNode\\Favorites");
    SapGuiTreeDblClickNode( "usr/cntlIMAGE_CONTAINER/shellcont/shell/shellcont[0]/shell","Extended Settings", "0000000007", "DblClNode\\Extended Settings");
    ThinkTime(2.3);
    SapGuiSetActiveWindow("wnd[0]", "SAPphone: Administration", SAPGUI_MATCH_ExactNoCase);

    // Simulate inbound call
    SapGuiPressButton("usr/btn%_AUTOTEXT005", " Simulate inbound call");

    // Daten des Anrufs eingeben
    ThinkTime(8.5);
    SapGuiSetActiveWindow("wnd[1]", "Daten des Anrufs eingeben", SAPGUI_MATCH_ExactNoCase);
    SapGuiTableSetText("usr/tblSAPLPHOAD102_ADDITIONAL", 0, 0, "asdf");
    SapGuiTableSetFocusCell("usr/tblSAPLPHOAD102_ADDITIONAL", 0, 0, "asdf");
    SapGuiVerifyTableCheckbox("usr/tblSAPLPHOAD102_ADDITIONAL", 0, 0, true, SAPGUI_VERIFY_EQUAL, SEVERITY_ERROR);
  end TMain;
Parent topic: Verifying Functions


SapGuiVerifyTableRadioValue Function

Action

This function verifies whether a radio button in a table cell is selected.

Include file

SapGui.bdh

Syntax

SapGuiVerifyTableRadioValue( in sControlId : string,
                             in nRow       : number,
                             in nCol       : number,
                             in bValue     : boolean,
                             in nOptions   : number optional,
                             in nSeverity  : number optional := SEVERITY_ERROR ) : boolean;
Parameter | Description
sControlId | The unique id of the table.
nRow | The row of the cell to be verified.
nCol | The column of the cell to be verified.
bValue | The value to be verified.
nOptions This parameter specifies the type of check to be performed. Available options are:
  • SAPGUI_VERIFY_EQUAL. Verifies, whether the state of the checkbox's state is equal to the value specified in the second parameter.
  • SAPGUI_VERIFY_NOT_EQUAL. Verifies, whether the checkbox's state is not equal to the value specified in the second parameter.
nSeverity Optional: Severity of the error that is raised if the verification fails. Can be one of the following values:
  • SEVERITY_SUCCESS: Success; no error (numerical value: 0)
  • SEVERITY_INFORMATIONAL: Informational; no error (numerical value: 1)
  • SEVERITY_WARNING: Warning; no error (numerical value: 2)
  • SEVERITY_ERROR: (Default) Error; simulation continues (numerical value: 3)
  • SEVERITY_TRANS_EXIT: Error; the active transaction is aborted (numerical value: 4)
  • SEVERITY_PROCESS_EXIT: Error; the simulation is aborted (numerical value: 5)

Return value

  • true if successful
  • false otherwise

Example

transaction TMain
  var
    sConnID : string;
  begin
    sConnID := SapGuiOpenConnection( " /SAP_CODEPAGE=1100 /FULLMENU 10.5.2.132 0 /3");
    SapGuiSetActiveConnection(sConnID);
    SapGuiSetActiveSession("ses[0]");
    SapGuiSetActiveWindow("wnd[0]", "SAP", SAPGUI_MATCH_ExactNoCase);
    SapGuiWindowAction(SAPGUI_WND_MAXIMIZE);
    ThinkTime(4.3);
    SapGuiLogon("ddic", "*******", "000", "");
    SapGuiIgnoreError(SAPENGINE_STATUSBAR_CHANGED, SEVERITY_SUCCESS);
    ThinkTime(2.4);
    SapGuiSetActiveWindow("wnd[0]", "SAP Easy Access", SAPGUI_MATCH_ExactNoCase);
    SapGuiTreeExpandNode("usr/cntlIMAGE_CONTAINER/shellcont/shell/shellcont[0]/shell", "Office", "0000000003", "Expand\\Office");

    // NodeName: Telephone Integration
    // NodePath: 2\1\2
    SapGuiTreeExpandNode("usr/cntlIMAGE_CONTAINER/shellcont/shell/shellcont[0]/shell", "Telephone Integration", "0000000005", "Expand\\Telephone Integration");

    // NodeName: Extended Settings
    // NodePath: 2\1\2\2
    SapGuiTreeSelectNode("usr/cntlIMAGE_CONTAINER/shellcont/shell/shellcont[0]/shell", "Extended Settings", "0000000007", false, "SelNode\\Extended Settings");

    // NodeName: Favorites
    // NodePath: 1
    SapGuiSelectTopNode("usr/cntlIMAGE_CONTAINER/shellcont/shell/shellcont[0]/shell", "Favorites", "Favo", "TopNode\\Favorites");
    SapGuiTreeDblClickNode( "usr/cntlIMAGE_CONTAINER/shellcont/shell/shellcont[0]/shell", "Extended Settings", "0000000007", "DblClNode\\Extended Settings");
    ThinkTime(2.3);
    SapGuiSetActiveWindow("wnd[0]", "SAPphone: Administration", SAPGUI_MATCH_ExactNoCase);

    // Simulate inbound call
    SapGuiPressButton("usr/btn%_AUTOTEXT005", " Simulate inbound call");

    // Daten des Anrufs eingeben
    ThinkTime(8.5);
    SapGuiSetActiveWindow("wnd[1]", "Daten des Anrufs eingeben", SAPGUI_MATCH_ExactNoCase);
    SapGuiTableSetText("usr/tblSAPLPHOAD102_ADDITIONAL", 0, 0, "asdf");
    SapGuiTableSetFocusCell("usr/tblSAPLPHOAD102_ADDITIONAL", 0, 0, "asdf");
    SapGuiVerifyTableRadioValue("usr/tblSAPLPHOAD102_ADDITIONAL", 0, 0, true, SAPGUI_VERIFY_EQUAL, SEVERITY_ERROR);
  end TMain;
Parent topic: Verifying Functions


SapGuiVerifyTableRowSelected Function

Action

This function verifies whether a check box in a table cell is checked.

Include file

SapGui.bdh

Syntax

SapGuiVerifyTableRowSelected( in sControlId : string,
                              in nRow       : number,
                              in nOptions   : number optional,
                              in nSeverity  : number optional := SEVERITY_ERROR ) : boolean;
Parameter | Description
sControlId | The unique id of the table.
nRow | The row to be verified.
nOptions This parameter specifies the type of check to be performed. Available options are:
  • SAPGUI_VERIFY_EQUAL. Verifies, whether the state of the checkbox's state is equal to the value specified in the second parameter.
  • SAPGUI_VERIFY_NOT_EQUAL. Verifies, whether the checkbox's state is not equal to the value specified in the second parameter.
nSeverity Optional: Severity of the error that is raised if the verification fails. Can be one of the following values:
  • SEVERITY_SUCCESS: Success; no error (numerical value: 0)
  • SEVERITY_INFORMATIONAL: Informational; no error (numerical value: 1)
  • SEVERITY_WARNING: Warning; no error (numerical value: 2)
  • SEVERITY_ERROR: (Default) Error; simulation continues (numerical value: 3)
  • SEVERITY_TRANS_EXIT: Error; the active transaction is aborted (numerical value: 4)
  • SEVERITY_PROCESS_EXIT: Error; the simulation is aborted (numerical value: 5)

Return value

  • true if successful
  • false otherwise

Example

transaction TMain
  var
    sConnID : string;
  begin
    sConnID := SapGuiOpenConnection( " /SAP_CODEPAGE=1100 /FULLMENU 10.5.2.132 0 /3");
    SapGuiSetActiveConnection(sConnID);
    SapGuiSetActiveSession("ses[0]");
    SapGuiSetActiveWindow("wnd[0]", "SAP", SAPGUI_MATCH_ExactNoCase);
    SapGuiWindowAction(SAPGUI_WND_MAXIMIZE);
    ThinkTime(4.3);
    SapGuiLogon("ddic", "*******", "000", "");
    SapGuiIgnoreError(SAPENGINE_STATUSBAR_CHANGED, SEVERITY_SUCCESS);
    ThinkTime(2.4);
    SapGuiSetActiveWindow("wnd[0]", "SAP Easy Access", SAPGUI_MATCH_ExactNoCase);
    SapGuiTreeExpandNode("usr/cntlIMAGE_CONTAINER/shellcont/shell/shellcont[0]/shell", "Office",
    "0000000003", "Expand\\Office");

    // NodeName: Telephone Integration
    // NodePath: 2\1\2
    SapGuiTreeExpandNode("usr/cntlIMAGE_CONTAINER/shellcont/shell/shellcont[0]/shell", "Telephone Integration",
    "0000000005", "Expand\\Telephone Integration");

    // NodeName: Extended Settings
    // NodePath: 2\1\2\2
    SapGuiTreeSelectNode("usr/cntlIMAGE_CONTAINER/shellcont/shell/shellcont[0]/shell", "Extended Settings",
    "0000000007", false, "SelNode\\Extended Settings");

    // NodeName: Favorites
    // NodePath: 1
    SapGuiSelectTopNode("usr/cntlIMAGE_CONTAINER/shellcont/shell/shellcont[0]/shell", "Favorites", "Favo",
    "TopNode\\Favorites");
    SapGuiTreeDblClickNode( "usr/cntlIMAGE_CONTAINER/shellcont/shell/shellcont[0]/shell", "Extended Settings",
    "0000000007", "DblClNode\\Extended Settings");
    ThinkTime(2.3);
    SapGuiSetActiveWindow("wnd[0]", "SAPphone: Administration", SAPGUI_MATCH_ExactNoCase);

    // Simulate inbound call
    SapGuiPressButton("usr/btn%_AUTOTEXT005", " Simulate inbound call");

    // Daten des Anrufs eingeben
    ThinkTime(8.5);
    SapGuiSetActiveWindow("wnd[1]", "Daten des Anrufs eingeben", SAPGUI_MATCH_ExactNoCase);
    SapGuiTableSetText("usr/tblSAPLPHOAD102_ADDITIONAL", 0, 0, "asdf");
    SapGuiTableSetFocusCell("usr/tblSAPLPHOAD102_ADDITIONAL", 0, 0, "asdf");
    SapGuiVerifyTableRowSelected("usr/tblSAPLPHOAD102_ADDITIONAL", 0, SAPGUI_VERIFY_EQUAL, SEVERITY_ERROR);
  end TMain;
Parent topic: Verifying Functions


SapGuiVerifyTableText Function

Action

This function verifies the text of a table cell.

Include file

SapGui.bdh

Syntax

SapGuiVerifyTableText( in sControlId : string,
                       in nRow       : number,
                       in nCol       : number,
                       in sValue     : string,
                       in nOptions   : number optional,
                       in nSeverity  : number optional := SEVERITY_ERROR ) : boolean;
Parameter | Description
sControlId | The unique id of the table.
nRow | The row of the cell to be verified.
nCol | The column of the cell to be verified.
sValue | The value to be verified.
nOptions This parameter specifies the type of check to be performed. Available options are:
  • SAPGUI_VERIFY_EQUAL. Verifies, whether the state of the checkbox's state is equal to the value specified in the second parameter.
  • SAPGUI_VERIFY_NOT_EQUAL. Verifies, whether the checkbox's state is not equal to the value specified in the second parameter.
  • SAPGUI_VERIFY_CASE_SENSITIVE. Performs a case sensitive comparison. By default the comparison is done case insensitive.
  • SAPGUI_VERIFY_IGNORE_WHITESPACE. Ignores any whitespaces found in the values to be compared.
nSeverity Optional: Severity of the error that is raised if the verification fails. Can be one of the following values:
  • SEVERITY_SUCCESS: Success; no error (numerical value: 0)
  • SEVERITY_INFORMATIONAL: Informational; no error (numerical value: 1)
  • SEVERITY_WARNING: Warning; no error (numerical value: 2)
  • SEVERITY_ERROR: (Default) Error; simulation continues (numerical value: 3)
  • SEVERITY_TRANS_EXIT: Error; the active transaction is aborted (numerical value: 4)
  • SEVERITY_PROCESS_EXIT: Error; the simulation is aborted (numerical value: 5)

Return value

  • true if successful
  • false otherwise

Example

transaction TMain
  var
    sConnID : string;
  begin
    sConnID := SapGuiOpenConnection( " /SAP_CODEPAGE=1100 /FULLMENU 10.5.2.132 0 /3");
    SapGuiSetActiveConnection(sConnID);
    SapGuiSetActiveSession("ses[0]");
    SapGuiSetActiveWindow("wnd[0]", "SAP", SAPGUI_MATCH_ExactNoCase);
    SapGuiWindowAction(SAPGUI_WND_MAXIMIZE);
    ThinkTime(4.3);
    SapGuiLogon("ddic", "*******", "000", "");
    SapGuiIgnoreError(SAPENGINE_STATUSBAR_CHANGED, SEVERITY_SUCCESS);
    ThinkTime(2.4);
    SapGuiSetActiveWindow("wnd[0]", "SAP Easy Access", SAPGUI_MATCH_ExactNoCase);
    SapGuiTreeExpandNode("usr/cntlIMAGE_CONTAINER/shellcont/shell/shellcont[0]/shell", "Office",
    "0000000003", "Expand\\Office");

    // NodeName: Telephone Integration
    // NodePath: 2\1\2
    SapGuiTreeExpandNode("usr/cntlIMAGE_CONTAINER/shellcont/shell/shellcont[0]/shell", "Telephone Integration",
    "0000000005", "Expand\\Telephone Integration");

    // NodeName: Extended Settings
    // NodePath: 2\1\2\2
    SapGuiTreeSelectNode("usr/cntlIMAGE_CONTAINER/shellcont/shell/shellcont[0]/shell", "Extended Settings",
    "0000000007", false, "SelNode\\Extended Settings");

    // NodeName: Favorites
    // NodePath: 1
    SapGuiSelectTopNode("usr/cntlIMAGE_CONTAINER/shellcont/shell/shellcont[0]/shell", "Favorites", "Favo",
    "TopNode\\Favorites");
    SapGuiTreeDblClickNode( "usr/cntlIMAGE_CONTAINER/shellcont/shell/shellcont[0]/shell", "Extended Settings",
    "0000000007", "DblClNode\\Extended Settings");
    ThinkTime(2.3);
    SapGuiSetActiveWindow("wnd[0]", "SAPphone: Administration", SAPGUI_MATCH_ExactNoCase);

    // Simulate inbound call
    SapGuiPressButton("usr/btn%_AUTOTEXT005", " Simulate inbound call");

    // Daten des Anrufs eingeben
    ThinkTime(8.5);
    SapGuiSetActiveWindow("wnd[1]", "Daten des Anrufs eingeben", SAPGUI_MATCH_ExactNoCase);
    SapGuiTableSetText("usr/tblSAPLPHOAD102_ADDITIONAL", 0, 0, "asdf");
    SapGuiTableSetFocusCell("usr/tblSAPLPHOAD102_ADDITIONAL", 0, 0, "asdf");
    SapGuiVerifyTableText("usr/tblSAPLPHOAD102_ADDITIONAL", 0, 0, "asdf",
    SAPGUI_VERIFY_EQUAL, SEVERITY_ERROR);
  end TMain;
Parent topic: Verifying Functions


SapGuiVerifyTabSelected Function

Action

This function verifies whether a tab is currently the selected one inside a tab control.

Include file

SapGui.bdh

Syntax

SapGuiVerifyTabSelected( in sControlId : string,
                         in bSelected  : boolean,
                         in nSeverity  : numberoptional := SEVERITY_ERROR ) : boolean;
Parameter | Description
sControlId | The unique id of the tab.
bSelected | If the parameter is set to "true", the verification will succeed when the tab is selected.
nSeverity Optional: Severity of the error that is raised if the verification fails. Can be one of the following values:
  • SEVERITY_SUCCESS: Success; no error (numerical value: 0)
  • SEVERITY_INFORMATIONAL: Informational; no error (numerical value: 1)
  • SEVERITY_WARNING: Warning; no error (numerical value: 2)
  • SEVERITY_ERROR: (Default) Error; simulation continues (numerical value: 3)
  • SEVERITY_TRANS_EXIT: Error; the active transaction is aborted (numerical value: 4)
  • SEVERITY_PROCESS_EXIT: Error; the simulation is aborted (numerical value: 5)

Return value

  • true if successful
  • false otherwise

Example

transaction TMain
  var
    sText : string;
    sConnID : string;
  begin

    // Connecting to SAP
    sConnID := SapGuiOpenConnection( " /SAP_CODEPAGE=1100 /FULLMENU 10.5.2.132 0 /3");
    SapGuiSetActiveConnection(sConnID);
    SapGuiSetActiveSession("ses[0]");

    // SAP
    SapGuiSetActiveWindow("wnd[0]", "SAP", SAPGUI_MATCH_ExactNoCase);
    SapGuiWindowAction(SAPGUI_WND_MAXIMIZE);

    // Logon to SAP System
    // Before running a test you have to customize the password parameter!
    ThinkTime(2.0);
    SapGuiLogon("ddic", "minisap", "000", "");
    SapGuiVerifyTabSelected("/usr/tabsG_SELONETABSTRIP/tabpTAB002/", true, SEVERITY_ERROR);
  end TMain;
Parent topic: Verifying Functions


SapGuiVerifyTextValue Function

Action

This function verifies the value of a SapGui text control. This may either be a label or an edit field.

Include file

SapGui.bdh

Syntax

SapGuiVerifyTextValue( in sControlId : string,
                       in sText      : string,
                       in nOptions   : number optional,
                       in nSeverity  : number optional := SEVERITY_ERROR ) : boolean;
Parameter | Description
sControlId | The unique id of a text element or edit field.
sText | Compares the current text of the control to the value specified in this parameter according to the comparison flags in the third parameter.
nOptions This parameter specifies the type of check to be performed. Available options are:
  • SAPGUI_VERIFY_EQUAL. Verifies, whether the state of the checkbox's state is equal to the value specified in the second parameter.
  • SAPGUI_VERIFY_NOT_EQUAL. Verifies, whether the checkbox's state is not equal to the value specified in the second parameter.
  • SAPGUI_VERIFY_CASE_SENSITIVE. Performs a case sensitive comparison. By default the comparison is done case insensitive.
  • SAPGUI_VERIFY_IGNORE_WHITESPACE. Ignores any whitespaces found in the values to be compared.
nSeverity Optional: Severity of the error that is raised if the verification fails. Can be one of the following values:
  • SEVERITY_SUCCESS: Success; no error (numerical value: 0)
  • SEVERITY_INFORMATIONAL: Informational; no error (numerical value: 1)
  • SEVERITY_WARNING: Warning; no error (numerical value: 2)
  • SEVERITY_ERROR: (Default) Error; simulation continues (numerical value: 3)
  • SEVERITY_TRANS_EXIT: Error; the active transaction is aborted (numerical value: 4)
  • SEVERITY_PROCESS_EXIT: Error; the simulation is aborted (numerical value: 5)

Return value

  • true if successful
  • false otherwise

Example

transaction TMain
  var
    sText : string;
    sConnID : string;
  begin

    // Connecting to SAP
    sConnID := SapGuiOpenConnection( " /SAP_CODEPAGE=1100 /FULLMENU 10.5.2.132 0 /3");
    SapGuiSetActiveConnection(sConnID);
    SapGuiSetActiveSession("ses[0]");

    // SAP
    SapGuiSetActiveWindow("wnd[0]", "SAP", SAPGUI_MATCH_ExactNoCase);
    SapGuiWindowAction(SAPGUI_WND_MAXIMIZE);
    SapGuiLogon("ddic", "minisap", "000", "");
    SapGuiVerifyTextValue( "/usr/sub:SAPMSYST:0020/txtINFO_TAB-TDLINE[8,0]", "Only released for training purposes", SAPGUI_VERIFY_EQUAL | SAPGUI_VERIFY_CASE_SENSITIVE,OR);
  end TMain;
Parent topic: Verifying Functions


SapGuiVerifyTreeCheckbox Function

Action

This function verifies a SapGui check box attached to an item in a SapGui tree. It can be used to ensure whether a check box is checked or not checked.

Include file

SapGui.bdh

Syntax

SapGuiVerifyTreeCheckbox( in sControlId : string,
                          in sNode      : string,
                          in sItem      : string,
                          in bValue     : boolean,
                          in nOptions   : number optional,
                          in nSeverity  : number optional := SEVERITY_ERROR ) : boolean;
Parameter | Description
sControlId | The unique id of a tree control.
sNode | Specifies the node of the tree.
sItem | The item where the checkbox is located.
bValue | The value to be verified.
nOptions This parameter specifies the type of check to be performed. Available options are:
  • SAPGUI_VERIFY_EQUAL. Verifies, whether the state of the checkbox's state is equal to the value specified in the second parameter.
  • SAPGUI_VERIFY_NOT_EQUAL. Verifies, whether the checkbox's state is not equal to the value specified in the second parameter.
nSeverity Optional: Severity of the error that is raised if the verification fails. Can be one of the following values:
  • SEVERITY_SUCCESS: Success; no error (numerical value: 0)
  • SEVERITY_INFORMATIONAL: Informational; no error (numerical value: 1)
  • SEVERITY_WARNING: Warning; no error (numerical value: 2)
  • SEVERITY_ERROR: (Default) Error; simulation continues (numerical value: 3)
  • SEVERITY_TRANS_EXIT: Error; the active transaction is aborted (numerical value: 4)
  • SEVERITY_PROCESS_EXIT: Error; the simulation is aborted (numerical value: 5)

Return value

  • true if successful
  • false otherwise

Example

transaction TMain
  var
    sConnID : string;
  begin

    // Connecting to SAP
    sConnID := SapGuiOpenConnection( " /SAP_CODEPAGE=1100 /FULLMENU 10.5.2.132 0 /3");
    SapGuiSetActiveConnection(sConnID);
    SapGuiSetActiveSession("ses[0]");

    // SAP
    SapGuiSetActiveWindow("wnd[0]", "SAP", SAPGUI_MATCH_ExactNoCase);
    SapGuiWindowAction(SAPGUI_WND_MAXIMIZE);

    // Logon to SAP System
    // Before running a test you have to customize the password parameter!
    ThinkTime(2.0);
    SapGuiLogon("ddic", "*******", "000", "");

    // SAP Easy Access
    SapGuiIgnoreError(SAPENGINE_STATUSBAR_CHANGED, SEVERITY_SUCCESS);
    ThinkTime(3.7);
    SapGuiSetActiveWindow("wnd[0]", "SAP Easy Access", SAPGUI_MATCH_ExactNoCase);

    // NodeName: Office
    // NodePath: 2\1
    ThinkTime(7.3);
    SapGuiTreeExpandNode( "usr/cntlIMAGE_CONTAINER/shellcont/shell/shellcont[0]/shell", "Office", 0000000003", "Expand\\Office");
    SapGuiTreeExpandNode( "usr/cntlIMAGE_CONTAINER/shellcont/shell/shellcont[0]/shell", "Telephone Integration", 0000000005", "Expand\\Telephone Integration");
    SapGuiVerifyTreeCheckbox( "usr/cntlIMAGE_CONTAINER/shellcont/shell/shellcont[0]/shell", "Office", "0000000003", true, SAPGUI_VERIFY_EQUAL, SEVERITY_ERROR);
  end TMain;
Parent topic: Verifying Functions


SapGuiVerifyTreeItemText Function

Action

This function verifies the text of an item in a SapGui tree control.

Include file

SapGui.bdh

Syntax

SapGuiVerifyTreeItemText( in sControlId : string,
                          in sNode      : string,
                          in sItem      : string,
                          in sValue     : string,
                          in nOptions   : number optional,
                          in nSeverity  : number optional := SEVERITY_ERROR ) : boolean ;
Parameter | Description
sControlId | The unique id of a tree control.
sNode | The name of the node.
sItem | The name of the item to be verified.
sValue | Compares the current text of the control to the value specified in this parameter according to the comparison flags in the third parameter.
nOptions This parameter specifies the type of check to be performed. Available options are:
  • SAPGUI_VERIFY_EQUAL. Verifies, whether the state of the checkbox's state is equal to the value specified in the second parameter.
  • SAPGUI_VERIFY_NOT_EQUAL. Verifies, whether the checkbox's state is not equal to the value specified in the second parameter.
  • SAPGUI_VERIFY_CASE_SENSITIVE. Performs a case sensitive comparison. By default the comparison is done case insensitive.
  • SAPGUI_VERIFY_IGNORE_WHITESPACE. Ignores any whitespaces found in the values to be compared.
nSeverity Optional: Severity of the error that is raised if the verification fails. Can be one of the following values:
  • SEVERITY_SUCCESS: Success; no error (numerical value: 0)
  • SEVERITY_INFORMATIONAL: Informational; no error (numerical value: 1)
  • SEVERITY_WARNING: Warning; no error (numerical value: 2)
  • SEVERITY_ERROR: (Default) Error; simulation continues (numerical value: 3)
  • SEVERITY_TRANS_EXIT: Error; the active transaction is aborted (numerical value: 4)
  • SEVERITY_PROCESS_EXIT: Error; the simulation is aborted (numerical value: 5)

Return value

  • true if successful
  • false otherwise

Example

transaction TMain
  var
    sConnID : string;
  begin

    // Connecting to SAP
    sConnID := SapGuiOpenConnection( " /SAP_CODEPAGE=1100 /FULLMENU 10.5.2.132 0 /3");
    SapGuiSetActiveConnection(sConnID);
    SapGuiSetActiveSession("ses[0]");

    // SAP
    SapGuiSetActiveWindow("wnd[0]", "SAP", SAPGUI_MATCH_ExactNoCase);
    SapGuiWindowAction(SAPGUI_WND_MAXIMIZE);

    // Logon to SAP System
    // Before running a test you have to customize the password parameter!
    ThinkTime(2.0);
    SapGuiLogon("ddic", "*******", "000", "");

    // SAP Easy Access
    SapGuiIgnoreError(SAPENGINE_STATUSBAR_CHANGED, SEVERITY_SUCCESS);
    ThinkTime(3.7);
    SapGuiSetActiveWindow("wnd[0]", "SAP Easy Access", SAPGUI_MATCH_ExactNoCase);

    // NodeName: Office
    // NodePath: 2\1
    ThinkTime(7.3);
    SapGuiTreeExpandNode( "usr/cntlIMAGE_CONTAINER/shellcont/shell/shellcont[0]/shell", "Office", "0000000003", "Expand\\Office");
    SapGuiTreeExpandNode( "usr/cntlIMAGE_CONTAINER/shellcont/shell/shellcont[0]/shell", "Telephone Integration", "0000000005", "Expand\\Telephone Integration");
    SapGuiVerifyTreeItemText( "usr/cntlIMAGE_CONTAINER/shellcont/shell/shellcont[0]/shell", "Office", "0000000003", "ItemText", SAPGUI_VERIFY_EQUAL, SEVERITY_ERROR);
  end TMain;
Parent topic: Verifying Functions


SapGuiVerifyTreeNodeText Function

Action

This function verifies the text of a node in a SapGui tree control.

Include file

SapGui.bdh

Syntax

SapGuiVerifyTreeNodeText( in sControlId : string,
                          in sNode      : string,
                          in sValue     : string,
                          in nOptions   : number optional,
                          in nSeverity  : number optional := SEVERITY_ERROR ) : boolean;
Parameter | Description
sControlId | The unique id of a tree control.
sNode | The name of the node.
sValue | Compares the current text of the control to the value specified in this parameter according to the comparison flags in the third parameter.
nOptions This parameter specifies the type of check to be performed. Available options are:
  • SAPGUI_VERIFY_EQUAL. Verifies, whether the state of the checkbox's state is equal to the value specified in the second parameter.
  • SAPGUI_VERIFY_NOT_EQUAL. Verifies, whether the checkbox's state is not equal to the value specified in the second parameter.
  • SAPGUI_VERIFY_CASE_SENSITIVE. Performs a case sensitive comparison. By default the comparison is done case insensitive.
  • SAPGUI_VERIFY_IGNORE_WHITESPACE. Ignores any whitespaces found in the values to be compared.
nSeverity Optional: Severity of the error that is raised if the verification fails. Can be one of the following values:
  • SEVERITY_SUCCESS: Success; no error (numerical value: 0)
  • SEVERITY_INFORMATIONAL: Informational; no error (numerical value: 1)
  • SEVERITY_WARNING: Warning; no error (numerical value: 2)
  • SEVERITY_ERROR: (Default) Error; simulation continues (numerical value: 3)
  • SEVERITY_TRANS_EXIT: Error; the active transaction is aborted (numerical value: 4)
  • SEVERITY_PROCESS_EXIT: Error; the simulation is aborted (numerical value: 5)

Return value

  • true if successful
  • false otherwise

Example

transaction TMain
  var
    sConnID : string;
  begin

    // Connecting to SAP
    sConnID := SapGuiOpenConnection( " /SAP_CODEPAGE=1100 /FULLMENU 10.5.2.132 0 /3");
    SapGuiSetActiveConnection(sConnID);
    SapGuiSetActiveSession("ses[0]");

    // SAP
    SapGuiSetActiveWindow("wnd[0]", "SAP", SAPGUI_MATCH_ExactNoCase);
    SapGuiWindowAction(SAPGUI_WND_MAXIMIZE);

    // Logon to SAP System
    // Before running a test you have to customize the password parameter!
    ThinkTime(2.0);
    SapGuiLogon("ddic", "*******", "000", "");

    // SAP Easy Access
    SapGuiIgnoreError(SAPENGINE_STATUSBAR_CHANGED, SEVERITY_SUCCESS);
    ThinkTime(3.7);
    SapGuiSetActiveWindow("wnd[0]", "SAP Easy Access", SAPGUI_MATCH_ExactNoCase);

    // NodeName: Office
    // NodePath: 2\1
    ThinkTime(7.3);
    SapGuiTreeExpandNode( "usr/cntlIMAGE_CONTAINER/shellcont/shell/shellcont[0]/shell", "Office", "0000000003", "Expand\\Office");
    SapGuiTreeExpandNode( "usr/cntlIMAGE_CONTAINER/shellcont/shell/shellcont[0]/shell", "Telephone Integration", "0000000005", "Expand\\Telephone Integration");
    SapGuiVerifyTreeNodeText( "usr/cntlIMAGE_CONTAINER/shellcont/shell/shellcont[0]/shell", "Office", "NodeText", SAPGUI_VERIFY_EQUAL, SEVERITY_ERROR);
  end TMain;
Parent topic: Verifying Functions


SapGuiVerifyWindowAvailability Function

Action

Verifies whether a SapGui window exists and can be accessed during a test run.

Include file

SapGui.bdh

Syntax

SapGuiVerifyWindowAvailability( in sControlId    : string,
                                in sWindowTitle  : string optional,
                                in bAbsolutePath : boolean optional,
                                in nSeverity     : number optional := SEVERITY_ERROR ) : boolean;
Parameter | Description
sControlId | The unique id of the SapGui window.
sWindowTitle | Matches the title of the window if the window as specified in the first parameter could be found. Set this parameter to NULL to have the function not perform a title verification.
bAbsolutePath | If set to true, the id of the control has to be specified using the absolute path. This includes the connection, session, window and control id. Otherwise the verification will be performed looking up the control in the active session.
nSeverity Optional: Severity of the error that is raised if the verification fails. Can be one of the following values:
  • SEVERITY_SUCCESS: Success; no error (numerical value: 0)
  • SEVERITY_INFORMATIONAL: Informational; no error (numerical value: 1)
  • SEVERITY_WARNING: Warning; no error (numerical value: 2)
  • SEVERITY_ERROR: (Default) Error; simulation continues (numerical value: 3)
  • SEVERITY_TRANS_EXIT: Error; the active transaction is aborted (numerical value: 4)
  • SEVERITY_PROCESS_EXIT: Error; the simulation is aborted (numerical value: 5)

Return value

  • true if successful
  • false otherwise

Example

transaction TMain
  var
    sConnID : string;
  begin
    // Connecting to SAP
    sConnID := SapGuiOpenConnection( " /SAP_CODEPAGE=1100 /FULLMENU 10.5.2.132 0 /3");
    SapGuiSetActiveConnection(sConnID);
    SapGuiSetActiveSession("ses[0]");

    // SAP
    SapGuiSetActiveWindow("wnd[0]", "SAP", SAPGUI_MATCH_ExactNoCase);
    SapGuiWindowAction(SAPGUI_WND_MAXIMIZE);

    // Logon to SAP System
    // Before running a test you have to customize the password parameter!
    ThinkTime(2.0);
    SapGuiLogon("ddic", "minisap", "000", "");
    SapGuiVerifyWindowAvailability("wnd[0]", false, SEVERITY_ERROR);
  end TMain;
Parent topic: Verifying Functions


Siebel Functions Overview

Tokenizing functions:

It is not reasonable to parse individual values from Siebel 7 Web server responses, because the values appear in a condensed format. This makes it impossible to identify meaningful left boundaries for parsing functions, because such boundaries would include other dynamic information, e.g. a length specificiation of the value to be parsed or fragments of a previous value.

Therefore, Siebel 7 Web scripts include parsing functions for entire value arrays, and use tokenizing functions to retrieve individual values (tokens) from such parsed value arrays.

Reformatting functions:

The formats of string representations of phone numbers, date values, time values and combined date/time values are different in server responses from client requests. This is because the Siebel Web client reformats values received from the server or entered by the user before they are sent back to the server in subsequent requests.

Without further provision, this makes it impossible to replace hard coded values in the script with parsed values, both for the Recorder and for manual script customization.

The reformatting functions mimic this client side reformatting, and thus allow to have these values in the script in the same format which is used in server responses. This makes it possible to replace these hared coded values with parsed values, both for the Recorder and for manuall script customization.

  • Siebel7WebInit Function
    Establishes several global parsing and verification functions for catching application level errors.
  • SiebelTokenHtml Function
    Extract single tokens from value arrays as used by Siebel 7 Web applications in HTML responses.
  • SiebelTokenHtmlSingleQuote Function
    Extract single tokens from value arrays as used by Siebel 7 Web applications in HTML responses.
  • SiebelTokenApplet Function
    Extract single tokens from value arrays as used by Siebel 7 Web applications in non-HTML responses.
  • SiebelPhone Function
    Reformats a phone number in the same way as the Siebel 7 Web client does.
  • SiebelTime Function
    Reformats a time string value in the same way as the Siebel 7 Web client does for the US-English locale.
  • SiebelDate Function
    Reformats a date string value in the same way as the Siebel 7 Web client does for the US-English locale.
  • SiebelDateTime Function
    Reformats a string containing a date/time combination value in the same way as the Siebel 7 Web client does for the US-English locale.
  • SiebelDecodeJsString Function
    Replaces escape sequences in a string, as used within JavaScript strings, with the corresponding control characters.
  • Siebel7Param Function
    Assembles a length prefixed string from a raw value.
Parent topic: ERP/CRM Functions


Siebel7WebInit Function

Action

Establishes several global parsing and verification functions for catching application level errors. This function should be called in the init transaction of Siebel 7 scripts.

Include file

Siebel7Web.bdh

Syntax

Siebel7WebInit( );

Example

transaction TInit
  begin
    WebSetBrowser(WEB_BROWSER_MSIE6);
    Siebel7WebInit();
  end TInit;
Parent topic: Siebel Functions Overview


SiebelTokenHtml Function

Action

Extract single tokens from value arrays as used by Siebel 7 Web applications in HTML responses.

Include file

Siebel7Web.bdh

Syntax

SiebelTokenHtml( inout sValueArray : string,
                 in    nTokenIndex : number) : string;

Return value

Returns the nTokenIndex-th token in the value array. Token indizes are 0-based.

Parameter | Description
hObject | Handle to a .NET Object
nReturn | Integer variable that will receive the return value of the last DotNetCallMethod call

sValueArray must be a sequences of strings (tokens) enclosed in double quotes ("). Any sequence of characters may appear before the first token, after the last token and between tokens. Such extra content is skipped by these functions.

Example

transaction TTokenHtml
  var
    sValArrayHtml   : string;
    sValArrayHtmlSQ : string;
    i               : number;
    sToken          : string;
  begin
    sValArrayHtml   := "var row = [\"Foo\",\"\",\"Bar\",\"USD\",\n"
                       "// this is a javascript comment\n"
                       " \"05/23/2003\",\"N\",\"1-T8T\"];";
    sValArrayHtmlSQ := "var row = ['Foo','','Bar','USD',\n"
                       "// this is a javascript comment\n"
                       "  '05/23/2003','N','1-T8T'];";
    Writeln("-- Output of SiebelTokenHtml --");
    for i := 0 to 6 do
      sToken := SiebelTokenHtml(sValArrayHtml, i);
      Writeln("Token #" + string(i) + " = <" + sToken + ">");
    end;
    Writeln("-- Output of SiebelTokenHtmlSingleQuote --");
    for i := 0 to 6 do
      sToken := SiebelTokenHtmlSingleQuote(sValArrayHtmlSQ, i);
      Writeln("Token #" + string(i) + " = <" + sToken + ">");
    end;
end TTokenHtml;

Output

-- Output of SiebelTokenHtml --
Token #0 = <Foo>
Token #1 = <>
Token #2 = <Bar>
Token #3 = <USD>
Token #4 = <05/23/2003>
Token #5 = <N>
Token #6 = <1-T8T>
-- Output of SiebelTokenHtmlSingleQuote --
Token #0 = <Foo>
Token #1 = <>
Token #2 = <Bar>
Token #3 = <USD>
Token #4 = <05/23/2003>
Token #5 = <N>
Token #6 = <1-T8T>
Parent topic: Siebel Functions Overview
Related reference
SiebelTokenApplet Function
SiebelTokenHtmlSingleQuote Function


SiebelTokenHtmlSingleQuote Function

Action

Extract single tokens from value arrays as used by Siebel 7 Web applications in HTML responses.

Include file

Siebel7Web.bdh

Syntax

SiebelTokenHtmlSingleQuote( inout sValueArray : string,
                            in    nTokenIndex : number) : string;

Return value

Returns the nTokenIndex-th token in the value array. Token indizes are 0-based.

Parameter | Description
sValueArray | Value array, usually parsed from a server response.
nTokenIndex | The token index (0-based)

sValueArray must be a sequences of strings (tokens) enclosed in single quotes ('). Any sequence of characters may appear before the first token, after the last token and between tokens. Such extra content is skipped by these functions.

Example

transaction TTokenHtml
  var
    sValArrayHtml   : string;
    sValArrayHtmlSQ : string;
    i               : number;
    sToken          : string;
  begin
    sValArrayHtml   := "var row = [\"Foo\",\"\",\"Bar\",\"USD\",\n"
                       "// this is a javascript comment\n"
                       " \"05/23/2003\",\"N\",\"1-T8T\"];";
    sValArrayHtmlSQ := "var row = ['Foo','','Bar','USD',\n"
                       "// this is a javascript comment\n"
                       "  '05/23/2003','N','1-T8T'];";
    Writeln("-- Output of SiebelTokenHtml --");
    for i := 0 to 6 do
      sToken := SiebelTokenHtml(sValArrayHtml, i);
      Writeln("Token #" + string(i) + " = <" + sToken + ">");
    end;
    Writeln("-- Output of SiebelTokenHtmlSingleQuote --");
    for i := 0 to 6 do
      sToken := SiebelTokenHtmlSingleQuote(sValArrayHtmlSQ, i);
      Writeln("Token #" + string(i) + " = <" + sToken + ">");
    end;
end TTokenHtml;

Output

-- Output of SiebelTokenHtml --
Token #0 = <Foo>
Token #1 = <>
Token #2 = <Bar>
Token #3 = <USD>
Token #4 = <05/23/2003>
Token #5 = <N>
Token #6 = <1-T8T>
-- Output of SiebelTokenHtmlSingleQuote --
Token #0 = <Foo>
Token #1 = <>
Token #2 = <Bar>
Token #3 = <USD>
Token #4 = <05/23/2003>
Token #5 = <N>
Token #6 = <1-T8T>
Parent topic: Siebel Functions Overview
Related reference
SiebelTokenHtml Function
SiebelTokenApplet Function


SiebelTokenApplet Function

Action

Extract single tokens from value arrays as used by Siebel 7 Web applications in non-HTML responses.

Include file

Siebel7Web.bdh

Syntax

SiebelTokenApplet( inout sValueArray : string,
                   in    nTokenIndex : number) : string;

Return value

Returns the nTokenIndex-th token in the value array. Token indizes are 0-based.

Parameter | Description
sValueArray | Value array, usually parsed from a server response.
nTokenIndex | The token index (0-based)

sValueArray is a sequence of length prefixed strings with no leading, trailing or intermittent characters allowed. Each length prefixed strings consists of:

  1. the length of the actual value, in decimal ASCII

  2. an asterisk (*)

  3. the actual value

Example

transaction TTokenApplet
  var
    sValArray : string;
    i         : number;
    sToken    : string;
  begin
    sValArray := "3*Foo0*3*Bar3*USD10*05/23/20031*N5*1-T8T";
    Writeln("-- Output of SiebelTokenApplet --");
    for i := 0 to 6 do
      sToken := SiebelTokenApplet(sValArray, i);
      Writeln("Token #" + string(i) + " = <" + sToken + ">");
    end;
  end TTokenApplet;

Output

-- Output of SiebelTokenApplet --
Token #0 = <Foo>
Token #1 = <>
Token #2 = <Bar>
Token #3 = <USD>
Token #4 = <05/23/2003>
Token #5 = <N>
Token #6 = <1-T8T>
Parent topic: Siebel Functions Overview
Related reference
SiebelTokenHtml Function
SiebelTokenHtmlSingleQuote Function


SiebelPhone Function

Action

Reformats a phone number in the same way as the Siebel 7 Web client does.

Include file

Siebel7Web.bdh

Syntax

SiebelPhone( inout sPhone : string) : string;

Return value

Reformatted phone number.

Parameter | Description
sPhone | Undecorated phone number consisting only of digits

sPhone must be an undecorated phone number, the return value is a reformatted phone number as follows:

  • "(" is inserted at the start.

  • ") " is inserted after the 3rd digit.

  • "-" is inserted after the 6th digit.

  • " x" is inserte after the 10th digit if the original phone number is longer than 10 digits.

Example

transaction TPhone
  begin
    Writeln(SiebelPhone("1234567890"));
    Writeln(SiebelPhone("12345678901"));
    Writeln(SiebelPhone("12345678901234567890"));
  end TPhone;

Output

(123) 456-7890
(123) 456-7890 x1
(123) 456-7890 x1234567890See also
Parent topic: Siebel Functions Overview
Related reference
Siebel7Param Function
SiebelTime Function
SiebelDate Function
SiebelDateTime Function
SiebelDecodeJsString Function


SiebelTime Function

Action

Reformats a time string value in the same way as the Siebel 7 Web client does for the US-English locale.

Include file

Siebel7Web.bdh

Syntax

SiebelTime( inout sTime : string) : string;

Return value

Time string reformatted the same way as the Siebel 7 Web client does.

Parameter | Description
sTime | Time string in the format as used in Siebel 7 server responses.

sTime must be a time string in the format H:M:S, where H (hour) must be in the range 0-23 and M (minutes) and S (seconds) must be in the range 0-59. All values may be 1-digit or -2-digit values. The reformatted return value is in the format HH:MM:SS AM|PM. HH, MM and SS each consist of exactly 2 digits, leading zeros are inserted if necessary. HH is in the range 1-12, the postfix "AM" or "PM" is added as appropriate.

Example

transaction TTime
  begin
    Writeln(SiebelTime("0:0:0"));
    Writeln(SiebelTime("1:0:0"));
    Writeln(SiebelTime("2:0:0"));
    Writeln(SiebelTime("11:1:2"));
    Writeln(SiebelTime("11:01:02"));
    Writeln(SiebelTime("12:1:02"));
    Writeln(SiebelTime("13:01:2"));
    Writeln(SiebelTime("22:59:59"));
    Writeln(SiebelTime("23:59:59"));
  end TTime;

Output

12:00:00 AM
01:00:00 AM
02:00:00 AM
11:01:02 AM
11:01:02 AM
12:01:02 PM
01:01:02 PM
10:59:59 PM
11:59:59 PM
Parent topic: Siebel Functions Overview
Related reference
Siebel7Param Function
SiebelPhone Function
SiebelDate Function
SiebelDateTime Function
SiebelDecodeJsString Function


SiebelDate Function

Action

Reformats a date string value in the same way as the Siebel 7 Web client does for the US-English locale.

Include file

Siebel7Web.bdh

Syntax

SiebelDate( inout sDate : string) : string;

Return value

Date string reformatted the same way as the Siebel 7 Web client does.

Parameter | Description
sDate | Date string in the format as used in Siebel 7 server responses.

sDate must be a date string in the format M/D/Y, where M (month) must be in the range 1-12, D (day) must be in the range 1-31 and Y(year) can be any value. Leading zeros are allowed and usually present in date values returned from the server. The reformatted return value is in the same format, however leading zeros are removed.

Example

transaction TDate
begin
    Writeln(SiebelDate("01/01/2004"));
    Writeln(SiebelDate("1/1/2004"));
    Writeln(SiebelDate("09/09/2004"));
    Writeln(SiebelDate("10/01/2004"));
    Writeln(SiebelDate("01/10/2004"));
    Writeln(SiebelDate("12/31/2004"));
  end TDate;

Output

1/1/2004
1/1/2004
9/9/2004
10/1/2004
1/10/2004
12/31/2004
Parent topic: Siebel Functions Overview
Related reference
Siebel7Param Function
SiebelPhone Function
SiebelTime Function
SiebelDateTime Function
SiebelDecodeJsString Function


SiebelDateTime Function

Action

Reformats a string containing a date/time combination value in the same way as the Siebel 7 Web client does for the US-English locale.

Include file

Siebel7Web.bdh

Syntax

SiebelDateTime( inout sDateTime : string) : string;

Return value

Time string reformatted the same way as the Siebel 7 Web client does.

Parameter | Description
sDateTime | Date/Time string in the format as used in Siebel 7 server responses.

sDateTime must contain a date value followed by a time value, separated by at least one whitespace. The date value must be formatted in the same way as required by the function SiebelDate, the time value must be formatted in the same way as required by the function SiebelTime. The return value is reformatted in the same way as done by the functions SiebelDate and SiebelTime. The date and the time value are separated by one blank.

Example

transaction TDateTime
  begin
    Writeln(SiebelDateTime("01/01/2004 0:0:0"));
    Writeln(SiebelDateTime("1/1/2004 11:1:2"));
    Writeln(SiebelDateTime("09/09/2004 11:01:02"));
    Writeln(SiebelDateTime("10/01/2004 12:1:02"));
    Writeln(SiebelDateTime("01/10/2004 13:01:2"));
    Writeln(SiebelDateTime("12/31/2004 23:59:59"));
  end TDateTime;

Output

1/1/2004 12: 0: 0 AM
1/1/2004 11: 1: 2 AM
9/9/2004 11: 1: 2 AM
10/1/2004 12: 1: 2 PM
1/10/2004  1: 1: 2 PM
12/31/2004 11:59:59 PM
Parent topic: Siebel Functions Overview
Related reference
Siebel7Param Function
SiebelPhone Function
SiebelTime Function
SiebelDate Function
SiebelDecodeJsString Function


SiebelDecodeJsString Function

Action

Replaces escape sequences in a string, as used within JavaScript strings, with the corresponding control characters.

Include file

Siebel7Web.bdh

Syntax

SiebelDecodeJsString( inout sString : string ) : string;

Return value

Original string with escape sequences replaced by the corresponding control characters.

Parameter | Description
sString | Any string.

The following two-character sequences are replaced by the corresponding control character:

"\n" replaced by a newline character

"\r" replaced by a carriage return character

"\t" replaced by a tab character

"\f" replaced by a form feed character

Example

transaction TDecodeJs
  var
    sString : string;
  begin
    sString := "First Line\\r\\n\\tSecond line indented with tab\\r\\nThirdLine";
    Writeln("Original:\n-----\n" + sString + "\n-----");
    Writeln("Decoded:\n-----\n" + SiebelDecodeJsString(sString) + "\n-----");
  end TDecodeJs;

Output

Original:
-----
First Line\r\n\tSecond line indented with tab\r\nThirdLine
-----
Decoded:
-----
First Line
Second line indented with tab
ThirdLine
-----
Parent topic: Siebel Functions Overview
Related reference
Siebel7Param Function
SiebelPhone Function
SiebelTime Function
SiebelDate Function
SiebelDateTime Function


Siebel7Param Function

Action

Assembles a length prefixed string from a raw value.

Include file

Siebel7Web.bdh

Syntax

Siebel7Param( inout sString : string) : string;

Return value

Original string prefixed with a length specification and an asterisk.

Parameter | Description
sString | Any string.

This function returns the original string prefixed with a length specification in decimal ASCII representation and an asterisk. This length prefixed format is commonly used in Siebel HTTP traffic. This function is recorded for the benefit of making customization and randomization of Siebel scripts easier.

Example

dclrand
  rChars : RndStr("abcd", 1 .. 30);

dcltrans
  transaction TParam
  begin
    Writeln(Siebel7Param(""));
    Writeln(Siebel7Param("Y"));
    Writeln(Siebel7Param("No"));
    Writeln(Siebel7Param("Foo"));
    Writeln(Siebel7Param("Bar"));
    Writeln(Siebel7Param("Lucent Technologies Incorporated"));
    Writeln(Siebel7Param(rChars));
    Writeln(Siebel7Param(rChars));
    Writeln(Siebel7Param(rChars));
  end TParam;

Output

0*
1*Y
2*No
3*Foo
3*Bar
32*Lucent Technologies Incorporated
29*cdbcdaaabcbddcbacaadbdcbadcdb
17*dbadccbbaaabcadad
24*cadaaabadbbbddcacacbaadc
Parent topic: Siebel Functions Overview
Related reference
SiebelPhone Function
SiebelTime Function
SiebelDate Function
SiebelDateTime Function
SiebelDecodeJsString Function


PeopleSoft Overview

Silk Performer offers support for load testing of PeopleSoft 8.x applications. This support is based on Silk Performer's Web page-level support.

The PeopleSoft project type adds PeopleSoft-specific enhancements for:

  • Automatic handling of dynamic data (session handling)

  • Detection of application level errors with fine grained customization of error severities

  • Ease of customization of login data, thinktimes, page timer names and also access to table rows for easier randomization

Wrapper Functions

The BDH files contain wrapper functions for all page-level API functions. These wrapper functions call the original API functions and perform some additional tasks.

The following wrapper functions are defined:

Wrapper function | Wrapped original function
WebPageUrlPS | WebPageUrl
WebPageLinkPS | WebPageLink
WebPageSubmitPS | WebPageSubmit
WebPageSubmitBinPS | WebPageSubmitBin
WebPageFormPS | WebPageForm
WebPageFileUploadPS | WebPageFileUpload
Parent topic: ERP/CRM Functions


Internet Functions

For proper use of the Silk Performer Internet functions, the file WebAPI.bdh must be included in your scripts. When you use the Silk Performer Recorder to record Internet traffic, this file is automatically included in your script.

Example

use "WebAPI.bdh"

dcluser
  user
    VUser
  transactions
    TInit        : begin;
    TWebFormPost : 50;

Internet Functions

  • Handling Uniform Resource Locators (URLs)
    A Uniform Resource Locator (URL) is a compact representation of the location and access method for a resource located on the Internet.
  • WebAddToHNC Function
    Enters a host to the host name cache of a user.
  • WebRemoveFromHNC Function
    Removes an already resolved host from the host name cache of a user.
  • Settings Functions Reference
    Silk Performer provides functions to allow you to specify in your test script any of the Web-related settings you can specify in the Silk Performer interface.
  • FTP Functions Reference
    The FTP (File Transfer Protocol) functions deal with FTP file and directory manipulation and navigation.
  • HLS Functions Reference
    Lists BDL functions for testing applications that use HTTP Live Streaming (HLS).
  • JSON Functions Reference
    Provides basic knowledge about JSON and lists all functions of the JSON API.
  • LDAP Functions Reference
    The following function set is an implementation of the Lightweight Directory Access Protocol.
  • MAPI Functions Reference
    Tests MAPI (Messaging Application Programming Interface) applications like MS Outlook.
  • MMS Functions Reference
    Lists BDL functions for testing Multimedia Messaging Service (MMS) applications.
  • POP3 Functions Reference
    Describes the complete implementation of the Post Office Protocol 3
  • Radius Functions Reference
    Lists the functions that enable user authentication and account login for RADIUS servers.
  • SMTP Functions Reference
    Lists the complete implementation of the Simple Mail Transfer Protocol.
  • SSL (Secure Socket Layer) Extensions
    Provides configuration options for replaying scripts in a secure environment.
  • TCP/IP Functions Reference
    Lists the functions for testing applications that use the TCP/IP protocol.
  • UDP Functions Reference
  • Web Functions Reference
    Silk Performer provides full support for testing Web applications.
  • XML Functions Reference
    Silk Performer Web API provides functions for parsing/verifying node and attribute values of a Web response.
Parent topic: Benchmark Description Language (BDL) Reference
Related concepts
Program Structure of Load Testing Scripts


Handling Uniform Resource Locators (URLs)

A Uniform Resource Locator (URL) is a compact representation of the location and access method for a resource located on the Internet. Each URL consists of a scheme (HTTP, HTTPS, FTP or Gopher) and a scheme-specific string. This string can also include a combination of a directory path, a search string and/or the name of a resource.

Canonicalized URLs

The format of all URLs must follow prescribed syntax and semantics in order to enable access to resources via the Web. Canonicalization is the process of formatting a URL to follow this prescribed syntax and semantics. Characters that must be encoded include any characters that have no corresponding graphic character in the US-ASCII coded character set (hexadecimal 80-FF, which are not used in the US-ASCII coded character set, and hexadecimal 00-1F and 7F, which are control characters), blank spaces, "%" (which is used to encode other characters), and unsafe characters (<, >, ", #, {, }, |, \, ^, ~, [, ], and ').

Printable ASCII characters being URL-encoded by Silk Performer % ? # [ ] { } | \ & = @ : ^ ~ ' ` " $ + ! * ' ( ) , < >

Note: All characters after the query string delimiter '?' will not be encoded by Silk Performer's low-level web functions.

For encoding URLs, Silk Performer provides the WebBase64Encode function

Parent topic: Internet Functions
Related concepts
Syntax of Load Testing Scripts
Program Structure of Load Testing Scripts
Related reference
WebBase64Encode Function


WebAddToHNC Function

Action

This function is used to enter a host to the host name cache of a user. If a host is found in the host name cache during replay, the specified IP-address is used for connects (no DNS queries are made).

Include file

WebAPI.bdh

Syntax

WebAddToHNC(in sHostName : string,
in sIpAddress : string): boolean;

Return value

  • true if the host name cache has been updated successfully.

  • false otherwise.

Parameter | Description
sHostName | Name of the host that should be entered into the host name cache.
sIpAddress | IP-address of the host.

Example

dcltrans
transaction TMain
begin
  WebAddToHNC("lab3", "192.168.20.56");
  WebPageUrl("http://lab3/shopit/", "ShopIt - Greetings");
end TMain;
Parent topic: Internet Functions


WebRemoveFromHNC Function

Action

This function is used to remove an already resolved host from the host name cache of a user. If a hostname cannot be found in the host name cache during replay, it has to be resolved (again). If the Emulate DNS lookup checkbox is checked every user sends its own DNS query to the DNS server (otherwise it is possible that the system caches the response of a prior DNS query).

Include file

WebAPI.bdh

Syntax

WebRemoveFromHNC(in sHostName : string): boolean;

Return value

  • true if the host name cache has been updated successfully.

  • false otherwise.

Parameter | Description
sHostName | Name of the host that should be deleted from the host name cache.

Example

dcltrans
transaction TMain
begin
  WebPageUrl("http://lab3/shopit/", "ShopIt - Greetings");
  WebRemoveFromHNC("lab3");
  WebPageUrl("http://lab3/", "home page");
end TMain;
Parent topic: Internet Functions


Settings Functions Reference

Silk Performer provides a number of settings functions to allow you to specify in your test script any of the Web-related settings you can specify in the Silk Performer interface. This allows you to specify Web settings individually for each test script and change settings within a single script.

Note: For nearly every WebSet function used to specify a setting, there is a parallel WebGet function to get the current specification.

Most of the WebSet functions wait until all threads have returned. Threads are started by low-level web function calls. The Web settings in the workbench can then be overridden by WebSet function calls.

Example

dcltrans
  transaction TInit
  begin
    WebSetUserAgent("Mozilla 2.0 compatible (Selfmade Browser)");
  end TInit;
  • WebDumpSettings Function
    Writes all current WebSettings into the output file.
  • General Settings
  • Simulation Settings
  • Logging Settings
Parent topic: Internet Functions


WebDumpSettings Function

Action

Writes all current WebSettings into the output file. This function helps in documenting benchmark tests where different settings are used.

Include file

WebAPI.bdh

Syntax

WebDumpSettings();

Example

dcltrans
  transaction TWebInit
  begin
    WebDumpSettings();
  end TWebInit;

Sample scripts

WebMulti01.bdf

Parent topic: Settings Functions Reference


General Settings

  • WebSetBuffer Function
    Determines the size of the buffers used to receive Internet traffic.
  • WebSetDomainSuppress Function
    Specifies a domain from which documents must not be loaded by future Web function calls.
  • WebSetOption Function
    Allows you to set a variety of web options.
  • WebGetOption Function
    Allows you to retrieve the values of the options that have been set with the function WebSetOption().
  • WebGetPageInfo Function
    Retrieves information about the actual page, such as the number of hyperlinks or forms.
  • WebSetStandardHost Function
    Sets the replacement name for the predefined host name "standardhost".
  • WebGetStandardHost Function
    Gets the replacement name for the predefined host name standardhost.
  • WebSetVerification Function
    Specifies whether or not to check if the Internet traffic that the virtual users receive differs from the traffic that the Recorder captured during the recording session.
  • WebSetVerificationEx Function
    Specifies which verification function should be executed during replay.
  • WebSetModem Function
    Sets the simulation bandwidth.
Parent topic: Settings Functions Reference


WebSetBuffer Function

Action

Determines the size of the buffers used to receive Internet traffic. By default, the size of both buffers is set to 8 KB each.

Note: Since Silk Performer allocates two buffers in addition to the WinSock buffers for handling Internet traffic, you need for each connection four times as much system memory as you specify through this function.

Include file

WebAPI.bdh

Syntax

WebSetBuffer( in nBuffer : number,
              in nSize   : number ): boolean;

Return value

  • true if successful

  • false otherwise

Parameter | Description
nBuffer

Specifies which buffer size to set. The following options are possible:

  • WEB_BUFFER_SOCKET. Sets the buffers used for receiving Internet traffic.

nSize | Buffer size in bytes.

Example

dcltrans
  transaction TMain
  begin
    // set size of buffers to 32 KB each
    WebSetBuffer(WEB_BUFFER_SOCKET, 32768);
    WebUrl("http://www.MyCompany.com");
  end TMain;
Parent topic: General Settings


WebSetDomainSuppress Function

Action

Specifies a domain from which documents must not be loaded by future Web function calls. Connections to the suppressed domains will not be established so that the requests are not performed. Whenever a connection is suppressed, an informational line is scripted to the VU output pane. To reset the list of suppressed domains call WebSetDomainSuppress with an empty string as parameter value.

Include file

WebAPI.bdh

Syntax

WebSetDomainSuppress( in sDomains: string,
                      in bExclude: boolean optional );
Parameter | Description
sDomains | List of domains from which no file must be requested (for example, "addthis.com"). Allowed separators are blank spaces, commas, or semicolons. Specify an empty string to lift the restrictions.
bExclude | Set to true to suppress all domains except those specified by the sDomains parameter. Default is false.

Example

dcltrans
  transaction TMain
  begin
    WebSetDomainSuppress("addthis.com");
    WebPageUrl("http://mycompany.com/");
  end TMain;
Parent topic: General Settings


WebSetOption Function

Action

Allows you to set a variety of web options.

Include file

WebAPI.bdh

Syntax

WebSetOption( in nOption : number,
              in uValue  : union ): boolean;

Return value

  • true if the option was set successfully

  • false otherwise

Parameter | Description
nOption

Can be one of the following values:

  • WEB_OPT_EMULATE_DNS - Enables Silk Performer to emulate a DNS lookup mechanism for each virtual user, which is helpful for DNS-based load balancing. If this option is set in combination with a user behavior option, it allows each virtual user to send its individual DNS query to the DNS server.

  • WEB_OPT_ENABLE_CONTENT_ENCODING - Enables Silk Performer to decode compressed data received from the server. If this option is set, Silk Performer sends an Accept-Encoding header to inform the server that encoded data (via gzip and deflated compression methods) can be submitted.

  • WEB_OPT_AUTO_LOAD_IMAGES - Enables the automatic downloading of embedded images. Set nValue to 1 to load the images, or to 0 to not load the images. This option affects the page-level web functions. This function overrides the Automatically load images option in the Emulation category of the Web profile settings.

  • WEB_OPT_LINK_CHECK - Once a document is loaded, all hyperlinks are checked and validated. Set nValue to 1 to check the links, or to 0 to not check the links. This option affects the page-level web functions. (This function overrides the Link checking option in the Verification category of the Web profile settings.)

  • WEB_OPT_HISTORY_SIZE - Sets the history size (maximum number of pages in the history). nValue must be greater than 0. This option affects the page-level web functions.

  • WEB_OPT_MAX_CONN_ATTEMPTS - Determines how often a virtual user will attempt to connect to the server before an error is reported. nValue must be greater than 0.

  • WEB_OPT_HIGH_RES - Used to determine the resolution of the page statistic timers. This parameter is deprecated - it no longer influences precision of timings. The internal resolution of timers is 1 nanosecond.

  • WEB_OPT_TUNNEL_INFO - If the nValue parameter is set to 1, each tunnel request to a proxy server is logged to the TrueLog. Additional authentication requests will be displayed as well. If the nValue parameter is set to 0 (default), no tunnel request information is logged.

  • WEB_OPT_GRACEFUL_SHUTDOWN - By default Silk Performer closes connections using a reset (RST). Set nValue to 1 to use a graceful connection close (FIN) instead.

  • WEB_OPT_STAT_TO_TSD - If this option is enabled (specify a value of STATFLAG_HtmlDoc, STATFLAG_OtherDoc, STATFLAG_RootDoc, or STATFLAG_All), each page-level web function with a timer name adds detailed timers to the time series data. The provided value specifies which portion of the page is to be measured. See WebPageStatToTsd for a detailed description.

  • WEB_OPT_DISABLE_OUTDATA_TRUELOG - Use this option to suppress the logging of Out Header and Out Body information in the TrueLog. This feature can be used to hide sensitive data from the TrueLog.

  • WEB_OPT_DETAILED_PAGE_STAT - Use this option to enable the extended page statistics feature. This allows for browsing of the page tree (as with TrueLog Explorer) and retrieving similar data to that displayed on TrueLog Explorer s Statistics tab. If a value other than 0 is provided, the extended page statistics functionality is enabled. The provided value is also used as the default flag value of the nFlags parameter throughout the WebPageStat functions. Possible values are:

    • PAGE_STAT_FLAG_UseHtml Includes all nodes of the document section of the page (commonly html documents).
    • PAGE_STAT_FLAG_UseEmbedded Includes all nodes of the embedded section of the page (commonly images or scripts).
    • PAGE_STAT_FLAG_NodeTypeLoad Includes all nodes that caused a request to be sent to the server (no cache hits and no suppressed documents).
    • PAGE_STAT_FLAG_NodeTypeCacheHit Includes all nodes that have been found in the cache (full cache hit), so that no request to the server is sent.
    • PAGE_STAT_FLAG_NodeTypeSuppress Includes all nodes for which no request has been sent to the server, because they have been suppressed by the user (WebPageSuppress or WebSetDomainSuppress).
    • PAGE_STAT_FLAG_RedirChainOnlyLast Excludes all nodes but the last of a potential redirection chain (a redirection chain occurs when a request is retried or reissued because of a redirection or a server authentication request).
    • PAGE_STAT_FLAG_AllLoadedDocs is a combination of the flags PAGE_STAT_FLAG_UseHtml, PAGE_STAT_FLAG_UseEmbedded, PAGE_STAT_FLAG_NodeTypeLoad, and PAGE_STAT_FLAG_RedirChainOnlyLast.
    • PAGE_STAT_FLAG_AllLoadedNodes is a combination of the flags PAGE_STAT_FLAG_UseHtml, PAGE_STAT_FLAG_UseEmbedded, and PAGE_STAT_FLAG_NodeTypeLoad.

  • WEB_OPT_SET_FORMS_CASE_SENSITIVE - Comparison between BDL form and HTML form names is normally case-insensitive. Use this option if your server requires case-sensitive form names. To enable case-sensitivity, set the uValue parameter to 1.

  • WEB_OPT_USE_URLHOST_AS_SPN - Use the URL host name as Service Principal Name for Kerberos authentication instead of the fully qualified domain name. To use the URL host name, set the uValue parameter to 1. To use the fully qualified domain name, omit this parameter or set the uValue parameter to 0. This setting must be used if Kerberos authentication does not work when server and client are configured to use CNAME values.

  • WEB_OPT_NAGLE - Use this option to enable Nagle's algorithm. To turn it on, set the parameter to 2. To turn it off, set it to 1. If the parameter is not set or set to 0, the system's default value is used, which usually enables Nagle's algorithm. Note that low-level TCP/IP projects (for example Terminal Emulation) are the exception. They rely on real-time responses while transmitting small packets of data. For these projects, Silk Performer automatically disables Nagle's algorithm unless specified otherwise by WebSetOption.

  • WEB_OPT_HTTP_VERSION - Use this option to set the preferred HTTP version.
    Note: This option overwrites the preferred HTTP version specified in the profile settings as well as the highest supported HTTP version of the simulated browser.
    Possible values are:
    • HTTP_VERSION_PREFER_10: use HTTP/1.0
    • HTTP_VERSION_PREFER_11: use HTTP/1.1
    • HTTP_VERSION_PREFER_2: use HTTP/2
  • WEB_OPT_HTTP2_ALLOW_HTTP11 - If a server does not support HTTP/2, the attempt to connect to that server through HTTP/2 will fail. For such a case, you can either allow a fallback on HTTP/1.1 or you can prevent such a fallback. Set this option to True to fall back on HTTP/1.1 and to display an informational message. Set this option to False to display an error and to not fall back on an earlier HTTP version.
  • WEB_OPT_HTTP2_ENABLE_SERVER_PUSH - Use this option to enable or disable HTTP/2 server push.
  • WEB_OPT_SUPPORT_NEGOTIATE_AUTHENTICATION - Set to false to disable the Negotiate authentication mechanism (for example for Kerberos).

uValue | The new value for the selected option.

Example

dcltrans
  transaction TMain
  var
    nSize: number;
  begin
    // enable link checking
    WebSetOption(WEB_OPT_LINK_CHECK, 1);
    WebPageUrl("http://purple/");
    //check history size
    WebGetOption(WEB_OPT_HISTORY_SIZE, nSize);
    Print(string(nSize));
  end TMain;
Parent topic: General Settings
Related reference
WebGetOption Function


WebGetOption Function

Action

Allows you to retrieve the values of the options that have been set with the function WebSetOption().

Note: The topic WebSetOption Function provides a list of all options that can be set.

Include file

WebAPI.bdh

Syntax

WebGetOption( in  nOption : number,
              out uValue  : union ): boolean;

Return value

  • true if successful

  • false otherwise

Parameter | Description
nOption | Refer to WebSetOption Function for a list of all available options.
uValue | Variable that receives the value of the selected option.

Example

dcltrans
  transaction TMain
  var
    nSize: number;
  begin
    // enable link checking
    WebSetOption(WEB_OPT_LINK_CHECK, 1);
    WebPageUrl("http://purple/");
    //check history size
    WebGetOption(WEB_OPT_HISTORY_SIZE, nSize);
    Print(string(nSize));
  end TMain;
Parent topic: General Settings
Related reference
WebSetOption Function


WebGetPageInfo Function

Action

Retrieves information about the actual page, such as the number of hyperlinks or forms.

Include file

WebAPI.bdh

Syntax

WebGetPageInfo( in  nOption : number,
                out nValue  : number ) : boolean;

Return value

  • true if successful

  • false otherwise

Parameter | Description
nOption

Can be one of the following values:

  • WEB_PAGE_INFO_HREF. Specify this option to retrieve the number of hyperlinks in the actual page.

  • WEB_PAGE_INFO_FORMS. Specify this option to retrieve the number of HTML forms in the actual page.

  • WEB_PAGE_INFO_FRAMES. Specify this option to retrieve the number frames in the actual page.

nValue | Variable, that receives the specified value.

Example

dcltrans
  transaction TWeb
  var
    nValue : number;
  begin
    WebPageUrl("http://standardhost/");
    WebGetPageInfo(WEB_PAGE_INFO_HREF, nValue);
    Print(string(nValue));
    WebGetPageInfo(WEB_PAGE_INFO_FORMS, nValue);
    Print(string(nValue));
  end TWeb;

Parent topic: General Settings


WebSetStandardHost Function

Action

Sets the replacement name for the predefined host name standardhost. If not specified, the default setting is taken from the active profile settings (Settings > Active Profile > Internet > Hosts > Standardhost).

Include file

WebAPI.bdh

Syntax

WebSetStandardHost(in sHost : string,
                   in nPort : number optional): boolean;

Return value

  • true if successful

  • false otherwise

Parameter | Description
sHost | Replacement name for the predefined host name standardhost.
nPort | Port number appended to the replacement name (optional).

Example

dcltrans
  transaction TMain
  var
    hWeb: number;
  begin
    // Use a standard host name and default port number
    WebSetStandardHost("www.myserver.com");
    // Connect to www.myserver.com on port 80
    WebUrl("http://standardhost", 0.0);
    // Use standard host name and override default/custom port numbers
    WebSetStandardHost("www.myserver.com", 8000);
    // Connect to www.myserver.com on port 8000
    WebUrl("http://standardhost", 0.0);
    // Connect to www.myserver.com on port 8000
    WebTcpipConnect(hWeb, "standardhost", 0);
    // Connect to www.myserver.com on port 8000
    // Since "standardhost" is passed to the function,
    // the third parameter is overridden
    WebTcpipConnect(hWeb, "standardhost", 4000);
  end TMain;

Sample scripts

WebMultiClientIpAddresses01.bdf

Parent topic: General Settings
Related reference
WebGetStandardHost Function


WebGetStandardHost Function

Action

Gets the replacement name for the predefined host name standardhost.

Include file

WebAPI.bdh

Syntax

WebGetStandardHost( out sHost   : string,
                    in  nMaxLen : number optional,
                    out nPort   : number optional): boolean;

Return value

  • true if successful

  • false otherwise

Parameter | Description
sHost | String buffer receiving the current name of the standardhost.
nMaxLen | The maximum length of the receive buffer sHost (optional).
nPort | Variable receiving the current port number of the standardhost (optional).

Example

dcltrans
  transaction TInit
  var
    sHost : string;
    nPort : number;
  begin
    WebGetStandardHost(sHost,
STRING_COMPLETE, nPort);
    write("Standardhost: "); write(sHost);
    write(":"); write(nPort); writeln;
  end TInit;
Parent topic: General Settings
Related reference
WebSetStandardHost Function


WebSetVerification Function

Action

Specifies whether to check if the Internet traffic Silk Performer receives differs from the traffic the Recorder captured during a former recording session.

Note: This function is obsolete. It can still be used, although it's recommended to use the WebSetVerificationEx function instead.

Include file

WebAPI.bdh

Syntax

WebSetVerification( in bVerify     : boolean,
                    in nDifference : number,
                    in bTitle      : boolean,
                    in bHtml       : boolean optional,
                    in bTable      : boolean optional,
                    in bData       : boolean optional,
                    in bXml        : boolean optional );
Parameter | Description
bVerify | Specifies whether to enable response data verification. If this parameter is set to true, Silk Performer generates a digest used for verification.
nDifference | Maximum number of digest entries that may differ from the digest generated by the Recorder.
bTitle | Specifies if the WebVerifyHtmlTitle functions in the script should be executed.
bHtml | Specifies if the WebVerifyHtmlXXX functions in the script should be executed (optional). They are not executed if this parameter is omitted.
bTable | Specifies if the WebVerifyTable functions in the script should be executed (optional). They are not executed if this parameter is omitted.
bData | Specifies if the WebVerifyDataXXX functions in the script should be executed (optional). They are not executed if this parameter is omitted.
bXml | Specifies if the WebXmlVerifyXXX functions in the script should be executed (optional). They are not executed if this parameter is omitted.

Example

const
  sDigest := "\h35e2fa05...";

dcltrans
  transaction TMain
  begin
    WebSetVerification(true, 10, false);
    WebVerifyHtml("Silk Performer");
    WebVerifyResponseData(sDigest, sizeof(sDigest));
    WebUrl("http://www.MyCompany.com");
  end TMain;
Parent topic: General Settings
Related reference
WebSetVerificationEx Function
WebVerifyData Function
WebVerifyDataBound Function
WebVerifyHtml Function
WebVerifyHtmlBound Function
WebVerifyHtmlTitle Function
WebVerifyTable Function
WebVerifyDataDigest Function
WebVerifyHtmlDigest Function
WebXmlVerifyNodeValue Function
WebXmlVerifyNodeAttribute Function


WebSetVerificationEx Function

Action

Specifies which verification function should be executed during replay.

Include file

WebAPI.bdh

Syntax

WebSetVerificationEx( in nFlagVerify : number,
                      in bOn         :boolean,
                      in nDifference :number optional );
Parameter | Description
nFlagVerify

Specifies any combination of following flags:

  • WEB_VERIFY_FLAG_Data Specifies if the WebVerifyData function and/or WebVerifyDataBound function in the script should be executed.

  • WEB_VERIFY_FLAG_Html Specifies if the WebVerifyHtml function and/or WebVerifyHtmlBound function in the script should be executed.

  • WEB_VERIFY_FLAG_Xml Specifies if the WebXmlVerifyNodeAttribute function and/or WebXmlVerifyNodeValue function in the script should be executed.

  • WEB_VERIFY_FLAG_Title Specifies if the WebVerifyHtmlTitle function in the script should be executed.

  • WEB_VERIFY_FLAG_Table Specifies if the WebVerifyTable function in the script should be executed.

  • WEB_VERIFY_FLAG_DataDigest Specifies if the WebVerifyDataDigest function in the script should be executed.

  • WEB_VERIFY_FLAG_HtmlDigest Specifies if the WebVerifyHtmlDigest function in the script should be executed.
bOn | If this parameter is set to TRUE, all specified verifications (by the nFlagVerify parameter) are enabled. If this parameter is set to FALSE, all specified verifications are disabled.
nDifference | If the WEB_VERIFY_FLAG_DataDigest or WEB_VERIFY_FLAG_HtmlDigest flags are specified, this parameter defines the maximum number of digest entries that may differ to still match the verification (optional).

Example

const
  sDigest := "\h35e2fa05";
dcltrans
  transaction TMain
  begin
    WebSetVerificationEx (WEB_VERIFY_FLAG_Html | WEB_VERIFY_FLAG_Xml, true);
    WebSetVerificationEx(WEB_VERIFY_FLAG_Title, false);
    WebSetVerificationEx(WEB_VERIFY_FLAG_DataDigest, true, 10);
    WebVerifyHtml("Silk Performer");
    WebVerifyTitle("Silk Performer - Home"); //not executed
    WebVerifyResponseData(sDigest, sizeof(sDigest));
    WebUrl("http://www.MyCompany.com");
  end TMain;
Parent topic: General Settings


WebSetModem Function

Action

Sets the simulation bandwidth.

Include file

ModemAPI.bdh

Syntax

WebSetModem( in nModem : number,
             in fComp  : float optional );

Return value

  • none

Parameter Description
nModem

Can be one of the following values:

  • MOD_WIRELESS_96

  • MOD_WIRELESS_144

  • MOD_GPRS_28

  • MOD_GPRS_56

  • MOD_GPRS_112

  • MOD_MODEM_96

  • MOD_MODEM_144

  • MOD_MODEM_288

  • MOD_MODEM_336

  • MOD_MODEM_56

  • MOD_ISDN_64

  • MOD_ISDN_128

  • MOD_T1_154

  • MOD_GLITE_15

  • MOD_ADSL_768

  • MOD_ADSL_15

  • MOD_ADSL_6

  • MOD_ADSL_8

  • MOD_ADSL_9

  • MOD_VDSL_13

  • MOD_VDSL_52

  • MOD_HDSL_1544

  • MOD_HDSL_2

  • MOD_SDSL_768

  • MOD_SDSL_1544

  • MOD_SDSL_2048

  • MOD_BLUETOOTH

fComp

For the modem types where the hardware compression rate can be set (see the profile settings), this is the hardware compression rate to use.

By default, the commpresion rate is set to 1.0.

Example

dcltrans
  transaction TWebInit
  begin
    WebSetModem(MOD_ISDN_128);
    WebDumpSettings();
  end TWebInit;
Parent topic: General Settings


Simulation Settings

  • WebSetLocalAddress Function
    Assigns a specific IP address to the virtual user.
  • WebGetLocalAddress Function
    Returns the local IP address that is used by the calling virtual user.
  • WebSetSecurity Function
    Sets the security mode to use when exchanging data with a remote server.
  • WebGetSecurity Function
    Returns the currently active security mode for web traffic simulation.
  • WebSetSpeed Function
    Sets the simulation speed.
  • WebGetSpeed Function
    Gets the current value of the simulation speed as a number.
  • WebSetTimeout Function
    Specifies timeouts for Silk Performer's replay engine.
  • WebGetTimeout Function
    Gets the currently specified timeouts for Silk Performer's replay engine.
  • WebSetUserAuth Function
    Sets the password for user authentication.
  • WebSetUserAuthBasic Function
    Sets the password for basic user authentication.
  • WebSetUserAuthDigest Function
    Sets the password for digest user authentication.
  • WebSetUserAuthNtlm Function
  • WebSetUserBehavior Function
    Specifies whether the user resets his browser emulation after each transaction.
Parent topic: Settings Functions Reference


WebSetLocalAddress Function

Action

Assigns a specific IP address to the virtual user.

To assign individual IP addresses to virtual users, you first have to set up multiple IP addresses for the network device. This is done with the Silk Performer System Configuration Manager. Afterwards, you can assign each of the IP addresses to a different virtual user.

Include file

WebAPI.bdh

Syntax

WebSetLocalAddress( in sAddress : string ): boolean;

Return value

  • true if successful

  • false otherwise

Parameter | Description
sAddress | IP address

Example

dcltrans
  transaction TMain
  begin
    WebSetLocalAddress("192.168.20.20");
    WebUrl("http://standardhost");
  end TMain;
Parent topic: Simulation Settings
Related reference
WebGetLocalAddress Function


WebGetLocalAddress Function

Action

Returns the local IP address that is used by the calling virtual user. If the Client IP address multiplexing option in the Internet category of the profile settings is checked, this function can be used to retrieve the randomly assigned IP address.

Include file

WebAPI.bdh

Syntax

WebGetLocalAddress( out sIPAddress  : string,
                    in  nAddressLen : number optional ): boolean;

Return value

  • true if the function succeeds

  • false otherwise

Parameter | Description
sIPAddress | String variable that receives the IP address.
nAddressLen | Maximum length of the IP address to return (optional).

Example

dcltrans
  transaction TMain
  var
    sAddress: string;
  begin
    WebGetLocalAddress(sAddress);
    write("IP address = "); writeln(sAddress);
  end TMain;
Parent topic: Simulation Settings
Related reference
WebSetLocalAddress Function


WebSetSecurity Function

Action

Sets the security mode to use when exchanging data with a remote server. This function is very practical to switch programmatically between secure an insecure mode without the need to modify any other function calls.

Note: This function overrides the corresponding setting in the Security tab of the Profile Settings - Internet dialog.

Include file

WebAPI.bdh

Syntax

WebSetSecurity(in nSecurity: number): boolean;

Return value

  • true if successful

  • false otherwise

Parameter Description
nSecurity

Value can assume one of the following:

  • WEB_SECURITY_NONE. Disables the use of security

  • WEB_SECURITY_SSL. Enables the use of SSL for all protocols except FTP

Example

dcltrans
  transaction TWebSecure
  begin
    WebUrl("http://standardhost/gmo/products.htm", 5.45);
    WebSetSecurity(WEB_SECURITY_SSL);
    WebUrl("http://standardhost/gmo/images/backpack.gif", 0.01);
    WebUrl("http://standardhost/gmo/images/boots.gif", 5.28);
    WebUrl("http://standardhost/gmo/products.htm", 9.06);
    WebSetSecurity(WEB_SECURITY_NONE);
    WebUrl("http://standardhost/gmo/images/socks.gif", 0.11);
    WebUrl("http://standardhost/gmo/images/shorts.gif", 0.19);
    // This URL always is requested through SSL due to HTTPS scheme
    WebUrl("https://standardhost/gmo/index.html", 0.45);
  end TWebSecure;

Sample scripts

WebSecure01.bdf, WebSecure02.bdf

Parent topic: Simulation Settings
Related reference
WebGetSecurity Function
SSL (Secure Socket Layer) Extensions


WebGetSecurity Function

Action

Returns the currently active security mode for web traffic simulation on protocol level..

Include file

WebAPI.bdh

Syntax

WebGetSecurity(): number;

Return value

One of the following values defined in WebAPI.bdh:

  • WEB_SECURITY_NONE

  • WEB_SECURITY_SSL

Example

dcltrans
  transaction TWebInit
  begin
    write("Security: ");
    if WebGetSecurity() = WEB_SECURITY_SSL then write("SSL");
    writeln;
  else
    write("none");
    writeln;
    end;
  end TWebInit;
Parent topic: Simulation Settings
Related reference
WebSetSecurity Function
SSL (Secure Socket Layer) Extensions


WebSetSpeed Function

Action

Sets the simulation speed. The simulation uses short wait periods between transfers of small data packets. Packeting emulates the behavior of a modem or ISDN terminal.

Include file

WebAPI.bdh

Syntax

WebSetSpeed(in nSpeed       : number,
            in nFlag        : number optional,
            in bDuplex      : boolean optional,
            in fCompression : float optional): boolean;

Return value

  • true if successful

  • false otherwise

Parameter | Description
nSpeed

Can be a [bit/sec] number or one of the following values:

  • WEB_SPEED_14. 14.4 kBit/sec

  • WEB_SPEED_28. 28.8 kBit/sec

  • WEB_SPEED_33. 33.6 kBit/sec

  • WEB_SPEED_56. 56 kBit/sec

  • WEB_SPEED_64. 64 kBit/sec

  • WEB_SPEED_128. 128 kBit/sec

  • WEB_SPEED_DSL. 384 kBit/sec

  • WEB_SPEED_T1. 1540 kBit/sec

  • WEB_SPEED_MAX. maximum possible speed
nFlag

Specifies whether the given speed should be simulated for sending or for receiving data, or for both (optional). This parameter can be any combination of the following values:

  • WEB_SPEED_SEND. Sets the simulation speed for sending data.

  • WEB_SPEED_RECV. Sets the simulation speed for receiving data.

By default, the simulation speed is set for both sending and receiving data.
bDuplex | Specifies whether send and receive operations can perform simultaneously or not (optional). By default, this value is set to false.
fCompression | Specifies the hardware compression rate of the simulated network device (optional). By default, this value is set to 1.0.

Example

dcltrans
  transaction TWebInit
  begin
    WebSetSpeed(WEB_SPEED_28);
    WebDumpSettings();
  end TWebInit;

Sample scripts

WebMulti01.bdf, WebMultiClientIpAddresses01.bdf

Parent topic: Simulation Settings
Related reference
WebGetSpeed Function


WebGetSpeed Function

Action

Gets the current value of the simulation speed as a number. A value of 0 represents maximum speed.

Include file

WebAPI.bdh

Syntax

WebGetSpeed(in nFlag : number optional,
out bDuplex : boolean optional
out fCompression : float optional): number;

Return value

current value of the simulation speed

Parameter | Description
nFlag

Specifies whether to retrieve the simulation speed for sending or for receiving data (optional). This parameter can be one of the following values:

  • WEB_SPEED_SEND. Gets the simulation speed for sending data.

  • WEB_SPEED_RECV. Gets the simulation speed for receiving data (default).
bDuplex | Variable that receives a boolean value which indicates whether the simulation speeds for sending and receiving data differ (optional).
fCompression | Variable that receives the hardware compression rate of the simulated network device (optional).

Example

dcltrans
  transaction TWebInit
  begin
    write("SimulationSpeed: ");
    write(WebGetSpeed());
    writeln;
  end TWebInit;
Parent topic: Simulation Settings
Related reference
WebSetSpeed Function


WebSetTimeout Function

Action

Specifies timeouts for Silk Performer's replay engine. Timeouts can occur either if data cannot be sent to the server in a specified time interval, or if data cannot be received from the server. For both cases, the default setting is to report no timeout.

Include file

WebAPI.bdh

Syntax

WebSetTimeout( in nFlag : number,
               in nTime : number ): boolean;

Return value

  • true if successful

  • false otherwise

Parameter | Description
nFlag

Specifies which timeout value to set. Possible options are:

  • WEB_TIMEOUT_SEND. Specify a value for timeout reported when data cannot be sent to the server. Set nTime to 0 to wait forever (or until the connection is closed).

  • WEB_TIMEOUT_RECV. Specify a value for timeout reported when no data can be received from the server. Set nTime to 0 to wait forever (or until the connection is closed).

  • WEB_TIMEOUT_CONNECT. Specify a value for timeout reported when a connection to a server cannot be established. Set nTime to 0 to use the system's default time out.
nTime | Timeout value in milliseconds

Example

dcltrans
  transaction TWebSetTimeout
  var
    hWeb: number;
  begin
    // report timeout when data cannot be received within 30 seconds
    WebSetTimeout(WEB_TIMEOUT_RECV, 30000);
    WebTcpipConnect(hWeb, "192.231.34.1", WEB_PORT_HTTP);
    WebTcpipSend(hWeb, "GET / HTTP/1.0\r\n"
                "User-Agent: CustomClient/1.0\r\n"
                "Accept: */*\r\n\r\n");

    // timeout if less than 100 bytes are received
    WebTcpipRecvExact(hWeb, NULL, 100);
    WebTcpipShutdown(hWeb);
  end TWebSetTimeout;

Sample scripts

AsyncOdb.bdf, Factory.bdf, AsyncFact.bdf

Parent topic: Simulation Settings


WebGetTimeout Function

Action

Gets the currently specified timeouts for Silk Performer's replay engine.

Include file

WebAPI.bdh

Syntax

WebGetTimeout( in nFlag : number ) : number;

Return value

Current timeout value in milliseconds.

Parameter Description
nFlag

Specifies whether to retrieve the timeout value for sending, receiving or connecting. Possible options are:

  • WEB_TIMEOUT_SEND. Gets the value for timeout reported when data cannot be sent to the server.

  • WEB_TIMEOUT_RECV. Gets the value for timeout reported when no data can be received from the server.

  • WEB_TIMEOUT_CONNECT. Gets the value for timeout reported when a connection to a server cannot be established.

Example

transaction TTimeout
  begin
    WebSetTimeout(WEB_TIMEOUT_SEND, 1000);
    WebSetTimeout(WEB_TIMEOUT_RECV, 2000);
    WebSetTimeout(WEB_TIMEOUT_CONNECT, 3000);

    print(string(WebGetTimeout(WEB_TIMEOUT_SEND)));
    print(string(WebGetTimeout(WEB_TIMEOUT_RECV)));
    print(string(WebGetTimeout(WEB_TIMEOUT_CONNECT)));

  end TTimeout;
Parent topic: Simulation Settings


WebSetUserAuth Function

Action

Sets the password for user authentication. This setting is ignored if a user name and/or password is specified in the URL of a low-level call.

Note: This function overrides the corresponding setting on the Authentication tab of the Profile Settings – Web dialog. It also sets the credentials for Basic, Digest and NTLM/Kerberos authentication, if they are not set explicitly.

Include file

WebAPI.bdh

Syntax

WebSetUserAuth( in sUsername     : string allownull,
                in sPassword     : string optional,
                in sUrl          : string optional,
                in sRealm        : string optional,
                in bReactiveOnly : boolean optional): boolean;

Return value

  • true if successful

  • false otherwise

Parameter | Description
sUsername | User name. This parameter may be NULL.
sPassword | Password. This parameter may be NULL (optional).
sUrl | URL representing protection space for basic authentication (optional)
sRealm | Realm for which to set authentication (optional). This realm then provides a special context for the username/password to a Web site. For example, www.MyCompany.com uses realm "www.MyCompany.com", whereas www.MyCompany.com/support uses realm "MyCompany support".
bReactiveOnly | If this parameter is set to true (default is false), the user and password pair can only be used in a reaction to a 401 response from the server.

Calling this function inserts the username/password pair into the authentication database used when a server requests basic authentication (code 401). On subsequent requests, the authentication header line will be added to the request headers automatically.

  • To set the default username password, call WebSetUserAuth("user1", "pass1");

  • To delete the default username/password, call WebSetUserAuth("", ""); This does not remove the entry from the authentication database.

  • To remove all cached authentication entries from the cookie database, call WebSetUserAuth(NULL, NULL);

  • In addition, you can add authentication entries directly to the authentication database by providing a protection space and the realm. For example, WebSetUserAuth("BasicAuthUser", "BasicAuthPass", "http://lab1/testsite/", "lab1");

Example

dcltrans
  transaction TMyTransaction
  begin
    // Enable user authentication
    // User sends e-mail address as password
    WebSetUserAuth("steve", "steve@mydomain.com");

     // Now send the request including username and password
    WebUrl("http://www.mydomain.com/", 0.0);

     // Disable user authentication
    WebSetUserAuth(NULL, NULL);
  end TMyTransaction;

Sample scripts

WebAuth01.bdf

SilkEssential sample

Ftp.sep

Parent topic: Simulation Settings
Related reference
WebSetUserAuthNtlm Function
WebSetUserAuthBasic Function
WebSetUserAuthDigest Function
WebSetProxyAuth Function
WebSetProxyAuthBasic Function
WebSetProxyAuthNtlm Function


WebSetUserAuthBasic Function

Action

Sets the password for basic user authentication. This setting is ignored if a user name and/or password is specified in the URL of a low-level call.

Note: This function overrides the corresponding setting on the Authentication tab of the Profile Settings – Web dialog. In contrast to the WebSetUserAuth function, this function does not change the credentials for Digest or NTLM/Kerberos authentication.

Include file

WebAPI.bdh

Syntax

WebSetUserAuthBasic( in sUsername     : string allownull,
                     in sPassword     : string optional,
                     in sUrl          : string optional,
                     in sRealm        : string optional,
                     in bReactiveOnly : boolean optional ): boolean;

Return value

  • true if successful

  • false otherwise

Parameter | Description
sUsername | User name. This parameter may be NULL.
sPassword | Password (optional).
sUrl | URL representing protection space for basic authentication (optional).
sRealm | Realm for which to set authentication (optional). This realm then provides a special context for the username/password to a Web site. For example, www.MyCompany.com uses realm "www.MyCompany.com", whereas www.MyCompany.com/support uses realm "MyCompany support".
bReactiveOnly | If this parameter is set to true (optional; default is false), the user and password pair can only be used in a reaction to a 401 response from the server.

Calling this function inserts the username/password pair into the authentication database used when a server requests basic authentication (code 401). On subsequent requests, the authentication header line will be added to the request headers automatically.

  • To set the default username password, call WebSetUserAuthBasic("user1", "pass1");

  • To delete the default username/password, call WebSetUserAuthBasic("", ""); This does not remove the entry from the authentication database.

  • To remove all cached authentication entries from the cookie database, call WebSetUserAuthBasic(NULL);

  • In addition, you can add authentication entries directly to the authentication database by providing a protection space and the realm. For example, WebSetUserAuthBasic("BasicAuthUser", "BasicAuthPass", "http://lab1/testsite/", "lab1");

Example

dcltrans
  transaction TMyTransaction
  begin
    // Enable user authentication
    // User sends e-mail address as password
    WebSetUserAuthBasic("steve", "steve@mydomain.com");

    // Now send the request including username and password
    WebUrl("http://www.mydomain.com/", 0.0);

    // Disable user authentication
    WebSetUserAuthBasic(NULL);
  end TMyTransaction;
Parent topic: Simulation Settings
Related reference
WebSetUserAuthNtlm Function
WebSetUserAuth Function
WebSetUserAuthDigest Function
WebSetProxyAuth Function
WebSetProxyAuthBasic Function
WebSetProxyAuthNtlm Function


WebSetUserAuthDigest Function

Action

Sets the password for digest user authentication.

Note: This function overrides the corresponding setting on the Authentication tab of the Profile Settings – Web dialog. In contrast to the WebSetUserAuth function, this function does not change the credentials for Basic or NTLM/Kerberos authentication.

Include file

WebAPI.bdh

Syntax

WebSetUserAuthDigest( in sUsername : string allownull,
                      in sPassword : string allownull,
                      in sUrl      : string allownull,
                      in sRealm    : string allownull ): boolean;

Return value

  • true if successful

  • false otherwise

Parameter | Description
sUsername | User name; this parameter may be NULL.
sPassword | Password (optional)
sUrl | URL representing protection space for digest authentication (optional)
sRealm | Realm for which to set authentication (optional). This realm provides a special context for the username/password to a Web site. For example, www.MyCompany.com uses realm "www.MyCompany.com", whereas www.MyCompany.com/support uses realm "MyCompany support".

Calling this function inserts the username/password pair into the authentication database used when a server requests digest authentication (code 401). On subsequent requests, the authentication header line is added to the request headers automatically.

  • To set the default username/password, call WebSetUserAuthDigest("user1", "pass1");

  • To delete the default username/password, call WebSetUserAuthDigest("", ""); This does not remove the entry from the authentication database.

  • To remove all cached authentication entries from the cookie database, call WebSetUserAuthDigest(NULL);

  • In addition, you can add authentication entries directly to the authentication database by providing a protection space and the realm. For example, WebSetUserAuthDigest("DigestcAuthUser", "DigestAuthPass", "http://lab1/testsite/", "lab1");

Example

dcltrans
  transaction TWeb
  begin
    WebSetUserAuthDigest("domain\\user", "password");
    WebPageUrl("http://www.mydomain.com/");
  end TWeb;
Parent topic: Simulation Settings
Related reference
WebSetUserAuthNtlm Function
WebSetUserAuth Function
WebSetUserAuthBasic Function
WebSetProxyAuth Function
WebSetProxyAuthBasic Function
WebSetProxyAuthNtlm Function


WebSetUserAuthNtlm Function

Action

Sets the password for NTLM/Kerberos authentication. In contrary to the WebSetUserAuth function it does not change the credentials for a basic user authentication.

Note: This function overrides the corresponding setting on the Authentication tab of the Profile Settings – Web dialog. In contrast to the WebSetUserAuth function, this function does not change the credentials for Basic or Digest authentication.

Include file

WebAPI.bdh

Syntax

WebSetUserAuthNtlm( in sUsername : string,
                    in sPassword : string ): boolean;

Return value

  • true if successful

  • false otherwise

Parameter | Description
sUsername | User name. If you have to specify a domain use the notation: "domain\\user".
sPassword | Password.

Example

dcltrans
  transaction TMyTransaction
  begin
    WebSetUserAuthNtlm("testlab\\steve", "secret");
    WebUrl("http://lab1/");

    WebSetUserAuthNtlm("", "");
  end TMyTransaction;
Parent topic: Simulation Settings
Related reference
WebSetUserAuth Function
WebSetUserAuthBasic Function
WebSetUserAuthDigest Function
WebSetProxyAuth Function
WebSetProxyAuthBasic Function
WebSetProxyAuthNtlm Function


WebSetUserBehavior Function

Action

Specifies whether the user resets his browser emulation after each transaction. This function enables you to generate a simulation of a user who visits a Web site for the first time — if you specify to clear the document cache, the document history, the cookie database, the authentication databases, and the SSL context cache — or a user who revisits a Web site.

Note: This function overrides the corresponding setting in the Simulation tab of the Profile Settings - Web dialog.

Include file

WebAPI.bdh

Syntax

WebSetUserBehavior(in nUserBehavior: number): boolean;

Return value

  • true if successful

  • false otherwise

Parameter Description
nUserBehavior

Specifies the user behavior. This parameter must be one of following values:

  • WEB_USERBEHAVIOR_DISABLE. The user does not reset his browser emulation during a test.

  • WEB_USERBEHAVIOR_FIRST_TIME. After each transaction, the user closes the persistent connections, resets his browser emulation, and clears the document cache, the document history, the cookie database, and the SSL context cache.

  • WEB_USERBEHAVIOR_REVISITING. After each transaction, the user closes the persistent connections and clears the document history, the non-persistent cookie database, and the SSL context cache.

Example

dcltrans
  transaction TInit
  begin
    WebSetDocumentCache(true, WEB_CACHE_CHECK_ALWAYS);
    // simulate a returning user, with all the documents
    // in the cache and cookies in the cookie database.
    WebSetUserBehavior(WEB_USERBEHAVIOR_REVISITING);
  end TInit;
Parent topic: Simulation Settings


Logging Settings

  • WebSetLogDetail Function
    Specifies the detail of logging information.
  • WebSetLogMaxLines Function
    Specifies the maximum number of header or data lines to write to the log per session.
Parent topic: Settings Functions Reference


WebSetLogDetail Function

Action

Specifies the detail of logging information.

Include file

WebAPI.bdh

Syntax

WebSetLogDetail(in nLogFlags: number): boolean;

Return value

  • true if successful

  • false otherwise

Parameter Description
nLogFlags

Can be a combination of the following constants:

  • WEB_LOG_API

  • WEB_LOG_API_DETAIL

  • WEB_LOG_REQUEST_HEADER

  • WEB_LOG_RESPONSE_HEADER

  • WEB_LOG_REQUEST_DATA

  • WEB_LOG_RESPONSE_DATA

  • WEB_LOG_REQUEST_BINARY

  • WEB_LOG_RESPONSE_BINARY

  • WEB_LOG_INFO

  • WEB_LOG_NONPRINTING_CHR

  • WEB_LOG_IMAGES_APPLETS

  • WEB_LOG_ALL

Example

dcltrans
  transaction TInit
  begin
    WebSetLogDetail(WEB_LOG_REQUEST_HEADER | WEB_LOG_RESPONSE_HEADER);
  end TInit;
Parent topic: Logging Settings


WebSetLogMaxLines Function

Action

Specifies the maximum number of header or data lines to write to the log per session.

Include file

WebAPI.bdh

Syntax

WebSetLogMaxLines(in nLogFlags : number,
                  in nMaxLines : number): boolean;

Return value

  • true if successful

  • false otherwise

Parameter | Description
nLogFlags

Can be a combination of the following constants:

  • WEB_LOG_REQUEST_DATA

  • WEB_LOG_RESPONSE_DATA
nMaxLines | Maximum number of lines per session to write to the log

Example

dcltrans
  transaction TInit
  begin
    WebSetLogMaxLines(WEB_LOG_REQUEST_DATA | WEB_LOG_RESPONSE_DATA, 10);
  end TInit;
Parent topic: Logging Settings


FTP Functions Reference

The FTP (File Transfer Protocol) functions deal with FTP file and directory manipulation and navigation. Using a CERN proxy exclusively requires using the WebUrl function because CERN proxies require an HTML request containing an FTP URL.

  • WebSetPassiveFTP Function
    Sets the passive transfer semantics mode for FTP.
  • WebGetPassiveFTP Function
    Checks whether the Passive FTP flag is set.
  • WebFtpCloseFile Function
    Closes a file handle previously opened with WebFtpOpenFile.
  • WebFtpConnect Function
    Connects to the FTP server specified by sUrl.
  • WebFtpCreateDirectory Function
    Creates a new directory on the FTP server.
  • WebFtpDeleteFile Function
    Deletes a file stored on the FTP server.
  • WebFtpFindFirstFile Function
    Searches the specified directory of the given FTP session.
  • WebFtpFindNextFile Function
    Continues a file search started as a result of a preceding call to WebFtpFindFirstFile
  • WebFtpGetCurrentDirectory Function
    Retrieves the current directory for the specified FTP session.
  • WebFtpGetFile Function
    Retrieves a file from the FTP server.
  • WebFtpGetFileSize Function
    Retrieves the file size of a remote file, enumerated using WebFtpFindFirstFile/WebFtpFindNextFile functions.
  • WebFtpGetFileTime Function
    Retrieves the file date and time properties of a remote file, enumerated using WebFtpFindFirstFile/WebFtpFindNextFile functions.
  • WebFtpListDirectory Function
    Searches the specified directory of the given FTP session and retrieves a directory listing of the path specified in sSearchPath.
  • WebFtpOpenFile Function
    Opens a file on a remote server.
  • WebFtpPut Function
    Puts random data bytes in a file on the FTP server.
  • WebFtpPutFile Function
    Stores a file on the FTP server.
  • WebFtpReadFile Function
    Reads data from a previously opened file on a remote server.
  • WebFtpRemoveDirectory Function
    Removes the specified directory on the FTP server.
  • WebFtpRenameFile Function
    Renames a file or directory stored on the FTP server.
  • WebFtpSetCurrentDirectory Function
    Changes to a different working directory on the FTP server.
  • WebFtpShutdown Function
    Closes an open connection from a previous call to WebFtpConnect to a FTP server.
  • WebFtpWriteFile Function
    Writes data to a previously opened file on a remote server.
Parent topic: Internet Functions


WebSetPassiveFTP Function

Action

Sets the passive transfer semantics mode for FTP.

Include file

WebAPI.bdh

Syntax

WebSetPassiveFTP(in bPassive: boolean): boolean;

Return value

  • true if successful

  • false otherwise

Parameter | Description
bPassive | Passive transfer semantics mode

Example

dcltrans
  transaction TWebInit
  begin
    WebSetPassiveFTP(true);
end TWebInit;
Parent topic: FTP Functions Reference
Related reference
WebGetPassiveFTP Function


WebGetPassiveFTP Function

Action

Checks whether the Passive FTP flag is set.

Include file

WebAPI.bdh

Syntax

WebGetPassiveFTP(): boolean;

Return value

  • true if flag is set

  • false otherwise

Example

dcltrans
  transaction TWebInit
  begin
    write("FtpPassiveMode: ");
    if WebGetPassiveFtp() then
    write("true"); writeln;
    else
    write("false"); writeln;
end;
end TWebInit;
Parent topic: FTP Functions Reference
Related reference
WebSetPassiveFTP Function


WebFtpCloseFile Function

Action

Closes a file handle previously opened with WebFtpOpenFile.

Include file

WebAPI.bdh

Syntax

WebFtpCloseFile(in hFtp: number): boolean;

Return value

  • true if successful

  • false otherwise

Parameter | Description
hFtp | Valid handle to an FTP session. This handle must have been returned from a previous call to WebFtpConnect. Beside that, the file must have been opened using WebFtpOpenFile.

Example

dcltrans
  transaction TWriteFile
  var
    hFtp : number;
    sData : string(50);
    nData : number; // number of bytes written

  begin
    sData := "Hello world!";
    WebFtpConnect(hFtp, "localhost", WEB_PORT_FTP, "user", "pass");
    WebFtpOpenFile(hFtp, "testfile.txt", false, true);
    WebFtpWriteFile(hFtp, sData, Strlen(sData), nData);
    write(nData);
    writeln(" bytes written");
    WebFtpCloseFile(hFtp);
    WebFtpShutdown(hFtp);
  end TWriteFile;
Parent topic: FTP Functions Reference
Related reference
WebFtpOpenFile Function
WebFtpReadFile Function
WebFtpWriteFile Function


WebFtpConnect Function

Action

Connects to the FTP server specified by sUrl. You cannot connect to an FTP server via CERN proxies. Use WebUrl in that case. The handle returned in hFtp has to be used with all subsequent WebFtp function calls.

Include file

WebAPI.bdh

Syntax

WebFtpConnect( out hFtp  : number,
               in  sHost : string,
               in  nPort : number,
               in  sUser : string,
               in  sPass : string ): boolean;

Return value

  • true if the connection could be established

  • false otherwise

Parameter | Description
hFtp | Variable receiving the handle to the FTP session. If this parameter contains a handle to an FTP session prior to the WebFtpConnect function call, the memory allocated with the handle is released. Whenever you want to create a new FTP session, make sure this variable is initialized with 0 (this is automatically done within transactions when they are executed for the first time, but not within functions).
sHost | Host name of the remote FTP server to connect to.
nPort | Remote port to connect to. Use WEB_PORT_FTP to connect to the standard port.
sUser | User name
sPass | Password

Example

dcltrans
  transaction TMyTransaction
  var
    hFtp: number;
  begin
    WebFtpConnect(hFtp, "standardhost", WEB_PORT_FTP, "", "");
    WebFtpShutdown(hFtp);
  end TMyTransaction;

Sample scripts

WebMulti01.bdf

SilkEssential sample

Ftp.sep

Parent topic: FTP Functions Reference
Related reference
WebFtpShutdown Function


WebFtpCreateDirectory Function

Action

Creates a new directory on the FTP server.

Include file

WebAPI.bdh

Syntax

WebFtpCreateDirectory( in hFtp       : number,
                       in sDirectory : string ): boolean;

Return value

  • true if successful

  • false otherwise

Parameter | Description
hFtp | Valid handle to an FTP session. This handle must have been returned from a previous call to WebFtpConnect.
sDirectory | String that contains the name of the directory to create on the remote system. This can be either a fully qualified path or a name relative to the current directory.
Note: Use WebFtpGetCurrentDirectory to determine the remote site's current working directory, instead of assuming that the remote system uses a hierarchical naming scheme for directories. The sDirectory parameter can be either partially or fully qualified file names relative to the current directory. A backslash (\) or forward slash (/) can be used as the directory separator for either name. WebFtpCreateDirectory translates the directory name separators to the appropriate character before they are used.

Example

// Create a directory on the FTP server.
dcltrans
  transaction TWebFtpDir
  var
    hFtp: number;
  begin
    WebFtpConnect(hFtp, "standardhost", WEB_PORT_FTP,
                 "anonymous", "mymail@address.com");
    WebFtpCreateDirectory(hFtp, "/test_directory");
    WebFtpShutdown(hFtp);
  end TWebFtpDir;

Sample scripts

WebMulti01.bdf

SilkEssential sample

Ftp.sep

Parent topic: FTP Functions Reference
Related reference
WebFtpSetCurrentDirectory Function
WebFtpGetCurrentDirectory Function
WebFtpRemoveDirectory Function


WebFtpDeleteFile Function

Action

Deletes a file stored on the FTP server.

Include file

WebAPI.bdh

Syntax

WebFtpDeleteFile( in hFtp      : number,
                  in sFileName : string ): boolean;

Return value

  • true if successful

  • false otherwise

Parameter | Description
hFtp | Valid handle to an FTP session. This handle must have been returned from a previous call to WebFtpConnect.
sFileName | Null-terminated string that contains the name of the file to delete on the remote system
Note: The sFile parameter can be either partially or fully qualified file names relative to the current directory. A backslash (\) or forward slash (/) can be used as the directory separator for either name. WebFtpDeleteFile translates the directory name separators to the appropriate character before they are used.

Example

// Deletes a file on the FTP server.
dcltrans
  transaction TWebFtpDeleteFile
  var
    hFtp: number;
  begin
    WebFtpConnect(hFtp, "standardhost", WEB_PORT_FTP,
                  "anonymous", "mymail@address.com");
    WebFtpDeleteFile(hFtp, "renamed_test_file.txt");
    WebFtpShutdown(hFtp);
  end TWebFtpDeleteFile;

Sample scripts

WebMulti01.bdf

SilkEssential sample

Ftp.sep

Parent topic: FTP Functions Reference
Related reference
WebFtpGetFile Function
WebFtpPutFile Function
WebFtpPut Function
WebFtpRenameFile Function


WebFtpFindFirstFile Function

Action

Searches the specified directory of the given FTP session. File and directory entries are returned in the sFile string. This function lists both files and directories.

Include file

WebAPI.bdh

Syntax

WebFtpFindFirstFile( in  hFtp        : number,
                     in  sSearchFile : string allownull,
                     out sFile       : string,
                     in  nMaxFile    : number optional,
                     out nAttribute  : number optional): boolean;

Return value

  • true for the request if the directory enumeration was started successfully

  • false otherwise

Parameter | Description
hFtp | Valid handle to an FTP session. This handle must have been returned from a previous call to WebFtpConnect.
sSearchFile | String that specifies a valid directory path or file name for the FTP server's file system. If the value of sSearchFile is NULL or if it is an empty string, it will find the first file in the current directory on the server.
sFile | Parameter that receives the name of the file or directory
nMaxFile | Optional: Specifies the maximum length of the string to put into sFile
nAttribute

Optional: Parameter that receives one or more of the following attribute flags:

  • WEB_FTP_FA_READONLY

  • WEB_FTP_FA_HIDDEN

  • WEB_FTP_FA_SYSTEM

  • WEB_FTP_FA_DIRECTORY

  • WEB_FTP_FA_ARCHIVE

  • WEB_FTP_FA_NORMAL

  • WEB_FTP_FA_TEMPORARY

  • WEB_FTP_FA_COMPRESSED

  • WEB_FTP_FA_NO_MORE_FILES. Signals end of directory listing

Note: If the function finds no matching files, it returns false and sets the variable nAttribute to WEB_FTP_FA_NO_MORE_FILES.
Note: Only one WebFtpFindFirstFile can occur at a time within a given FTP session. The enumerations, therefore, are correlated with the FTP session handle. This is because FTP protocol allows only a single directory enumeration per session. After beginning a directory enumeration with WebFtpFindFirstFile, the WebFtpFindNextFile function can be used to continue the enumeration.

Example

// Connect to the ftp server and list the root directory
// 1) using WebFtpFindFirstFile, WebFtpFindNextFile in loops
// 2) using only the command WebFtpListDirectory
dcltrans
  transaction TWebFtpListDir
  var
    hFtp       : number;
    sFileName  : string(MAX_PATH);
    nAttribute : number;
    nFiles     : number;
    bOk        : boolean;
  begin
    WebFtpConnect(hFtp, "standardhost", WEB_PORT_FTP, "", "");
    nFiles := 0;

    // Custom directory list
    bOk := WebFtpFindFirstFile(hFtp, "", sFileName,
                               MAX_PATH, nAttribute);
    while bOk do
      Printwrite(sFileName + ); write(" " + ); write(nAttribute);
      writeln;
      nFiles++; := nFiles + 1;
      bOk := WebFtpFindNextFile(hFtp, sFileName,
                                MAX_PATH, nAttribute);
    end;

    if nAttribute = WEB_FTP_FA_NO_MORE_FILES then
      Printwrite((string(nFiles) + ); write(" files found"); writeLn;
    else
      writePrint("Error retrieving directory information!"); writeln;
    end;

    // The following command does the same
    WebFtpListDirectory(hFtp, "");
    WebFtpShutdown(hFtp);
  end TWebFtpListDir;

SilkEssential sample

Ftp.sep

Parent topic: FTP Functions Reference
Related reference
WebFtpListDirectory Function
WebFtpFindNextFile Function
WebFtpConnect Function


WebFtpFindNextFile Function

Action

Continues a file search started as a result of a preceding call to WebFtpFindFirstFile.

Include file

WebAPI.bdh

Syntax

WebFtpFindNextFile( in  hFtp       : number,
                    out sFile      : string,
                    in  nMaxFile   : number optional,
                    out nAttribute : number optional): boolean;

Return value

  • true if successful

  • false otherwise

Parameter | Description
hFtp | Valid handle to an FTP session. This handle must have been returned from a previous call to WebFtpConnect. A successful call to WebFtpFindFirstFile has to be completed before WebFtpFindNextFile can be used.
sFile | Parameter that receives the name of the file or directory
nMaxFile | Optional: Parameter that specifies the maximum length of the string to put into sFile
nAttribute

Optional: Parameter that receives one or more of the following attribute flags:

  • WEB_FTP_FA_READONLY

  • WEB_FTP_FA_HIDDEN

  • WEB_FTP_FA_SYSTEM

  • WEB_FTP_FA_DIRECTORY

  • WEB_FTP_FA_ARCHIVE

  • WEB_FTP_FA_NORMAL

  • WEB_FTP_FA_TEMPORARY

  • WEB_FTP_FA_COMPRESSED

  • WEB_FTP_FA_NO_MORE_FILES. Signals end of directory listing

Note: If there are no more files to enumerate, WebFtpFindNextFile returns false and sets the variable to WEB_FTP_FA_NO_MORE_FILES.

Example

dcltrans
  transaction TWebFtpListDir
  var
    hFtp       : number;
    sFileName  : string(MAX_PATH);
    nAttribute : number;
    nFiles     : number;
    bOk        : boolean;
  begin
    WebFtpConnect(hFtp, "standardhost", WEB_PORT_FTP, "", "");
    nFiles := 0;

    // Custom directory list
    bOk := WebFtpFindFirstFile(hFtp, "", sFileName,
                               MAX_PATH, nAttribute);
    while bOk do
      Print(sFileName + " " + nAttribute);
      nFiles++;
      bOk := WebFtpFindNextFile(hFtp, sFileName,
                                MAX_PATH, nAttribute);
    end;

    if nAttribute = WEB_FTP_FA_NO_MORE_FILES then
      Print(string(nFiles) + " files found");
    else
      Print("Error retrieving directory information!");
    end;

    // The following command does the same
    WebFtpListDirectory(hFtp, "");
    WebFtpShutdown(hFtp);
  end TWebFtpListDir;

SilkEssential sample

Ftp.sep

Parent topic: FTP Functions Reference
Related reference
WebFtpListDirectory Function
WebFtpFindFirstFile Function
WebFtpConnect Function


WebFtpGetCurrentDirectory Function

Action

Retrieves the current directory for the specified FTP session.

Include file

WebAPI.bdh

Syntax

WebFtpGetCurrentDirectory( in  hFtp              : number,
                           out sCurrentDirectory : string,
                           in  nMaxDir           : number optional ): boolean;

Return value

  • true if successful

  • false otherwise

Parameter | Description
hFtp | Valid handle to an FTP session. This handle must have been returned from a previous call to WebFtpConnect.
sCurrentDirectory | A string that receives the current directory name, which specifies the absolute path to the current directory.
nMaxDir | Maximum length of the string to put into sCurrentDirectory (optional).

Make sure the length of the string is greater than or equal to nMaxDir. If the sCurrentDirectory buffer is not large enough, nMaxDir receives the number of bytes required to retrieve the full, current directory name.

Example

// Connects to the FTP server and retrieves the current directory.
dcltrans
  transaction TWebFtpDir
  var
    hFtp : number;
    sDirName : string(MAX_PATH);
  begin
    WebFtpConnect(hFtp, "standardhost", WEB_PORT_FTP,
                    "anonymous", "mymail@address.com");
    WebFtpGetCurrentDirectory(hFtp, sDirName);
    WebFtpShutdown(hFtp);
  end TWebFtpDir;

SilkEssential sample

Ftp.sep

Parent topic: FTP Functions Reference
Related reference
WebFtpCreateDirectory Function
WebFtpSetCurrentDirectory Function
WebFtpRemoveDirectory Function


WebFtpGetFile Function

Action

Retrieves a file from the FTP server.

Include file

WebAPI.bdh

Syntax

WebFtpGetFile( in hFtp            : number,
               in sRemoteFile     : string,
               in bBinaryTransfer : boolean ): boolean;

Return value

  • true if successful

  • false otherwise

Parameter | Description
hFtp | Valid handle to an FTP session. This handle must have been returned from a previous call to WebFtpConnect.
sRemoteFile | String that contains the name of the file to retrieve from the remote system. Can be either partially or fully qualified file name relative to the current directory. A backslash (\) or forward slash (/) can be used as the directory separator for either name. WebFtpGetFile translates the directory name separators to the appropriate characters before they are used.
bBinaryTransfer

If this parameter is set to true, WebGetFile transfers the file using FTP's Image (Type I) transfer method. The file is transferred exactly as it exists with no changes. This is the default transfer method.

If this parameter is set to false, FTP's ASCII (Type A) transfer method is used. Control and formatting information is converted to local equivalents.
Note: The file is only read from the remote host, but not stored on the local computer. Use the functions WebFtpOpenFile, WebFtpReadFile, WebFtpWriteFile and WebFtpCloseFile to exchange files between the local and the remote host.

Example

// Gets a file from the FTP server.
dcltrans
  transaction TWebFtpDir
  var
    hFtp: number;
  begin
    WebFtpConnect(hFtp, "standardhost", WEB_PORT_FTP,
                 "anonymous", "mymail@address.com");
    WebFtpGetFile(hFtp, "test_file.txt", FALSE);
    WebFtpShutdown(hFtp);
  end TWebFtpDir;

SilkEssential sample

Ftp.sep

Parent topic: FTP Functions Reference
Related reference
WebFtpDeleteFile Function
WebFtpPutFile Function
WebFtpPut Function
WebFtpRenameFile Function


WebFtpGetFileSize Function

Action

Retrieves the file size of a remote file, enumerated using WebFtpFindFirstFile/WebFtpFindNextFile functions.

Include file

WebAPI.bdh

Syntax

WebFtpGetFileSize( in  hFtp      : number,
                   out fFileSize : float ): boolean;

Return value

  • true if successful

  • false otherwise

Parameter | Description
hFtp | Valid handle to an FTP session. This handle must have been returned from a previous call to WebFtpConnect.
fFileSize | Variable that receives the file size in bytes. This parameter is an 8 byte float which allows to cope with files greater than 4 GB.

Example

dcltrans
  transaction TGetFileSize
  var
    hFtp  : number;
    fFileSize : float;
    nDate     : number;
    nTime     : number;
    sFileName : string;
    sDateTime : string;

  begin
    WebFtpConnect(hFtp, "localhost", WEB_PORT_FTP, "user", "pass");
    WebFtpFindFirstFile(hFtp, "testfile.txt", sFileName);
    WebFtpGetFileSize(hFtp, fFileSize);
    Print("The file " + sFileName + " has " + fFileSize + " bytes.");
    WebFtpGetFileTime(hFtp, nDate, nTime, WEB_FTP_FILETIME_MODIFIED);
    FormatDateTime(nDate, nTime, "%Y-%m-%d %H:%M:%S", sDateTime);
    Print(sFilename + " modified time is " + sDateTime);
    WebFtpShutdown(hFtp);
  end TGetFileSize;
Parent topic: FTP Functions Reference


WebFtpGetFileTime Function

Action

Retrieves the file date and time properties of a remote file, enumerated using WebFtpFindFirstFile/WebFtpFindNextFile functions.

Include file

WebAPI.bdh

Syntax

WebFtpGetFileTime( in  hFtp  : number,
                   out uDate : number,
                   out uTime : number,
                   in  eTime : number): boolean;

Return value

  • true if successful

  • false otherwise

Parameter | Description
hFtp | Valid handle to an FTP session. This handle must have been returned from a previous call to WebFtpConnect.
uDate | Variable that receives the file date property with format YYYYMMDD.
uTime | Variable that receives the file time property of the current day in seconds.
eTime Specifies which file time property should be retrieved. The following options are supported:
  • WEB_FTP_FILETIME_CREATED
  • WEB_FTP_FILETIME_MODIFIED
  • WEB_FTP_FILETIME_ACCESSED

Example

Note: The uDate and uTime variables are ready to be passed to the FormatDateTime function to convert the timestamp into a readable format.
dcltrans
  transaction TGetFileSize
  var
    hFtp      : number;
    fFileSize : float;
    nDate     : number;
    nTime     : number;
    sFileName : string;
    sDateTime : string;
  begin
    WebFtpConnect(hFtp, "localhost", WEB_PORT_FTP, "user", "pass");
    WebFtpFindFirstFile(hFtp, "testfile.txt", sFileName);
    WebFtpGetFileSize(hFtp, fFileSize);
    Print("The file " + sFileName + " has " + fFileSize + " bytes.");

    WebFtpGetFileTime(hFtp, nDate, nTime, WEB_FTP_FILETIME_MODIFIED);
    FormatDateTime(nDate, nTime, "%Y-%m-%d %H:%M:%S", sDateTime);
    Print(sFilename + " modified time is " + sDateTime);

    WebFtpShutdown(hFtp);
  end TGetFileSize;
Parent topic: FTP Functions Reference


WebFtpListDirectory Function

Action

Searches the specified directory of the given FTP session and retrieves a directory listing of the path specified in sSearchPath. If you want to access the data of the directory listing, use WebFtpFindFirstFile and WebFtpFindNextFile instead, as illustrated in the example below.

Include file

WebAPI.bdh

Syntax

WebFtpListDirectory( in hFtp        : number,
                     in sSearchPath : string optional ): boolean;

Return value

  • true if the directory list was started successfully

  • false otherwise

Parameter | Description
hFtp | Valid handle to an FTP session. This handle must have been returned from a previous call to WebFtpConnect.
sSearchPath | String that specifies a valid directory path or file name for the FTP server's file system. If the value of sSearchPath is NULL or if it is an empty string, this function will find the first file in the current directory on the server (optional).
Note: If the function finds no matching files, it returns false.

Example

// Connect to the ftp server and list the root directory
// 1) using WebFtpFindFirstFile, WebFtpFindNextFile in loops
// 2) using only the command WebFtpListDirectory
dcltrans
  transaction TWebFtpListDir
  var
    hFtp       : number;
    sFileName  : string(MAX_PATH);
    nAttribute : number;
    nFiles     : number;
    bOk        : boolean;
  begin
    WebFtpConnect(hFtp, "standardhost", WEB_PORT_FTP, "", "");
    nFiles := 0;

    // Custom directory list enumeration
    bOk := WebFtpFindFirstFile(hFtp, "", sFileName,
                               MAX_PATH, nAttribute);

    while bOk do
      write(sFileName); write(" "); write(nAttribute); writeln;
      nFiles := nFiles + 1;
      bOk := WebFtpFindNextFile(hFtp, sFileName,
                                MAX_PATH, nAttribute);
    end;

    if nAttribute = WEB_FTP_FA_NO_MORE_FILES then
      write(nFiles); write(" files found"); writeLn;
    else
      write("Error retrieving directory information!");
      writeln;
    end;

    // This command sends the FTP commands to get a directory list
    WebFtpListDirectory(hFtp, "");
    WebFtpShutdown(hFtp);
  end TWebFtpListDir;

SilkEssential sample

Ftp.sep

Parent topic: FTP Functions Reference
Related reference
WebFtpFindFirstFile Function
WebFtpFindNextFile Function
WebFtpConnect Function


WebFtpOpenFile Function

Action

Opens a file on a remote server.

Include file

WebAPI.bdh

Syntax

WebFtpOpenFile(in hFtp : number,
                           in sFile : string,
                           in bBinaryTransfer : boolean,
                           in bWriteMode : boolean): boolean;

Return value

  • true if successful

  • false otherwise

Parameter | Description
hFtp | Valid handle to an FTP session. This handle must have been returned from a previous call to WebFtpConnect.
sFile | Target filename
bBinaryTransfer

If set to true, the file is opened for using FTP's Image (Type I) transfer method. The file is written and read exactly as it exists with no changes. This is the default transfer method.

If set to false, FTP's ASCII (Type A) transfer method is used for reading and writing. Control and formatting information is converted to local equivalents.
bWriteMode

Specifies whether a file is opened for writing or reading purpose.

If this parameter is set to true, the file is opened in write mode. In this case, the previous file content is overwritten. Otherwise, the file is opened for reading purpose.

Example

dcltrans
transaction TWriteFile
var
    hFtp : number;
    sData : string(50);
    nData : number; // number of bytes written

begin  sData := "Hello world!";
    WebFtpConnect(hFtp, "localhost", WEB_PORT_FTP, "user", "pass");
    WebFtpOpenFile(hFtp, "testfile.txt", false, true);
    WebFtpWriteFile(hFtp, sData, Strlen(sData), nData);
  write(nData); write(" bytes written");
  writeln;
    WebFtpCloseFile(hFtp);
    WebFtpShutdown(hFtp);
end TWriteFile;
Parent topic: FTP Functions Reference
Related reference
WebFtpCloseFile Function
WebFtpReadFile Function
WebFtpWriteFile Function


WebFtpPut Function

Action

Puts random data bytes in a file on the FTP server.

Include file

WebAPI.bdh

Syntax

WebFtpPut( in hFtp            : number,
           in nBytes          : number,
           in sRemoteFile     : string,
           in bBinaryTransfer : boolean): boolean;

Return value

  • true if successful

  • false otherwise

Parameter | Description
hFtp | Valid handle to an FTP session
nBytes | Number of bytes to be generated randomly
sRemoteFile | String that contains the name of the file to create on the remote system. Can be either partially or fully qualified file name relative to the current directory. A backslash (\) or forward slash (/) can be used as the directory separator for either name. WebFtpPut translates the directory name separators to the appropriate character before they are used.
bBinaryTransfer

If this parameter is set to true, WebGetFile transfers the file using FTP's Image (Type I) transfer method. The file is transferred exactly as it exists with no changes. This is the default transfer method.

If this parameter is set to false, FTP's ASCII (Type A) transfer method is used. Control and formatting information is converted to local equivalents.

Example

// Put random data bytes in a file on the FTP server.
dcltrans
  transaction TWebFtpDir
  var
    hFtp   : number;
    nBytes : number;
  begin
    WebFtpConnect(hFtp, "standardhost", WEB_PORT_FTP,
                   "anonymous", "mymail@address.com");
    nBytes := RndUniN(1000..5000);
    WebFtpPut(hFtp, nBytes, "RndGenTestFile", true);
    WebFtpShutdown(hFtp);
  end TWebFtpDir;

Sample scripts

WebMulti01.bdf

Parent topic: FTP Functions Reference
Related reference
WebFtpDeleteFile Function
WebFtpGetFile Function
WebFtpPutFile Function
WebFtpRenameFile Function


WebFtpPutFile Function

Action

Stores a file on the FTP server.

Include file

WebAPI.bdh

Syntax

WebFtpPutFile( in hFtp            : number,
               in sLocalFile      : string,
               in sRemoteFile     : string,
               in bBinaryTransfer : boolean ): boolean;

Return value

  • true if successful

  • false otherwise

Parameter | Description
hFtp | Valid handle to an FTP session
sLocalFile | String that contains the name of the file to send from the local system
sRemoteFile | String that contains the name of the file to create on the remote system. Can be either partially or fully qualified file name relative to the current directory. A backslash (\) or forward slash (/) can be used as the directory separator for either name. WebFtpPutFile translates the directory name separators to the appropriate character before they are used.
bBinaryTransfer

If this parameter is set to true, WebGetFile transfers the file using FTP's Image (Type I) transfer method. The file is transferred exactly as it exists with no changes. This is the default transfer method.

If this parameter is set to false, FTP's ASCII (Type A) transfer method is used. Control and formatting information is converted to local equivalents.

Example

// Store a file on the FTP server.
dcltrans
  transaction TWebFtpDir
  var
    hFtp: number;
  begin
    WebFtpConnect(hFtp, "standardhost", WEB_PORT_FTP,
                     "anonymous", "mymail@address.com");
    WebFtpPutFile(hFtp, "perfrep1.qrp", "test_file.txt", false);
    WebFtpShutdown(hFtp);
  end TWebFtpDir;

SilkEssential sample

Ftp.sep

Parent topic: FTP Functions Reference
Related reference
WebFtpDeleteFile Function
WebFtpGetFile Function
WebFtpPut Function
WebFtpRenameFile Function


WebFtpReadFile Function

Action

Reads data from a previously opened file on a remote server.

Include file

WebAPI.bdh

Syntax

WebFtpReadFile( in  hFtp     : number,
                out sData    : string,
                in  nMaxData : number,
                out nRead    : number ): boolean;

Return value

  • true if successful

  • false otherwise

Parameter | Description
hFtp | Valid handle to an FTP session. This handle must have been returned from a previous call to WebFtpConnect. Beside that, the file must have been opened using WebFtpOpenFile.
sData | Buffer to store the received data. Make sure to set nMaxData <= size of sData
nMaxData | Maximum amount of data to read from server. Make sure to set nMaxData <= size of sData
nRead | Variables that receives the number of bytes read

Example

dcltrans
  transaction TReadFile
  var
    hFtp  : number;
    sData : string(5000);
    nData : number; // number of bytes read
  begin
    WebFtpConnect(hFtp, "localhost", WEB_PORT_FTP, "user", "pass");
    WebFtpOpenFile(hFtp, "testfile.txt", false, false);
    WebFtpReadFile(hFtp, sData, STRING_COMPLETE, nData);
    write(sData); writeln;
    WebFtpCloseFile(hFtp);
    WebFtpShutdown(hFtp);
  end TReadFile;
Parent topic: FTP Functions Reference
Related reference
WebFtpCloseFile Function
WebFtpOpenFile Function
WebFtpWriteFile Function


WebFtpRemoveDirectory Function

Action

Removes the specified directory on the FTP server.

Include file

WebAPI.bdh

Syntax

WebFtpRemoveDirectory( in hFtp       : number,
                       in sDirectory : string ) : boolean;

Return value

  • true if successful

  • false otherwise

Parameter | Description
hFtp | Valid handle to an FTP session. This handle must have been returned from a previous call to WebFtpConnect.
sDirectory | String that contains the name of the directory to remove on the remote system. This can be either a fully qualified path or a name relative to the current directory.
Note: Use WebFtpGetCurrentDirectory to determine the remote site's current working directory, instead of assuming that the remote system uses a hierarchical naming scheme for directories. The lpszDirectory parameter can be either partially or fully qualified file names relative to the current directory. A backslash (\) or forward slash (/) can be used as the directory separator for either name. WebFtpRemoveDirectory translates the directory name separators to the appropriate character before they are used.

Example

// Create and remove a directory on the FTP server.
dcltrans
  transaction TWebFtpDir
  var
    hFtp: number;
  begin
    WebFtpConnect(hFtp, "standardhost", WEB_PORT_FTP,
                 "anonymous", "mymail@address.com");
    WebFtpCreateDirectory(hFtp, "/test_directory");
    WebFtpRemoveDirectory(hFtp, "/test_directory");
    WebFtpShutdown(hFtp);
  end TWebFtpDir;

Sample scripts

WebMulti01.bdf

SilkEssential sample

Ftp.sep

Parent topic: FTP Functions Reference
Related reference
WebFtpCreateDirectory Function
WebFtpSetCurrentDirectory Function
WebFtpGetCurrentDirectory Function


WebFtpRenameFile Function

Action

Renames a file or directory stored on the FTP server.

Include file

WebAPI.bdh

Syntax

WebFtpRenameFile( in hFtp         : number,
                  in sOldFilename : string,
                  in sNewFilename : string ) : boolean;

Return value

  • true if successful

  • false otherwise

Parameter | Description
hFtp | Valid handle to an FTP session
sOldFilename | String that contains the name of the file that will have its name changed on the remote FTP server
sNewFilename | Null-terminated string that contains the new name for the remote file
Note: The sOldFilename and sNewFilename parameters can be either partially or fully qualified file names relative to the current directory. A backslash (\) or forward slash (/) can be used as the directory separator for either name. WebFtpRenameFile translates the directory name separators to the appropriate character before they are used.

Example

// Rename a file on the FTP server.
dcltrans
  transaction TWebFtpDir
  var
    hFtp: number;
  begin
    WebFtpConnect(hFtp, "standardhost", WEB_PORT_FTP,
                 "anonymous", "mymail@address.com");
    WebFtpRenameFile(hFtp, "test_file.txt","renamed_test_file.txt");
    WebFtpShutdown(hFtp);
  end TWebFtpDir;

SilkEssential sample

Ftp.sep

Parent topic: FTP Functions Reference
Related reference
WebFtpDeleteFile Function
WebFtpGetFile Function
WebFtpPutFile Function
WebFtpPut Function


WebFtpSetCurrentDirectory Function

Action

Changes to a different working directory on the FTP server.

Include file

WebAPI.bdh

Syntax

WebFtpSetCurrentDirectory( in hFtp      : number,
                           in sDirectory : string ) : boolean;

Return value

  • true if successful

  • false otherwise

Parameter | Description
hFtp | Valid handle to an FTP session. This handle must have been returned from a previous call to WebFtpConnect.
sDirectory | String that contains the name of the directory to change to on the remote system. This can be either a fully qualified path or a name relative to the current directory.
Use WebFtpGetCurrentDirectory to determine the remote site's current working directory, instead of assuming that the remote system uses a hierarchical naming scheme for directories. The sDirectory parameter can be either partially or fully qualified file names relative to the current directory. A backslash (\) or forward slash (/) can be used as the directory separator for either name. WebFtpSetCurrentDirectory translates the directory name separators to the appropriate character before they are used.

Example

// Set the current directory on the FTP server.
dcltrans
  transaction TWebFtpDir
  var
    hFtp: number;
  begin
    WebFtpConnect(hFtp, "standardhost", WEB_PORT_FTP,
                 "anonymous", "mymail@address.com");
    WebFtpSetCurrentDirectory(hFtp, "/");
    WebFtpShutdown(hFtp);
  end TWebFtpDir;

Sample scripts

WebMulti01.bdf

SilkEssential sample

Ftp.sep

Parent topic: FTP Functions Reference
Related reference
WebFtpCreateDirectory Function
WebFtpGetCurrentDirectory Function
WebFtpRemoveDirectory Function


WebFtpShutdown Function

Action

Closes an open connection from a previous call to WebFtpConnect to a FTP server.

Include file

WebAPI.bdh

Syntax

WebFtpShutdown( inout hFtp      : number,
                in    bGraceful : boolean optional ) : boolean;

Return value

  • true if successful

  • false otherwise

Parameter | Description
hFtp | Valid handle to an FTP session. This handle must have been returned from a previous call to WebFtpConnect.
bGraceful | If this parameter is set to true a QUIT command is sent before the connection is closed (optional). If this parameter is omitted no QUIT command is sent.

Example

// Connect to the ftp server
dcltrans
  transaction TMyTransaction
  var
    hFtp: number;
  begin
    WebFtpConnect(hFtp, "standardhost", WEB_PORT_FTP, "", "");
    WebFtpShutdown(hFtp);
  end TMyTransaction;

Sample scripts

WebMulti01.bdf

SilkEssential sample

Ftp.sep

Parent topic: FTP Functions Reference
Related reference
WebFtpConnect Function


WebFtpWriteFile Function

Action

Writes data to a previously opened file on a remote server.

Include file

WebAPI.bdh

Syntax

WebFtpWriteFile(in hFtp : number,
                        in sData : string,
                        in nData : number,
                        out nWritten : number): boolean;

Return value

  • true if successful

  • false otherwise

Parameter | Description
hFtp | Valid handle to an FTP session. This handle must have been returned from a previous call to WebFtpConnect. Beside that, the file must have been opened using WebFtpOpenFile.
sData | Buffer that contains the data to write
nData | Number of bytes to write to the file
nWritten | Variable that receives the number of bytes written

Example

dcltrans
  transaction TWriteFile
  var
    hFtp : number;
    sData : string(50);
    nData : number; // number of bytes written
  begin
    sData := "Hello world!";
    WebFtpConnect(hFtp, "localhost", WEB_PORT_FTP, "user", "pass");
    WebFtpOpenFile(hFtp, "testfile.txt", false, true);
    WebFtpWriteFile(hFtp, sData, Strlen(sData), nData);
    write(nData); write(" bytes written"); writeln;
    WebFtpCloseFile(hFtp);
    WebFtpShutdown(hFtp);
end TWriteFile;
Parent topic: FTP Functions Reference
Related reference
WebFtpCloseFile Function
WebFtpOpenFile Function
WebFtpReadFile Function


HLS Functions Reference

Lists BDL functions for testing applications that use HTTP Live Streaming (HLS).

  • HlsInit Function
    Initializes an HLS stream.
  • HlsPlay Function
    Starts an HLS stream. A WebUrl function with the playlist (.m3u8) must be called before HlsPlay.
Parent topic: Internet Functions


HlsInit Function

Action

Initializes an HLS stream handle. Similar to web parsing functions, HlsInit has to be called prior to a web function, which requests a playlist resource either directly or indirectly through a web page with an embedded playlist. Once the returned handle is associated with the playlist, it can be passed to a subsequent HlsPlay function call to start simulating playback of the stream.

Include file

hls.bdh

Syntax

HlsInit(): number;

Return value

hStream: Handle to the HLS stream.

Example

dcltrans
    transaction TNoParams
  var
    hStream : number;
  begin
    hStream := HlsInit();
    WebUrl("http://lnz-streaming/basic/basicshort.m3u8");
    HlsPlay(hStream, "Identifier", 0.00, 60.0, "MyLiveStream");
  end TNoParams;
Parent topic: HLS Functions Reference


HlsPlay Function

Action

Starts downloading stream segments and simulates playback of the HLS stream associated with the stream handle. A web function to request a playlist (.m3u8) resource must be called prior to HlsPlay to associate the stream handle with the stream. The function blocks until either the stream playback completed or the playback was interrupted due to a buffer underrun.

The HlsPlay function leads to shorter scripts as it prevents that every single media segment is listed in the script. It also ensures that the resulting TrueLog remains clear, because all media segments are listed under the respective node in the tree. Furthermore, it enables recording dynamically generated live playlists in the first place, as this would not be possible with conventional recording.

Include file

hls.bdh

Syntax

HlsPlay( in hStream     : number,
         in sIdentifier : string optional,
         in fStartTime  : double optional,
         in fDuration   : double optional,
         in sTimer      : string optional): boolean;
Parameter | Description
hStream | Handle to HLS stream that was created by HlsInit function.
sIdentifier | Specifies the value of the EXT-X-MEDIA tag's NAME or BANDWIDTH attribute or its 1-based index within the master playlist. By default, the first stream in the master playlist is chosen. (optional). For example: If the first stream in your master playlist had the attributes BANDWIDTH=246440, NAME="smallResolution", you could choose it by specifying the identifiers smallResolution (for the name), 246440 (for the bandwidth), 1 (the index of the first element), or by leaving it empty (default).
fStartTime | Specifies the start time in seconds (optional). The default value is 0.0. Requires a float, so make sure to include a comma with your value.
fDuration | Specifies the duration in seconds (optional). Specify FULL_STREAM (default) for a complete playback. Requires a float, so make sure to include a comma with your value.
sTimer | Optional timer name to associate measures with the stream. If a timer name is provided, Silk Performer reports stream statistics.

Return value

  • true if the play attempt is completed successfully
  • false otherwise

Example

dcltrans
    transaction TNoParams
  var
    hStream : number;
  begin
    hStream := HlsInit();
    WebUrl("http://lnz-streaming/basic/basicshort.m3u8");
    HlsPlay(hStream, "Identifier", 0.0, 60.0, "MyLiveStream");
  end TNoParams;
Parent topic: HLS Functions Reference


JSON Functions Reference

  • JSON General Information
    Describes the basic JSON knowledge.
  • JSON Functions
    Lists all functions of the JSON API.
Parent topic: Internet Functions


JSON General Information

  • JSON Basics
    Provides the basic knowledge you need to know, to work with the JSON API.
  • JSON First Steps
    Describes how to get started with JSON.
  • JSON Encoding
    Describes how to convert ANSI strings to UTF-8 strings and vice versa.
Parent topic: JSON Functions Reference


JSON Basics

This section provides the basic knowledge you need to know, to work with the JSON API.

  • JSON Object Structure
    Describes what a JSON object is, how it is structured, and what value data types are available.
  • JSON Array Structure
    Describes what a JSON array is, how it is structured, and what data types are allowed in a JSON array.
Parent topic: JSON General Information


JSON Object Structure

A JSON object contains zero, one, or more key-value pairs, also called properties. The object is surrounded by curly braces {}. Every key-value pair is separated by a comma. The order of the key-value pair is irrelevant.

A key-value pair consists of a key and a value, separated by a colon (:). The key is a string, which identifies the key-value pair. The value can be any of the following data types:

string | surrounded by quotation marks (" ")
number |
float |
array | JSON array
object | JSON object (can be nested)
boolean | true or false
empty | null

Examples

{ } //Empty JSON object

{
     “StringProperty”: “StringValue”,
     “NumberProperty”: 10,
     “FloatProperty”: 20.13,
     “BooleanProperty”: true,
     “EmptyProperty”: null
}

{
    “NestedObjectProperty”: {
        “Name”: “Neste  Object”
    },
    “NestedArrayProperty”: [10,20,true,40]
}
Parent topic: JSON Basics


JSON Array Structure

A JSON array contains zero, one, or more ordered elements, separated by a comma. The JSON array is surrounded by square brackets [ ].

A JSON array is zero terminated, the first index of the array is zero (0). Therefore, the last index of the array is length - 1.

In contrast to regular arrays from the BDL, the elements of a JSON array can be of different data types. The following data types are allowed for JSON arrays:

string | surrounded by quotation marks (" ")
number |
float |
array | JSON array (can be nested)
object | JSON object
boolean | true or false
empty | null

Examples

[ ] //Empty JSON array

[ 0, 1, 2, 3, 4, 5]

[ “StringValue”, 10, 20.13, true, null ]

[
 {
   “Name” : “Nested Object”
 },
 [ 10, 20, true, 40, “Nested Array” ]
]
Parent topic: JSON Basics


JSON First Steps

This section describes how to get started with JSON.

  • Getting Access to the JSON API
    Describes how to get access to the JSON API.
  • Creating JSON Arrays and JSON Objects
    Describes how to create JSON arrays and JSON objects.
  • Receiving Nested JSON Objects and JSON Arrays
    Describes how to retrieve the value of a specified property or of a specified element from a JSON object or a JSON array.
  • Getting the String Representation
    Describes the JsonToText function, which returns a JSON array or a JSON object as string.
  • Working with Properties and Elements
    Describes how to get property values from a JSON object or element values from a JSON array and how to set these values.
  • Removing Properties and Elements
    Describes how to remove properties and elements from JSON objects and JSON arrays.
  • Getting and Setting the Size of a JSON Array
    Describes how to get and set the number of elements of a JSON array.
  • Deleting JSON Objects and JSON Arrays
    Describes how to delete JSON objects and arrays.
Parent topic: JSON General Information


Getting Access to the JSON API

To get access to the JSON API, use the statement Json.bdh.

Parent topic: JSON First Steps


Creating JSON Arrays and JSON Objects

The BDL JSON API provides many functions to create and receive JSON arrays and JSON objects.

JsonParse

This function creates a JSON array or a JSON object from a string value. It returns the handle to the JSON array or the JSON object.

When the JSON array or the JSON object is not needed any longer, it is important to manually delete it from the memory with the function JsonFree.

dcltrans
    transaction TMain
    var
        jsonArray  : number;
        jsonObject : number;
    begin
        jsonArray := JsonParse(“[ \“StringValue\”, 10, 20.13, true, null ]”);
        jsonObject := JsonParse(“{ \”Id\”: 1, \”Name\” : \“New Object\” }”);

        ...

        JsonFree(jsonArray);
        JsonFree(jsonObject);
    end TMain;

JsonObjectCreate, JsonArrayCreate

This function creates an empty JSON object or an empty JSON array. It returns the handle to the JSON object or the JSON array.

When the JSON object or the JSON array is not needed any longer, it is important to manually delete it from the memory with the function JsonFree.

dcltrans
    transaction TMain
    var
        jsonObject : number;
        jsonArray : number;
    begin
        jsonObject := JsonObjectCreate;
        jsonArray:= JsonArrayCreate;

        ...

        JsonFree(jsonObject);
        JsonFree(jsonArray);
    end TMain;
Parent topic: JSON First Steps


Receiving Nested JSON Objects and JSON Arrays

JsonGetObjectProperty, JsonGetArrayProperty

These functions retrieve the value of a specified property from a JSON object. If the property does not exist in the JSON object or the property does not contain a JSON object value or a JSON array value, nothing happens.

JSON objects and JSON arrays that are received by these functions can be removed from memory with JsonFree. However, objects and arrays are automatically deleted when you call JsonFree on the parent JSON object.

dcltrans
  transaction TMain
  var
    jsonParentString : string;
    jsonParent       : number;
    jsonArray        : number;
    jsonObject       : number;
  begin
    jsonParentString :=
"{"
  "\"NestedObjectProperty\": {"
    "\"Name\": \"Nested Object\""
    "},"
  "\NestedArrayProperty\": [10,20,true,40]"
"}";
    jsonParent := JsonParse(jsonParentString);

    JsonGetArrayProperty(jsonParent, "NestedArrayProperty", jsonArray);
    JsonGetObjectProperty(jsonParent, "NestedObjectProperty", jsonObject);

    ...

    JsonFree(jsonParent);
  end TMain;

JsonArrayGetObjectElement, JsonArrayGetArrayElement

These functions retrieve the value of a specified element from a JSON array. Their behavior is similar to the behavior of the functions JsonGetObjectProperty and JsonGetArrayProperty. The only difference is that they return specified elements from a JSON array instead of properties from a JSON object.

dcltrans
  transaction TMain
  var
    jsonParentString : string;
    jsonParent       : number;
    jsonArray        : number;
    jsonObject       : number;
  begin
    jsonParentString :=
"["
  "{"
    "\"Name\": \"Nested Object\""
  "},"
  "[10,20,true,40]"
"]";
    jsonParent := JsonParse(jsonParentString);

    JsonArrayGetArrayElement(jsonParent, "NestedArrayProperty", jsonArray);
    JsonArrayGetObjectElement(jsonParent, "NestedObjectProperty", jsonObject);

    ...

    JsonFree(jsonParent);
  end TMain;
Parent topic: JSON First Steps


Getting the String Representation

JsonToText

This function returns the whole JSON array or the whole JSON object as string. The resulting string has the following characteristics:
  • The properties of an object are sorted ascending by their name.
  • The elements of an array are sorted ascending by their index.
  • This string representation contains no whitespaces for formatting.
Parent topic: JSON First Steps


Working with Properties and Elements

There are several functions to get property values from a JSON object or element values from a JSON array and to set these values. The functions differ in the data type of the property or element they want to get or set.

Get, set, and create properties

Note: The name of a property is case sensitive.

JsonGet … Property(handle : in number,
                   property : in string,
                   value : out … ): boolean;
JsonSet … Property(handle : in number,
                   property : in string,
                   value : in … ): boolean;

In case the requested property does not exist in the JSON object, nothing happens and the function JsonGet ... Property returns false. When calling the function JsonSet ... Property with a not existing property name, the property will be created.

Get, set, and create elements

Note: The index of the array is zero terminated.

JsonArrayGet … Element (handle : in number,
                           index : in number,
                           value : out … ): boolean;
JsonArraySet … Element (handle : in number,
                           index : in number,
                           value : in … ): boolean;

In case the requested element does not exist in the JSON object, nothing happens and the function JsonArrayGet ... Element returns false. When calling the function JsonArraySet ... Element with a not existing index, the value will be appended to the array. Therefore there is no guarantee that the index of the new element is equal to the specified index.

Parent topic: JSON First Steps


Removing Properties and Elements

The JSON API provides several functions to remove properties from JSON objects and elements from JSON arrays.

JsonRemoveProperty

Existing properties can be removed from a JSON object.

dcltrans
    transaction TMain
    var
        jsonObject : number;
        jsonText   : string;
    begin
        jsonObject := JsonParse(“{ \”Id\”: 1, \”Name\” : \“New Object\” }”);

        JsonToText(jsonArray, jsonText);
        Print(“Before: “ + jsonText);

        JsonRemoveProperty(jsonObject, “Name”);

        JsonToText(jsonArray, jsonText);
        Print(“After: “ + jsonText);

        JsonFree(jsonObject);
    end TMain;

Output
Before: {”Id”:1,”Name”:“New Object”}
After:  {”Id”:1}

JsonArrayRemoveElement

Existing elements can be removed from a JSON array. The index of all following elements decreases by one. Also the size of the JSON array decreases by one.

dcltrans
    transaction TMain
    var
        jsonArray : number;
        jsonText  : string;
    begin
        jsonArray := JsonParse(“[ \“StringValue\”, 10, 20.13, true, null ]”);

        JsonToText(jsonArray, jsonText);
        Print(“Before: “ + jsonText);

        JsonArrayRemoveElement(jsonArray, 0);

        JsonToText(jsonArray, jsonText);
        Print(“After:  “ + jsonText);

        JsonFree(jsonArray);
    end TMain;

Output
Before: [“StringValue”,10,20.13,true,null]
After:  [10,20.13,true,null]

JsonArrayResize

This function changes the size of a JSON array. If he specified size is lower than the actual size, the last elements of the JSON array are removed. If the specified size is higher than the actual size, empty elements are added to the end of the JSON array.

transaction TMain
var
  jsonText  : string;
  jsonArray : number;
begin
  jsonArray := JsonParse("[0,1,2,3,4]");

  JsonArrayResize(jsonArray, 2);

  JsonToText(jsonArray, jsonText);
  Print("resized array: " + jsonText);

  JsonFree(jsonArray);
end TMain;

Output
resized array: [0,1]
Parent topic: JSON First Steps


Getting and Setting the Size of a JSON Array

The size of a JSON array is the number of elements. As JSON arrays are zero terminated, the size of a JSON array is always the last index + 1.

JsonGetArrayLength

The function JsonGetArrayLength returns the number of elements in a JSON array.

transaction TMain
var
  jsonArray   : number;
  arrayLength : number;
begin
  jsonArray := JsonParse("[0,1,2,3,4]");

  arrayLength := JsonGetArrayLength(jsonArray);

  Print("Length: " + string(arrayLength));
  JsonFree(jsonArray);
end TMain;

Output
Length: 5

JsonArrayResize

This function changes the size of a JSON array. If the specified size is lower than the actual size, the last elements of the JSON array are removed. If the specified size is higher than the actual size, empty elements are added to the end of the JSON array.

transaction TMain
var
  jsonText  : string;
  jsonArray : number;
begin
  jsonArray := JsonParse("[0,1,2,3,4]");

  JsonArrayResize(jsonArray, 2);

  JsonToText(jsonArray, jsonText);
  Print("resized array: " + jsonText);

  JsonFree(jsonArray);
end TMain;

Output
resized array: [0,1]
Parent topic: JSON First Steps


Deleting JSON Objects and JSON Arrays

JsonFree

JSON objects and JSON arrays consume memory until they are deleted manually. Therefore it is important to delete them when they are not needed any longer.

In case the handle of a deleted JSON object or a deleted JSON array is passed to a function, nothing happens. The function returns false.

Parent topic: JSON First Steps


JSON Encoding

All functions of the JSON API expect and return UTF-8 strings. Therefore, the functions JsonParse, JsonSetStringProperty, and JsonArraySetStringElement expect the values in UTF-8 representation. Accordingly, the functions JsonToText, JsonGetStringProperty, and JsonArrayGetStringElement deliver the values in UTF-8 encoding.

To convert ANSI strings to UTF-8 strings and vice versa, you can use the functions ToUTF8 and FromUTF8.

If there are no special characters (for example ©, ¥, £, ä, ö, ü) in the text, all JSON API functions convert the ANSI string to an UTF-8 string implicitly. Otherwise an explicit conversion is required.

It is recommended to convert ANSI strings to UTF-8 strings in any case.

Encoding rules for all JSON API functions:

Input | Output | FromUTF8 (Output)
ToUTF8("CYL") | CYL | CYL
ToUTF8("©¥£") | Â©Â¥Â£ | ©¥£
ToUTF8("&copy;&yen;&pound;") | &copy;&yen;&pound; | &copy;&yen;&pound;
CYL | CYL | CYL
©¥£ | ©¥£ | Error: string conversion failed
&copy;&yen;&pound; | &copy;&yen;&pound; | &copy;&yen;&pound;
Note: TrueLog Explorer only displays JSON data in ANSI encoding correctly. Therefore, a call to the function FromUTF8 is necessary.

JsonParse decodes UTF-8 characters automatically.

Additional encoding rules for JsonParse:

Input | Output | FromUTF8 (Output)
ToUTF8( " \u00A9\u00A5\u00A3") | Â©Â¥Â£ | ©¥£
\u00A9\u00A5\u00A3 | Â©Â¥Â£ | ©¥£

You do not need to convert texts without special characters.

transaction TMain
var
  jsonText, jsonResult : string;
  jsonArray            : number;
begin
  jsonText := "[
                 \"CYL\",
                 \"&copy;&yen;&pound;\"
              ]";

  jsonArray := JsonParse(jsonText);
  JsonToText(jsonArray, jsonResult);

  Print(“UTF8: “ + jsonResult);
  Print(“ANSI: “ + FromUTF8(jsonResult));
  JsonFree(jsonArray);
End Tmain;

Output:

UTF8: [“CYL”,“&copy;&yen;&pound;”]
ANSI: [“CYL”,“&copy;&yen;&pound;”]

If a text contains a special character and you try to convert it to ANSI, an error occurs.

transaction TMain
var
  jsonText, jsonResult : string;
  jsonArray            : number;
begin
  jsonText := "[
                 \"CYL\",
                 \"&copy;&yen;&pound;\"
                 \"©¥£\"
              ]";

  jsonArray := JsonParse(jsonText);
  JsonToText(jsonArray, jsonResult);

  Print(“UTF8: “ + jsonResult);
  Print(“ANSI: “ + FromUTF8(jsonResult));

  JsonFree(jsonArray);
End Tmain;

Output:

UTF8: [“CYL”,“&copy;&yen;&pound;”,“©¥£”]
Error: String conversion failed

When the input text is converted to UTF-8, everything works as expected:

transaction TMain
var
  jsonText, jsonResult : string;
  jsonArray            : number;
begin
  jsonText := "[
                 \"CYL\",
                 \"&copy;&yen;&pound;\",
                 \"©¥£\"
              ]";

  jsonArray := JsonParse(jsonText);
  JsonToText(jsonArray, jsonResult);

  Print(“UTF8: “ + jsonResult);
  Print(“ANSI: “ + FromUTF8(jsonResult));

  JsonFree(jsonArray);
End Tmain;

Output:

UTF8: [“CYL”,“&copy;&yen;&pound;”,“ Â©Â¥Â£”]
ANSI: [“CYL”,“&copy;&yen;&pound;”,“ ©¥£”]
Parent topic: JSON General Information


JSON Functions

This section lists all functions of the JSON API.

  • JsonArrayCreate Function
    Creates an empty JSON array.
  • JsonArrayGetArrayElement Function
    Gets the value of a specified JSON array element from a JSON array.
  • JsonArrayGetBooleanElement Function
    Gets the value of a specified boolean element from a JSON array.
  • JsonArrayGetFloatElement Function
    Gets the value of a specified float element from a JSON array.
  • JsonArrayGetNumberElement Function
    Gets the value of a specified number element from a JSON array.
  • JsonArrayGetObjectElement Function
    Gets the value of a specified JSON object element from a JSON array.
  • JsonArrayGetStringElement Function
    Gets the value of a specified string element from a JSON array.
  • JsonArrayRemoveElement Function
    Removes an element from a JSON array.
  • JsonArrayResize Function
    Changes the size of a JSON array.
  • JsonArraySetArrayElement Function
    Sets the value of a specified JSON array element from a JSON array.
  • JsonArraySetBooleanElement Function
    Sets the value of a specified boolean element from a JSON array.
  • JsonArraySetFloatElement Function
    Sets the value of a specified float element from a JSON array.
  • JsonArraySetNumberElement Function
    Sets the value of a specified number element from a JSON array.
  • JsonArraySetObjectElement Function
    Sets the value of a specified JSON object element from a JSON array.
  • JsonArraySetStringElement Function
    Sets the value of a specified string element from a JSON array.
  • JsonFree Function
    Deletes a JSON object or a JSON array from the memory.
  • JsonGetArrayLength Function
    Retrieves the number of elements in a JSON array.
  • JsonGetArrayProperty Function
    Retrieves the value of a specified JSON array property from a JSON object.
  • JsonGetBooleanProperty Function
    Retrieves the value of a specified boolean property from a JSON object.
  • JsonGetFloatProperty Function
    Retrieves the value of a specified float property from a JSON object.
  • JsonGetNumberProperty Function
    Retrieves the value of a specified number property from a JSON object.
  • JsonGetObjectProperty Function
    Retrieves the value of a specified JSON object property from a JSON object.
  • JsonGetStringProperty Function
    Retrieves the value of a specified string property from a JSON object.
  • JsonObjectCreate Function
    Creates an empty JSON object.
  • JsonParse Function
    Creates a new JSON object or a new JSON array from the given string.
  • JsonRemoveProperty Function
    Removes a property from a JSON object.
  • JsonSetArrayProperty Function
    Sets the value of a specified JSON array property from a JSON object.
  • JsonSetBooleanProperty Function
    Sets the value of a specified boolean property from a JSON object.
  • JsonSetFloatProperty Function
    Sets the value of a specified float property from a JSON object.
  • JsonSetNumberProperty Function
    Sets the value of a specified number property from a JSON object.
  • JsonSetObjectProperty Function
    Sets the value of a specified JSON object property from a JSON object.
  • JsonSetStringProperty Function
    Sets the value of a specified string property from a JSON object.
  • JsonToText Function
    Gets the string representation of a JSON object or a JSON array.
Parent topic: JSON Functions Reference


JsonArrayCreate Function

Action

Creates an empty JSON array.

It is highly recommended to delete any JSON array that is no longer needed from the memory. For every call of JsonArrayCreate should be a call of JsonFree.

Include file

Json.bdh

Syntax

JsonArrayCreate(): number;

Return value

Valid handle to a JSON array.

Example

transaction TMain
var
  jsonArray : number;
begin
  jsonArray := JsonArrayCreate();
  JsonArraySetStringElement(jsonArray, 0, "New String Value");

  ...

  JsonFree(jsonArray);
end TMain;
Parent topic: JSON Functions


JsonArrayGetArrayElement Function

Action

Retrieves the value of a specified element from a JSON array. If the array element does not exist in the JSON array or the array element does not contain a JSON array value nothing happens.

Include file

Json.bdh

Syntax

JsonArrayGetArrayElement( in  handle : number,
                          in  index  : number,
                          out value  : number ): boolean;
Parameter | Description
handle | Valid handle to a JSON array
index | The index position in the JSON array. Lower bound is zero (0).
value | Parameter that contains the value of the specified element. The value is a handle to a JSON array.

Return value

  • true if element successfully found
  • false otherwise

Example

transaction TMain
var
  jsonText, elementValue       : string;
  jsonArray, nestedArray, i, j : number;
begin
  WebParseDataBound(jsonText);
  WebPageUrl("http://mycompany.com/api/jsondata");
  jsonArray := JsonParse(jsonText);

  for i := 0 to (JsonGetArrayLength(jsonArray) - 1) do
    //get nested array
    JsonArrayGetArrayElement(jsonArray, i, nestedArray);
    Print("Array at index " + string(i));
    //iterate over nested array
    for j := 0 to (JsonGetArrayLength(nestedArray) - 1) do
      JsonArrayGetStringElement(nestedArray, j, elementValue);
      Print("index: " + string(j) + ", value: " + elementValue);
    end;
  end;

  JsonFree(jsonArray);
end TMain;
Parent topic: JSON Functions


JsonArrayGetBooleanElement Function

Action

Retrieves the value of a specified element from a JSON array. If the array element does not exist in the JSON array or the array element does not contain a boolean value nothing happens.

Include file

Json.bdh

Syntax

JsonArrayGetBooleanElement( in handle : number,
                            in index  : number,
                            out value : boolean ): boolean;
Parameter | Description
handle | Valid handle to a JSON array
index | The index position in the JSON array. Lower bound is zero (0).
value | Parameter that contains the value of the specified element

Return value

  • true if element successfully found
  • false otherwise

Example

transaction TMain
var
  jsonText     : string;
  jsonArray, i : number;
  elementValue : boolean;
begin
  WebParseDataBound(jsonText);
  WebPageUrl("http://mycompany.com/api/jsondata");
  jsonArray := JsonParse(jsonText);

  for i := 0 to (JsonGetArrayLength(jsonArray) - 1) do
    JsonArrayGetBooleanElement(jsonArray, i, elementValue);
    Print("index: " + string(i) + ", value: " + string(elementValue));
  end;

  JsonFree(jsonArray);
end TMain;
Parent topic: JSON Functions


JsonArrayGetFloatElement Function

Action

Retrieves the value of a specified element from a JSON array. If the array element does not exist in the JSON array or the arrayelement does not contain a float value nothing happens.

Include file

Json.bdh

Syntax

JsonArrayGetFloatElement( in handle : number,
                          in index  : number,
                          out value : float ): boolean;
Parameter | Description
handle | Valid handle to a JSON array
index | The index position in the JSON array. Lower bound is zero (0).
value | Parameter that contains the value of the specified element

Return value

  • true if element successfully found
  • false otherwise

Example

transaction TMain
var
  jsonText     : string;
  jsonArray, i : number;
  elementValue : float;
begin
  WebParseDataBound(jsonText);
  WebPageUrl("http://mycompany.com/api/jsondata");
  jsonArray := JsonParse(jsonText);

  for i := 0 to (JsonGetArrayLength(jsonArray) - 1) do
    JsonArrayGetFloatElement(jsonArray, i, elementValue);
    Print("index: " + string(i) + ", value: " + string(elementValue));
  end;

  JsonFree(jsonArray);
end TMain;
Parent topic: JSON Functions


JsonArrayGetNumberElement Function

Action

Retrieves the value of a specified element from a JSON array. If the array element does not exist in the JSON array or the array element does not contain a number value nothing happens.

Include file

Json.bdh

Syntax

JsonArrayGetNumberElement( in handle : number,
                           in index  : number,
                           out value : number ): boolean;
Parameter | Description
handle | Valid handle to a JSON array
index | The index position in the JSON array. Lower bound is zero (0).
value | Parameter that contains the value of the specified element

Return value

  • true if element successfully found
  • false otherwise

Example

transaction TMain
var
  jsonText                   : string;
  jsonArray, i, elementValue : number;
begin
  WebParseDataBound(jsonText);
  WebPageUrl("http://mycompany.com/api/jsondata");
  jsonArray := JsonParse(jsonText);

  for i := 0 to (JsonGetArrayLength(jsonArray) - 1) do
    JsonArrayGetNumberElement(jsonArray, i, elementValue);
    Print("index: " + string(i) + ", value: " + string(elementValue));
  end;

  JsonFree(jsonArray);
end TMain;
Parent topic: JSON Functions


JsonArrayGetObjectElement Function

Action

Retrieves the value of a specified element from a JSON array. If the array element does not exist in the JSON array or the array element does not contain a JSON object value nothing happens.

Include file

Json.bdh

Syntax

JsonArrayGetObjectElement( in handle : number,
                           in index  : number,
                           out value : number ): boolean;
Parameter | Description
handle | Valid handle to a JSON array
index | The index position in the JSON array. Lower bound is zero (0).
value | Parameter that contains the value of the specified element. The value is a handle to a JSON object

Return value

  • true if element successfully found
  • false otherwise

Example

transaction TMain
var
  jsonText                             : string;
  jsonArray, i, elementValue, objectId : number;
begin
  WebParseDataBound(jsonText);
  WebPageUrl("http://mycompany.com/api/jsondata");
  jsonArray := JsonParse(jsonText);

  for i := 0 to (JsonGetArrayLength(jsonArray) - 1) do
    JsonArrayGetObjectElement(jsonArray, i, elementValue);
    JsonGetNumberProperty(elementValue, "Id", objectId);
    Print("Object at index " + string(i) + " has the id " + string(objectId));
  end;

  JsonFree(jsonArray);
end TMain;
Parent topic: JSON Functions


JsonArrayGetStringElement Function

Action

Retrieves the value of a specified element from a JSON array. If the array element does not exist in the JSON array or the array element does not contain a string value nothing happens.

Include file

Json.bdh

Syntax

JsonArrayGetStringElement( in handle : number,
                           in index  : number,
                           out value : string ): boolean;
Parameter | Description
handle | Valid handle to a JSON array
index | The index position in the JSON array. Lower bound is zero (0).
value | Parameter that contains the value of the specified element

Return value

  • true if element successfully found
  • false otherwise

Example

transaction TMain
var
  jsonText, elementValue : string;
  jsonArray, i           : number;
begin
  WebParseDataBound(jsonText);
  WebPageUrl("http://mycompany.com/api/jsondata");
  jsonArray := JsonParse(jsonText);

  for i := 0 to (JsonGetArrayLength(jsonArray) - 1) do
    JsonArrayGetStringElement(jsonArray, i, elementValue);
    Print("index: " + string(i) + ", value: " + elementValue);
  end;

  JsonFree(jsonArray);
end TMain;
Parent topic: JSON Functions


JsonArrayRemoveElement Function

Action

Removes an element with the specified index from a JSON array. The index of all following elements decreases by one. Also the size of the array decreases by one.

Include file

Json.bdh

Syntax

JsonArrayRemoveElement( in handle : number,
                        in index  : number ): boolean;
Parameter | Description
handle | Valid handle to a JSON array
index | The index position in the JSON array. Lower bound is zero (0).

Return value

  • true if element successfully removed
  • false otherwise

Example

transaction TMain
var
  jsonArray, i, current : number;
begin
  jsonArray := JsonParse("[0,1,2,3,4,5,6,7]");

  //remove all even numbers of array
  i := 0;
  while i < JsonGetArrayLength(jsonArray) do
    JsonArrayGetNumberElement(jsonArray, i, current);
    if ((curr mod 2) = 0) then
      JsonArrayRemoveElement(jsonArray, i);
    else
      i := i + 1;
    end;
  end;

  JsonFree(jsonArray);
end TMain;
Parent topic: JSON Functions


JsonArrayResize Function

Action

Resizes a JSON array. If the specified size is lower than the actual size, the last elements of the JSON array are removed. If the specified size is higher than the actual size, empty elements are added to the end of the JSON array.

Include file

Json.bdh

Syntax

JsonArrayResize( in handle : number,
                 in size   : number ): boolean;
Parameter | Description
handle | Valid handle to a JSON array
size | The new size of the JSON array

Return value

  • true if the size of the JSON array changed
  • false otherwise

Example

transaction TMain
var
  jsonText  : string;
  jsonArray : number;
begin
  jsonArray := JsonParse("[0,1,2,3,4]");

  JsonArrayResize(jsonArray, 2);
  JsonToText(jsonArray, jsonText);
  Print("resized array: " + jsonText);

  JsonArrayResize(jsonArray, 4);
  JsonToText(jsonArray, jsonText);
  Print("resized array: " + jsonText);

  JsonFree(jsonArray);
end TMain;

Output

resized array: [0,1]
resized array: [0,1,null,null]
Parent topic: JSON Functions


JsonArraySetArrayElement Function

Action

Replaces the value of a specified element from a JSON array. If the array element does not exist in the JSON array, a new element with the specified value will be appended to the array. If the array element does not contain a JSON array value, nothing happens.

Include file

Json.bdh

Syntax

JsonArraySetArrayElement( in handle : number,
                          in index  : number,
                          in value  : number ): boolean;
Parameter | Description
handle | Valid handle to a JSON array
index | The index position in the JSON array. Lower bound is zero (0).
value | A handle to the JSON array, which should be the new value of the element

Return value

  • true if value successfully written to element
  • false otherwise

Example

transaction TMain
var
  jsonText            : string;
  jsonArray, newValue : number;
begin
  WebParseDataBound(jsonText);
  WebPageUrl("http://mycompany.com/api/jsondata");
  jsonArray := JsonParse(jsonText);

  newValue := JsonParse("[0,1,2,3,4]");
  JsonArraySetArrayElement(jsonArray, 1, newValue);

  /* add new value
   * index of the new value := size
   * size := size + 1 */
  JsonArraySetArrayElement(jsonArray, 999999, newValue);

  JsonFree(newValue);
  JsonFree(jsonArray);
end TMain;
Parent topic: JSON Functions


JsonArraySetBooleanElement Function

Action

Replaces the value of a specified element from a JSON array. If the array element does not exist in the JSON array, a new element with the specified value will be appended to the array. If the array element does not contain a boolean value, nothing happens.

Include file

Json.bdh

Syntax

JsonArraySetBooleanElement( in handle : number,
                            in index  : number,
                            in value  : boolean ): boolean;
Parameter | Description
handle | Valid handle to a JSON array
index | The index position in the JSON array. Lower bound is zero (0).
value | The new value of the element

Return value

  • true if value successfully written to element
  • false otherwise

Example

transaction TMain
var
  jsonText               : string;
  jsonArray, i           : number;
  newValue, currentValue : boolean;
begin
  WebParseDataBound(jsonText);
  WebPageUrl("http://mycompany.com/api/jsondata");
  jsonArray := JsonParse(jsonText);

  //set every JSON array element to true
  newValue := true;
  for i := 0 to (JsonGetArrayLength(jsonArray) - 1) do
    JsonArrayGetBooleanElement(jsonArray, i, currentValue);
    if not currentValue then
      JsonArraySetBooleanElement(jsonArray, i, newValue);
    end;
  end;

  /* add new value
   * index of the new value := size
   * size := size + 1 */
  JsonArraySetBooleanElement(jsonArray, 999999, newValue);

  JsonFree(jsonArray);
end TMain;
Parent topic: JSON Functions


JsonArraySetFloatElement Function

Action

Replaces the value of a specified element from a JSON array. If the array element does not exist in the JSON array, a new element with the specified value will be appended to the array. If the array element does not contain a float value, nothing happens.

Include file

Json.bdh

Syntax

JsonArraySetFloatElement( in handle : number,
                          in index  : number,
                          in value  : float ): boolean;
Parameter | Description
handle | Valid handle to a JSON array
index | The index position in the JSON array. Lower bound is zero (0).
value | The new value of the element

Return value

  • true if value successfully written to element
  • false otherwise

Example

transaction TMain
var
  jsonText               : string;
  jsonArray, i           : number;
  newValue, currentValue : float;
begin
  WebParseDataBound(jsonText);
  WebPageUrl("http://mycompany.com/api/jsondata");
  jsonArray := JsonParse(jsonText);

  //every JSON array element is greater than or equal 11.22
  newValue := 11.22;
  for i := 0 to (JsonGetArrayLength(jsonArray) - 1) do
    JsonArrayGetFloatElement(jsonArray, i, currentValue);
    if currentValue < newValue then
      JsonArraySetFloatElement(jsonArray, i, newValue);
    end;
  end;

  /* add new value
   * index of the new value := size
   * size := size + 1 */
  JsonArraySetFloatElement(jsonArray, 999999, newValue);

  JsonFree(jsonArray);
end TMain;
Parent topic: JSON Functions


JsonArraySetNumberElement Function

Action

Replaces the value of a specified element from a JSON array. If the array element does not exist in the JSON array, a new element with the specified value will be appended to the array. If the array element does not contain a number value, nothing happens.

Include file

Json.bdh

Syntax

JsonArraySetNumberElement( in handle : number,
                           in index  : number,
                           in value  : number ): boolean;
Parameter | Description
handle | Valid handle to a JSON array
index | The index position in the JSON array. Lower bound is zero (0).
value | The new value of the element

Return value

  • true if value successfully written to element
  • false otherwise
transaction TMain
var
  jsonText                             : string;
  jsonArray, i, newValue, currentValue : number;
begin
  WebParseDataBound(jsonText);
  WebPageUrl("http://mycompany.com/api/jsondata");
  jsonArray := JsonParse(jsonText);

  //every JSON array element is greater than or equal 10
  newValue := 10;
  for i := 0 to (JsonGetArrayLength(jsonArray) - 1) do
    JsonArrayGetNumberElement(jsonArray, i, currentValue);
    if currentValue < newValue then
      JsonArraySetNumberElement(jsonArray, i, newValue);
    end;
  end;

  /* add new value
   * index of the new value := size
   * size := size + 1 */
  JsonArraySetNumberElement(jsonArray, 999999, newValue);

  JsonFree(jsonArray);
end TMain;
Parent topic: JSON Functions


JsonArraySetObjectElement Function

Action

Replaces the value of a specified element from a JSON array. If the array element does not exist in the JSON array, a new element with the specified value will be appended to the array. If the array element does not contain a JSON object value, nothing happens.

Include file

Json.bdh

Syntax

JsonArraySetObjectElement( in handle : number,
                           in index  : number,
                           in value  : number ): boolean;
Parameter | Description
handle | Valid handle to a JSON array
index | The index position in the JSON array. Lower bound is zero (0).
value | A handle to the JSON object, which should be the new value of the element

Return value

  • true if value successfully written to element
  • false otherwise

Example

transaction TMain
var
  jsonText  : string;
  jsonArray : number;
  newValue  : number;
begin
  WebParseDataBound(jsonText);
  WebPageUrl("http://mycompany.com/api/jsondata");
  jsonArray := JsonParse(jsonText);

  newValue := JsonParse("{\"Name\": \"new Object\"}");
  JsonArraySetObjectElement(jsonArray, 1, newValue);

  /* add new value
   * index of the new value := size
   * size := size + 1 */
  JsonArraySetObjectElement(jsonArray, 999999, newValue);

  JsonFree(newValue);
  JsonFree(jsonArray);
end TMain;
Parent topic: JSON Functions


JsonArraySetStringElement Function

Action

Replaces the value of a specified element from a JSON array. If the array element does not exist in the JSON array, a new element with the specified value will be appended to the array. If the array element does not contain a string value, nothing happens.

Include file

Json.bdh

Syntax

JsonArraySetStringElement( in handle : number,
                           in index  : number,
                           in value  : string ): boolean;
Parameter | Description
handle | Valid handle to a JSON array
index | The index position in the JSON array. Lower bound is zero (0).
value | The new value of the element

Return value

  • true if value successfully written to element
  • false otherwise

Example

transaction TMain
var
  jsonText               : string;
  jsonArray, i           : number;
  newValue, currentValue : string;
begin
  WebParseDataBound(jsonText);
  WebPageUrl("http://mycompany.com/api/jsondata");
  jsonArray := JsonParse(jsonText);

  //every JSON array element which contains the string "old string value" is set to "new string value"
  newValue := "new string value";
  for i := 0 to (JsonGetArrayLength(jsonArray) - 1) do
    JsonArrayGetStringElement(jsonArray, i, currentValue);
    if currentValue = "old string value" then
      JsonArraySetStringElement(jsonArray, i, newValue);
    end;
  end;

  /* add new value
   * index of the new value := size
   * size := size + 1 */
  JsonArraySetStringElement(jsonArray, 999999, newValue);

  JsonFree(jsonArray);
end TMain;
Parent topic: JSON Functions


JsonFree Function

Action

Deletes a JSON object or a JSON array from the memory. The JSON object or the JSON array does not consume memory any more. After calling the function JsonFree the properties and elements cannot be accessed any more.

This function also deletes all nested JSON objects and JSON arrays.

It is highly recommended to delete every JSON object and JSON array from the memory when it is not needed any more. For every call of JsonParse, JsonObjectCreate and JsonArrayCreate should be a call of JsonFree.

Include file

Json.bdh

Syntax

JsonFree( in handle : number ): boolean;
Parameter | Description
handle | Valid handle to a JSON object or a JSON array

Return value

  • true if successfully deleted
  • false otherwise

Example

transaction TMain
var
  jsonText                 : string;
  jsonObject, nestedObject : number;
begin
  WebParseDataBound(jsonText);
  WebPageUrl("http://mycompany.com/api/jsondata");
  jsonObject := JsonParse(jsonText);
  JsonGetObjectProperty(jsonObject, "nested object property", nestedObject);

  //jsonObject and nestedObject are still in memory and consume space
  JsonFree(jsonObject);
  //jsonObject is not in the memory any more
  //nestedObject is also deleted

  //nothing happens and the four functions return false
  JsonSetStringProperty(jsonObject, "StringProperty", "new string value");
  JsonSetStringProperty(nestedObject, "StringProperty", "new string value");
  JsonFree(jsonObject);
  JsonFree(nestedObject);
end TMain;
Parent topic: JSON Functions


JsonGetArrayLength Function

Action

Retrieves the number of elements in a JSON array. Number of elements := last index + 1

Include file

Json.bdh

Syntax

JsonGetArrayLength( in handle : number ): number;
Parameter | Description
handle | Valid handle to a JSON array

Return value

The number of elements in the JSON array.

Example

transaction TMain
var
  jsonArray   : number;
  arrayLength : number;
begin
  jsonArray := JsonParse("[0,1,2,3,4]");
  arrayLength := JsonGetArrayLength(jsonArray);
  Print("Length: " + string(arrayLength));
  JsonFree(jsonArray);
end TMain;

Output

Length: 5
Parent topic: JSON Functions


JsonGetArrayProperty Function

Action

Retrieves the value of a specified property from a JSON object. If the property does not exist in the JSON object or the property does not contain a JSON array value, nothing happens.

Include file

Json.bdh

Syntax

JsonGetArrayProperty( in handle   : number,
                      in property : string,
                      out value   : number ): boolean;
Parameter | Description
handle | Valid handle to a JSON object
property | Name of the property in the JSON object (case sensitive)
value | Parameter that contains the value of the specified property. The value is a handle to a JSON array.

Return value

  • true if property successfully found
  • false otherwise

Example

transaction TMain
var
  jsonText      : string;
  jsonObject    : number;
  propertyValue : number;
begin
  WebParseDataBound(jsonText);
  WebPageUrl("http://mycompany.com/api/jsondata");
  jsonObject := JsonParse(jsonText);

  JsonGetArrayProperty(jsonObject, "JsonArrayPropertyName", propertyValue);

  Print("JSON array property: " + propertyValue);
  JsonFree(jsonObject);
end TMain;
Parent topic: JSON Functions


JsonGetBooleanProperty Function

Action

Retrieves the value of a specified property from a JSON object. If the property does not exist in the JSON object or the property does not contain a boolean value, nothing happens.

Include file

Json.bdh

Syntax

JsonGetBooleanProperty( in handle   : number,
                        in property : string,
                        out value   : boolean ): boolean;
Parameter | Description
handle | Valid handle to a JSON object
property | Name of the property in the JSON object (case sensitive)
value | Parameter that contains the value of the specified property

Return value

  • true if property successfully found
  • false otherwise

Example

transaction TMain
var
  jsonText      : string;
  jsonObject    : number;
  propertyValue : boolean;
begin
  WebParseDataBound(jsonText);
  WebPageUrl("http://mycompany.com/api/jsondata");
  jsonObject := JsonParse(jsonText);

  JsonGetBooleanProperty(jsonObject, "BooleanPropertyName", propertyValue);

  Print("boolean property: " + propertyValue);
  JsonFree(jsonObject);
end TMain;
Parent topic: JSON Functions


JsonGetFloatProperty Function

Action

Retrieves the value of a specified property from a JSON object. If the property does not exist in the JSON object or the property does not contain a float value, nothing happens.

Include file

Json.bdh

Syntax

JsonGetFloatProperty( in handle   : number,
                      in property : string,
                      out value   : float ): boolean;
Parameter | Description
handle | Valid handle to a JSON object
property | Name of the property in the JSON object (case sensitive)
value | Parameter that contains the value of the specified property

Return value

  • true if property successfully found
  • false otherwise

Example

transaction TMain
var
  jsonText      : string;
  jsonObject    : number;
  propertyValue : float;
begin
  WebParseDataBound(jsonText);
  WebPageUrl("http://mycompany.com/api/jsondata");
  jsonObject := JsonParse(jsonText);

  JsonGetFloatProperty(jsonObject, "FloatPropertyName", propertyValue);

  Print("float property: " + propertyValue);
  JsonFree(jsonObject);
end TMain;
Parent topic: JSON Functions


JsonGetNumberProperty Function

Action

Retrieves the value of a specified property from a JSON object. If the property does not exist in the JSON object or the property does not contain a number value, nothing happens.

Include file

Json.bdh

Syntax

JsonGetNumberProperty( in handle   : number,
                       in property : string,
                       out value   : number ): boolean;
Parameter | Description
handle | Valid handle to a JSON object
property | Name of the property in the JSON object (case sensitive)
value | Parameter that contains the value of the specified property

Return value

  • true if property successfully found
  • false otherwise

Example

transaction TMain
var
  jsonText      : string;
  jsonObject    : number;
  propertyValue : number;
begin
  WebParseDataBound(jsonText);
  WebPageUrl("http://mycompany.com/api/jsondata");
  jsonObject := JsonParse(jsonText);

  JsonGetNumberProperty(jsonObject, "NumberPropertyName", propertyValue);

  Print("number property: " + propertyValue);
  JsonFree(jsonObject);
end TMain;
Parent topic: JSON Functions


JsonGetObjectProperty Function

Action

Retrieves the value of a specified property from a JSON object. If the property does not exist in the JSON object or the property does not contain a JSON object value, nothing happens.

Include file

Json.bdh

Syntax

JsonGetObjectProperty( in handle   : number,
                       in property : string,
                       out value   : number ): boolean;
Parameter | Description
handle | Valid handle to a JSON object
property | Name of the property in the JSON object (case sensitive)
value | Parameter that contains the value of the specified property. The value is a handle to a JSON object.

Return value

  • true if property successfully found
  • false otherwise

Example

transaction TMain
var
  jsonText      : string;
  jsonObject    : number;
  propertyValue : number;
begin
  WebParseDataBound(jsonText);
  WebPageUrl("http://mycompany.com/api/jsondata");
  jsonObject := JsonParse(jsonText);

  JsonGetObjectProperty(jsonObject, "JsonObjectPropertyName", propertyValue);

  Print("JSON object property: " + propertyValue);
  JsonFree(jsonObject);
end TMain;
Parent topic: JSON Functions


JsonGetStringProperty Function

Action

Retrieves the value of a specified property from a JSON object. If the property does not exist in the JSON object or the property does not contain a string value, nothing happens.

Include file

Json.bdh

Syntax

JsonGetStringProperty( in handle   : number,
                       in property : string,
                       out value   : string ): boolean;
Parameter | Description
handle | Valid handle to a JSON object
property | Name of the property in the JSON object (case sensitive)
value | Parameter that contains the value of the specified property

Return value

  • true if property successfully found
  • false otherwise

Example

transaction TMain
var
  jsonText      : string;
  jsonObject    : number;
  propertyValue : string;
begin
  WebParseDataBound(jsonText);
  WebPageUrl("http://mycompany.com/api/jsondata");
  jsonObject := JsonParse(jsonText);

  JsonGetStringProperty(jsonObject, "StringPropertyName", propertyValue);

  Print("string property: " + propertyValue);
  JsonFree(jsonObject);
end TMain;
Parent topic: JSON Functions


JsonObjectCreate Function

Action

Creates an empty JSON object.

It is highly recommended to delete every JSON object from the memory when it is not needed any longer. For every call of JsonObjectCreate should be a call of JsonFree.

Include file

Json.bdh

Syntax

JsonObjectCreate(): number;

Return value

Valid handle to a JSON object.

Example

transaction TMain
var
  jsonObject : number;
begin
  jsonObject := JsonObjectCreate();
  JsonSetStringProperty(jsonObject, "NewProperty", "New String Value");

  ...

  JsonFree(jsonObject);
end TMain;
Parent topic: JSON Functions


JsonParse Function

Action

Creates a new JSON object or a new JSON array from the given string.

It is highly recommended to delete every parsed JSON object and every parsed JSON array from the memory when it is not needed any longer. For every call of JsonParse should be a call of JsonFree.

Include file

Json.bdh

Syntax

JsonParse( in jsonText : string ): number;
Parameter | Description
jsonText | The string representation of the new JSON object or the new JSON array

Return value

  • handle to a JSON object or a JSON array if successful
  • 0 otherwise

Example

transaction TMain
var
  jsonText   : string;
  jsonObject : number;
begin
  WebParseDataBound(jsonText);
  WebPageUrl("http://mycompany.com/api/jsondata");
  jsonObject := JsonParse(jsonText);

  ...

  JsonFree(jsonObject);
end TMain;
Parent topic: JSON Functions


JsonRemoveProperty Function

Action

Removes a property from a JSON object.

Include file

Json.bdh

Syntax

JsonRemoveProperty( in handle   : number,
                    in property : string ): boolean;
Parameter | Description
handle | Valid handle to a JSON object
property | Name of the property in the JSON object (case sensitive)

Return value

  • true if property successfully removed
  • false otherwise

Example

transaction TMain
var
  jsonText   : string;
  jsonObject : number;
begin
  WebParseDataBound(jsonText);
  WebPageUrl("http://mycompany.com/api/jsondata");
  jsonObject := JsonParse(jsonText);

  JsonRemoveProperty(jsonObject, "PropertyName");

  JsonFree(jsonObject);
end TMain;
Parent topic: JSON Functions


JsonSetArrayProperty Function

Action

Replaces the value of a specified property from a JSON object. If the property does not exist in the JSON object, a new property with the specified name and value will be created. If the the property does not contain a JSON array value, nothing happens.

Include file

Json.bdh

Syntax

JsonSetArrayProperty( in handle   : number,
                      in property : string,
                      in value    : number ): boolean;
Parameter | Description
handle | Valid handle to a JSON object
property | Name of the property in the JSON object (case sensitive)
value | A handle to the JSON array, which should be the new value of the property

Return value

  • true if value successfully written to property
  • false otherwise

Example

transaction TMain
var
  jsonText   : string;
  jsonObject : number;
  newValue   : number;
begin
  WebParseDataBound(jsonText);
  WebPageUrl("http://mycompany.com/api/jsondata");
  jsonObject := JsonParse(jsonText);

  newValue := JsonParse("[0,1,2,3,4]");
  JsonSetArrayProperty(jsonObject, "JsonArrayPropertyName", newValue);

    JsonFree(newValue);
  JsonFree(jsonObject);
end TMain;
Parent topic: JSON Functions


JsonSetBooleanProperty Function

Action

Replaces the value of a specified property from a JSON object. If the property does not exist in the JSON object, a new property with the specified name and value will be created. If the the property does not contain a boolean value, nothing happens.

Include file

Json.bdh

Syntax

JsonSetBooleanProperty( in handle   : number,
                        in property : string,
                        in value    : boolean ): boolean;
Parameter | Description
handle | Valid handle to a JSON object.
property | Name of the property in the JSON object (case sensitive)
value | The new value of the property

Return value

  • true if value successfully written to property
  • false otherwise

Example

transaction TMain
var
  jsonText   : string;
  jsonObject : number;
  newValue   : boolean;
begin
  WebParseDataBound(jsonText);
  WebPageUrl("http://mycompany.com/api/jsondata");
  jsonObject := JsonParse(jsonText);

  newValue := true;
  JsonSetBooleanProperty(jsonObject, "BooleanPropertyName", newValue);

  JsonFree(jsonObject);
end TMain;
Parent topic: JSON Functions


JsonSetFloatProperty Function

Action

Replaces the value of a specified property from a JSON object. If the property does not exist in the JSON object, a new property with the specified name and value will be created. If the property does not contain a float value, nothing happens.

Include file

Json.bdh

Syntax

JsonSetFloatProperty( in handle   : number,
                      in property : string,
                      in value    : float ): boolean;
Parameter | Description
handle | Valid handle to a JSON object
property | Name of the property in the JSON object (case sensitive)
value | The new value of the property

Return value

  • true if value successfully written to property
  • false otherwise

Example

transaction TMain
var
  jsonText   : string;
  jsonObject : number;
  newValue   : float;
begin
  WebParseDataBound(jsonText);
  WebPageUrl("http://mycompany.com/api/jsondata");
  jsonObject := JsonParse(jsonText);

  newValue := 11.22;
  JsonSetFloatProperty(jsonObject, "FloatPropertyName", newValue);

  JsonFree(jsonObject);
end TMain;
Parent topic: JSON Functions


JsonSetNumberProperty Function

Action

Replaces the value of a specified property from a JSON object. If the property does not exist in the JSON object, a new property with the specified name and value will be created. If the property does not contain a number value, nothing happens.

Include file

Json.bdh

Syntax

JsonSetNumberProperty( in handle   : number,
                       in property : string,
                       in value    : number ): boolean;
Parameter | Description
handle | Valid handle to a JSON object
property | Name of the property in the JSON object (case sensitive)
value | The new value of the property

Return value

  • true if value successfully written to property
  • false otherwise

Example

transaction TMain
var
  jsonText   : string;
  jsonObject : number;
  newValue   : number;
begin
  WebParseDataBound(jsonText);
  WebPageUrl("http://mycompany.com/api/jsondata");
  jsonObject := JsonParse(jsonText);

  newValue := 10;
  JsonSetNumberProperty(jsonObject, "NumberPropertyName", newValue);

  JsonFree(jsonObject);
end TMain;
Parent topic: JSON Functions


JsonSetObjectProperty Function

Action

Replaces the value of a specified property from a JSON object. If the property does not exist in the JSON object, a new property with the specified name and value will be created. If the property does not contain a JSON object value, nothing happens.

Include file

Json.bdh

Syntax

JsonSetObjectProperty( in handle   : number,
                       in property : string,
                       in value    : number ): boolean;
Parameter | Description
handle | Valid handle to a JSON object
property | Name of the property in the JSON object (case sensitive)
value | A handle to the JSON object, which should be the new value of the property

Return value

  • true if value successfully written to property
  • false otherwise

Example

transaction TMain
var
  jsonText   : string;
  jsonObject : number;
  newValue   : number;
begin
  WebParseDataBound(jsonText);
  WebPageUrl("http://mycompany.com/api/jsondata");
  jsonObject := JsonParse(jsonText);

  newValue := JsonParse("{\"Name\": \"new Object\"}");
  JsonSetObjectProperty(jsonObject, "JsonObjectPropertyName", newValue);

    JsonFree(newValue);
  JsonFree(jsonObject);
end TMain;
Parent topic: JSON Functions


JsonSetStringProperty Function

Action

Replaces the value of a specified property from a JSON object. If the property does not exist in the JSON object, a new property with the specified name and value will be created. If the property does not contain a string value, nothing happens.

Include file

Json.bdh

Syntax

JsonSetStringProperty( in handle   : number,
                       in property : string,
                       in value    : string ): boolean;
Parameter | Description
handle | Valid handle to a JSON object
property | Name of the property in the JSON object (case sensitive)
value | The new value of the property

Return value

  • true if value successfully written to property
  • false otherwise

Example

transaction TMain
var
  jsonText   : string;
  jsonObject : number;
  newValue   : string;
begin
  WebParseDataBound(jsonText);
  WebPageUrl("http://mycompany.com/api/jsondata");
  jsonObject := JsonParse(jsonText);

  newValue := "new string value";
  JsonSetStringProperty(jsonObject, "StringPropertyName", newValue);

  JsonFree(jsonObject);
end TMain;
Parent topic: JSON Functions


JsonToText Function

Action

Gets the string representation of a JSON object or a JSON array.

The properties of an object are sorted ascending by their name. The elements of an array are sorted ascending by their index. This string representation contains no whitespaces for formatting.

Include file

Json.bdh

Syntax

JsonToText( in handle : number,
            out text  : string ): boolean;
Parameter | Description
handle | Valid handle to a JSON object or a JSON array
text | The string representation of the given JSON object or the given JSON array

Return value

  • true if successful
  • false otherwise

Example

transaction TMain
var
  jsonText              : string;
  jsonArray, jsonObject : number;
begin
  jsonArray := JsonParse("[0,1,2,3,4]");
  JsonToText(jsonArray, jsonText);
  Print("JSON array: " + jsonText);
  JsonFree(jsonArray);

  jsonObject := JsonParse("{\"name\":\"new object\",\"id\":1}");
  JsonToText(jsonObject, jsonText);
  Print("JSON object: " + jsonText);
  JsonFree(jsonObject);
end TMain;

Output

JSON array: [0,1,2,3,4]
JSON object: {"id":1,"name":"new object"}
Parent topic: JSON Functions


LDAP Functions Reference

The following function set is an implementation of the Lightweight Directory Access Protocol.

  • WebLdapAdd Function
    Creates a new LDAP directory entry.
  • WebLdapAttributeAdd Function
    Adds a new attribute to an LDAP directory entry.
  • WebLdapBind Function
    Exchanges authentication information between the client and the server.
  • WebLdapCompare Function
    Compares an attribute type and value with a given LDAP directory entry.
  • WebLdapConnect Function
    Establishes a connection for LDAP transactions with a specified host.
  • WebLdapControlAdd Function
    Adds a control to the next WebLdapAdd, WebLdapCompare, WebLdapDelete, WebLdapModify, WebLdapRename, WebLdapSearch or WebLdapExtendedOperation function call.
  • WebLdapControlGet Function
    Retrieves the control returned from the server after a WebLdapAdd, WebLdapCompare, WebLdapDelete, WebLdapModify, WebLdapRename, WebLdapSearch or WebLdapExtendedOperation function call.
  • WebLdapDelete Function
    Removes an entry from an LDAP directory.
  • WebLdapDisconnect Function
    Closes the connection for LDAP transactions that was established with WebLdapConnect.
  • WebLdapExtendedOperation Function
    Sends a request to the server to perform an extended operation synchronously.
  • WebLdapGetNativeHandle Function
    Returns the native LDAP handle that can be passed to external functions.
  • WebLdapModify Function
    Modifies a specified LDAP directory entry.
  • WebLdapNextAttribute Function
    Steps through all attributes of the entry returned by a previous call to WebLdapNextEntry.
  • WebLdapNextEntry Function
    Steps through all results received from WebLdapSearch.
  • WebLdapNextValue Function
    Steps through all attributes of an entry returned by a previous call to WebLdapNextEntry.
  • WebLdapRename Function
    Renames an existing LDAP directory entry.
  • WebLdapSearch Function
    Requests that a search is performed on its behalf by a server.
  • WebLdapValueAdd Function
    Adds, replaces or deletes an attribute value of an LDAP directory entry.
Parent topic: Internet Functions


WebLdapAdd Function

Action

Creates a new LDAP directory entry. Both the WebLdapAttributeAdd and the WebLdapValueAdd function are required to specify the new directory attributes and values.

Include file

WebAPI.bdh

Syntax

WebLdapAdd( in hLdap  : number,
            in sEntry : string ): boolean;

Return value

  • true if successful

  • false otherwise

Parameter | Description
hLdap | Handle to a Web connection that was created by WebLdapConnect
sEntry | Name of the new directory entry

Example

dcltrans
  transaction TMain
  var
    hLdap: number;
  begin
    WebLdapConnect(hLdap, "standardhost", WEB_PORT_LDAP);
    WebLdapBind(hLdap, "cn=adminname", "password");

    WebLdapAttributeAdd(hLdap, WEB_LDAP_MOD_ADD, "cn");
    WebLdapValueAdd(hLdap, "firstname lastname");
    WebLdapAttributeAdd(hLdap, WEB_LDAP_MOD_ADD, "sn");
    WebLdapValueAdd(hLdap, "lastname");
    WebLdapAdd(hLdap, "cn=myCN,o=Name");

    WebLdapDisconnect(hLdap);
  end TMain;

SilkEssential sample

LDAP.sep

Parent topic: LDAP Functions Reference
Related reference
WebLdapConnect Function
WebLdapAttributeAdd Function
WebLdapNextAttribute Function
WebLdapNextEntry Function
WebLdapNextValue Function
WebLdapRename Function
WebLdapSearch Function
WebLdapValueAdd Function
WebLdapModify Function
WebLdapDelete Function


WebLdapAttributeAdd Function

Action

Adds a new attribute to an LDAP directory entry.

Include file

WebAPI.bdh

Syntax

WebLdapAttributeAdd( in hLdap      : number,
                     in nModType   : number,
                     in sAttribute : string ) : boolean;

Return value

  • true if successful

  • false otherwise

Parameter | Description
hLdap | Handle to a Web connection that was created by WebLdapConnect
nModType

Specifies the type of modification. It can be one of the following:

  • WEB_LDAP_MOD_ADD. Add a directory entry

  • WEB_LDAP_MOD_DELETE. Delete a directory entry

  • WEB_LDAP_MOD_REPLACE. Replace a directory entry
sAttribute | Specifies the attribute type in the given entry to which the modification applies. It is simply a string indicating the attribute type name, for example, "mail", "cn", ...

Example

dcltrans
  transaction TMain
  var
    hLdap: number;
  begin
    WebLdapConnect(hLdap, "standardhost", WEB_PORT_LDAP);
    WebLdapBind(hLdap, "cn=adminname", "password");
    WebLdapAttributeAdd(hLdap, WEB_LDAP_MOD_REPLACE, "attribute");
    WebLdapValueAdd(hLdap, "value");
    WebLdapModify(hLdap, "cn=TestCN,o=Name");
    WebLdapDisconnect(hLdap);
  end TMain;

SilkEssential sample

LDAP.sep

Parent topic: LDAP Functions Reference
Related reference
WebLdapConnect Function
WebLdapNextAttribute Function
WebLdapNextEntry Function
WebLdapNextValue Function
WebLdapRename Function
WebLdapSearch Function
WebLdapValueAdd Function


WebLdapBind Function

Action

Exchanges authentication information between the client and the server.

Include file

WebAPI.bdh

Syntax

WebLdapBind( in hLDAP : number,
             in sDN   : string optional,
             in sCred : string optional ): boolean;

Return value

  • true if the bind attempt was completed successfully

  • false otherwise

Parameter | Description
hLDAP | Handle to a Web connection that was created by WebLdapConnect.
sDN | An unambiguous name of the directory object that the client wishes to bind as (optional). This field may take a NULL value for the purposes of anonymous binds.
sCred | Authentication information used to authenticate the name, if any, provided in the bind request (optional). This value may be NULL.

Example

const
  LDAP_SIZELIMIT := 100;
  LDAP_TIMELIMIT := 10000;

dclrand
  rsName: RndFile("Gfname.rnd", 20);

dclfunc
  function FWebLdapPrintSearchResults(hLdap: number)
  var
    sName    : string(500);
    nEntries : number;
  begin
    nEntries := 0;

    while WebLdapNextEntry(hLdap, sName, STRING_COMPLETE, false) do
      nEntries := nEntries + 1;
      write("entry: "); write(sName); writeln;

      while WebLdapNextAttribute(hLdap, sName) do
        write(" attrib: "); write(sName); writeln;

        while WebLdapNextValue(hLdap, sName) do
          write(" value: "); write(sName); writeln;
        end;
      end;
    end;

    if (nEntries = 0) then
      write("No entries found");
      writeln;
    end;

    writeln;
  end FWebLdapPrintSearchResults;

dcltrans
  transaction TWebLdap
  var
    sQuery : string(1000);
    hLdap  : number;
    rsName : string;
  begin
    WebLdapConnect(hLdap, "standardhost", WEB_PORT_LDAP);
    WebLdapBind(hLdap, NULL, NULL);

    rsName := "adminname";
    sQuery := "cn=" + rsName;
    if (not WebLdapSearch(hLdap, "", NULL, sQuery, LDAP_SIZELIMIT, LDAP_TIMELIMIT)) then
      write("LDAP Search failed"); writeln;
    else
      FWebLdapPrintSearchResults(hLdap);
    end;

    WebLdapDisconnect(hLdap);
  end TWebLdap;

SilkEssential sample

LDAP.sep

Parent topic: LDAP Functions Reference
Related reference
WebLdapConnect Function
WebLdapAttributeAdd Function
WebLdapNextAttribute Function
WebLdapNextEntry Function
WebLdapNextValue Function
WebLdapRename Function
WebLdapSearch Function
WebLdapValueAdd Function


WebLdapCompare Function

Action

Compares an attribute type and value with a given LDAP directory entry.

Include file

WebAPI.bdh

Syntax

WebLdapCompare( in hLdap      : number,
                in sEntry     : string,
                in sAttribute : string,
                in sValue     : string,
                in nLength    : number optional ): boolean;

Return value

  • true if the attribute type and value are equal to the specified LDAP directory entry

  • false otherwise

Parameter | Description
hLdap | Handle to a connection that was created by WebLdapConnect.
sEntry | Name of the directory entry that will be compared with the attribute type and value
sAttribute | Attribute type that will be compared with the specified LDAP directory entry
sValue | Value type that will be compared with the specified LDAP directory entry
nLength | Length of the value type that will be compared with the specified LDAP directory entry (optional). This parameter has to be passed to the function only if the value contains binary data

Example

dcltrans
  transaction TWebLdapCompare
  var
    hLdap : number;
    equal : boolean;
  begin
    WebLdapConnect(hLdap, "standardhost", WEB_PORT_LDAP);
    equal := WebLdapCompare(hLdap, "uid=user,o=company",
                           "attribute", "value1");
    equal := WebLdapCompare(hLdap, "uid=user,o=company",
                           "attribute", "value2");
    equal := WebLdapCompare(hLdap, "uid=user,o=company",
                           "attribute", "value3");
    WebLdapDisconnect(hLdap);
  end TWebLdapCompare;

SilkEssential sample

LDAP.sep

Parent topic: LDAP Functions Reference
Related reference
WebLdapConnect Function
WebLdapAttributeAdd Function
WebLdapNextAttribute Function
WebLdapNextEntry Function
WebLdapNextValue Function
WebLdapRename Function
WebLdapSearch Function
WebLdapValueAdd Function


WebLdapConnect Function

Action

Establishes a connection for LDAP transactions with a specified host.

Include file

WebAPI.bdh

Syntax

WebLdapConnect( inout hLDAP : number,
                in    sHost : string,
                in    nPort : number,
                in    nFlag : number optional ): boolean;

Return value

  • true if the connection attempt was completed successfully

  • false otherwise

Parameter | Description
hLDAP

Variable receiving a handle to the Web connection

If this parameter contains a handle to a Web connection prior to the WebLdapConnect function call, the memory allocated with the handle is released. Whenever you want to create a new Web connection, make sure this variable is initialized with 0 (this is automatically done within transactions when they are executed for the first time, but not within functions)
sHost | Domain name or IP address of the LDAP server, for example, hostname.com or 192.231.34.1
nPort | Port to connect to, usually WEB_PORT_LDAP (389)
nFlag

Flag specifiying the LDAP version (optional):

  • WEB_LDAP_FLAG_VERSION1

  • WEB_LDAP_FLAG_VERSION2

  • WEB_LDAP_FLAG_VERSION3

Besides, this flag specifies additional configuration of secure queries. Possible values are:

  • WEB_LDAP_FLAG_SSL

This value has to be set to 0 for insecure transactions (default).

Example

dcltrans
  transaction TWebLdap
  var
     hLdap: number;
  begin
    WebLdapConnect(hLdap, "standardhost", WEB_PORT_LDAP);
     WebLdapDisconnect(hLdap);
  end TWebLdap;

SilkEssential sample

LDAP.sep

Parent topic: LDAP Functions Reference
Related reference
WebLdapDisconnect Function


WebLdapControlAdd Function

Action

Adds a control to the next WebLdapAdd, WebLdapCompare, WebLdapDelete, WebLdapModify, WebLdapRename, WebLdapSearch or WebLdapExtendedOperation function call. To assign multiple controls, this function must be called repeatedly.

Include file

WebAPI.bdh

Syntax

WebLdapControlAdd( in hLdap       : number,
                   in sOid        : string,
                   in sData       : string allownull,
                   in nLength     : number,
                   in bIsCritical : boolean,
                   in nFlag       : number ): boolean;

Return value

  • true if successful

  • false otherwise

Parameter | Description
hLdap | Handle to a Web connection that was created with WebLdapConnect.
sOid | The object identifier of the control.
sData

The data associated with the control

  • If you want to specify a zero-length value, set nLength to 0 and sData to a zero-length string.

  • To indicate that no data is associated with the control, set sData to NULL.
nLength | The length of sData.
bIsCritical | Specifies whether the control is critical to the operation.
nFlag

Specifies the kind of control. This parameter is one of the following:

  • WEB_LDAP_SERVER_CONTROL

  • WEB_LDAP_CLIENT_CONTROL

Example

const
  LDAP_SIZELIMIT := 100;
  LDAP_TIMELIMIT := 10000;
transaction TWebLdap
  var
  hLdap, nDataLen, nLenOid : number;
  sOid, sData              : string;
  bIsCritic                : boolean;
 const
    // this is a representation of a server-side sorting control
    // which specifies that results shall be sorted by cn in
    // ascending order
    cControlData:="\h300630040402636E";
  begin
    WebLdapConnect(hLdap, "standardhost", WEB_PORT_LDAP,
                 WEB_LDAP_FLAG_VERSION3);
    WebLdapBind(hLdap, "cn=adminname", "password");
    WebLdapControlAdd(hLdap,"1.2.840.113556.1.4.473", cControlData,
                      sizeof(cControlData), true, WEB_LDAP_SERVER_CONTROL);
    if (not WebLdapSearch(hLdap, "o=MyCompany", NULL, "cn=*",
      LDAP_SIZELIMIT, LDAP_TIMELIMIT, 0)) then
      write("LDAP Search failed"); writeln;
    else
      TWebLdapPrintSearchResults(hLdap);
      write("Search ok"); writeln;
    end;

    nDataLen := 100; //returned sData size is max 100
    nLenOid := sizeof(sOid);

    WebLdapControlGet(hLdap, sOid, nLenOid, sData, nDataLen, bIsCritic);

    write("result control - ");
    write("oid:"); write(sOid);
    write(", data:"); write(sData);
    writeln;   WebLdapDisconnect(hLdap);
  end TWebLdap;
Parent topic: LDAP Functions Reference
Related reference
WebLdapConnect Function
WebLdapAttributeAdd Function
WebLdapNextAttribute Function
WebLdapNextEntry Function
WebLdapNextValue Function
WebLdapRename Function
WebLdapSearch Function
WebLdapValueAdd Function


WebLdapControlGet Function

Action

Retrieves the control returned from the server after a WebLdapAdd, WebLdapCompare, WebLdapDelete, WebLdapModify, WebLdapRename, WebLdapSearch or WebLdapExtendedOperation function call. If the server has returned multiple controls, this function must be called repeatedly.

Include file

WebAPI.bdh

Syntax

WebLdapControlGet( in    hLdap       : number,
                   out   sOid        : string,
                   in    nOidLen     : number,
                   out   sData       : string,
                   inout nLength     : number,
                   out   bIsCritical : boolean): boolean;

Return value

  • true if successful

  • false otherwise

Parameter | Description
hLdap | Handle to a Web connection that was created with WebLdapConnect.
sOid | The object identifier of the control.
nOidLen | Specifies the maximal length of sOid.
sData | The data associated with the control.
nLength | Specifies the maximal length of sData. After the function call, this parameter contains the actual length.
bIsCritical | Specifies whether the control is critical to the operation.

Example

const
  LDAP_SIZELIMIT := 100;
  LDAP_TIMELIMIT := 10000;

transaction TWebLdap
  var
    hLdap, nDataLen : number;
    sOid, sData     : string;
    bIsCritic       : boolean;
  const
    // this is a representation of a server-side sorting control
    // which specifies that results shall be sorted by cn in
    // ascending order
    cControlData:="\h300630040402636E";
  begin
    WebLdapConnect(hLdap, "standardhost", WEB_PORT_LDAP,
                   WEB_LDAP_FLAG_VERSION3);
    WebLdapBind(hLdap, "cn=adminname", "password");
    WebLdapControlAdd(hLdap,"1.2.840.113556.1.4.473", cControlData,
                      sizeof(cControlData), true,
                      WEB_LDAP_SERVER_CONTROL);

     if (not WebLdapSearch(hLdap, "o=MyCompany", NULL, "cn=*",
      LDAP_SIZELIMIT, LDAP_TIMELIMIT, 0)) then
      write("LDAP Search failed"); writeln;
    else
      TWebLdapPrintSearchResults(hLdap);
        write("Search ok"); writeln;
    end;

    nDataLen := 100; //returned sData size is max 100
    nLenOid := sizeof(sOid);

    WebLdapControlGet(hLdap, sOid, nLenOid, sData, nDataLen, bIsCritic);
    write("result control - ");
    write("oid:"); write(sOid);
    write(", data:"); write(sData);
    writeln;

     WebLdapDisconnect(hLdap);
  end TWebLdap;
Parent topic: LDAP Functions Reference
Related reference
WebLdapConnect Function
WebLdapAttributeAdd Function
WebLdapNextAttribute Function
WebLdapNextEntry Function
WebLdapNextValue Function
WebLdapRename Function
WebLdapSearch Function
WebLdapValueAdd Function


WebLdapDelete Function

Action

Removes an entry from an LDAP directory.

Include file

WebAPI.bdh

Syntax

WebLdapDelete( in hLdap  : number,
               in sEntry : string ): boolean;

Return value

  • true if successful

  • false otherwise

Parameter | Description
hLdap | Handle to a Web connection that was created by WebLdapConnect
sEntry | Name of the directory entry

Example

dcltrans
  transaction TMain
  var
    hLdap: number;
  begin
    WebLdapConnect(hLdap, "standardhost", WEB_PORT_LDAP);
    WebLdapBind(hLdap, "cn=adminname", "password");
    WebLdapDelete(hLdap, "cn=newCN,o=Name");
    WebLdapDisconnect(hLdap);
  end TMain;

SilkEssential sample

LDAP.sep

Parent topic: LDAP Functions Reference
Related reference
WebLdapConnect Function
WebLdapAttributeAdd Function
WebLdapNextAttribute Function
WebLdapNextEntry Function
WebLdapNextValue Function
WebLdapRename Function
WebLdapSearch Function
WebLdapValueAdd Function
WebLdapAdd Function
WebLdapModify Function


WebLdapDisconnect Function

Action

Closes the connection for LDAP transactions that was established with WebLdapConnect.

Include file

WebAPI.bdh

Syntax

WebLdapDisconnect( inout hLDAP: number );

Return value

  • true if disconnection was completed successfully

  • false otherwise

Parameter | Description
hLDAP | Handle to a Web connection that was created by WebLdapConnect

Example

dcltrans
  transaction TWebLdap
  var
    hLdap: number;
  begin
    WebLdapConnect(hLdap, "standardhost", WEB_PORT_LDAP);
    WebLdapDisconnect(hLdap);
  end TWebLdap;

SilkEssential sample

LDAP.sep

Parent topic: LDAP Functions Reference
Related reference
WebLdapConnect Function


WebLdapExtendedOperation Function

Action

Sends a request to the server to perform an extended operation synchronously.

Include file

WebAPI.bdh

Syntax

WebLdapExtendedOperation( in  hLdap         : number,
                          in  sRequestOid   : string,
                          in  sRequestData  : string,
                          in  nReqDataLen   : number,
                          out sReturnedOid  : string,
                          out nRetOidLen    : number,
                          out sReturnedData : string,
                          out nRetDataLen   : number ): boolean;

Return value

  • true if successful

  • false otherwise

Parameter | Description
hLdap | Handle to a Web connection that was created with WebLdapConnect.
sRequestOid | The object identifier of the extended operation.
sRequestData | The data associated with the extended operation.
nReqDataLen | The length of sRequestData.
sReturnedOid | Variable receiving the OID the server returns after having performed the extended operation.
nRetOidLen | Variable receiving the length of sReturnedOid.
sReturnedData | Variable receiving the data the server returned after having performed the extended operation.
nRetDataLen | Variable receiving the length of sReturnedData.
Parent topic: LDAP Functions Reference
Related reference
WebLdapConnect Function
WebLdapAttributeAdd Function
WebLdapNextAttribute Function
WebLdapNextEntry Function
WebLdapNextValue Function
WebLdapRename Function
WebLdapSearch Function
WebLdapValueAdd Function


WebLdapGetNativeHandle Function

Action

Returns the native LDAP handle that can be passed to external functions.

Include file

WebAPI.bdh

Syntax

WebLdapGetNativeHandle(in hLdap: number): number;

Return value

the native handle

Parameter | Description
hLdap | Handle to a Web connection that was created with WebLdapConnect.

Example

transaction TWebLdap
  var
    hLdap, nHandle: number;
  begin
    WebLdapConnect(hLdap, "standardhost",WEB_PORT_LDAP, WEB_LDAP_FLAG_VERSION3);
    WebLdapBind(hLdap, "cn=adminname", "password");
    nHandle := WebLdapGetNativeHandle(hLdap);
    write("Native handle:"); writeln(nHandle); WebLdapDisconnect(hLdap);
  end TWebLdap;
Parent topic: LDAP Functions Reference
Related reference
WebLdapConnect Function
WebLdapAttributeAdd Function
WebLdapNextAttribute Function
WebLdapNextEntry Function
WebLdapNextValue Function
WebLdapRename Function
WebLdapSearch Function
WebLdapValueAdd Function


WebLdapModify Function

Action

Modifies a specified LDAP directory entry. To create a new LDAP directory entry, call the WebLdapAdd function. Both the WebLdapAttributeAdd and the WebLdapValueAdd function are required to specify the directory entry modifications.

Include file

WebAPI.bdh

Syntax

WebLdapModify( in hLdap  : number,
               in sEntry : string ): boolean;

Return value

  • true if successful

  • false otherwise

Parameter | Description
hLdap | Handle to a Web connection that was created by WebLdapConnect
sEntry | Specifies the name of the directory entry

Example

dcltrans
  transaction TMain
  var
    hLdap: number;
  begin
    WebLdapConnect(hLdap, "standardhost", WEB_PORT_LDAP);
    WebLdapBind(hLdap, "cn=adminname", "password");
    WebLdapAttributeAdd(hLdap, WEB_LDAP_MOD_REPLACE, "attribute");
    WebLdapValueAdd(hLdap, "value");
    WebLdapModify(hLdap, "cn=TestCN,o=Name");
     WebLdapDisconnect(hLdap);
  end TMain;

SilkEssential sample

LDAP.sep

Parent topic: LDAP Functions Reference
Related reference
WebLdapConnect Function
WebLdapAttributeAdd Function
WebLdapNextAttribute Function
WebLdapNextEntry Function
WebLdapNextValue Function
WebLdapRename Function
WebLdapSearch Function
WebLdapValueAdd Function
WebLdapAdd Function
WebLdapDelete Function


WebLdapNextAttribute Function

Action

Steps through all attributes of the entry returned by a previous call to WebLdapNextEntry.

Include file

WebAPI.bdh

Syntax

WebLdapNextAttribute( in  hLDAP   : number,
                      out sName   : string,
                      in  nMaxLen : number optional): boolean

Return value

  • true if there was at least one attribute left to receive from the entry

  • false otherwise

Parameter | Description
hLDAP | Handle to a Web connection that was created by WebLdapConnect.
sName | This variable will receive the name of the next attribute.
nMaxLen | Specifies the maximum length of the attribute name (optional).

Example

dclfunc
  function TWebLdapPrintSearchResults(hLdap: number)
  var
    sName : string(500);
    nEntries : number;
  begin
    nEntries := 0;
    while WebLdapNextEntry(hLdap, sName, STRING_COMPLETE, false) do
    nEntries := nEntries + 1;
      write("entry: "); write(sName); writeln;
      while WebLdapNextAttribute(hLdap, sName) do
        write(" attrib: "); write(sName); writeln;
        while WebLdapNextValue(hLdap, sName) do
          write(" value: "); write(sName); writeln;
        end;
      end;
    end;

    if (nEntries = 0) then
      write("No entries found");
      writeln;
    end;
    writeln;
  end TWebLdapPrintSearchResults;

SilkEssential sample

LDAP.sep

Parent topic: LDAP Functions Reference
Related reference
WebLdapConnect Function
WebLdapAttributeAdd Function
WebLdapNextEntry Function
WebLdapNextValue Function
WebLdapRename Function
WebLdapSearch Function
WebLdapValueAdd Function


WebLdapNextEntry Function

Action

Steps through all results received from WebLdapSearch.

Include file

WebAPI.bdh

Syntax

WebLdapNextEntry( in  hLDAP     : number,
                  out sName     : string,
                  in  nMaxLen   : number,
                  in  bFriendly : boolean ): boolean;

Return value

  • true if there was at least one entry left to receive

  • false otherwise

Parameter | Description
hLDAP | Handle to a Web connection that was created by WebLdapConnect
sName | This variable will receive the name of the next entry
nMaxLen | Specifies the maximum length of the entry name
bFriendly | If this variable is set to true, the results are printed in a human-readable form

Example

dclfunc
  function TWebLdapPrintSearchResults(hLdap: number)
  var
    sName    : string(500);
    nEntries : number;
  begin    nEntries := 0;
    while WebLdapNextEntry(hLdap, sName, STRING_COMPLETE, false) do
      nEntries := nEntries + 1;
      write("entry: "); write(sName); writeln;
      while WebLdapNextAttribute(hLdap, sName) do
        write(" attrib: "); write(sName); writeln;
        while WebLdapNextValue(hLdap, sName) do
          write(" value: "); write(sName); writeln;
        end;
      end;
    end;

    if (nEntries = 0) then
      write("No entries found");
      writeln;
    end;
    writeln;
  end TWebLdapPrintSearchResults;

SilkEssential sample

LDAP.sep

Parent topic: LDAP Functions Reference
Related reference
WebLdapConnect Function
WebLdapAttributeAdd Function
WebLdapNextAttribute Function
WebLdapNextValue Function
WebLdapRename Function
WebLdapSearch Function
WebLdapValueAdd Function


WebLdapNextValue Function

Action

Steps through all attributes of an entry returned by a previous call to WebLdapNextEntry.

Include file

WebAPI.bdh

Syntax

WebLdapNextValue( in  hLDAP   : number,
                  out sName   : string,
                  in  nMaxLen : number optional,
                  out nLen    : number optional,
                  out bBinary : boolean optional): boolean

Return value

  • true if there was at least one value left to receive from the attribute

  • false otherwise

Parameter | Description
hLDAP | Handle to a Web connection that was created by WebLdapConnect.
sName | This variable will receive the content of the next value.
nMaxLen | Specifies the maximum length of the value content (optional).
nLen | Variable receiving the actual size of the value content (optional).
bBinary | Variable receiving an indicator whether the sName variable contains binary data (optional).

Example

dclfunc
  function TWebLdapPrintSearchResults(hLdap: number)
  var
    sName : string(500);
    nEntries : number;
  begin
    nEntries := 0;

    while WebLdapNextEntry(hLdap, sName, STRING_COMPLETE, false) do
      nEntries := nEntries + 1;
      write("entry: "); write(sName); writeln;

      while WebLdapNextAttribute(hLdap, sName) do
        write(" attrib: "); write(sName); writeln;

        while WebLdapNextValue(hLdap, sName) do
          write(" value: "); write(sName); writeln;
        end;
      end;
    end;

    if(nEntries = 0) then
      write("No entries found");
      writeln;
    end;

    writeln;
  end TWebLdapPrintSearchResults;

SilkEssential sample

LDAP.sep

Parent topic: LDAP Functions Reference
Related reference
WebLdapConnect Function
WebLdapAttributeAdd Function
WebLdapNextAttribute Function
WebLdapNextEntry Function
WebLdapRename Function
WebLdapSearch Function
WebLdapValueAdd Function


WebLdapRename Function

Action

Renames an existing LDAP directory entry. This function allows only renaming leaf entries, not interior nodes of an LDAP directory.

Include file

WebAPI.bdh

Syntax

WebLdapRename( in hLdap      : number,
               in sOldName   : string,
               in sNewName   : string,
               in sNewParent : string allownull,
               in bDelete    : boolean ): boolean;

Return value

  • true if successful

  • false otherwise

Parameter | Description
hLdap | Handle to a Web connection that was created by WebLdapConnect
sOldName | Name of the directory entry to be renamed. This entry must be a leaf in the LDAP directory tree
sNewName | New relative distinguished name (RDN) to assign to the entry
sNewParent | Specifies the distinguished name of the new parent entry. Pass NULL to the function if you do not want to move the entry to a different location in the directory tree
bDelete | Specifies whether the attribute values in the old relative distinguished name should be removed from the entry or retained as non-distinguished values

Example

dcltrans
  transaction TMain
  var
    hLdap: number;
  begin
    WebLdapConnect(hLdap, "standardhost", WEB_PORT_LDAP);
    WebLdapBind(hLdap, "cn=adminname", "password");
    WebLdapRename(hLdap, "cn=oldCN,o=Name", "cn=newCN ", NULL, false);
    WebLdapDisconnect(hLdap);
  end TMain;

SilkEssential sample

LDAP.sep

Parent topic: LDAP Functions Reference
Related reference
WebLdapConnect Function
WebLdapAttributeAdd Function
WebLdapNextAttribute Function
WebLdapNextEntry Function
WebLdapNextValue Function
WebLdapSearch Function
WebLdapValueAdd Function


WebLdapSearch Function

Action

Requests that a search is performed on its behalf by a server. This can be used to read attributes from a single entry, from entries immediately below a particular entry, or a whole sub tree of entries.

Include file

WebAPI.bdh

Syntax

WebLdapSearch( in  hLDAP      : number,
               in  sBase      : string,
               in  sAttrib    : string allownull,
               in  sFilters   : string,
               in  nSizeLimit : number optional,
               in  nTimeLimit : number optional,
               in  nFlags     : number optional,
               out nEntries   : number optional): boolean;

Return value

  • true if the search request was completed successfully

  • false if an error occurred or no matching entries can be found

Parameter | Description
hLDAP | Handle to a Web connection that was created by WebLdapConnect
sBase | An unambiguous name that is the base object entry relative to which the search is to be performed
sAttrib | A list of the attributes to be returned from each entry that matches the search filter. There are two special values that may be used: an empty list with no attributes, and the attribute description string "*". Both of these signify that all user attributes are to be returned. (The "*" allows the client to request all user attributes in addition to specific operational attributes).
sFilters | A filter that defines the conditions that must be fulfilled in order for the search to match a given entry
nSizeLimit | A size limit that restricts the maximum number of entries to be returned as a result of the search (optional). A value of 0 in this field indicates that no client-requested size limit restrictions apply for the search.
nTimeLimit | A time limit that restricts the maximum time (in seconds) allowed for a search (optional). A value of 0 in this field indicates that no client-requested time limit restrictions apply for the search.
nFlags

You can combine various flags for the search query (optional).

An indicator as to whether search results will contain both attribute types and values or just attribute types. Setting this flag causes only attribute types (not values) to be returned; otherwise both attribute types and values are returned. (Not set by default.)

  • WEB_LDAP_FLAG_ATTRS_ONLY

An indicator as to how alias objects (as defined in X.501) are to be handled in searching. The possible values of this flag have the following semantics:

  • WEB_LDAP_FLAG_DEREF_NEVER. Do not dereference aliases in searching or in locating the base object of the search

  • WEB_LDAP_FLAG_DEREF_SEARCHING. Dereference aliases in subordinates of the base object in searching, but not in locating the base object of the search

  • WEB_LDAP_FLAG_DEREF_FINDING. Dereference aliases in locating the base object of the search, but not when searching subordinates of the base object

  • WEB_LDAP_FLAG_DEREF_ALWAYS. Dereference aliases both in searching and in locating the base object of the search. This is the default setting

An indicator of the scope to be used for performing the search. These are:

  • WEB_LDAP_FLAG_SCOPE_BASE

  • WEB_LDAP_FLAG_SCOPE_ONELEVEL

  • WEB_LDAP_FLAG_SCOPE_SUBTREE (default)
nEntries | Receives the number of entries returned by the search query (optional)

Example

const
  LDAP_SIZELIMIT := 100;
  LDAP_TIMELIMIT := 10000;
dclrand
  rsName: RndFile("Gfname.rnd", 20);

dclfunc
  function FWebLdapPrintSearchResults(hLdap: number)
  var
    sName    : string(500);
    nEntries : number;
  begin
    nEntries := 0;

    while WebLdapNextEntry(hLdap, sName, STRING_COMPLETE, false) do
      nEntries := nEntries + 1;
      write("entry: "); write(sName); writeln;

      while WebLdapNextAttribute(hLdap, sName)do
        write(" attrib: "); write(sName); writeln;

        while WebLdapNextValue(hLdap, sName) do
          write(" value: "); write(sName); writeln;
        end;
      end;
    end;

    if (nEntries = 0) then
      write("No entries found");
      writeln;
    end;

    writeln;
  end FWebLdapPrintSearchResults;

dcltrans
  transaction TWebLdap
  var
    sQuery : string(1000);
    hLdap  : number;
  begin
    WebLdapConnect(hLdap, "standardhost", WEB_PORT_LDAP);
    WebLdapBind(hLdap, NULL, NULL);
    sQuery := "cn=" + rsName;

    if (not WebLdapSearch(hLdap, "", NULL, sQuery, LDAP_SIZELIMIT, LDAP_TIMELIMIT)) then
      write("LDAP Search failed"); writeln;
    else
     FWebLdapPrintSearchResults(hLdap);
    end;

     WebLdapDisconnect(hLdap);
  end TWebLdap;

SilkEssential sample

LDAP.sep

Parent topic: LDAP Functions Reference
Related reference
WebLdapConnect Function
WebLdapAttributeAdd Function
WebLdapNextAttribute Function
WebLdapNextEntry Function
WebLdapNextValue Function
WebLdapRename Function
WebLdapValueAdd Function


WebLdapValueAdd Function

Action

Adds, replaces or deletes an attribute value of an LDAP directory entry.

Include file

WebAPI.bdh

Syntax

WebLdapValueAdd( in hLdap   : number,
                 in sValue  : string,
                 in nLength : number optional ) : boolean;

Return value

  • true if successful

  • false otherwise

Parameter | Description
hLdap | Handle to a Web connection that was created by WebLdapConnect
sValue | Specifies one of the attribute values to add, delete or replace. To assign multiple values to an attribute, this function must be called multiple times.
nLength | Length of the attribute value (optional). Passing this parameter to the function is necessary if the attribute value contains binary data.

Example

dcltrans
  transaction TMain
  var
    hLdap: number;
  begin
    WebLdapConnect(hLdap, "standardhost", WEB_PORT_LDAP);
    WebLdapBind(hLdap, "cn=adminname", "password");
    WebLdapAttributeAdd(hLdap, WEB_LDAP_MOD_REPLACE, "attribute");
    WebLdapValueAdd(hLdap, "value");
    WebLdapModify(hLdap, "cn=TestCN,o=Name");
    WebLdapDisconnect(hLdap);
  end TMain;

SilkEssential sample

LDAP.sep

Parent topic: LDAP Functions Reference
Related reference
WebLdapConnect Function
WebLdapAttributeAdd Function
WebLdapNextAttribute Function
WebLdapNextEntry Function
WebLdapNextValue Function
WebLdapRename Function
WebLdapSearch Function
WebLdapModify Function
WebLdapAdd Function


MAPI Functions Reference

MAPI (Messaging Application Programming Interface) is a message architecture and a client interface component. It enables applications to access multiple message systems with only one interface.

Mail Clients like MS Outlook implement this interface. Therefore it is possible to use MAPI for accessing Microsoft Exchange Mailboxes via MS Outlook’s MAPI interface.

Silk Performer introduces a new API for accessing MAPI mailboxes and for creating/deleting and modifying messages within those mailboxes.

Problems with MAPI

Security

Most Mail Clients in their latest versions introduce new security options. Microsoft Outlook or Eudora for example – prohibit MAPI Access to their application by default.

In order to use Silk Performer MAPI Support – those security settings need to be changed. This is normally done in the options menu of the respective client application.

Incomplete Implementation

Not all mail clients implement the full range of the MAPI interface. If a MAPI client that does not support a certain interface method is used, you will likely see replay error like “Function not supported”. This is therefore no problem of Silk Performer – it is just a limitation of the used client.

MAPI Support in Silk Performer

Silk Performer MAPI Support is only for replaying. There is no recording of MAPI activities so far.

The new API functions are:

Logon/Logoff:

  • MapiLogoff: Closes a MAPI Session that has been opened with MapiLogon.

  • MapiLogon: Creates a new MAPI Session. You need to specify the MAPI profile name and a password to logon to a new MAPI session.

Sending:

  • MapiSendMessage: Creates a new message in the active session and sends it right away.

  • MapiSendMessageEx: Sends a message that has been created with MapiCreateMessage.

Creating/Deleting/Saving:

  • MapiCreateMessage: Creates a new message and returns a handle for that new message.

  • MapiDeleteMessage: Deletes a message.

  • MapiSaveMessage: Saves changes to a message.

Accessing Message Properties:

  • MapiGetLastError: Calling this method returns the error number of the last MAPI call.

  • MapiGetMessageAttachment: Retrieves information about a message attachment.

  • MapiGetMessageProperty: Retrieves message property values from a valid MAPI Message.

  • MapiGetMessageRecipient: Retrieves information about a message recipient.

  • MapiGetMessage: Retrieves a message identified by the Message ID from an active MAPI Session.

  • MapiGetNextMsgId: Returns the next Message ID in the Inbox of the MAPI Session.

  • MapiSetMessageAttachment: Sets information about a message attachment.

  • MapiSetMessageProperty: Sets a message property value of a valid MAPI Message.

  • MapiSetMessageRecipient: Sets information about a message recipient.

Misc functions:

  • MapiInit: Initializes MAPI Support for the current virtual user.

  • MapiExit: Unloads MAPI support for the current virtual user.

  • MapiFreeMessage: Frees the memory occupied by the message handle of the virtual user.

  • MAPI Messages
  • MAPI Sample
    Illustrates a sample that uses the new MAPI API
  • Logon/Logoff Functions
  • Sending Functions
  • Creating/Deleting/Saving Functions
  • Accessing Message Properties
  • Misc Functions
Parent topic: Internet Functions


MAPI Messages

MAPI Messages can be accessed by their unique ID’s. MapiGetNextMsgId is the function that allows to you query for all message ID’s in your Inbox.

A full sample bdf file can be found in the samples directory of your installation.

Getting Message ID’s

To get the first message – simply call:

MapiGetNextMsgId(ghSession, “”, sNextMsgId)

To get the next message pass a message id as second parameter, e.g.:

MapiGetNextMsgId(ghSession, sLastMsgId, sNextMsgId).

The following loop will allow you to iterate through all messages:

sLastMsgId := “”;
while(MapiGetNextMsgId(ghSession, sLastMsgId, sNextMsgId)) do
  SLastMsgId := sNextMsgId;
end;

Access a message

To access message properties (text, sender, recipient, …) you have to call MapiGetMessage. MapiGetMessage returns a message handle on which you can call several different functions to get/set message properties. It is very important to FREE a message handle with MapiFreeMessage after the handle is no longer needed!

A message has the following properties:

  • MAPI_PROP_MSG_SUBJECT

  • MAPI_PROP_MSG_NOTETEXT

  • MAPI_PROP_MSG_MSGTYPE

  • MAPI_PROP_MSG_DATERECEIVED

  • MAPI_PROP_MSG_CONVERSATIONID

  • MAPI_PROP_MSG_SENDER_NAME

  • MAPI_PROP_MSG_SENDER_ADDRESS

  • MAPI_PROP_MSG_RECIPIENT_COUNT

  • MAPI_PROP_MSG_ATTACH_COUNT

Properties can be accessed with MapiGetMessageProperty and MapiSetMessageProperty. If you change a message property you have to save the message with MapiSaveMessage in order to commit the changes.

Access recipients

A message can have multiple recipients. The number of recipients can be accessed with the property MAPI_PROP_MSG_RECIPIENT_COUNT. The recipient itself can be access with MapiGetMessageRecipient and the respective recipient ID. The recipient ID is the index of the recipient where the first index is 0. So – a message with a recipient count value of 2 has recipients with index 0 and 1!

When you set recipients you first have to set the number of recipients in the MAPI_PROP_MSG_RECIPIENT_COUNT and then set each recipient individually with MapiSetMessageRecipient.

Access attachments

Attachments are similar to recipients. First you have to get the number of attachments by getting property MAPI_PROP_MSG_ATTACH_COUNT. Then you can use MapiGetMessageAttachment and the respective attachment ID.

In order to get attachments you have to ensure that you call MapiGetMessage with false for the parameter bSuppressAttachments.

When you set attachments you first have to set the number of attachments in the MAPI_PROP_MSG_ATTACH_COUNT and then set each attachment individually with MapiSetAttachment.

Parent topic: MAPI Functions Reference


MAPI Sample

The following sample uses the new MAPI API to:

  • Logon to a MAPI Session

  • Read all messages in the Inbox

  • Delete the first message in the Inbox

  • Change the subject of the first message in the Inbox

  • Sends a new Message

benchmark BenchmarkName

use "kernel.bdh"
use "mapi.bdh"

var
  ghSession : number init 0;
// Workload Section
dcluser
  user
    VirtUser
  transactions
    TInit           : begin;
    TGetMsgs        : 1;
    TSendMsg        : 1;
    TSendMsgEx      : 1;
    TDeleteMsg      : 1;
    TChangeMsg      : 1;
    TEnd            : end;

// Transactions Section
dcltrans
  transaction TInit
  begin
    MapiInit();
    ghSession := MapiLogon("Outlook", null);
    if(ghSession = 0) then halt; end;
  end TInit;

  transaction TGetMsgs
  var
    hMsg, nRecipCount, nAttachCount, i : number;
    sLastMsgId, sNextMsgId             : string;
    sValue                             : string;
  begin
    sLastMsgId := "";
    // Iterate through all Mails and retrieve mail properties
    while(MapiGetNextMsgId(ghSession, sLastMsgId, sNextMsgId)) do
      hMsg := MapiGetMessage(ghSession, true, false, false, false, sNextMsgId);

      MapiGetMessageProperty(hMsg, MAPI_PROP_MSG_MSGTYPE, sValue);
      writeln("MsgType: " + sValue);
      MapiGetMessageProperty(hMsg, MAPI_PROP_MSG_SUBJECT, sValue);
      writeln("Subject: " + sValue);
      MapiGetMessageProperty(hMsg, MAPI_PROP_MSG_DATERECEIVED, sValue);
      writeln("Date: " + sValue);
      MapiGetMessageProperty(hMsg, MAPI_PROP_MSG_SENDER_NAME, sValue);
      writeln("Send-Name: " + sValue);
      MapiGetMessageProperty(hMsg, MAPI_PROP_MSG_SENDER_ADDRESS, sValue);
      writeln("Sender-Address: " + sValue);

      // Iterate through all Recipients
      if(MapiGetMessageProperty(hMsg, MAPI_PROP_MSG_RECIPIENT_COUNT, sValue)) then
        nRecipCount := number(sValue);
        writeln("RecipientCount: " + sValue);

        for i:=0 to nRecipCount-1 do
          MapiGetMessageRecipient(hMsg, i, true, sValue);
          writeln("Recipient-Name: " + sValue);
          MapiGetMessageRecipient(hMsg, i, false, sValue);
          writeln("Recipient-Address: " + sValue);
        end;
      end;

       // Iterate through all Attachments
      if(MapiGetMessageProperty(hMsg, MAPI_PROP_MSG_ATTACH_COUNT, sValue)) then
        nAttachCount := number(sValue);
        writeln("AttachCount: " + sValue);

        for i:=0 to nAttachCount-1 do
          MapiGetMessageAttachment(hMsg, i, true, sValue);
          writeln("Attach-File: " + sValue);
          MapiGetMessageAttachment(hMsg, i, false, sValue);
          writeln("Attach-Path: " + sValue);
        end;
      end;

      writeln("---------------------------------------------------");

      // Free the message
      MapiFreeMessage(hMsg);
      sLastMsgId := sNextMsgId;
    end;
  end TGetMsgs;

  transaction TSendMsg
  begin
    // Send a new message
    MapiSendMessage(
      ghSession,
      "TestSubject",
      "Test Message Text" ,
      "",
      "SenderName",
      "sender@sendersdomain",
      "RecipientName",
      "recipient@recipientdomain");
  end TSendMsg;

  transaction TSendMsgEx
  var
    hMsg : number;
  begin
    // Create a new message
    hMsg := MapiCreateMessage(
      "TestSubject",
      "Test Message Text",
      "",
      "SenderName",
      "sender@sendersdomain",
      "RecipientName",
      "recipient@recipientdomain");
    if(hMsg = 0) then halt; end;

    // Add a 2nd Recipient
    MapiSetMessageProperty(hMsg, MAPI_PROP_MSG_RECIPIENT_COUNT, "2");
    MapiSetMessageRecipient(hMsg, 1, "2nd Recipient", "test@test.com",
MAPI_MSG_RECIPTYPE_CC);

    // Add an attachment
    MapiSetMessageProperty(hMsg, MAPI_PROP_MSG_ATTACH_COUNT, "1");
    MapiSetMessageAttachment(hMsg, 0, "test.txt", "c:\\temp\\test.txt");

    // Send the message
    MapiSendMessageEx(ghSession, hMsg);

    // Free the message
    MapiFreeMessage(hMsg);
  end TSendMsgEx;

  transaction TDeleteMsg
  var
    sMsgId : string;
    hMsg   : number;
  begin
    // delete the first message
    if MapiGetNextMsgId(ghSession, "", sMsgId) then
      MapiDeleteMessage(ghSession, sMsgId);
    end;
  end TDeleteMsg;

  transaction TChangeMsg
  var
    sMsgId, sSubject : string;
    hMsg   : number;
  begin
    // retrieve the first message and change the message subject
    if MapiGetNextMsgId(ghSession, "", sMsgId) then
      hMsg := MapiGetMessage(ghSession, true, false, true, true, sMsgId);
      if(hMsg <> 0) then
        // get the subject - add the value 'Modified' and set the new value
        MapiGetMessageProperty(hMsg, MAPI_PROP_MSG_SUBJECT, sSubject);
        sSubject := sSubject + " Modified";
        MapiSetMessageProperty(hMsg, MAPI_PROP_MSG_SUBJECT, sSubject);

        // Save the changes
        MapiSaveMessage(ghSession, hMsg, sMsgId);

        // Free Message
        MapiFreeMessage(hMsg);
      end;
    end;
  end TChangeMsg;

  transaction TEnd
  begin
    // Logoff
    MapiLogoff(ghSession);
    MapiExit();
  end TEnd;
Parent topic: MAPI Functions Reference


Logon/Logoff Functions

  • MapiLogoff Function
    Closes a MAPI Session that has been opened with MapiLogon.
  • MapiLogon Function
    Creates a new MAPI Session.
Parent topic: MAPI Functions Reference


MapiLogoff Function

Action

Closes a MAPI Session that has been opened with MapiLogon.

Include file

Mapi.bdh

Syntax

MapiLogoff( in hSession : number ) : boolean;
Parameter | Description
hSession | Valid MAPI Session Handle

Return value

  • true if successful
  • false otherwise

Example

See MAPI Sample

Parent topic: Logon/Logoff Functions
Related reference
MAPI Sample


MapiLogon Function

Action

Creates a new MAPI Session. You need to specify the MAPI profile name and a password to logon to a new MAPI session. The method returns a valid session handle that will be passed to other MAPI functions for sending/reading/deleting messages.

Inclue file

Mapi.bdh

Syntax

MapiLogon( in sProfileName : string,
           in sPassword    : string allownull ): number;
Parameter | Description
sProfileName | Name of your local MAPI profile, e.g.: Outlook, Exchange Server, …
sPassword | If you need a password to logon to your MAPI profile - provide the password. Otherwise pass NULL.

Return value

  • Session Handle if successful
  • 0 otherwise

Example

See MAPI Sample

Parent topic: Logon/Logoff Functions
Related reference
MAPI Sample


Sending Functions

  • MapiSendMessage Function
    Creates a new message in the active session and sends it right away.
  • MapiSendMessageEx Function
    Sends a message that has been created with MapiCreateMessage.
Parent topic: MAPI Functions Reference


MapiSendMessage Function

Action

Creates a new message in the active session and sends it right away.

Include file

Mapi.bdh

Syntax

MapiSendMessage( in hSession      : number,
                 in sSubject      : string,
                 in sMessageText  : string,
                 in sMessageType  : string,
                 in sSenderName   : string,
                 in sSenderAddress: string,
                 in sToName       : string,
                 in sToAddress    : string ) : boolean;
Parameter | Description
hSession | Valid MAPI Session Handle
sSubject | Subject for the Mail Message
sMessageText | Body Text for the Mail Message
sMessageType | For normal messages - this parameter should be NULL. Depending on the Mail Client - different Message Types might be supported, e.g.: Notes, Calendar, …
sSenderName | Display name of the Mail Sender
sSenderAddress | Mail address of the Mail Sender
sToName | Display name of the Mail Recipient
sToAddress | Mail address of the Mail Recipient

Return value

  • true if successful
  • false otherwise

Example

See MAPI Sample

Parent topic: Sending Functions
Related reference
MAPI Sample


MapiSendMessageEx Function

Action

Sends a message that has been created with MapiCreateMessage. Before you send a message you can use the MapiSetMessage functions to set additional recipients or add attachments.

Include file

Mapi.bdh

Syntax

MapiSendMessageEx(   in   hSession    : number;
                     in   hMessage    : number); boolean
Parameter | Description
hSession | Valid MAPI Session Handle
hMessage | Valid MAPI Message Handle

Return value

  • true if successful
  • false otherwise

Example

See MAPI Sample

Parent topic: Sending Functions
Related reference
MAPI Sample


Creating/Deleting/Saving Functions

  • MapiCreateMessage Function
    Creates a new message and returns a handle for that new message.
  • MapiDeleteMessage Function
    Deletes a message.
  • MapiSaveMessage Function
    Saves changes to a message.
Parent topic: MAPI Functions Reference


MapiCreateMessage Function

Action

Creates a new message and returns a handle for that new message.

The message can be changed afterwards and send on an active session. The message can then be sent with MapiSendMessageEx and can be altered with the MapiSetMessage functions.

Include file

Mapi.bdh

Syntax

MapiCreateMessage( in sSubject      : string,
                   in sMessageText  : string,
                   in sMessageType  : string,
                   in sSenderName   : string,
                   in sSenderAddress: string,
                   in sToName       : string,
                   in sToAddress    : string ) : number;
Parameter | Description
sSubject | Subject for the Mail Message
sMessageText | Body Text for the Mail Message
sMessageType | For normal messages - this parameter should be NULL. Depending on the Mail Client - different Message Types might be supported, e.g.: Notes, Calendar, …
sSenderName | Display name of the Mail Sender
sSenderAddress | Mail address of the Mail Sender
sToName | Display name of the Mail Recipient
sToAddress | Mail address of the Mail Recipient

Return value

  • Message handle if successful
  • 0 if failed

Example

See MAPI Sample

Parent topic: Creating/Deleting/Saving Functions
Related reference
MAPI Sample


MapiDeleteMessage Function

Action

Deletes a message.

Include file

Mapi.bdh

Syntax

MapiDeleteMessage( in hSession: number,
                   in sMsgId  :string ) : boolean;
Parameter | Description
hSession | Valid MAPI Session Handle.
sMsgId | Message ID that should be deleted.

Return value

  • true if successful
  • false otherwise

Example

See MAPI Sample

Parent topic: Creating/Deleting/Saving Functions
Related reference
MAPI Sample


MapiSaveMessage Function

Action

Saves changes to a message. A message can be changed with MapiSetMessage functions and afterwards - those changes can be saved with this function.

Include file

Mapi.bdh

Syntax

MapiSaveMessage( in hSession: number,
                 in hMessage: number,
                 in sMsgId  : string ) : boolean;
Parameter | Description
hSession | Valid MAPI Session Handle
hMessage | Valid MAPI Message Handle
sMsgId | Valid MAPI Message ID.

Return value

  • true if successful
  • false otherwise

Example

See MAPI Sample

Parent topic: Creating/Deleting/Saving Functions
Related reference
MAPI Sample


Accessing Message Properties

  • MapiGetLastError Function
    Returns the error number of the last MAPI call.
  • MapiGetMessage Function
    Retrieves a message identified by the Message ID from an active MAPI Session.
  • MapiGetMessageAttachment Function
    Retrieves information about a message attachment.
  • MapiGetMessageProperty Function
    Retrieves message property values from a valid MAPI Message.
  • MapiGetMessageRecipient Function
    Retrieves information about a message recipient.
  • MapiGetNextMsgId Function
    Returns the next message ID in the inbox of the MAPI session.
  • MapiSetMessageAttachment Function
    Sets information about a message attachment.
  • MapiSetMessageProperty Function
    Sets a message property value of a valid MAPI Message.
  • MapiSetMessageRecipient Function
    Sets information about a message recipient.
Parent topic: MAPI Functions Reference


MapiGetLastError Function

Action

Returns the error number of the last MAPI call. If the last MAPI call was successful - 0 will be returned.

Note: GetLastError returns the internal mapi error code if the last error was a MAPI Runtime error (6).

Include file

Mapi.bdh

Syntax

MapiGetLastError() : number;

Return value

  • Native MAPI Error Code
  • 0 if no error occurred

Example

See MAPI Sample

Parent topic: Accessing Message Properties
Related reference
MAPI Sample


MapiGetMessage Function

Action

Retrieves a message identified by the Message ID from an active MAPI Session. The returned handle can be used to access the Message properties.

When retrieving a message - attachments will be stored to temporary files, which might have some impact on the overall performance. Check the additional parameters to suppress attachements.

Inlcude file

Mapi.bdh

Syntax

MapiGetMessage( in hSession           : number,
                in bPeekMessage       : boolean,
                in bBodyAsAttachment  : boolean,
                in bEnvelopeOnly      : boolean,
                in bSupressAttachments: boolean,
                in sMsgId             : string ) : number;
Parameter | Description
hSession | Valid MAPI Session Handle
bPeekMessage | If true - the message is not marked as read. Some Mail Clients display read/unread messages with a different style
bBodyAsAttachment | If true - the message body will be the first attachment and can be retrieved with MapiGetMessageAttachment
bEnvelopeOnly | If true - only message header information is accessible. Neither attachments nor the message text is accessible. This option greatly enhances the performance.
bSuppressAttachment | If true - no attachments will be retrieved. This option greatly enhances the performance as no temporary files need to be written.
sMsgId | Message ID of the message that should be read. You can obtain a Message ID with MapiGetNextMsgId.

Return value

  • Message Handle if successful
  • 0 otherwise

Example

See MAPI Sample

Parent topic: Accessing Message Properties
Related reference
MAPI Sample


MapiGetMessageAttachment Function

Action

Retrieves information about a message attachment. Getting the property value of MAPI_PROP_MSG_ATTACH_COUNT will retrieve the number of recipients. The attachment ID's are 0 based.

Include file

Mapi.bdh

Syntax

MapiGetMessageAttachment( in hMessage     : number,
                          in nAttachmentID: number,
                          in bFileOrPath  : boolean,
                          in sAttachment  : string ) : boolean;
Parameter | Description
nMessageID | Valid MAPI Message Handle
nAttachmentID | ID of the attachment that should be retrieved. This needs to be a value between 0 and MAPI_PROP_MSG_ATTACH_COUNT-1. The ID is 0 based! So - the first attachment has ID 0 - the second one 1, …
bFileOrPath | True to retrieve the filename of the attachment. False to retrieve the full path of the attachment.
sAttachment | Filename or Full Path of the Attachment.

Return value

  • true if successful
  • false otherwise

Example

See MAPI Sample

Parent topic: Accessing Message Properties
Related reference
MAPI Sample


MapiGetMessageProperty Function

Action

Retrieves message property values from a valid MAPI Message.

Include file

Mapi.bdh

Syntax

MapiGetMessageProperty( in hMessage      : number,
                        in nPropertyID   : number,
                        in sPropertyValue: string ) : boolean;
Parameter | Description
hMessage | Valid MAPI Message Handle
nPropertyID

Property ID that should be retrieved:

  • MAPI_PROP_MSG_SUBJECT
  • MAPI_PROP_MSG_NOTETEXT
  • MAPI_PROP_MSG_MSGTYPE
  • MAPI_PROP_MSG_DATERECEIVED
  • MAPI_PROP_MSG_CONVERSATIONID
  • MAPI_PROP_MSG_SENDER_NAME
  • MAPI_PROP_MSG_SENDER_ADDRESS
  • MAPI_PROP_MSG_RECIPIENT_COUNT
  • MAPI_PROP_MSG_ATTACH_COUNT
sPropertyValue | Retrieves the property value

Return value

  • true if successful
  • false otherwise

Example

See MAPI Sample

Parent topic: Accessing Message Properties
Related reference
MAPI Sample


MapiGetMessageRecipient Function

Action

Retrieves information about a message recipient. Getting the property value of MAPI_PROP_MSG_RECIPIENT_COUNT will retrieve the number of recipients. The recipient ID's are 0 based.

Include

Mapi.bdh

Syntax

MapiGetMessageRecipient( in hMessage             : number,
                         in nRecipientID         : number,
                         in bNameOrAddress       : boolean,
                         in sRecipient: string ) : boolean;
Parameter | Description
hMessage | Valid MAPI Message Handle
nRecipientID | ID of the recipient that should be retrieved. This needs to be a value between 0 and MAPI_PROP_MSG_RECIPIENT_COUNT-1. The ID is 0 based! So - the first recipient has ID 0 - the second one 1, …
bNameOrAddress | True to retrieve the name of the recipient. False to retrieve the address of the recipient
sRecipient | Recipient's name or address

Return value

  • true if successful
  • false otherwise

Exmple

See MAPI Sample

Parent topic: Accessing Message Properties
Related reference
MAPI Sample


MapiGetNextMsgId Function

Action

Returns the next message ID in the inbox of the MAPI session. To retrieve the first message, pass an empty message ID as LastMsgId. Please note that MapiGetNextMsgId retrieves messages in chronologically ascending order, i.e., from oldest to most current. Thus, to retrieve the most current message, it is necessary to iterate through all messages in the inbox.

Include file

Mapi.bdh

Syntax

MapiGetNextMsgId( in hSession  : number,
                  in sLastMsgId: string,
                  in sNextMsgId: string ) : boolean;
Parameter | Description
hSession | Valid MAPI Session Handle
sLastMsgId | Last Message ID or empty value to get the first message
sNextMsgId | Will retrieve the next message in the current MAPI Session.

Return value

  • true if successful
  • false otherwise

Example

See MAPI Sample

Parent topic: Accessing Message Properties
Related reference
MAPI Sample


MapiSetMessageAttachment Function

Action

Sets information about a message attachment. Getting the property value of MAPI_PROP_MSG_ATTACH_COUNT will retrieve the number of recipients. The attachment ID's are 0 based.

Include file

Mapi.bdh

Syntax

MapiSetMessageAttachment( in hMessage     : number,
                          in nAttachmentID: number,
                          in sFileName    : string,
                          in sFullPath    : string ) : boolean;
Parameter | Description
hMessage | Valid MAPI Message Handle.
nAttachmentID | ID of the attachment that should be set. This needs to be a value between 0 and MAPI_PROP_MSG_ATTACH_COUNT-1. The ID is 0 based! So - the first attachment has ID 0 - the second one 1, …
sFileName | Filename of the attachment.
sFullPath | Fullpath of the attachment.

Return value

  • true if successful
  • false otherwise

Example

See MAPI Sample

Parent topic: Accessing Message Properties
Related reference
MAPI Sample


MapiSetMessageProperty Function

Action

Sets a message property value of a valid MAPI Message.

Include file

Mapi.bdh

Syntax

MapiSetMessageProperty( in hMessage      : number,
                        in nPropertyID   : number,
                        in sPropertyValue: string ) : boolean;
Parameter | Description
hMessage | Valid MAPI Message Handle
nPropertyID

Property ID that should be retrieved:

  • MAPI_PROP_MSG_SUBJECT
  • MAPI_PROP_MSG_NOTETEXT
  • MAPI_PROP_MSG_MSGTYPE
  • MAPI_PROP_MSG_DATERECEIVED
  • MAPI_PROP_MSG_CONVERSATIONID
  • MAPI_PROP_MSG_SENDER_NAME
  • MAPI_PROP_MSG_SENDER_ADDRESS
  • MAPI_PROP_MSG_RECIPIENT_COUNT
  • MAPI_PROP_MSG_ATTACH_COUNT
sPropertyValue | New property value

Return value

  • true if successful
  • false otherwise

Example

See MAPI Sample

Parent topic: Accessing Message Properties
Related reference
MAPI Sample


MapiSetMessageRecipient Function

Action

Sets information about a message recipient. Getting the property value of MAPI_PROP_MSG_RECIPIENT_COUNT will retrieve the number of recipients. The recipient ID's are 0 based.

Include file

Mapi.bdh

Syntax

MapiSetMessageRecipient( in hMessage      : number,
                         in nRecipientID  : number,
                         in sName         : string,
                         in sAddress      : string,
                         in nRecipientType: number ) : boolean;
Parameter | Description
hMessageID | Valid MAPI Message Handle
nRecipientID | ID of the recipient that should be set. This needs to be a value between 0 and MAPI_PROP_MSG_RECIPIENT_COUNT-1. The ID is 0 based. So - the first recipient has ID 0 - the second one 1, …
sName | Name of the Recipient
sAddress | Address of the Recipient
nRecipientType
Type of recipient:
  • MAPI_MSG_RECIPTYPE_ORIG
  • MAPI_MSG_RECIPTYPE_TO
  • MAPI_MSG_RECIPTYPE_CC
  • MAPI_MSG_RECIPTYPE_BCC

Return value

  • true if successful
  • false otherwise

Example

See MAPI Sample

Parent topic: Accessing Message Properties
Related reference
MAPI Sample


Misc Functions

  • MapiExit Function
    Unloads MAPI support for the current virtual user. Should be called as last method in a test run.
  • MapiFreeMessage Function
    Frees the memory occupied by the message handle of the virtual user.
  • MapiInit Function
    Initializes MAPI Support for the current virtual user.
Parent topic: MAPI Functions Reference


MapiExit Function

Action

Unloads MAPI support for the current virtual user. Should be called as last method in a test run.

Include file

Mapi.bdh

Syntax

MapiExit();

Example

See MAPI Sample

Parent topic: Misc Functions
Related reference
MAPI Sample


MapiFreeMessage Function

Action

Frees the memory occupied by the message handle of the virtual user. This method should always be called if a message handle is no longer needed.

Include file

Mapi.bdh

Syntax

MapiFreeMessage ( in hMessage : number );
Parameter | Description
hMessage | Valid MAPI Message Handle

Return value

None

Example

See MAPI Sample

Parent topic: Misc Functions
Related reference
MAPI Sample


MapiInit Function

Action

Initializes MAPI Support for the current virtual user. Needs to be called before other MAPI methods are called

Include file

Mapi.bdh

Syntax

MapiInit() :  boolean;

Return value

  • true if successful
  • false otherwise

Example

See MAPI Sample

Parent topic: Misc Functions
Related reference
MAPI Sample


MMS Functions Reference

Silk Performer offers the ability to compose and parse MMS messages, which can be sent and received using HTTP.

MMS manipulation functions:

  • MmsAddContent Function
    Adds content data to the MMS body.
  • MmsAddContentEx Function
    Adds content data to the MMS body.
  • MmsAddFile Function
    Adds a file to the MMS body.
  • MmsAddFileEx Function
    Adds a file to the MMS body.
  • MmsCopyMms Function
    Copies the binary representation of the specified MMS to the provided buffer.
  • MmsCreateMms Function
    Creates a new MMS.
  • MmsDeleteMms Function
    Deletes a MMS.
  • MmsGetCustomHeader Function
    Retrieves the specified custom MMS header.
  • MmsGetHeader Function
    Retrieves the specified header of a MMS.
  • MmsGetHeaderString Function
    Retrieves the specified header of a MMS.
  • MmsParseMms Function
    Parses a MMS from its binary representation.
  • MmsSetCustomHeader Function
    Sets a custom MMS header.
  • MmsSetHeader Function
    Sets a MMS header.
  • MmsSetHeaderString Function
    Sets a MMS header.
Parent topic: Internet Functions


MmsAddContent Function

Action

Adds content data to the MMS body.

Include file

MmsLib.bdh

Syntax

MmsAddContent( in hMms             : number,
               in sData            : string,
               in nDataLen         : number,
               in nContentType     : number,
               in sContentId       : string,
               in sContentLocation : string ): boolean;

Return value

  • true if successful

  • false otherwise

Parameter | Description
hMms | Handle for the MMS, returned by a call to MmsCreateMms.
sData | Data to add to the MMS body.
nDataLen | Length of the data.
nContentType | Specifies the content type. See mmslib.bdh for available values.
sContentId | Specifies the content ID.
sContentLocation | Specifies the content location.

Example

dcltrans
  transaction TInit
  var    hMms : number;
  begin
    MmsCreateMms(hMms);
    MmsSetHeader(hMms, MMS_HEADER_MsgType, MMS_M_SEND_REQ);
    MmsSetHeader(hMms, MMS_HEADER_MmsVersion, MMS_MSGVERSION_10);
    MmsSetHeader(hMms, MMS_HEADER_ContentType, WAP_CONTENT_ApplicationVndWapMultipartRelated);
    MmsSetHeaderString(hMms, MMS_HEADER_From, "31743678001");
    MmsSetHeaderString(hMms, MMS_HEADER_To, "31743689031");
    MmsSetHeaderString(hMms, MMS_HEADER_TransactionId, "17");
    MmsAddContent(hMms, "only text", 9, WAP_CONTENT_TextPlain, "text", "text");
    WapPostMms("http://10.5.8.12:8899/mmsc", hMms);
    MmsDeleteMms(hMms);
  end TInit;
Parent topic: MMS Functions Reference
Related reference
MmsAddContentEx Function
MmsAddFileEx Function
MmsAddFile Function


MmsAddContentEx Function

Action

Adds content data to the MMS body. The content type is specified as text. Use this function to append content with no well-known (numeric) content type.

Include file

MmsLib.bdh

Syntax

MmsAddContentEx( in hMms             : number,
                 in sData            : string,
                 in nDataLen         : number,
                 in sContentType     : string,
                 in sContentId       : string,
                 in nContentLocation : string ): boolean;

Return value

  • true if successful

  • false otherwise

Parameter | Description
hMms | Handle for the MMS, returned by a call to MmsCreateMms.
sData | Data to add to the MMS body.
nDataLen | Length of the data.
sContentType | Specifies the content type. See mmslib.bdh for available values.
sContentId | Specifies the content ID.
sContentLocation | Specifies the content location.

Example

dcltrans
  transaction TInit
    var
    hMms : number;
  begin
    MmsCreateMms(hMms);
    MmsSetHeader(hMms, MMS_HEADER_MsgType, MMS_M_SEND_REQ);
    MmsSetHeader(hMms, MMS_HEADER_MmsVersion, MMS_MSGVERSION_10);
    MmsSetHeader(hMms, MMS_HEADER_ContentType, WAP_CONTENT_ApplicationVndWapMultipartRelated);
    MmsSetHeaderString(hMms, MMS_HEADER_From, "31743678001");
    MmsSetHeaderString(hMms, MMS_HEADER_To, "31743689031");
    MmsSetHeaderString(hMms, MMS_HEADER_TransactionId, "17");
    MmsAddContentEx(hMms, "only text", 9, "text/plain", "text", "text");
    WebPostMms("http://10.5.8.12:8899/mmsc", hMms);
    MmsDeleteMms(hMms);
  end TInit;
Parent topic: MMS Functions Reference
Related reference
MmsAddContent Function
MmsAddFileEx Function
MmsAddFile Function


MmsAddFile Function

Action

Adds a file to the MMS body.

Include file

MmsLib.bdh

Syntax

MmsAddFile( in hMms             : number,
            in sFile            : string,
            in nContentType     : number,
            in sContentId       : string,
            in sContentLocation : string): boolean;

Return value

  • true if successful

  • false otherwise

Parameter | Description
hMms | Handle for the MMS, returned by a call to MmsCreateMms.
sFile | File to add to the MMS.
nContentType | Specifies the content type. See mmslib.bdh for available values.
sContentId | Specifies the content ID.
sContentLocation | Specifies the content location.

Example

dcltrans
  transaction TInit
    var
    hMms : number;
  begin
    MmsCreateMms(hMms);
    MmsSetHeader(hMms, MMS_HEADER_MsgType, MMS_M_SEND_REQ);
    MmsSetHeader(hMms, MMS_HEADER_MmsVersion, MMS_MSGVERSION_10);
    MmsSetHeader(hMms, MMS_HEADER_ContentType, WAP_CONTENT_ApplicationVndWapMultipartRelated);
    MmsSetHeaderString(hMms, MMS_HEADER_From, "31743678001");
    MmsSetHeaderString(hMms, MMS_HEADER_To, "31743689031");
    MmsSetHeaderString(hMms, MMS_HEADER_TransactionId, "17");
    MmsAddFile(hMms, "smile.gif", WAP_CONTENT_ImageGif, "smile.gif", "smile.gif");
    WapPostMms("http://10.5.8.12:8899/mmsc", hMms);
    MmsDeleteMms(hMms);
  end TInit;
Parent topic: MMS Functions Reference
Related reference
MmsParseMms Function
MmsAddContentEx Function
MmsAddContent Function
MmsAddFileEx Function


MmsAddFileEx Function

Action

Adds a file to the MMS body. The content type is specified as text. Use this function to append content with no well-known (numeric) content type.

Include file

MmsLib.bdh

Syntax

MmsAddFileEx( in hMms             : number,
              in sFile            : string,
              in sContentType     : string,
              in sContentId       : string,
              in nContentLocation : string ): boolean;

Return value

  • true if successful

  • false otherwise

Parameter | Description
hMms | Handle for the MMS, returned by a call to MmsCreateMms.
sFile | File to add to the MMS.
sContentType | Specifies the content type. See mmslib.bdh for available values.
sContentId | Specifies the content ID.
sContentLocation | Specifies the content location.

Example

dcltrans
  transaction TInit
  var
    hMms : number;
  begin
    MmsCreateMms(hMms);
    MmsSetHeader(hMms, MMS_HEADER_MsgType, MMS_M_SEND_REQ);
    MmsSetHeader(hMms, MMS_HEADER_MmsVersion, MMS_MSGVERSION_10);
    MmsSetHeader(hMms, MMS_HEADER_ContentType, WAP_CONTENT_ApplicationVndWapMultipartRelated);
    MmsSetHeaderString(hMms, MMS_HEADER_From, "31743678001");
    MmsSetHeaderString(hMms, MMS_HEADER_To, "31743689031");
    MmsSetHeaderString(hMms, MMS_HEADER_TransactionId, "17");
    MmsAddFileEx(hMms, "audio.amr", "audio/amr", "sound", "sound");
    WapPostMms("http://10.5.8.12:8899/mmsc", hMms);
    MmsDeleteMms(hMms);
  end TInit;
Parent topic: MMS Functions Reference
Related reference
MmsAddContentEx Function
MmsAddContent Function
MmsAddFile Function


MmsCopyMms Function

Action

Copies the binary representation of the specified MMS to the provided buffer.

Include file

MmsLib.bdh

Syntax

MmsCopyMms( in  hMms    : number,
            out sMms    : string,
            in  nMaxMms : number optional,
            out nCopied : number optional ): boolean;

Return value

  • true if successful

  • false otherwise

Parameter | Description
hMms | Handle for the MMS, returned by a call to MmsCreateMms.
sMms | Variable that retrieves the binary representation of the MMS.
nMaxMms | Optional: Maximum length of the string that can be returned. This value must be less than or equal to the size of the string variable sMms.
nCopied | Optional: Variable receiving the number of actually copied bytes.

Example

dcltrans
  transaction TInit
  var
    hMms   : number;
    sMms   : string(0x10000);
    nBytes : number;
  begin
    MmsCreateMms(hMms);
    MmsSetHeader(hMms, MMS_HEADER_MsgType, MMS_M_SEND_REQ);
    MmsSetHeader(hMms, MMS_HEADER_MmsVersion, MMS_MSGVERSION_10);
    MmsSetHeader(hMms, MMS_HEADER_ContentType, WAP_CONTENT_ApplicationVndWapMultipartRelated);
    MmsSetHeaderString(hMms, MMS_HEADER_From, "31743678001");
    MmsSetHeaderString(hMms, MMS_HEADER_To, "31743689031");
    MmsSetHeaderString(hMms, MMS_HEADER_TransactionId, "17");
    MmsAddFile(hMms, "smile.gif", WAP_CONTENT_ImageGif, "smile.gif", "smile.gif");
    MmsCopyMms(hMms, sMms, STRING_COMPLETE, nBytes);
    Writedata(sMms, nBytes);
    MmsDeleteMms(hMms);
  end TInit;
Parent topic: MMS Functions Reference
Related reference
MmsParseMms Function


MmsCreateMms Function

Action

Creates a new MMS.

Include file

MmsLib.bdh

Syntax

MmsCreateMms( out hMms : number );
Parameter | Description
hMms | Variable receiving a handle for the MMS.

Example

dcltrans
  transaction TInit
    var
    hMms : number;
  begin
    MmsCreateMms(hMms);
    MmsSetHeader(hMms, MMS_HEADER_MsgType, MMS_M_SEND_REQ);
    MmsSetHeader(hMms, MMS_HEADER_MmsVersion, MMS_MSGVERSION_10);
    MmsSetHeader(hMms, MMS_HEADER_ContentType, WAP_CONTENT_ApplicationVndWapMultipartRelated);
    MmsSetHeaderString(hMms, MMS_HEADER_From, "31743678001");
    MmsSetHeaderString(hMms, MMS_HEADER_To, "31743689031");
    MmsSetHeaderString(hMms, MMS_HEADER_TransactionId, "17");
    MmsAddFile(hMms, "smile.gif", WAP_CONTENT_ImageGif, "smile.gif", "smile.gif");
    WapPostMms("http://10.5.8.12:8899/mmsc", hMms);
    MmsDeleteMms(hMms);
  end TInit;
Parent topic: MMS Functions Reference
Related reference
MmsDeleteMms Function


MmsDeleteMms Function

Action

Deletes a MMS. Each MMS that iss created with the MmsCreateMms function must be deleted using this function.

Include file

MmsLib.bdh

Syntax

MmsDeleteMms( in hMms : number );
Parameter | Description
hMms | Handle for the MMS, returned by a call to MmsCreateMms.

Example

dcltrans
  transaction TInit
var
    hMms : number;
  begin
    MmsCreateMms(hMms);
    MmsSetHeader(hMms, MMS_HEADER_MsgType, MMS_M_SEND_REQ);
    MmsSetHeader(hMms, MMS_HEADER_MmsVersion, MMS_MSGVERSION_10);
    MmsSetHeader(hMms, MMS_HEADER_ContentType, WAP_CONTENT_ApplicationVndWapMultipartRelated);
    MmsSetHeaderString(hMms, MMS_HEADER_From, "31743678001");
    MmsSetHeaderString(hMms, MMS_HEADER_To, "31743689031");
    MmsSetHeaderString(hMms, MMS_HEADER_TransactionId, "17");
    MmsAddFile(hMms, "smile.gif", WAP_CONTENT_ImageGif, "smile.gif", "smile.gif");
    WapPostMms("http://10.5.8.12:8899/mmsc", hMms);
    MmsDeleteMms(hMms);
  end TInit;
Parent topic: MMS Functions Reference
Related reference
MmsCreateMms Function


MmsGetCustomHeader Function

Action

Retrieves the specified custom MMS header. To retrieve the values of known MMS headers, use the MmsGetHeader and MmsGetHeaderString functions instead.

Include file

MmsLib.bdh

Syntax

MmsGetCustomHeader( in  hMms      : number,
                    in  sHeader   : string,
                    out sValue    : string,
                    in  nMaxValue : number optional,
                    out nCopied   : number optional ): boolean;

Return value

  • true if successful

  • false otherwise

Parameter | Description
hMms | Handle for the MMS, returned by a call to MmsCreateMms.
sHeader | Specifies the custom MMS header.
sValue | Specifies the value of the custom MMS header.
nMaxValue | Optional: Maximum length of the string that can be returned. This value must be less than or equal to the size of the string variable sValue.
nCopied | Optional: Variable receiving the number of actually copied bytes.

Example

dcltrans
  transaction TWap
  var
    sData   : string(0x10000);
    nData   : number;
    hMms    : number;
    nStatus : number;
    sGroup  : string;
  begin
    nData := WapGetContent(sData);
    MmsCreateMms(hMms);
    MmsParseMms(hMms, sData, nData, true);
    MmsGetCustomHeader(hMms, "GROUP", sGroup);
    MmsDeleteMms(hMms);
    print(sGroup);
  end TWap;
Parent topic: MMS Functions Reference
Related reference
MmsSetCustomHeader Function
MmsGetHeader Function
MmsSetHeader Function
MmsSetHeaderString Function


MmsGetHeader Function

Action

Retrieves the specified header of a MMS. If the header is not a number type header, use MmsGetHeaderString instead.

Include file

MmsLib.bdh

Syntax

MmsGetHeader( in  hMms    : number,
              in  nHeader : number,
              out nValue  : number ): boolean;

Return value

  • true if successful

  • false otherwise

Parameter | Description
hMms | Handle for the MMS, returned by a call to MmsCreateMms.
nHeader
One of the following constants:
  • MMS_HEADER_ContentType
  • MMS_HEADER_Date
  • MMS_HEADER_DeliveryReport
  • MMS_HEADER_MsgClass
  • MMS_HEADER_MsgType
  • MMS_HEADER_MmsVersion
  • MMS_HEADER_Priority
  • MMS_HEADER_ReadReply
  • MMS_HEADER_ReportAllowed
  • MMS_HEADER_ResponseStatus
  • MMS_HEADER_Status
nValue Variable that retrieves the value of the specified header. Based on the specified header type, one of the following values is used:
Header
Value
nHeader = MMS_HEADER_ContentType
  • WAP_CONTENT_ApplicationVndWapMultipartMixed
  • WAP_CONTENT_ApplicationVndWapMultipartRelated
nHeader = MMS_HEADER_Date
Value equals the number of seconds from 1970-01-01, 00:00:00 GMT. 0 specifies the current date.
nHeader = MMS_HEADER_DeliveryReport

  • MMS_Yes

  • MMS_No

nHeader = MMS_HEADER_MsgClass
  • MMS_MSGCLASS_Personal
  • MMS_MSGCLASS_Advertisement
  • MMS_MSGCLASS_Informational
  • MMS_MSGCLASS_Auto
nHeader = MMS_HEADER_MsgType
  • MMS_M_SEND_REQ
  • MMS_M_SEND_CONF
  • MMS_M_NOTIFICATION_IND
  • MMS_M_NOTIFYRESP_IND
  • MMS_M_RETRIEVE_CONF
  • MMS_M_ACKNOWLEDGE_IND
  • MMS_M_DELIVERY_IND
nHeader = MMS_HEADER_MmsVersion
MMS_MSGVERSION_10
nHeader = MMS_HEADER_Priority
  • MMS_PRIORITY_Low
  • MMS_PRIORITY_Normal
  • MMS_PRIORITY_High
nHeader = MMS_HEADER_ReadReply

  • MMS_Yes

  • MMS_No

nHeader = MMS_HEADER_ReportAllowed

  • MMS_Yes

  • MMS_No

nHeader = MMS_HEADER_ResponseStatus
  • MMS_RESPONSESTATUS_Ok
  • MMS_RESPONSESTATUS_ErrorUnspecified
  • MMS_RESPONSESTATUS_ErrorServiceDenied
  • MMS_RESPONSESTATUS_ErrorMessageFormatCorrupt
  • MMS_RESPONSESTATUS_ErrorSendingAddressUnresolved
  • MMS_RESPONSESTATUS_ErrorMessageNotFound
  • MMS_RESPONSESTATUS_ErrorNetworkProblem
  • MMS_RESPONSESTATUS_ErrorContentNotAccepted
  • MMS_RESPONSESTATUS_ErrorUnsupportedMessage
nHeader = MMS_HEADER_Status
  • MMS_STATUS_Expired
  • MMS_STATUS_Retrieved
  • MMS_STATUS_Rejected
  • MMS_STATUS_Deferred
  • MMS_STATUS_Unrecognised

Example

dcltrans
  transaction TWap
  var
    sData   : string(0x10000);
    nData   : number;
    hMms    : number;
    nStatus : number;
  begin
    nData := WapGetContent(sData);
    MmsCreateMms(hMms);
    MmsParseMms(hMms, sData, nData, true);
    MmsGetHeader(hMms, MMS_HEADER_ResponseStatus, nStatus);
    MmsDeleteMms(hMms);
    print(string(nStatus));
  end TWap;
Parent topic: MMS Functions Reference
Related reference
MmsSetHeader Function
MmsGetHeaderString Function


MmsGetHeaderString Function

Action

Retrieves the specified header of a MMS. If the header is not a string type header, use MmsGetHeader instead.

Include file

MmsLib.bdh

Syntax

MmsGetHeaderString( in  hMms      : number,
                    in  nHeader   : number,
                    out sValue    : string,
                    in  nMaxValue : number optional,
                    out nCopied   : number optional ): boolean;

Return value

  • true if successful

  • false otherwise

Parameter | Description
hMms | Handle for the MMS, returned by a call to MmsCreateMms.
nHeader One of the following constants:
  • MMS_HEADER_Bcc
  • MMS_HEADER_Cc
  • MMS_HEADER_ContentLocation
  • MMS_HEADER_From
  • MMS_HEADER_MsgId
  • MMS_HEADER_Subject
  • MMS_HEADER_To
  • MMS_HEADER_TransactionId
sValue Variable that retrieves the value of the specified header. Based on the specified header type, the returned string specifies one of the following:
  • MMS_HEADER_Bcc: An MMS address (phone number, e-mail address, IP address).
  • MMS_HEADER_Cc: An MMS address (phone number, e-mail address, IP address).
  • MMS_HEADER_ContentLocation: Content location of the MMS.
  • MMS_HEADER_From: An MMS address (phone number, e-mail address, IP address).
  • MMS_HEADER_MsgId: The message ID.
  • MMS_HEADER_Subject: The message subject.
  • MMS_HEADER_To: An MMS address (phone number, e-mail address, IP address).
  • MMS_HEADER_TransactionId: The transaction ID.
nMaxValue | Optional: Maximum length of the string that can be returned. This value must be less than or equal to the size of the string variable sValue.
nCopied | Optional: Variable receiving the number of actually copied bytes.

Example

dcltrans
  transaction TWap
  var
    sData   : string(0x10000);
    nData   : number;
    hMms    : number;
    sFrom   : string;
  begin
    nData := WapGetContent(sData);
    MmsCreateMms(hMms);
    MmsParseMms(hMms, sData, nData, true);
    MmsGetHeaderString(hMms, MMS_HEADER_From, sFrom);
    MmsDeleteMms(hMms);
    print(sFrom);
  end TWap;
Parent topic: MMS Functions Reference
Related reference
MmsGetHeader Function
MmsSetHeaderString Function
MmsSetHeader Function


MmsParseMms Function

Action

Parses a MMS from its binary representation. This function can be used to prepare a received MMS for header checking, for example checking response status.

Include file

MmsLib.bdh

Syntax

MmsParseMms( in hMms         : number,
             in sData        : string,
             in nDataLen     : number optional,
             in bHeadersOnly : boolean optional ): boolean;

Return value

  • true if successful

  • false otherwise

Parameter | Description
hMms | Handle for the MMS returned by a call to MmsCreateMms.
sData | Binary representation of the MMS to be parsed.
nDataLen | Optional: Length of the binary data.
bHeadersOnly | Optional: Specifies whether the parsing process should be stopped after the MMS headers (sufficient for header checking). A value of false specifies that the entire MMS should be parsed.

Example

dcltrans
  transaction TWap
  var
    sData   : string(0x10000);
    nData   : number;
    hMms    : number;
    sFrom   : string;
  begin
    nData := WapGetContent(sData);
    MmsCreateMms(hMms);
    MmsParseMms(hMms, sData, nData, true);
    MmsGetHeaderString(hMms, MMS_HEADER_From, sFrom);
    MmsDeleteMms(hMms);
    print(sFrom);
  end TWap;
Parent topic: MMS Functions Reference
Related reference
MmsCopyMms Function


MmsSetCustomHeader Function

Action

Sets a custom MMS header. The header and its value must be specified. To set known MMS headers, use the MmsSetHeader or MmsSetHeaderString functions instead.

Include file

MmsLib.bdh

Syntax

MmsSetCustomHeader( in hMms    : number,
                    in sHeader : string,
                    in sValue  : string ): boolean;

Return value

  • true if successful

  • false otherwise

Parameter | Description
hMms | Handle for the MMS, returned by a call to MmsCreateMms.
sHeader | Specifies the custom MMS header.
sValue | Specifies the value of the custom MMS header.

Example

dcltrans
transaction TInit
var
  hMms : number;
  begin
    MmsCreateMms(hMms);
    MmsSetHeader(hMms, MMS_HEADER_MsgType, MMS_M_SEND_REQ);
    MmsSetHeader(hMms, MMS_HEADER_MmsVersion, MMS_MSGVERSION_10);
    MmsSetHeader(hMms, MMS_HEADER_ContentType, WAP_CONTENT_ApplicationVndWapMultipartRelated);
    MmsSetHeaderString(hMms, MMS_HEADER_From, "31743678001");
    MmsSetHeaderString(hMms, MMS_HEADER_To, "31743689031");
    MmsSetHeaderString(hMms, MMS_HEADER_TransactionId, "17");
    MmsSetCustomHeader(hMms, "GROUP", "77");
    MmsAddFile(hMms, "info.gif", WAP_CONTENT_ImageGif, "", "info.gif");
    WapPostMms("http://10.5.8.12:8899/mmsc", hMms);
    MmsDeleteMms(hMms);
  end TInit;
Parent topic: MMS Functions Reference
Related reference
MmsGetCustomHeader Function
MmsSetHeader Function
MmsSetHeaderString Function


MmsSetHeader Function

Action

Sets a MMS header. The MMS_HEADER_MsgType is a mandatory header that specifies the MMS type. Based on the MMS type, all other headers are either mandatory or optional. See the MMS Encapsulation Protocol specification for details.

Include file

MmsLib.bdh

Syntax

MmsSetHeader( in hMms    : number,
              in nHeader : number,
              in nValue  : number ): boolean;

Return value

  • true if successful

  • false otherwise

Parameter | Description
hMms | Handle for the MMS, returned by a call to MmsCreateMms.
nHeader One of the following constants:
  • MMS_HEADER_ContentType
  • MMS_HEADER_Date
  • MMS_HEADER_DeliveryReport
  • MMS_HEADER_MsgClass
  • MMS_HEADER_MsgType (mandatory)
  • MMS_HEADER_MmsVersion
nValue Based on the specified MMS header type, one of the following values:
Header
Value
nHeader = MMS_HEADER_ContentType
  • WAP_CONTENT_ApplicationVndWapMultipartMixed
  • WAP_CONTENT_ApplicationVndWapMultipartRelated
nHeader = MMS_HEADER_Date
Value equals the number of seconds from 1970-01-01, 00:00:00 GMT. 0 specifies the current date.
nHeader = MMS_HEADER_DeliveryReport

  • MMS_Yes

  • MMS_No

nHeader = MMS_HEADER_MsgClass
  • MMS_MSGCLASS_Personal
  • MMS_MSGCLASS_Advertisement
  • MMS_MSGCLASS_Informational
  • MMS_MSGCLASS_Auto
nHeader = MMS_HEADER_MsgType
  • MMS_M_SEND_REQ
  • MMS_M_SEND_CONF
  • MMS_M_NOTIFICATION_IND
  • MMS_M_NOTIFYRESP_IND
  • MMS_M_RETRIEVE_CONF
  • MMS_M_ACKNOWLEDGE_IND
  • MMS_M_DELIVERY_IND
nHeader = MMS_HEADER_MmsVersion
MMS_MSGVERSION_10
nHeader = MMS_HEADER_Priority
  • MMS_PRIORITY_Low
  • MMS_PRIORITY_Normal
  • MMS_PRIORITY_High
nHeader = MMS_HEADER_ReadReply

  • MMS_Yes

  • MMS_No

nHeader = MMS_HEADER_ReportAllowed

  • MMS_Yes

  • MMS_No

Example

dcltrans
transaction TInit
    var
    hMms : number;
  begin
    MmsCreateMms(hMms);
    MmsSetHeader(hMms, MMS_HEADER_MsgType, MMS_M_SEND_REQ);
    MmsSetHeader(hMms, MMS_HEADER_MmsVersion, MMS_MSGVERSION_10);
    MmsSetHeader(hMms, MMS_HEADER_ContentType, WAP_CONTENT_ApplicationVndWapMultipartRelated);
    MmsSetHeaderString(hMms, MMS_HEADER_From, "31743678001");
    MmsSetHeaderString(hMms, MMS_HEADER_To, "31743689031");
    MmsSetHeaderString(hMms, MMS_HEADER_TransactionId, "17");
    MmsAddFile(hMms, "info.gif", WAP_CONTENT_ImageGif, "", "info.gif");
    WapPostMms("http://10.5.8.12:8899/mmsc", hMms);
    MmsDeleteMms(hMms);
  end TInit;
Parent topic: MMS Functions Reference
Related reference
MmsSetHeaderString Function
MmsGetHeader Function


MmsSetHeaderString Function

Action

Sets a MMS header. Based on the specified MMS type (MmsSetHeader) the listed headers are either mandatory or optional. See the MMS Encapsulation Protocol specification for details.

Include file

MmsLib.bdh

Syntax

MmsSetHeaderString( in hMms    : number,
                    in nHeader : number,
                    in sValue  : string ): boolean;

Return value

  • true if successful

  • false otherwise

Parameter | Description
hMms | Handle for the MMS, returned by a call to MmsCreateMms.
nHeader One of the following constants:
  • MMS_HEADER_Bcc
  • MMS_HEADER_Cc
  • MMS_HEADER_ContentLocation
  • MMS_HEADER_From
  • MMS_HEADER_MsgId
  • MMS_HEADER_Subject
  • MMS_HEADER_To
  • MMS_HEADER_TransactionId
sValue Based on the specified header type, the sValue parameter specifies one of the following:
  • MMS_HEADER_Bcc: An MMS address (phone number, e-mail address, IP address).
  • MMS_HEADER_Cc: An MMS address (phone number, e-mail address, IP address).
  • MMS_HEADER_ContentLocation: Content location of the MMS.
  • MMS_HEADER_From: An MMS address (phone number, e-mail address, IP address).
  • MMS_HEADER_MsgId: The message ID.
  • MMS_HEADER_Subject: The message subject.
  • MMS_HEADER_To: An MMS address (phone number, e-mail address, IP address).
  • MMS_HEADER_TransactionId: The transaction ID.

Example

dcltrans
transaction TInit
var
    hMms : number;
  begin
    MmsCreateMms(hMms);
    MmsSetHeader(hMms, MMS_HEADER_MsgType, MMS_M_SEND_REQ);
    MmsSetHeader(hMms, MMS_HEADER_MmsVersion, MMS_MSGVERSION_10);
    MmsSetHeader(hMms, MMS_HEADER_ContentType, WAP_CONTENT_ApplicationVndWapMultipartRelated);
    MmsSetHeaderString(hMms, MMS_HEADER_From, "31743678001");
    MmsSetHeaderString(hMms, MMS_HEADER_To, "31743689031");
    MmsSetHeaderString(hMms, MMS_HEADER_TransactionId, "17");
    MmsAddFile(hMms, "info.gif", WAP_CONTENT_ImageGif, "", "info.gif");
    WapPostMms("http://10.5.8.12:8899/mmsc", hMms);
    MmsDeleteMms(hMms);
  end TInit;
Parent topic: MMS Functions Reference
Related reference
MmsSetHeader Function
MmsGetHeaderString Function


POP3 Functions Reference

The following function set is a complete implementation of the Post Office Protocol 3. The MD5 message digest encryption standard and other optional POP3 commands are also implemented. The POP3 functions can also be used mixed with the Application Level functions. This means it is possible to use the same handle hWeb with WebPopConnect and WebTcpipRecv, for instance. Most of the POP3 functions send a command to the POP3 server and interpret the response immediately. For example, WebPopUser sends the USER command to the server and returns “true” if the server responds with "+OK".

POP3 functions

  • WebPopApop Function
    Sends a timestamp that is stored internally for use with WebPopApop.
  • WebPopCommand Function
    Sends a command string to a POP3 server.
  • WebPopConnect Function
    Connects to a POP3 server.
  • WebPopDele Function
    Marks the mail with number nMsg as deleted.
  • WebPopList Function
    Sends the LIST command to the server, which responds with a maildrop.
  • WebPopNoop Function
    Sends the No Operation command to the server.
  • WebPopPass Function
    Sends the password as plain ASCII text to the server.
  • WebPopQuit Function
    Sends the Quit command to the server.
  • WebPopResponse Function
    Retrieves a standard single-line response from the POP3 server.
  • WebPopResponseML Function
    Retrieves a multi-line response from the POP3 server.
  • WebPopRetr Function
    Retrieves a message with number nMsg from the server.
  • WebPopRset Function
    Invokes a rollback on the POP3 server. The server then performs an undo on message deletion.
  • WebPopShutdown Function
    Shuts down the connection to the POP3 server. First use WebPopQuit to commit the changes on the server.
  • WebPopStat Function
    Retrieves the mailbox status after a successful login.
  • WebPopTop Function
    Retrieves from the server the first nLines lines of the mail with number nMsg.
  • WebPopUidl Function
    Retrieves from the server a unique message ID string for message nMsg.
  • WebPopUser Function
    Sends the mailbox user name to the server.
Parent topic: Internet Functions


WebPopApop Function

Action

POP3 server login using MD5 message digest authentication. In response, in the banner greeting (during WebPopConnect) the server sends a timestamp that is stored internally for use with WebPopApop. The concatenated string of timestamp and password is then encrypted and sent to the server.

Include file

WebAPI.bdh

Syntax

WebPopApop( in hPop  : number,
            in sName : string,
            in sPass : string ): boolean;

Return value

  • true if the response was successfully received and the server confirmed with "+OK"

  • false otherwise

Parameter | Description
hPop | Handle to a Web connection that was created by WebPopConnect
sName | User name
sPass | Password

Example

dcltrans
  transaction TWebPop3
  const
    USERNAME := "username";
    PASSWORD := "password";
  var
    hPop, nMessages, nSize: number;
  begin
    WebPopConnect(hPop, "standardhost", WEB_PORT_POP3);

    // try to log in using secure MD5 encryption
    if not WebPopApop(hPop, USERNAME, PASSWORD) then

    // if APOP fails, try normal user/pass sequence
      if not WebPopUser(hPop, USERNAME) or
          not WebPopPass(hPop, PASSWORD) then
        WebPopShutdown(hPop);
        return 1;
      end;
    end;

    WebPopQuit(hPop);
    WebPopShutdown(hPop);
  end TWebPop3;

SilkEssential sample

eMail.sep

Parent topic: POP3 Functions Reference
Related reference
WebPopConnect Function
WebPopTop Function
WebPopUidl Function
WebPopUser Function
WebPopPass Function
WebPopStat Function


WebPopCommand Function

Action

Sends a command string to a POP3 server.

Include file

WebAPI.bdh

Syntax

WebPopCommand( in hPop     : number,
               in sCommand : string ): boolean;

Return value

  • true if successful

  • false otherwise

Parameter | Description
hPop | Handle to a Web connection that was created by WebPopConnect
sCommand | Command string. Make sure to append a carriage return and a line feed command ("\r\n") to the command string.

Example

dcltrans
  transaction TWebPopCommand
  const
    USERNAME := "username";
    PASSWORD := "password";
    COMMAND  := "...\r\n";
  // specify command string
  var
    hPop: number;
  begin
    WebPopConnect(hPop, "standardhost", WEB_PORT_POP3);
    WebPopUser(hPop, USERNAME);
    WebPopPass(hPop, PASSWORD);
    WebPopCommand(hPop, COMMAND);
    WebPopQuit(hPop);
    WebPopShutdown(hPop);
  end TWebPopCommand;
Parent topic: POP3 Functions Reference
Related reference
WebPopConnect Function
WebPopTop Function
WebPopUidl Function
WebPopUser Function
WebPopResponse Function
WebPopResponseML Function


WebPopConnect Function

Action

Connects to a POP3 server.

Include file

WebAPI.bdh

Syntax

WebPopConnect( out hPop    : number,
               in sHost    : string,
               in nPort    : number,
               in nSecure  : number optional ): boolean;

Return value

  • true if the response was successfully received and the server confirmed with "+OK"

  • false otherwise

Parameter | Description
hPop

Variable receiving a handle to the Web connection

If this parameter contains a handle to a Web connection prior to the WebPopConnect function call, the memory allocated with the handle is released. Whenever you want to create a new Web connection, make sure this variable is initialized with 0 (this is automatically done within transactions when they are executed for the first time, but not within functions)
sHost | Domain name or IP address of the POP3 server, for example, hostname.com or 192.231.34.1
nPort | Port to connect to, usually WEB_PORT_POP3
nSecurity

Specifies whether to establish a secure connection to the remote server (optional). Possible options are:

  • WEB_CONNECT_NONE. Establishes an insecure connection to the server (default)

  • WEB_CONNECT_SSL. Establishes a secure connection using SSL

Example

dcltrans
  transaction TWebPop3
  var
    hPop: number;
  begin
    WebPopConnect(hPop, "standardhost", WEB_PORT_POP3);
    WebPopShutdown(hPop);
  end TWebPop3;

Sample scripts

WebMulti01.bdf, WebSecure01.bdf

SilkEssential sample

eMail.sep

Parent topic: POP3 Functions Reference
Related reference
WebPopShutdown Function


WebPopDele Function

Action

Marks the mail with number nMsg as deleted.

Include file

WebAPI.bdh

Syntax

WebPopDele( in hPop : number,
            in nMsg : number ): boolean;

Return value

  • true if the response was successfully received and the server confirmed with "+OK"

  • false otherwise

Parameter | Description
hPop | Handle to a Web connection that was created by WebPopConnect
nMsg | Number of the message to delete

Example

dcltrans
  transaction TWebPop3
  const
    USERNAME := "username";
    PASSWORD := "password";
  var
    hPop, nMessages, nSize: number;
  begin
    WebPopConnect(hPop, "standardhost", WEB_PORT_POP3);

     // try to log in using secure MD5 encryption
    if not WebPopApop(hPop, USERNAME, PASSWORD) then

       // if APOP fails, try normal user/pass sequence
      if not WebPopUser(hPop, USERNAME) or
        not WebPopPass(hPop, PASSWORD) then
        WebPopShutdown(hPop);
        return 1;
      end;
    end;

    // retrieve mail status information
    WebPopStat(hPop, nMessages, nSize);
    WebPopList(hPop, IGNORE);

    // retrieve and delete all messages
    while nMessages > 0 do
      WebPopRetr(hPop, nMessages);
      WebPopDele(hPop, nMessages);
      nMessages := nMessages - 1;
    end;

    // try to delete msg 123456789 - an error msg will occur
    WebPopDele(hPop, 123456789);

    // roll back the delete command (no msgs will be deleted)
    WebPopRset(hPop);

    // commit pop transaction
    // (usually marked messages will be deleted)
    // There is nothing to delete due to the pop transaction
    // reset - WebPopRset
    WebPopQuit(hPop);
    WebPopShutdown(hPop);
  end TWebPop3;

SilkEssential sample

eMail.sep

Parent topic: POP3 Functions Reference
Related reference
WebPopConnect Function
WebPopTop Function
WebPopUidl Function
WebPopUser Function
WebPopRset Function
WebPopQuit Function


WebPopList Function

Action

Sends the LIST command to the server, which responds with a maildrop.

Include file

WebAPI.bdh

Syntax

WebPopList( in hPop: number,
            in nMsg: number ): boolean;

Return value

  • true if the response was successfully received and the server confirmed with "+OK"

  • false otherwise

Parameter | Description
hPop | Handle to a Web connection that was created by WebPopConnect
nMsg | Number of the message to list. Pass the IGNORE flag to the function to disable use of this parameter

Example

dcltrans
  transaction TWebPop3
  const
    USERNAME := "username";
    PASSWORD := "password";
  var
    hPop, nMessages, nSize: number;
  begin    WebPopConnect(hPop, "standardhost", WEB_PORT_POP3);
    WebPopUser(hPop, USERNAME);
    WebPopPass(hPop, PASSWORD);
    WebPopStat(hPop, nMessages, nSize);
    WebPopList(hPop, IGNORE);
    WebPopRset(hPop);
    WebPopQuit(hPop);
    WebPopShutdown(hPop);
  end TWebPop3;

Sample scripts

WebMulti01.bdf

SilkEssential sample

eMail.sep

Parent topic: POP3 Functions Reference
Related reference
WebPopConnect Function
WebPopTop Function
WebPopUidl Function
WebPopUser Function


WebPopNoop Function

Action

Sends the No Operation command to the server. This command can be used to check the availability of the POP3 server.

Include file

WebAPI.bdh

Syntax

WebPopNoop( in hPop: number ): boolean;

Return value

  • true if the response was successfully received and the server confirmed with "+OK"

  • false otherwise

Parameter | Description
hPop | Handle to a Web connection that was created by WebPopConnect

Example

dcltrans
  transaction TWebPop3
  const
    USERNAME := "username";
    PASSWORD := "password";
  var
    hPop, nMessages, nSize: number;
  begin
    WebPopConnect(hPop, "standardhost", WEB_PORT_POP3);
    WebPopUser(hPop, USERNAME);
    WebPopPass(hPop, PASSWORD);
    WebPopStat(hPop, nMessages, nSize);
    WebPopList(hPop, IGNORE);
    WebPopNoop(hPop);
    WebPopQuit(hPop);
    WebPopShutdown(hPop);
  end TWebPop3;
Parent topic: POP3 Functions Reference
Related reference
WebPopConnect Function
WebPopTop Function
WebPopUidl Function
WebPopUser Function


WebPopPass Function

Action

Sends the password as plain ASCII text to the server. Use WebPopUser first.

Include file

WebAPI.bdh

Syntax

WebPopPass( in hPop  : number,
            in sPass : string ): boolean;

Return value

  • true if the response was successfully received and the server confirmed with "+OK"

  • false otherwise

Parameter | Description
hPop | Handle to a Web connection that was created by WebPopConnect
sPass | Password

Example

dcltrans
  transaction TWebPop3
  const
    USERNAME := "username";
    PASSWORD := "password";
  var
    hPop, nMessages, nSize: number;
  begin
    WebPopConnect(hPop, "standardhost", WEB_PORT_POP3);
    WebPopUser(hPop, USERNAME);
    WebPopPass(hPop, PASSWORD);
    WebPopStat(hPop, nMessages, nSize);
    WebPopList(hPop, IGNORE);
    WebPopRset(hPop);
    WebPopQuit(hPop);
    WebPopShutdown(hPop);
  end TWebPop3;

Sample scripts

WebMulti01.bdf

SilkEssential sample

eMail.sep

Parent topic: POP3 Functions Reference
Related reference
WebPopConnect Function
WebPopTop Function
WebPopUidl Function
WebPopUser Function
WebPopApop Function
WebPopStat Function


WebPopQuit Function

Action

Sends the Quit command to the server. The server then commits the transaction by physically deleting all marked messages. Use WebPopShutdown after WebPopQuit to close the Internet connection.

Include file

WebAPI.bdh

Syntax

WebPopQuit( in hPop: number ): boolean;

Return value

  • true if the response was successfully received and the server confirmed with "+OK"

  • false otherwise

Parameter | Description
hPop | Handle to a Web connection that was created by WebPopConnect

Example

dcltrans
  transaction TWebPop3
  const
    USERNAME := "username";
    PASSWORD := "password";
  var
    hPop, nMessages, nSize: number;
  begin
    WebPopConnect(hPop, "standardhost", WEB_PORT_POP3);
    WebPopUser(hPop, USERNAME);
    WebPopPass(hPop, PASSWORD);
    WebPopStat(hPop, nMessages, nSize);
    WebPopList(hPop, IGNORE);
    WebPopRset(hPop);
    WebPopQuit(hPop);
    WebPopShutdown(hPop);
  end TWebPop3;

Sample scripts

WebMulti01.bdf

SilkEssential sample

eMail.sep

Parent topic: POP3 Functions Reference
Related reference
WebPopConnect Function
WebPopTop Function
WebPopUidl Function
WebPopUser Function
WebPopRset Function
WebPopDele Function


WebPopResponse Function

Action

Retrieves a standard single-line response from the POP3 server.

Include file

WebAPI.bdh

Syntax

WebPopResponse( in  hPop      : number,
                out sResponse : string,
                in  nMaxLen   : number): boolean;

Return value

  • true if the response was successfully received and the server confirmed with "+OK"

  • false otherwise

Parameter | Description
hPop | Handle to a Web connection that was created by WebPopConnect
sResponse | String buffer to hold the response. Can be set to NULL to use the internal buffer. The complete response is read from the server even if sResponse is too short to hold it.
nMaxLen | Maximum size of the returned response. Specify STRING_COMPLETE to get all received data.

Example

WebPopResponse(hPop, sResponse, STRING_COMPLETE);
WebPopResponse(hPop, NULL, 0);
Parent topic: POP3 Functions Reference
Related reference
WebPopConnect Function
WebPopTop Function
WebPopUidl Function
WebPopUser Function
WebPopResponseML Function


WebPopResponseML Function

Action

Retrieves a multi-line response from the POP3 server.

Include file

WebAPI.bdh

Syntax

WebPopResponseML(in hPop: number): boolean;

Return value

  • true if the response was successfully received and the server confirmed with "+OK"

  • false otherwise

Parameter | Description
hPop | Handle to a Web connection that was created by WebPopConnect
Note: Multiline responses are terminated by CRLF DOT CRLF.
Note: This function is used only after a WebTcpipSend command, which sends the custom POP3 command to the server. The response data is discarded after retrieval.
Parent topic: POP3 Functions Reference
Related reference
WebPopConnect Function
WebPopTop Function
WebPopUidl Function
WebPopUser Function
WebPopResponse Function
WebTcpipSend Function


WebPopRetr Function

Action

Retrieves a message with number nMsg from the server.

Include file

WebAPI.bdh

Syntax

WebPopRetr( in  hPop     : number,
            in  nMsg     : number,
            out sMailMsg : string optional,
            in  nMaxSize : number optional): boolean;

Return value

  • true if the response was successfully received and the server confirmed with "+OK"

  • false otherwise

Parameter | Description
hPop | Handle to a Web connection that was created by WebPopConnect.
nMsg | Number of the message to retrieve.
sMailMsg | String buffer receiving the mail message (optional).
nMaxSize | Size of the string buffer receiving the mail message (optional). Specify STRING_COMPLETE to get all received data.

Example

dcltrans
  transaction TWebPop3
  const
    USERNAME := "username";
    PASSWORD := "password";
  var
    hPop, nMessages, nSize : number;
    sMsg                   : string;
  begin    WebPopConnect(hPop, "standardhost", WEB_PORT_POP3);
    // try to log in using secure MD5 encryption
    if not WebPopApop(hPop, USERNAME, PASSWORD) then
      // if APOP fails, try normal user/pass sequence
      if not WebPopUser(hPop, USERNAME) or
      not WebPopPass(hPop, PASSWORD) then
      WebPopShutdown(hPop); return 1;
      end;
    end;

    // retrievemail status information
    WebPopStat(hPop, nMessages, nSize);
    WebPopList(hPop, IGNORE);

    // retrieve and delete all messages
    while nMessages > 0 do
      WebPopRetr(hPop, nMessages, sMsg);
      WebPopDele(hPop, nMessages);
      nMessages := nMessages - 1;
    end;

    // roll back the delete command (no msgs will be deleted)
    WebPopRset(hPop);

    // commit pop transaction
    WebPopQuit(hPop);

    WebPopShutdown(hPop);
  end TWebPop3;

SilkEssential sample

eMail.sep

Parent topic: POP3 Functions Reference
Related reference
WebPopConnect Function
WebPopTop Function
WebPopUidl Function
WebPopUser Function


WebPopRset Function

Action

Invokes a rollback on the POP3 server. The server then performs an undo on message deletion.

Include file

WebAPI.bdh

Syntax

WebPopRset( in hPop: number ): boolean;

Return value

  • true if the response was successfully received and the server confirmed with "+OK"

  • false otherwise

Parameter | Description
hPop | Handle to a Web connection that was created by WebPopConnect

Example

dcltrans
  transaction TWebPop3
  const
    USERNAME := "username";
    PASSWORD := "password";
  var
    hPop, nMessages, nSize: number;
  begin
    WebPopConnect(hPop, "standardhost", WEB_PORT_POP3);
    WebPopUser(hPop, USERNAME);
    WebPopPass(hPop, PASSWORD);
    WebPopStat(hPop, nMessages, nSize);
    WebPopList(hPop, IGNORE);
    WebPopRset(hPop);
    WebPopQuit(hPop);
    WebPopShutdown(hPop);
  end TWebPop3;

Sample scripts

WebMulti01.bdf

SilkEssential sample

eMail.sep

Parent topic: POP3 Functions Reference
Related reference
WebPopConnect Function
WebPopTop Function
WebPopUidl Function
WebPopUser Function
WebPopDele Function
WebPopQuit Function


WebPopShutdown Function

Action

Shuts down the connection to the POP3 server. First use WebPopQuit to commit the changes on the server.

Include file

WebAPI.bdh

Syntax

WebPopShutdown( inout hPop  : number,
                in    nMode : number optional ): boolean;

Return value

  • true if the response was successfully received and the server confirmed with "+OK"

  • false otherwise

Parameter | Description
hPop | Handle to a Web connection that was created by WebPopConnect
nMode

Determines the shutdown mode (optional). Any of the following options is possible:

  • WEB_SHUTDOWN_GRACEFUL. Initiates a graceful shutdown: first closes and then resets the connection

  • WEB_SHUTDOWN_IMMEDIATE. Initiates a standard connection close (default)

  • WEB_SHUTDOWN_RESET. Resets the connection

Example

dcltrans
  transaction TWebPop3
  var
   hPop: number;
  begin
    WebPopConnect(hPop, "standardhost", WEB_PORT_POP3);
    WebPopShutdown(hPop);
  end TWebPop3;

Sample scripts

WebMulti01.bdf, WebSecure01.bdf

SilkEssential sample

eMail.sep

Parent topic: POP3 Functions Reference
Related reference
WebPopConnect Function


WebPopStat Function

Action

Retrieves the mailbox status after a successful login.

Include file

WebAPI.bdh

Syntax

WebPopStat( in  hPop       : number,
            out nMsgNumber : number,
            out nMsgSize   : number ): boolean;

Return value

  • true if the response was successfully received and the server confirmed with "+OK"

  • false otherwise

Parameter | Description
hPop | Handle to a Web connection that was created by WebPopConnect
nMsgNumber | Parameter that receives the total number of messages available in the mailbox
nMsgSize | Parameter that receives the total size in bytes of available messages in the mailbox

Example

dcltrans
  transaction TWebPop3
  const
    USERNAME := "username";
    PASSWORD := "password";
  var
    hPop, nMessages, nSize: number;
  begin
    WebPopConnect(hPop, "standardhost", WEB_PORT_POP3);
    WebPopUser(hPop, USERNAME);
    WebPopPass(hPop, PASSWORD);
    WebPopStat(hPop, nMessages, nSize);
    WebPopList(hPop, IGNORE);
    WebPopRset(hPop);
    WebPopQuit(hPop);
    WebPopShutdown(hPop);
  end TWebPop3;

Sample scripts

WebMulti01.bdf

SilkEssential sample

eMail.sep

Parent topic: POP3 Functions Reference
Related reference
WebPopConnect Function
WebPopTop Function
WebPopUidl Function
WebPopUser Function
WebPopApop Function
WebPopPass Function


WebPopTop Function

Action

Retrieves from the server the first nLines lines of the mail with number nMsg.

Include file

WebAPI.bdh

Syntax

WebPopTop(in hPop   : number,
          in nMsg   : number,
          in nLines : number): boolean;

Return value

  • true if the response was successfully received and the server confirmed with "+OK"

  • false otherwise

Parameter | Description
hPop | Handle to a Web connection that was created by WebPopConnect
nMsg | Number of the message whose header is to be retrieved
nLines | Maximum size of the header sent by the server
Parent topic: POP3 Functions Reference
Related reference
WebPopConnect Function
WebPopUidl Function
WebPopUser Function
WebPopList Function


WebPopUidl Function

Action

Retrieves from the server a unique message ID string for message nMsg.

Include file

WebAPI.bdh

Syntax

WebPopUidl( in hPop : number,
            in nMsg : number ): boolean;

Return value

  • true if the response was successfully received and the server confirmed with "+OK"

  • false otherwise

Parameter | Description
hPop | Handle to a Web connection that was created by WebPopConnect
nMsg | Number of the message whose ID is to be retrieved
Parent topic: POP3 Functions Reference
Related reference
WebPopConnect Function
WebPopTop Function
WebPopUser Function
WebPopList Function


WebPopUser Function

Action

Sends the mailbox user name to the server.

Include file

WebAPI.bdh

Syntax

WebPopUser( in hPop  : number,
                  in sUser : string ): boolean;

Return value

  • true if the response was successfully received and the server confirmed with "+OK"

  • false otherwise

Parameter | Description
hPop | Handle to a Web connection that was created by WebPopConnect
sUser | User name

Example

dcltrans
  transaction TWebPop3
  const
    USERNAME := "username";
    PASSWORD := "password";
  var
    hPop, nMessages, nSize: number;
  begin
    WebPopConnect(hPop, "standardhost", WEB_PORT_POP3);
    WebPopUser(hPop, USERNAME);
    WebPopPass(hPop, PASSWORD);
    WebPopStat(hPop, nMessages, nSize);
    WebPopList(hPop, IGNORE);
    WebPopRset(hPop);
    WebPopQuit(hPop);
    WebPopShutdown(hPop);
  end TWebPop3;

Sample scripts

WebMulti01.bdf

SilkEssential sample

eMail.sep

Parent topic: POP3 Functions Reference
Related reference
WebPopConnect Function
WebPopTop Function
WebPopUidl Function
WebPopApop Function
WebPopPass Function
WebPopStat Function


Radius Functions Reference

Silk Performer offers a RADIUS client API that enables simulation of user authentication, authorization, and accounting in various scenarios. Typically the RADIUS protocol is used by ISPs and enterprises to manage access to the Internet or internal networks, wireless networks, and integrated e-mail services. In particular, a Remote Access Server, a Virtual Private Network server, a Network switch with port-based authentication, and a Network Access Server (NAS), are all gateways that control access to the network and all have a RADIUS client component that communicates with the RADIUS server.

Silk Performer's RADIUS API uses the Java Framework, and therefore requires that a Java Runtime Environment (JRE) be installed. To access Radius functions you must include the header file Radius.bdh in your scripts.

RADIUS functions include:

  • RadInit Function
    Initializes Java Framework and the Radius classes.
  • RadExit Function
    Frees all memory and uninitializes the Java Framework.
  • RadAuthenticate Function
    Attempts to authenticate the RADIUS server by transmitting a list of attributes (previously set using RadSetAttribute...() functions) to the server and retrieving a list of attributes from the server.
  • RadAccounting Function
    Sends accounting information to the RADIUS accounting server.
  • RadSetAttributeBinary Function
    Sets a binary attribute in the list of attributes that is sent to the RADIUS server during authentication.
  • RadSetAttributeNumber Function
    Sets a numeric attribute in the list of attributes that is sent to the RADIUS server during authentication.
  • RadGetAttributeNumber Function
    Retrieves a numeric attribute value from the list of attributes that is returned from the RADIUS server during authentication.
  • RadSetAttributeString Function
    Sets a string attribute in the list of attributes that is sent to the RADIUS server during authentication.
  • RadGetAttributeString Function
    Retrieves a string attribute value from the list of attributes that's returned by the RADIUS server during authentication.
  • RadClearAttributeList Function
    Clears the list of attributes that's sent to the RADIUS server during authentication.
Parent topic: Internet Functions
Related concepts
Radius


RadInit Function

Action

Initializes Java Framework and the Radius classes.

Include file

radius.bdh

Syntax

RadInit( in sServer   : string,
         in nAuthPort : number,
         in nAcctPort : number,
         in sSecret   : string,
         in nTimeout  : number optional): boolean;

Return value

  • true if successful

  • false otherwise

Parameter | Description
sServerl | Name or IP address of the RADIUS server
nAuthPort | UDP port where RADIUS authentication service is listening
nAcctPort | UDP port where RADIUS accounting service is listening
sSecret | Secret is used to access RADIUS service
nTimeout | Optional timeout value in milliseconds after communication is canceled

Example

dcltrans
  transaction TInit
  begin
    RadInit("radserver", 1812, 1813, "secret");
  end TInit;
Parent topic: Radius Functions Reference


RadExit Function

Action

Frees all memory and uninitializes the Java Framework.

Include file

radius.bdh

Syntax

RadExit( ): boolean;

Return value

  • true if successful

  • false otherwise

Example

dcltrans
  transaction TEnd
  begin
    RadExit();
  end TEnd;
Parent topic: Radius Functions Reference


RadAuthenticate Function

Action

Attempts to authenticate the RADIUS server by transmitting a list of attributes (previously set using RadSetAttribute...() functions) to the server and retrieving a list of attributes from the server. Returned attributes are accessed using RadGetAttribute...() functions.

Include file

radius.bdh

Syntax

RadAuthenticate( in sType  : string,
                 in sLogin : string,
                 in sPass  : string ): number;

Return value

  • RAD_AccessAccept if authentication is successful

  • RAD_AccessReject if authentication fails

Parameter | Description
sType

Authentication type. Valid options include:

  • RAD_AUTH_PAP

  • RAD_AUTH_CHAP

  • RAD_AUTH_MSCHAP

  • RAD_AUTH_MSCHAP2

  • RAD_AUTH_EAPMD5
sLogin | Login name.
sPass | Pass phrase valid for the login name.

Example

dcltrans
  transaction TRun
  var
    nCode : number;
  begin
    RadSetAttributeNumber(RAD_NasPort, 1234);
    RadSetAttributeString(RAD_CallingStationId, "+1 1234 123 1234");
    nCode := RadAuthenticate(RAD_AUTH_MSCHAP2, "user", "pass");
    if nCode = RAD_AccessAccept then
      Print("Authentication successful");
      Print("Service Type = " + string(RadGetAttributeNumber(RAD_ServiceType)));
      Print("Framed_Protocol = " +string(RadGetAttributeNumber(RAD_FramedProtocol)));
      Print("Login_IP_Host = " + RadGetAttributeString(RAD_LoginIpHost));
      Print("Login_TCP_Port = " +string(RadGetAttributeNumber(RAD_LoginTcpPort)));
      Print("Reply_Message = " + RadGetAttributeString(RAD_ReplyMessage));
    else
      Print("Authentication failed");
    end;
  end TRun;
Parent topic: Radius Functions Reference


RadAccounting Function

Action

Sends accounting information to the RADIUS accounting server. Accounting information is comprised of a list of attributes (previously set using RadSetAttribute...() functions) that are sent to the server. A list of attributes is also retrieved from the server. Returned attributes are accessed using RadGetAttribute...() functions.

Include file

radius.bdh

Syntax

RadAccounting( ): number;

Return value

  • RAD_AccountingResponse

Example

dcltrans
  transaction TRun
  var
    nCode : number;
  begin
    RadSetAttributeString(RAD_NasIpAddress, "123.123.123.123");
    RadSetAttributeString(RAD_CallingStationId, "+1 1234 123 1234");
    RadSetAttributeNumber(RAD_AcctStatusType, ACCT_STATUS_START);
    nCode := RadAccounting();
  end TRun;
Parent topic: Radius Functions Reference


RadSetAttributeBinary Function

Action

Sets a binary attribute in the list of attributes that is sent to the RADIUS server during authentication.

Include file

radius.bdh

Syntax

RadSetAttributeBinary( in nAttributeId    : number
                       in sAttributeValue : string,
                       in nLen            : number optional );
Parameter | Description
nAttributeId | Attribute identification. Any attribute value can be set as a binary data, although it is more comfortable to set them using the related typed function.
sAttributeValue | Binary value of the attribute to be set.
nLen | Number of character to be set (optional).

Example

dcltrans
  transaction TRun
  var
    nCode : number;
  begin
    RadSetAttributeNumber(RAD_NasPort, 1234);
    RadSetAttributeString(RAD_CallingStationId, "+1 1234 123 1234");
    RadSetAttributeBinary(RAD_VendorSpecific, "\h000001370b0a153ea6378f1b7012");
    nCode := RadAuthenticate(RAD_AUTH_MSCHAP2, "user", "pass");
    if nCode = RAD_AccessAccept then
      Print("Authentication successful");
      Print("Service Type = " + string(RadGetAttributeNumber(RAD_ServiceType)));
      Print("Framed_Protocol = " + string(RadGetAttributeNumber(RAD_FramedProtocol)));
      Print("Login_IP_Host = " + RadGetAttributeString(RAD_LoginIpHost));
      Print("Login_TCP_Port = " + string(RadGetAttributeNumber(RAD_LoginTcpPort)));
      Print("Reply_Message = " + RadGetAttributeString(RAD_ReplyMessage));
    else
      Print("Authentication failed");
    end;
  end TRun;
Parent topic: Radius Functions Reference


RadSetAttributeNumber Function

Action

Sets a numeric attribute in the list of attributes that is sent to the RADIUS server during authentication.

Include file

radius.bdh

Syntax

RadSetAttributeNumber( in nAttributeId    : number,
                       in nAttributeValue : number );
Parameter | Description
nAttributeId

Attribute identification. Valid values are:

  • RAD_NasPort

  • RAD_ServiceType

  • RAD_FramedProtocol

  • RAD_FramedCompression

  • RAD_NasPortType

  • RAD_PortLimit

  • RAD_AcctStatusType

  • RAD_AcctDelayTime

  • RAD_AcctInputOctets

  • RAD_AcctOutputOctets

  • RAD_AcctAuthentic

  • RAD_AcctSessionTime

  • RAD_AcctInputPackets

  • RAD_AcctOutputPackets

  • RAD_AcctTerminateCause

  • RAD_AcctLinkCount
nAttributeValue | Numeric value of the attribute to set.

Example

dcltrans
  transaction TRun
  var
    nCode : number;
  begin
    RadSetAttributeNumber(RAD_NasPort, 1234);
    RadSetAttributeString(RAD_CallingStationId, "+1 1234 123 1234");
    nCode := RadAuthenticate(RAD_AUTH_MSCHAP2, "user", "pass");
    if nCode = RAD_AccessAccept then
      Print("Authentication successful");
      Print("Service Type = " + string(RadGetAttributeNumber(RAD_ServiceType)));
      Print("Framed_Protocol = " + string(RadGetAttributeNumber(RAD_FramedProtocol)));
      Print("Login_IP_Host = " + RadGetAttributeString(RAD_LoginIpHost));
      Print("Login_TCP_Port = " + string(RadGetAttributeNumber(RAD_LoginTcpPort)));
      Print("Reply_Message = " + RadGetAttributeString(RAD_ReplyMessage));
    else
      Print("Authentication failed");
    end;
  end TRun;
Parent topic: Radius Functions Reference
Related reference
RadGetAttributeNumber Function


RadGetAttributeNumber Function

Action

Retrieves a numeric attribute value from the list of attributes that is returned from the RADIUS server during authentication.

Include file

radius.bdh

Syntax

RadGetAttributeNumber( in nAttributeId  : number ) : number;

Return value

  • Numeric value of the attribute.

Parameter Description
nAttributeId

Attribute identification. Valid values are:

  • RAD_ServiceType

  • RAD_FramedProtocol

  • RAD_LoginTcpPort

  • RAD_FramedRouting

  • RAD_FramedMtu

  • RAD_FramedCompression

  • RAD_LoginService

  • RAD_FramedIpxNetwork

  • RAD_SessionTimeout

  • RAD_IdleTimeout

  • RAD_TerminationAction

  • RAD_FramedAppleTalkLink

  • RAD_FramedAppleTalkNetwork

  • RAD_PortLimit

Example

dcltrans
  transaction TRun
  var
    nCode : number;
  begin
    RadSetAttributeNumber(RAD_NasPort, 1234);
    RadSetAttributeString(RAD_CallingStationId, "+1 1234 123 1234");
    nCode := RadAuthenticate(RAD_AUTH_MSCHAP2, "user", "pass");
    if nCode = RAD_AccessAccept then
      Print("Authentication successful");
      Print("Service Type = " + string(RadGetAttributeNumber(RAD_ServiceType)));
      Print("Framed_Protocol = " + string(RadGetAttributeNumber(RAD_FramedProtocol)));
      Print("Login_IP_Host = " + RadGetAttributeString(RAD_LoginIpHost));
      Print("Login_TCP_Port = " + string(RadGetAttributeNumber(RAD_LoginTcpPort)));
      Print("Reply_Message = " + RadGetAttributeString(RAD_ReplyMessage));
    else
      Print("Authentication failed");
    end;
  end TRun;
Parent topic: Radius Functions Reference
Related reference
RadSetAttributeNumber Function


RadSetAttributeString Function

Action

Sets a string attribute in the list of attributes that is sent to the RADIUS server during authentication.

Include file

radius.bdh

Syntax

RadSetAttributeString( in nAttributeId    : number,
                       in sAttributeValue : string );
Parameter | Description
nAttributeId

Attribute identification. Valid values are:

  • RAD_UserName

  • RAD_UserPassword

  • RAD_ChapPassword

  • RAD_CallbackNumber

  • RAD_State

  • RAD_Class

  • RAD_CalledStationId

  • RAD_CallingStationId

  • RAD_NasIdentifier

  • RAD_ProxyState

  • RAD_LoginLatService

  • RAD_LoginLatNode

  • RAD_LoginLatGroup

  • RAD_ChapChallenge

  • RAD_LoginLatPort

  • RAD_AcctSessionId

  • RAD_AcctMultiSessionId

  • RAD_NasIPAddress

  • RAD_FramedIpAddress

  • RAD_FramedIpNetmask

  • RAD_LoginIpHost
sAttributeValue | String value of the attribute to be set.

Example

dcltrans
  transaction TRun
  var
    nCode : number;
  begin
    RadSetAttributeNumber(RAD_NasPort, 1234);
    RadSetAttributeString(RAD_CallingStationId, "+1 1234 123 1234");
    nCode := RadAuthenticate(RAD_AUTH_MSCHAP2, "user", "pass");
    if nCode = RAD_AccessAccept then
      Print("Authentication successful");
      Print("Service Type = " + string(RadGetAttributeNumber(RAD_ServiceType)));
      Print("Framed_Protocol = " + string(RadGetAttributeNumber(RAD_FramedProtocol)));
      Print("Login_IP_Host = " + RadGetAttributeString(RAD_LoginIpHost));
      Print("Login_TCP_Port = " + string(RadGetAttributeNumber(RAD_LoginTcpPort)));
      Print("Reply_Message = " + RadGetAttributeString(RAD_ReplyMessage));
    else
      Print("Authentication failed");
    end;
  end TRun;
Parent topic: Radius Functions Reference
Related reference
RadGetAttributeString Function


RadGetAttributeString Function

Action

Retrieves a string attribute value from the list of attributes that's returned by the RADIUS server during authentication.

Include file

radius.bdh

Syntax

RadGetAttributeString( in nAttributeId  : number ): string;

Return value

  • String value of the attribute

Parameter Description
nAttributeId

Attribute identification. Valid values are:

  • RAD_LoginIpHost

  • RAD_FilterId

  • RAD_ReplyMessage

  • RAD_CallbackNumber

  • RAD_CallbackId

  • RAD_FramedRoute

  • RAD_State

  • RAD_Class

  • RAD_ProxyState

  • RAD_LoginLatService

  • RAD_LoginLatNode

  • RAD_LoginLatGroup

  • RAD_FramedAppleTalkZone

  • RAD_LoginLatPort

Example

dcltrans
  transaction TRun
  var
    nCode : number;
  begin
    RadSetAttributeNumber(RAD_NasPort, 1234);
    RadSetAttributeString(RAD_CallingStationId, "+1 1234 123 1234");
    nCode := RadAuthenticate(RAD_AUTH_MSCHAP2, "user", "pass");
    if nCode = RAD_AccessAccept then
      Print("Authentication successful");
      Print("Service Type = " + string(RadGetAttributeNumber(RAD_ServiceType)));
      Print("Framed_Protocol = " + string(RadGetAttributeNumber(RAD_FramedProtocol)));
      Print("Login_IP_Host = " + RadGetAttributeString(RAD_LoginIpHost));
      Print("Login_TCP_Port = " + string(RadGetAttributeNumber(RAD_LoginTcpPort)));
      Print("Reply_Message = " + RadGetAttributeString(RAD_ReplyMessage));
    else
      Print("Authentication failed");
    end;
  end TRun;
Parent topic: Radius Functions Reference
Related reference
RadSetAttributeString Function


RadClearAttributeList Function

Action

Clears the list of attributes that's sent to the RADIUS server during authentication.

Include file

radius.bdh

Syntax

RadClearAttributeList( );

Example

dcltrans
  transaction TRun
    begin
      RadSetAttributeNumber(RAD_NasPort, 1234);
      RadSetAttributeString(RAD_CallingStationId, "+1 1234 123 1234");
      RadAuthenticate(RAD_AUTH_MSCHAP2, "user", "pass");
      RadClearAttributeList();
    end TRun;
Parent topic: Radius Functions Reference


SMTP Functions Reference

The WebSMTP functions are a complete implementation of the Simple Mail Transfer Protocol.

Note: All host and e-mail addresses used for electronic processing have to be enclosed in angular brackets (< and >), for example, "John Jones <john.jones@company.com>".
  • WebSmtpCommand Function
    Sends a command string to an SMTP server.
  • WebSmtpConnect Function
    Connects to an SMTP server.
  • WebSmtpData Function
    Sends the mail message using a user-defined mail header.
  • WebSmtpDataEx Function
    Sends the mail message using a standard mail header with the most important arguments: sender, recipient, subject.
  • WebSmtpExpand Function
    Asks the mail server to confirm that the argument identifies a mailing list.
  • WebSmtpHello Function
    Sends a HELO command to the server.
  • WebSmtpHelloEx Function
    Sends an EHLO command to the server.
  • WebSmtpHelp Function
    Asks the server to respond with a help message.
  • WebSmtpMail Function
    Initiates a mail transaction.
  • WebSmtpNoop Function
    Used to determine whether the server is available.
  • WebSmtpQuit Function
    Commits the mail transaction.
  • WebSmtpRecipient Function
    Sets the recipient’s address.
  • WebSmtpReset Function
    Resets the mail servers state.
  • WebSmtpResponse Function
    Retrieves an SMTP response message after sending a command using WebTcpipSend.
  • WebSmtpSend Function
    Initiates a mail transaction.
  • WebSmtpSendAndMail Function
    Initiates a mail transaction.
  • WebSmtpSendOrMail Function
    Initiates a mail transaction.
  • WebSmtpSendData Function
    Sends a data string to an SMTP server.
  • WebSmtpShutdown Function
    Closes the connection to the mail server.
  • WebSmtpTurn Function
    Lets the recipient reply with an OK message.
  • WebSmtpVerify Function
    Asks the mail server to confirm that the argument identifies a user.
Parent topic: Internet Functions


WebSmtpCommand Function

Action

Sends a command string to an SMTP server.

Include file

WebAPI.bdh

Syntax

WebSmtpCommand( in hSmtp    : number,
                in sCommand : string ): boolean;

Return value

  • true if successful

  • false otherwise

Parameter | Description
hSmtp | Handle to a Web connection that was created by WebSmtpConnect
sCommand | Command string

Example

dcltrans
  transaction TWebSmtpCommand
  const
    COMMAND := "...\r\n"; // specify command string
  var
   hSmtp: number;
  begin
   WebSmtpConnect(hSmtp, "standardhost", WEB_PORT_SMTP);
   WebSmtpHello(hSmtp, "<MyDomain>");
   WebSmtpReset(hSmtp);   WebSmtpCommand(hSmtp, COMMAND);
   WebSmtpQuit(hSmtp);
   WebSmtpShutdown(hSmtp);
 end TWebSmtpCommand;
Parent topic: SMTP Functions Reference
Related concepts
Web Functions Reference
Related reference
WebSmtpConnect Function


WebSmtpConnect Function

Action

Connects to an SMTP server.

Include file

WebAPI.bdh

Syntax

WebSmtpConnect( out hSmtp     : number,
                in  sHost     : string,
                in  nPort     : number,
                in  nSecurity : number optional ): boolean;

Return value

  • true if the connection could be established and the server sent a response message

  • false otherwise

Parameter | Description
hSmtp

Variable receiving a handle to the Web connection

If this parameter contains a handle to a Web connection prior to the WebSmtpConnect function call, the memory allocated with the handle is released. Whenever you want to create a new Web connection, make sure this variable is initialized with 0 (this is automatically done within transactions when they are executed for the first time, but not within functions)
sHost | Address of the SMTP server
nPort | Port to connect at the SMTP server. The standard port is WEB_PORT_SMTP (25)
nSecurity

Specifies whether to establish a secure connection to the remote server (optional). Possible options are:

  • WEB_CONNECT_NONE. Establishes an insecure connection to the server (default)

  • WEB_CONNECT_SSL. Establishes a secure connection using SSL

Example

dcltrans
  transaction TWebSmtp
  var
    hSmtp: number;
  begin
    WebSmtpConnect(hSmtp, "standardhost", WEB_PORT_SMTP);
    WebSmtpHello(hSmtp, "<MyDomain>");
    WebSmtpQuit(hSmtp);
    WebSmtpShutdown(hSmtp);
  end TWebSmtp;

Sample scripts

WebMulti01.bdf

SilkEssential sample

eMail.sep

Parent topic: SMTP Functions Reference
Related reference
WebSmtpShutdown Function


WebSmtpData Function

Action

Sends the mail message using a user-defined mail header. The mail body is generated randomly using ASCII 128 characters.

Include file

WebAPI.bdh

Syntax

WebSmtpData(in hSmtp         : number,
            in sMailHeader   : string,
            in nMailBodySize : number): boolean;

Return value

  • true if the server responded with a positive return code

  • false otherwise

Parameter | Description
hSmtp | Handle to a Web connection that was created by WebSmtpConnect
sMailHeader | A CRLF-terminated string defining sender, recipient, subject and more. Sample: "To: <jim@mailprovider.com>\r\nFrom: tom<tom@mailprovider.com>"
nMailBodySize | Specifies the number of characters randomly generated
Parent topic: SMTP Functions Reference
Related concepts
Web Functions Reference
Related reference
WebSmtpConnect Function


WebSmtpDataEx Function

Action

Sends the mail message using a standard mail header with the most important arguments: sender, recipient, subject.

Include file

WebAPI.bdh

Syntax

WebSmtpDataEx( in hSmtp    : number,
               in sTo      : string,
               in sFrom    : string,
               in sSubject : string,
               in sBody    : string ): boolean;

Return value

  • true if the server responded with a positive return code

  • false otherwise

Parameter | Description
hSmtp | Handle to a Web connection that was created by WebSmtpConnect
sTo | Recipient’s e-mail address. Sample: "Jim Jason<jim@mailprovider.com>"
sFrom | Sender’s e-mail address
sSubject | Subject of the e-mail
sBody | The custom mail body
Note: Only 7-bit text data or MIME-encoded binaries in ASCII 128 format can be used as message body.

Example

dcltrans
  transaction TWebSmtp
  var
    hSmtp: number;
  begin
    WebSmtpConnect(hSmtp, "standardhost", WEB_PORT_SMTP);
    WebSmtpHello(hSmtp, "<MyDomain>");
    WebSmtpMail(hSmtp, "<john@mail.com>");
    WebSmtpRecipient(hSmtp, "<admin@mail.com>");
    WebSmtpDataEx(hSmtp,"admin<admin@mail.com>",
                       "SenderName", "ThisIsTheSubject",
                       "This is a testmessage");
    WebSmtpQuit(hSmtp);    WebSmtpShutdown(hSmtp);
  end TWebSmtp;

SilkEssential sample

eMail.sep

Parent topic: SMTP Functions Reference
Related concepts
Web Functions Reference
Related reference
WebSmtpConnect Function
WebSmtpSendData Function


WebSmtpExpand Function

Action

Asks the mail server to confirm that the argument identifies a mailing list.

Include file

WebAPI.bdh

Syntax

WebSmtpExpand( in hSmtp : number,
               in sUser : string ): boolean;

Return value

  • true if the server responded with a positive return code

  • false otherwise

Parameter | Description
hSmtp | Handle to a Web connection that was created by WebSmtpConnect
sUser | Mailing list to be confirmed. Sample: "support_list"
Parent topic: SMTP Functions Reference
Related concepts
Web Functions Reference
Related reference
WebSmtpVerify Function
WebSmtpConnect Function


WebSmtpHello Function

Action

Sends a HELO command to the server.

Include file

WebAPI.bdh

Syntax

WebSmtpHello( in hSmtp   : number,
              in sDomain : string ): boolean;

Return value

  • true if the server responded with a positive return code

  • false otherwise

Parameter | Description
hSmtp | Handle to a Web connection that was created by WebSmtpConnect
sDomain | Host name of the SMTP sender

Example

dcltrans
  transaction TWebSmtp
  var
    hSmtp: number;
  begin
    WebSmtpConnect(hSmtp, "standardhost", WEB_PORT_SMTP);
    WebSmtpHello(hSmtp, "<MyDomain>");
    WebSmtpQuit(hSmtp);
    WebSmtpShutdown(hSmtp);
  end TWebSmtp;

Sample scripts

WebMulti01.bdf

SilkEssential sample

eMail.sep

Parent topic: SMTP Functions Reference
Related concepts
Web Functions Reference
Related reference
WebSmtpConnect Function
WebSmtpHelloEx Function


WebSmtpHelloEx Function

Action

Sends an EHLO command to the server.

Note: WebSmtpHelloEx can be used to determine the server’s capabilities. If the function fails, use WebSmtpHello
.

Include file

WebAPI.bdh

Syntax

WebSmtpHelloEx( in hSmtp   : number,
                in sDomain : string ): boolean;

Return value

  • true if the server responded with a positive return code

  • false otherwise

Parameter | Description
hSmtp | Handle to a Web connection that was created by WebSmtpConnect
sDomain | Host name of the SMTP sender, for example, <myhostname.mailprovider.com>

Example

dcltrans
  transaction TWebSmtp
  var
    hSmtp: number;
  begin
    WebSmtpConnect(hSmtp, "standardhost", WEB_PORT_SMTP);
     if not WebSmtpHelloEx(hSmtp, "MyDomain") then
      WebSmtpHello(hSmtp, "MyDomain");
    end;
    WebSmtpQuit(hSmtp);
    WebSmtpShutdown(hSmtp);
  end TWebSmtp;

SilkEssential sample

eMail.sep

Parent topic: SMTP Functions Reference
Related concepts
Web Functions Reference
Related reference
WebSmtpConnect Function
WebSmtpHello Function


WebSmtpHelp Function

Action

Asks the server to respond with a help message.

Include file

WebAPI.bdh

Syntax

WebSmtpHelp( in hSmtp : number,
             in sHelp : string optional ): boolean;

Return value

  • true if the server responded with a positive return code

  • false otherwise

Parameter | Description
hSmtp | Handle to a Web connection that was created by WebSmtpConnect
sHelp | Optional command to ask for help. Sample: "HELLO"

Example

dcltrans
  transaction TWebSmtp
  var
    hSmtp: number;
  begin
    WebSmtpConnect(hSmtp, "standardhost", WEB_PORT_SMTP);
    WebSmtpHello(hSmtp, "<MyDomain>");
    WebSmtpHelp(hSmtp, "");
    WebSmtpQuit(hSmtp);
    WebSmtpShutdown(hSmtp);
  end TWebSmtp;

Sample scripts

WebMulti01.bdf

SilkEssential sample

eMail.sep

Parent topic: SMTP Functions Reference


WebSmtpMail Function

Action

Initiates a mail transaction.

Include file

WebAPI.bdh

Syntax

WebSmtpMail( in hSmtp        : number,
             in sReversePath : string ): boolean;

Return value

  • true if the server responded with a positive return code

  • false otherwise

Parameter | Description
hSmtp | Handle to a Web connection that was created by WebSmtpConnect
sReversePath | E-mail address the reply should be sent to. Sample: "<returnaddress@mailprovider.com>"

Example

dcltrans
transaction TWebSmtp
var
    hSmtp: number;
  begin
    WebSmtpConnect(hSmtp, "standardhost", WEB_PORT_SMTP);
    WebSmtpHello(hSmtp, "<MyDomain>");
    WebSmtpMail(hSmtp, "<john@mail.com>");
    WebSmtpQuit(hSmtp);
    WebSmtpShutdown(hSmtp);
  end TWebSmtp;

Sample scripts

WebMulti01.bdf

SilkEssential sample

eMail.sep

Parent topic: SMTP Functions Reference
Related concepts
Web Functions Reference
Related reference
WebSmtpConnect Function
WebSmtpTurn Function
WebSmtpResponse Function
WebSmtpSendAndMail Function
WebSmtpSend Function
WebSmtpSendOrMail Function
WebSmtpRecipient Function


WebSmtpNoop Function

Action

This command is used to determine whether the server is available. No operation is performed at the mail server.

Include file

WebAPI.bdh

Syntax

WebSmtpNoop(in hSmtp: number): boolean;

Return value

  • true if the server responded with a positive return code

  • false otherwise

Parameter | Description
hSmtp | Handle to a Web connection that was created by WebSmtpConnect
Parent topic: SMTP Functions Reference
Related concepts
Web Functions Reference
Related reference
WebSmtpConnect Function


WebSmtpQuit Function

Action

Commits the mail transaction. All previous commands actually affect only the server’s mail database.

Include file

WebAPI.bdh

Syntax

WebSmtpQuit( in hSmtp: number ): boolean;

Return value

  • true if the server responded with a positive return code

  • false otherwise

Parameter | Description
hSmtp | Handle to a Web connection that was created by WebSmtpConnect

Example

dcltrans
  transaction TWebSmtp
  var
    hSmtp: number;
  begin
    WebSmtpConnect(hSmtp, "standardhost", WEB_PORT_SMTP);
    WebSmtpHello(hSmtp, "<MyDomain>");
    WebSmtpQuit(hSmtp);
    WebSmtpShutdown(hSmtp);
  end TWebSmtp;

Sample scripts

WebMulti01.bdf

SilkEssential sample

eMail.sep

Parent topic: SMTP Functions Reference
Related concepts
Web Functions Reference
Related reference
WebSmtpConnect Function
WebSmtpReset Function


WebSmtpRecipient Function

Action

Sets the recipient’s address. Multiple recipients can be specified by repeated use of this command.

Include file

WebAPI.bdh

Syntax

WebSmtpRecipient( in hSmtp      : number,
                  in sRecipient : string ): boolean;

Return value

  • true if the server responded with a positive return code

  • false otherwise

Parameter | Description
hSmtp | Handle to a Web connection that was created by WebSmtpConnect
sRecipient | One or more recipients’ e-mail addresses. Sample: "john<john@mailprovider.com>"

Example

dcltrans
  transaction TWebSmtp
  var
    hSmtp: number;
  begin
    WebSmtpConnect(hSmtp, "standardhost", WEB_PORT_SMTP);
    WebSmtpHello(hSmtp, "<MyDomain>");
    WebSmtpRecipient(hSmtp, "<administrator@mail.com>");
    WebSmtpQuit(hSmtp);
    WebSmtpShutdown(hSmtp);
  end TWebSmtp;

Sample scripts

WebMulti01.bdf

SilkEssential sample

eMail.sep

Parent topic: SMTP Functions Reference
Related concepts
Web Functions Reference
Related reference
WebSmtpConnect Function
WebSmtpTurn Function
WebSmtpResponse Function
WebSmtpSendAndMail Function
WebSmtpSend Function
WebSmtpSendOrMail Function
WebSmtpMail Function


WebSmtpReset Function

Action

Resets the mail servers state. The server rolls back (undoes) all previous actions performed during the SMTP session.

Include file

WebAPI.bdh

Syntax

WebSmtpReset( in hSmtp: number ): boolean;

Return value

  • true if the server responded with a positive return code

  • false otherwise

Parameter | Description
hSmtp | Handle to a Web connection that was created by WebSmtpConnect

Example

dcltrans
  transaction TWebSmtp
  var
    hSmtp: number;
  begin
    WebSmtpConnect(hSmtp, "standardhost", WEB_PORT_SMTP);
    WebSmtpHello(hSmtp, "<MyDomain>");
    WebSmtpReset(hSmtp);
    WebSmtpQuit(hSmtp);    WebSmtpShutdown(hSmtp);
  end TWebSmtp;

Sample scripts

WebMulti01.bdf

SilkEssential sample

eMail.sep

Parent topic: SMTP Functions Reference
Related concepts
Web Functions Reference
Related reference
WebSmtpConnect Function
WebSmtpQuit Function


WebSmtpResponse Function

Action

Retrieves an SMTP response message after sending a command using WebTcpipSend.

Include file

WebAPI.bdh

Syntax

WebSmtpResponse( in  hSmtp        : number,
                 out sResponse    : string,
                 in  nMaxResponse : number,
                 out nReplyCode   : number): boolean;

Return value

  • true if the server responded with a positive return code

  • false otherwise

Parameter | Description
hSmtp | Handle to a Web connection that was created by WebSmtpConnect
sResponse | Buffer that receives the mail server’s response message
nMaxResponse | Size of the response buffer. Specify STRING_COMPLETE to get all received data.
nReplyCode | Parameter that receives the mail server’s reply code
Parent topic: SMTP Functions Reference
Related concepts
Web Functions Reference
Related reference
WebSmtpConnect Function
WebSmtpTurn Function
WebSmtpSendAndMail Function
WebSmtpSend Function
WebSmtpSendOrMail Function
WebSmtpMail Function
WebSmtpRecipient Function


WebSmtpSend Function

Action

Initiates a mail transaction.

Include file

WebAPI.bdh

Syntax

WebSmtpSend( in hSmtp        : number,
             in sReversePath : string ): boolean;

Return value

  • true if the server responded with a positive return code

  • false otherwise

Parameter | Description
hSmtp | Handle to a Web connection that was created by WebSmtpConnect
sReversePath | E-mail address the reply should be sent to. Sample: "<returnaddress@mailprovider.com>"
Parent topic: SMTP Functions Reference
Related concepts
Web Functions Reference
Related reference
WebSmtpConnect Function
WebSmtpTurn Function
WebSmtpResponse Function
WebSmtpSendAndMail Function
WebSmtpSendOrMail Function
WebSmtpMail Function
WebSmtpRecipient Function


WebSmtpSendAndMail Function

Action

Initiates a mail transaction.

Include file

WebAPI.bdh

Syntax

WebSmtpSendAndMail(in hSmtp        : number,
                   in sReversePath : string): boolean;

Return value

  • true if the server responded with a positive return code

  • false otherwise

Parameter | Description
hSmtp | Handle to a Web connection that was created by WebSmtpConnect
sReversePath | E-mail address the reply should be sent to. Sample: "<returnaddress@mailprovider.com>"
Parent topic: SMTP Functions Reference
Related concepts
Web Functions Reference
Related reference
WebSmtpConnect Function
WebSmtpTurn Function
WebSmtpResponse Function
WebSmtpSend Function
WebSmtpSendOrMail Function
WebSmtpMail Function
WebSmtpRecipient Function


WebSmtpSendOrMail Function

Action

Initiates a mail transaction.

Include file

WebAPI.bdh

Syntax

WebSmtpSendOrMail(in hSmtp        : number,
                  in sReversePath : string): boolean;

Return value

  • true if the server responded with a positive return code

  • false otherwise

Parameter | Description
hSmtp | Handle to a Web connection that was created by WebSmtpConnect
sReversePath | E-mail address the reply should be sent to. Sample: "<returnaddress@mailprovider.com>"
Parent topic: SMTP Functions Reference
Related concepts
Web Functions Reference
Related reference
WebSmtpConnect Function
WebSmtpTurn Function
WebSmtpResponse Function
WebSmtpSendAndMail Function
WebSmtpSend Function
WebSmtpMail Function
WebSmtpRecipient Function


WebSmtpSendData Function

Action

Sends a data string to an SMTP server.

Include file

WebAPI.bdh

Syntax

WebSmtpSendData( in hSmtp : number,
                 in sData : string ): boolean;

Return value

  • true if successful

  • false otherwise

Parameter | Description
hSmtp | Handle to a Web connection that was created by WebSmtpConnect
sData | Data string

Example

dcltrans
transaction TWebSmtpSendData
  const
    DATA := "...\r\n"; // specify data string
  var
    hSmtp: number;
  begin
    WebSmtpConnect(hSmtp, "standardhost", WEB_PORT_SMTP);
    WebSmtpHello(hSmtp, "<MyDomain>");
    WebSmtpReset(hSmtp);    WebSmtpSendData(hSmtp, DATA);
    WebSmtpQuit(hSmtp);    WebSmtpShutdown(hSmtp);
  end TWebSmtpSendData;

SilkEssential sample

eMail.sep

Parent topic: SMTP Functions Reference
Related concepts
Web Functions Reference
Related reference
WebSmtpConnect Function
WebSmtpDataEx Function


WebSmtpShutdown Function

Action

Closes the connection to the mail server.

Include file

WebAPI.bdh

Syntax

WebSmtpShutdown( inout hSmtp : number,
                 in    nMode : number optional): boolean;

Return value

  • true if the connection could be closed successfully

  • false otherwise

Parameter | Description
hSmtp | Handle to a Web connection that was created by WebSmtpConnect
nMode

Determines the shutdown mode (optional). Any of the following options is possible:

  • WEB_SHUTDOWN_GRACEFUL. Initiates a graceful shutdown: first closes and then resets the connection

  • WEB_SHUTDOWN_IMMEDIATE. Initiates a standard connection close (default)

  • WEB_SHUTDOWN_RESET. Resets the connection

Example

dcltrans
  transaction TWebSmtp
  var
   hSmtp: number;
  begin
    WebSmtpConnect(hSmtp, "standardhost", WEB_PORT_SMTP);
    WebSmtpHello(hSmtp, "<MyDomain>");
    WebSmtpQuit(hSmtp);
    WebSmtpShutdown(hSmtp);
  end TWebSmtp;

Sample scripts

WebMulti01.bdf

SilkEssential sample

eMail.sep

Parent topic: SMTP Functions Reference
Related concepts
Web Functions Reference
Related reference
WebSmtpConnect Function


WebSmtpTurn Function

Action

Lets the recipient reply with an OK message.

Include file

WebAPI.bdh

Syntax

WebSmtpTurn(in hSmtp: number): boolean;

Return value

  • true if the server responded with a positive return code

  • false otherwise

Parameter | Description
hSmtp | Handle to a Web connection that was created by WebSmtpConnect
Parent topic: SMTP Functions Reference
Related concepts
Web Functions Reference
Related reference
WebSmtpConnect Function
WebSmtpResponse Function
WebSmtpSendAndMail Function
WebSmtpSend Function
WebSmtpSendOrMail Function
WebSmtpMail Function
WebSmtpRecipient Function


WebSmtpVerify Function

Action

Asks the mail server to confirm that the argument identifies a user.

Include file

WebAPI.bdh

Syntax

WebSmtpVerify( in hSmtp : number,
               in sUser : string ): boolean;

Return value

  • true if the server responded with a positive return code

  • false otherwise

Parameter | Description
hSmtp | Handle to a Web connection that was created by WebSmtpConnect
sUser | Address to be confirmed. Sample: "<invalid@mailprovider.com>"
Parent topic: SMTP Functions Reference
Related concepts
Web Functions Reference
Related reference
WebSmtpExpand Function
WebSmtpConnect Function


SSL (Secure Socket Layer) Extensions

There are several Silk Performer configuration options for replaying scripts in a secure environment. These include the following:

  • Replaying scripts using SSL

  • Replaying scripts using client certificates

Example

use "WebAPI.bdh"

const
  USERS := 5;

 dcluser
  user
    WebUser(USERS)
  transactions
    TWeb : 1;

dcltrans
  transaction TWeb
  var
    sClientCert: string(1000);
  begin
    WebParseResponseData(sClientCert, 1000, "<BR>SUBJECTCN:", "<BR>");
    WebUrl("https://bowie/clientcert.asp", 0.0);
    WebThreadWait();

    if strlen(sClientCert) > 0 then
      write("The server got a client certificate from: ");
      write(sClientCert); writeln;
    else
      write("Error using client certificate number :");
      write(GetRuntimeID()); writeln;
    end;

     Print(sClientCert, 1, TEXT_MAGENTA);
  end TWeb;
  • SslSetClientCert Function
    Sets the client certificate that Silk Performer presents the secure server in behalf on the real client's certificate.
  • SslSetClientCertPassword Function
    Sets the password for the client certificate.
  • SslSetEncryption Function
    Sets the Secure Socket Layer protocol version and the ciphers used when Silk Performer establishes a secure connection to the server.
  • SslFlushSessionCache Function
    Clears all sessions from the SSL session cache so that all new connections will be authenticated and incur the public key operation overhead.
Parent topic: Internet Functions
Related concepts
Low-Level Web Functions Overview
Web Functions Reference
Related reference
WebGetSecurity Function
WebSetSecurity Function


SslSetClientCert Function

Action

Sets the client certificate that Silk Performer presents the secure server in behalf on the real client's certificate. To use a client certificate, it must be exported from the Web browser and imported into the Silk Performer certificate store first.

Include file

WebAPI.bdh

Syntax

SslSetClientCert( in sCertFile : string ): boolean;

Return value

  • true if successful

  • false otherwise

Parameter | Description
sCertFile | Certificate file (.pem) located in the Silk Performer user data directory. To copy a client certificate into the user data directory, it has to be exported from the Web browser.

Example

dcltrans
  transaction TSecureHTTP
  begin
    SslSetEncryption(SSL_VERSION_SSL3, SSL_CIPHERS_SSLv3);
    SslSetClientCert("Sunny.pem");
    WebUrl("https://www.company.com");
  end TSecureHTTP;

Sample scripts

WebSecure01.bdf, WebSecure02.bdf

Parent topic: SSL (Secure Socket Layer) Extensions
Related concepts
Web Functions Reference
Related tasks
Using a Client Certificate for Replay in a Script
Related reference
SslFlushSessionCache Function
SslSetEncryption Function


SslSetClientCertPassword Function

Action

Sets the password for the client certificate.

Include file

WebAPI.bdh

Syntax

SslSetClientCertPassword(in sCertPasword: string): boolean;

Return value

  • true if successful
  • false otherwise
Parameter | Description
sCertPasword | The password for the client certificate.

Example

dcltrans
  transaction TSecureHTTP
  begin
    SslSetEncryption(SSL_VERSION_SSL3, SSL_CIPHERS_SSLv3);
    SslSetClientCert("Sunny.pem");
    SslSetClientCertPassword("Performer")
    WebUrl("https://www.company.com");
  end TSecureHTTP;
Parent topic: SSL (Secure Socket Layer) Extensions


SslSetEncryption Function

Action

Sets the Secure Socket Layer protocol version and the ciphers used when Silk Performer establishes a secure connection to the server.

Include file

WebAPI.bdh

Syntax

SslSetEncryption( in nVersion : number,
                  in sCiphers : string optional ): boolean;

Return value

  • true if successful

  • false otherwise

Parameter Description
nVersion Specifies the Secure Socket Layer protocol version used when Silk Performer establishes a secure connection to the server. Valid options are:
  • SSL_VERSION_AUTO
  • SSL_VERSION_SSL3
  • SSL_VERSION_TLS1
  • SSL_VERSION_TLS11
  • SSL_VERSION_TLS12
  • SSL_VERSION_TLS13
sCiphers Optional: Specifies the ciphers used when Silk Performer establishes a secure connection to the server. Valid options are:
  • SSL_CIPHERS_MEDIUM. Perform 128-bit encryption
  • SSL_CIPHERS_HIGH. Use triple DES

You can also specify any cipher as described on OpenSSL ciphers. If this parameter is omitted, Silk Performer uses its default ciphers.

The sCiphers parameter can also be a string value with one or more cipher names, separated with a colon (:), or a combination of sets ("SSLv3", "MEDIUM" or "HIGH") and cipher names, or even with logical operators, for example "EXP:RC4-SHA:!HIGH". You can also mix TLSv1.3 ciphers with non-TLSv1.3 ciphers. Invalid cipher strings are ignored.

For a list of available cipher names, visit OpenSSL ciphers.

Example

dcltrans
  transaction TSecureHTTP
  begin
    SslSetEncryption(SSL_VERSION_SSL3, SSL_CIPHERS_SSLv3);
    WebUrl("https://www.company.com");
  end TSecureHTTP;

  transaction TSecureHTTP1
  begin
    SslSetEncryption(SSL_VERSION_SSL3, "EXP-RC4-MD5:EXP-DES-CBC-SHA");
    WebUrl("https://www.company.com");
  end TSecureHTTP1;

    // no cipher specified, request vs. TLSv1.3 server, expected ciphersuite: TLS_AES_256_GCM_SHA384
    SslSetEncryption(SSL_VERSION_TLS13);

    // ciphers set in specified order, request vs. TLSv1.3 server, expected ciphersuite is: TLS_AES_128_GCM_SHA256
    SslSetEncryption(SSL_VERSION_AUTO, "TLS_AES_128_GCM_SHA256:TLS_CHACHA20_POLY1305_SHA256:TLS_AES_256_GCM_SHA384");

    // set TLSv1.2 and TLSv1.3 ciphers, requests to TLSv1.2 and TLSv1.3 server
    SslSetEncryption(SSL_VERSION_AUTO, "ECDHE-RSA-AES128-GCM-SHA256:TLS_CHACHA20_POLY1305_SHA256");

    // same as above, but added some non-existing ciphers
    SslSetEncryption(SSL_VERSION_AUTO, "thisisnotacipher:ECDHE-RSA-AES128-GCM-SHA256:thisisnotaciphertoo:TLS_CHACHA20_POLY1305_SHA256:thisisalsonotacipher");

Sample scripts

WebSecure01.bdf, WebSecure02.bdf

Parent topic: SSL (Secure Socket Layer) Extensions
Related concepts
Web Functions Reference
Related reference
SslFlushSessionCache Function
SslSetClientCert Function


SslFlushSessionCache Function

Action

Clears all sessions from the SSL session cache so that all new connections will be authenticated and incur the public key operation overhead.

Note: That existing connections are not terminated and therefore further use their negotiated session key.

Include file

WebAPI.bdh

Syntax

SslFlushSessionCache(): boolean;

Return value

  • true if successful

  • false otherwise

Example

dcltrans
  transaction TMain
  begin
    SslSetEncryption(SSL_VERSION_SSL3, SSL_CIPHERS_SSLv3);
    WebUrl("https://www.company.com");
    WebUrl("https://www.company1.com");
    WebUrl("https://www.company2.com");
    WebUrl("https://www.company3.com");
    // flush all negotiated sessions
    SslFlushSessionCache();
  end TMain;
Parent topic: SSL (Secure Socket Layer) Extensions
Related concepts
Web Functions Reference
Related reference
SslSetClientCert Function
SslSetEncryption Function


TCP/IP Functions Reference

Application-level functions are used to handle protocols other than POP3, SMTP, FTP and HTTP as well as nonstandard Internet commands. They can also be used to build a prototype of a customer-defined client, such as a News client.

  • Web TCP/IP Functions
    Lists the functions for testing applications that use the Web TCP/IP protocol.
  • Web Telnet Functions
    Lists the functions for testing applications that use the Web telnet protocol.
Parent topic: Internet Functions


Web TCP/IP Functions

Silk Performer provides functions for testing applications that use the Web TCP/IP protocol.

  • WebTcpipAccept Function
    Listens for a connection to be established to a listener socket and accepts the connection.
  • WebTcpipConnect Function
    Connects to any host on the Internet or intranet. sHost can be the domain name or the IP address.
  • WebTcpipGetOptions Function
    Retrieves a TCP/IP connection’s specific options.
  • WebTcpipGetPacketBoundary Function
    Returns a packet boundary for an existing connection.
  • WebTcpipListen Function
    Creates a listener socket on a specified port and returns a handle to that socket.
  • WebTcpipRecv Function
    Retrieves data from the remote host.
  • WebTcpipRecvExact Function
    Receives an exact number of data bytes from a remote host unless an error occurs or the connection is closed by the server.
  • WebTcpipRecvClose Function
    Retrieves data from the remote host until the connection is closed by the server.
  • WebTcpipRecvPackets Function
    Receives individual or multiple in-coming packets from an open connection.
  • WebTcpipRecvPacketsUntilData Function
    Receives data from Telnet server until a packet with specified data arrives.
  • WebTcpipRecvProto Function
    Retrieves a calculated amount of data from the remote host.
  • WebTcpipRecvUntil Function
    Retrieves a response from the remote host until the pattern sPattern is found.
  • WebTcpipRecvProtoEx Function
    Like the WebTcpipRecvProto function, but with the additional possibility to verify a fixed portion of the tcp packet (by specifying its starting position and length), and two additional parameters to define the performed packet-length calculation (multiplication and addition).
  • WebTcpipRecvUntilIdle Function
    Receives data from a connection until the connection remains idle for a specified period of time.
  • WebTcpipScreenRecvPacketsUntilCursor Function
    Receives packets from a Telnet server until cursor is detected at a specified position.
  • WebTcpipScreenRecvPacketsUntilField Function
    Receives data from a given connection until the rendered screen contains a specified field.
  • WebTcpipScreenRecvPacketsUntilStatus Function
    Receives data from a given connection until rendered screen signals a specified status.
  • WebTcpipScreenRecvPacketsUntilText Function
    Receives data from a given connection until rendered screen contains specified text.
  • WebTcpipSelect Function
    Checks if a subsequent WebTcpipRecv operation on the provided connection handle will block, or succeed immediately.
  • WebTcpipSend Function
    Sends a string to the remote host. Before WebTcpipSend can be used, a valid connection has to be established with WebTcpipConnect.
  • WebTcpipSendFile Function
    Sends the data of a file in binary mode to the remote host.
  • WebTcpipSendBin Function
    Sends a string/buffer containing binary data to the remote host.
  • WebTcpipSendPacket Function
    Sends a single out-going packet to an open connection.
  • WebTcpipSetOptions Function
    Sets a TCP/IP connection’s specific options.
  • WebTcpipSetPacketBoundary Function
    Sets a packet boundary for an existing connection and is used to split in-coming and out-going data when using WebTcpipRecvPackets and WebTcpipSendPacket functions.
  • WebTcpipSetTelnetMode Function
    Switches pure TCP/IP connection mode to Telnet connection mode.
  • WebTcpipShutdown Function
    Shuts down the connection established by WebTcpipConnect.
  • WebTcpipSSLHandshake Function
    Performs a secure handshake on an open connection.
Parent topic: TCP/IP Functions Reference


WebTcpipAccept Function

Action

Listens for a connection to be established to a listener socket and accepts the connection. Before you can use this function, you have to create a valid connection handle with the WebTcpipListen function. The WebTcpipAccept function blocks the called until a connection is established.

Include file

WebAPI.bdh

Syntax

WebTcpipAccept( in  hTcpipListen : number
                out hTcpip       : number): boolean;

Return value

  • true if successful

  • false otherwise

Parameter | Description
hTcpipListen | Valid handle to a connection created with the WebTcpipListen function.
hTcpip | Variable receiving the handle to the accepted connection.

Example

dcltrans
  transaction TServer
  var
    hTcpip, hListen, nRecv : number;
    sData                  : string;
  begin
    // start listening on port 88
    WebTcpipListen(hListen, 88);
    // accept client request
    WebTcpipAccept(hListen, hTcpip);
    // receive data from the client
    WebTcpipRecvUntil(hTcpip, sData, STRING_COMPLETE, nRecv, "\r\n\r\n", 4);
    // process the client’s request
    // close the connections
    WebTcpipShutdown(hTcpip);
    WebTcpipShutdown(hListen);
  end TServer;
Parent topic: Web TCP/IP Functions
Related reference
WebTcpipConnect Function


WebTcpipConnect Function

Action

Connects to any host on the Internet or intranet. sHost can be the domain name or the IP address. You can also use the predefined host name standardhost, which can be set in the Workbench. A URL cannot be used with WebTcpipConnect. This function must be used before any other call to WebTcpip functions.

Include file

WebAPI.bdh

Syntax

WebTcpipConnect( out hWeb          : number,
                 in  sHost         : string,
                 in  nPort         : number,
                 in  nSecurity     : number optional,
                 in  sLocalAddress : string optional ): boolean;

Return value

  • true if the function succeeds, and the function stores a valid handle in hWeb

  • false otherwise

Parameter | Description
hWeb

Variable receiving a handle to the Web connection.

If this parameter contains a handle to a Web connection prior to the WebTcpipConnect function call, the memory allocated with the handle is released. Whenever you want to create a new Web connection, make sure this variable is initialized with 0 (this is automatically done within transactions when they are executed for the first time, but not within functions)
sHost | Domain name or IP address, for example, "hostname.com" or "192.231.34.1"
nPort

Port to connect to. The following constants can be used as the standard port:

  • WEB_PORT_FTP

  • WEB_PORT_TELNET

  • WEB_PORT_SMTP

  • WEB_PORT_GOPHER

  • WEB_PORT_HTTP

  • WEB_PORT_HTTPS

  • WEB_PORT_POP3

  • WEB_PORT_NNTP

  • WEB_PORT_IRC

  • WEB_PORT_LDAP

  • WEB_PORT_LDAP_SSL

  • WEB_PORT_SOCKS
nSecurity

Specifies whether to establish a secure connection to the remote server (optional). Possible options are:

  • WEB_CONNECT_NONE. Establishes an insecure connection to the server (default)

  • WEB_CONNECT_SSL. Establishes a secure connection using SSL
sLocalAddress | Specifies the local address and the port to which the socket should be bound (optional), for example, "192.168.70.101:4000".

Example

dcltrans
  transaction TWebApplevel
  var
    hWeb: number;
  begin
    WebTcpipConnect(hWeb, "standardhost", WEB_PORT_HTTP);
    WebTcpipShutdown(hWeb);
  end TWebApplevel;

Sample scripts

WebFileUpload01.bdf, WebMulti01.bdf, WebSecure01.bdf, WebTcpipHttp01.bdf, WebTcpipWebStone01.bdf

Parent topic: Web TCP/IP Functions


WebTcpipGetOptions Function

Action

Retrieves a TCP/IP connection’s specific options.

Include file

WebAPI.bdh

Syntax

WebTcpipGetOptions(     in hWeb      : number,
                        out nOptions : number ) : boolean;

Return value

  • true if the operation succeeded

  • false otherwise

Parameter | Description
hWeb | Valid handle to a Web connection created by WebTcpipConnect. This function currently reflects flags set by WebTcpipSetTelnetMode and will be extended by other configurations in future.
nOptions

Numeric variable where current bitflag option settings are to be placed. Currently the options may return any bitwise combination of:

  • TELNET_MODEOPT_FILTER_NOPS := 0x0001

  • TELNET_MODEOPT_AUTOANSWER_TM := 0x0002

  • TELNET_MODEOPT_FILTER_TM := 0x0004

  • TELNET_MODEOPT_RFC_1576 := 0x0007

  • TELNET_MODEOPT_AUTO_RECV := 0x0018

  • TEELNET_MODEOPT_SYNC := 0x0020;

See WebTcpipSetTelnetMode for details.

Example

dcltrans
  transaction TInit
  begin
    StrSetHostCP(28591); // 28591 (ISO 8859-1 Latin I)
  end TInit;

  transaction   TMain
  var
    hWeb0     : number;
    sBuffer   : string;
    sBoundary : string;
    nOption   : number;
  begin
    WebTcpipConnect(hWeb0, "My.TelnetHost.IP", WEB_PORT_TELNET);
    WebTcpipSetTelnetMode(hWeb0, TERMINAL_TYPE_ANSI, 80, 24, true, TELNET_MODEOPT_SYNC);
    WebTcpipGetOptions(hWeb0, nOption);
    if nOption <> TELNET_MODEOPT_RFC_1576 then
      WebTcpipSetOptions(hWeb0, TELNET_MODEOPT_RFC_1576);
    end;
    WebTelnetRecvCommand(hWeb0, TELNET_CMD_DO, TELNET_OPT_TerminalType);
    WebTelnetRecvCommand(hWeb0, TELNET_CMD_DO, TELNET_OPT_TerminalSpeed);
    WebTelnetRecvCommand(hWeb0, TELNET_CMD_DO, TELNET_OPT_XDisplayLocation);
    WebTelnetRecvCommand(hWeb0, TELNET_CMD_DO, TELNET_OPT_NewEnvironment);
    WebTelnetSendCommand(hWeb0, TELNET_CMD_WILL, TELNET_OPT_TerminalType);
    WebTelnetSendCommand(hWeb0, TELNET_CMD_WONT, TELNET_OPT_TerminalSpeed);
    WebTelnetSendCommand(hWeb0, TELNET_CMD_WONT, TELNET_OPT_XDisplayLocation);
    WebTelnetSendCommand(hWeb0, TELNET_CMD_WONT, TELNET_OPT_NewEnvironment);
    WebTelnetRecvSubNegotiation(hWeb0, TELNET_OPT_TerminalType);
    WebTelnetSendTerminalType(hWeb0, "vt100");
    WebTelnetRecvCommand(hWeb0, TELNET_CMD_WILL, TELNET_OPT_SuppressGoAhead);
    WebTelnetRecvCommand(hWeb0, TELNET_CMD_DO, TELNET_OPT_Echo);
    WebTelnetRecvCommand(hWeb0, TELNET_CMD_DO, TELNET_OPT_NegotiateWindowSize);
    WebTelnetRecvCommand(hWeb0, TELNET_CMD_WILL, TELNET_OPT_Status);
    WebTelnetRecvCommand(hWeb0, TELNET_CMD_DO, TELNET_OPT_RemoteFlowControl);
    WebTelnetSendCommand(hWeb0, TELNET_CMD_DO, TELNET_OPT_SuppressGoAhead);
    WebTelnetSendCommand(hWeb0, TELNET_CMD_WONT, TELNET_OPT_Echo);
    WebTelnetSendCommand(hWeb0, TELNET_CMD_WILL, TELNET_OPT_NegotiateWindowSize);
    WebTelnetSendSubNegotiation(hWeb0, TELNET_OPT_NegotiateWindowSize, "\h00500018");
    WebTelnetSendCommand(hWeb0, TELNET_CMD_DONT, TELNET_OPT_Status);
    WebTelnetSendCommand(hWeb0, TELNET_CMD_WONT, TELNET_OPT_RemoteFlowControl);
    WebTelnetRecvCommand(hWeb0, TELNET_CMD_WILL, TELNET_OPT_Echo);
    WebTcpipGetPacketBoundary(hWeb0, sBoundary);
    WebTcpipRecvPacketsUntilData(hWeb0, "login: ");
    WebTelnetTypeKeys(hWeb0, StrToHostCP("leo"), 359.3, TELNET_FLAG_CASE_SENSITIVE);
    WebTcpipSendBin(hWeb0, "\h0D00");
    WebTcpipRecvExact(hWeb0, NULL, 390);
    WebTcpipSetPacketBoundary(hWeb0, sBoundary);
    WebTcpipRecvUntilIdle(hWeb0, NULL, 5000);
    WebTcpipSendBin(hWeb0, "\h0D000D0A");
    WebTcpipRecvPackets(hWeb0, NULL, 3);
    WebTcpipSendBin(hWeb0, "\h0D00");
    WebTcpipSendPacket(hWeb0, StrToHostCP("8") + "\h0D00");
    WebTcpipRecvClose(hWeb0, NULL);
    WebTcpipShutdown(hWeb0);
  end TMain;
Parent topic: Web TCP/IP Functions
Related reference
WebTcpipConnect Function
WebTcpipSetOptions Function


WebTcpipGetPacketBoundary Function

Action

Returns a packet boundary for an existing connection. The packet boundary is used to split in-coming and out-going data when using WebTcpipRecvPackets and WebTcpipSendPackets functions. By default a “packet” consists of a TCP/IP packet. So in effect, the packet boundary is set to NULL.

Include file

WebAPI.bdh

Syntax

WebTcpipGetPacketBoundary(    in  hWeb      : number,
                              out sBoundary : string ) : boolean;

Return value

  • true if the operation was successful

  • false otherwise

Parameter | Description
hWeb | Valid handle to a Web connection created by WebTcpipConnect.
sBoundary | String variable in which the current packet boundary is placed. By default a NULL string (a raw TCP/IP packet) is returned.

Example

dcltrans
  transaction TInit
  begin
    StrSetHostCP(28591); // 28591 (ISO 8859-1 Latin I)
  end TInit;

  transaction   TMain
  var
    hWeb0     : number;
    sBuffer   : string;
    sBoundary : string;
    nOption   : number;
  begin
    WebTcpipConnect(hWeb0, "My.TelnetHost.IP", WEB_PORT_TELNET);
    WebTcpipSetTelnetMode(hWeb0, TERMINAL_TYPE_ANSI, 80, 24, true, TELNET_MODEOPT_SYNC);
    WebTcpipGetOptions(hWeb0, nOption);
    if nOption <> TELNET_MODEOPT_RFC_1576 then
      WebTcpipSetOptions(hWeb0, TELNET_MODEOPT_RFC_1576);
    end;
    WebTelnetRecvCommand(hWeb0, TELNET_CMD_DO, TELNET_OPT_TerminalType);
    WebTelnetRecvCommand(hWeb0, TELNET_CMD_DO, TELNET_OPT_TerminalSpeed);
    WebTelnetRecvCommand(hWeb0, TELNET_CMD_DO, TELNET_OPT_XDisplayLocation);
    WebTelnetRecvCommand(hWeb0, TELNET_CMD_DO, TELNET_OPT_NewEnvironment);
    WebTelnetSendCommand(hWeb0, TELNET_CMD_WILL, TELNET_OPT_TerminalType);
    WebTelnetSendCommand(hWeb0, TELNET_CMD_WONT, TELNET_OPT_TerminalSpeed);
    WebTelnetSendCommand(hWeb0, TELNET_CMD_WONT, TELNET_OPT_XDisplayLocation);
    WebTelnetSendCommand(hWeb0, TELNET_CMD_WONT, TELNET_OPT_NewEnvironment);
    WebTelnetRecvSubNegotiation(hWeb0, TELNET_OPT_TerminalType);
    WebTelnetSendTerminalType(hWeb0, "vt100");
    WebTelnetRecvCommand(hWeb0, TELNET_CMD_WILL, TELNET_OPT_SuppressGoAhead);
    WebTelnetRecvCommand(hWeb0, TELNET_CMD_DO, TELNET_OPT_Echo);
    WebTelnetRecvCommand(hWeb0, TELNET_CMD_DO, TELNET_OPT_NegotiateWindowSize);
    WebTelnetRecvCommand(hWeb0, TELNET_CMD_WILL, TELNET_OPT_Status);
    WebTelnetRecvCommand(hWeb0, TELNET_CMD_DO, TELNET_OPT_RemoteFlowControl);
    WebTelnetSendCommand(hWeb0, TELNET_CMD_DO, TELNET_OPT_SuppressGoAhead);
    WebTelnetSendCommand(hWeb0, TELNET_CMD_WONT, TELNET_OPT_Echo);
    WebTelnetSendCommand(hWeb0, TELNET_CMD_WILL, TELNET_OPT_NegotiateWindowSize);
    WebTelnetSendSubNegotiation(hWeb0, TELNET_OPT_NegotiateWindowSize, "\h00500018");
    WebTelnetSendCommand(hWeb0, TELNET_CMD_DONT, TELNET_OPT_Status);
    WebTelnetSendCommand(hWeb0, TELNET_CMD_WONT, TELNET_OPT_RemoteFlowControl);
    WebTelnetRecvCommand(hWeb0, TELNET_CMD_WILL, TELNET_OPT_Echo);
    WebTcpipGetPacketBoundary(hWeb0, sBoundary);
    WebTcpipRecvPacketsUntilData(hWeb0, "login: ");
    WebTelnetTypeKeys(hWeb0, StrToHostCP("leo"), 359.3, TELNET_FLAG_CASE_SENSITIVE);
    WebTcpipSendBin(hWeb0, "\h0D00");
    WebTcpipRecvExact(hWeb0, NULL, 390);
    WebTcpipSetPacketBoundary(hWeb0, sBoundary);
    WebTcpipRecvUntilIdle(hWeb0, NULL, 5000);
    WebTcpipSendBin(hWeb0, "\h0D000D0A");
    WebTcpipRecvPackets(hWeb0, NULL, 3);
    WebTcpipSendBin(hWeb0, "\h0D00");
    WebTcpipSendPacket(hWeb0, StrToHostCP("8") + "\h0D00");
    WebTcpipRecvClose(hWeb0, NULL);
    WebTcpipShutdown(hWeb0);
  end TMain;
Parent topic: Web TCP/IP Functions
Related reference
WebTcpipConnect Function
WebTcpipSetPacketBoundary Function


WebTcpipListen Function

Action

Creates a listener socket on a specified port and returns a handle to that socket.

Include file

WebAPI.bdh

Syntax

WebTcpipListen( inout hTcpipListen : number
                in nPort           : number ): boolean;

Return value

  • true if successful

  • false otherwise

Parameter | Description
hTcpipListen | Variable receiving a handle to the listener socket.
nPort | Specifies the port number to listen at.

Example

dcltrans
  transaction TServer
  var
    hTcpip, hListen, nRecv : number;
    sData : string;
  begin
    // start listening on port 88
    WebTcpipListen(hListen, 88);
    // accept client request
    WebTcpipAccept(hListen, hTcpip);
    // receive data from the client
    WebTcpipRecvUntil(hTcpip, sData, STRING_COMPLETE, nRecv, "\r\n\r\n", 4);
    // process the client’s request
    // close connections
    WebTcpipShutdown(hTcpip);
    WebTcpipShutdown(hListen);
  end TServer;
Parent topic: Web TCP/IP Functions
Related reference
WebTcpipConnect Function


WebTcpipRecv Function

Action

Retrieves data from the remote host.

Include file

WebAPI.bdh

Syntax

WebTcpipRecv( in  hWeb      : number,
              out sData     : string allownull,
              in  nMaxData  : number optional,
              out nReceived : number optional): boolean;

Return value

  • true if up to nMaxData bytes could be read successfully

  • false otherwise

Parameter | Description
hWeb | Valid handle to a Web connection that was created by WebTcpipConnect
sData | Buffer to store the received data. This field may be set to NULL to use only internal buffers, for example, if result is not to be parsed
nMaxData | Maximum amount of data to read from server. This value has no effect when sData is set to NULL.
nReceived | Parameter that receives the actual amount of data received from the server. Often more calls to WebTcpipRecv are needed to get all the data from the server.

Example

// Sample to retrieve an HTML page from a Web server
dcltrans
  transaction TWebRecv
  var
    hWeb0 : number;
    nRecv : number;
    sData : string;
  begin
    WebTcpipConnect(hWeb0, "purple", 80);
    WebTcpipSend(hWeb0, "GET / HTTP/1.0\r\n"
    "User-Agent: CustomClient/1.0\r\n"
    "Accept: */*\r\n\r\n");
    // Wait until WebRecv returns with 0 bytes read
    loop
    if not WebTcpipRecv(hWeb0, sData, 1000, nRecv) then
    write("error"); writeln;
  end;

    if nRecv = 0 then exit; end;
      write(nRecv); writeln;
      write(sData); writeln;
    end;

    writeln;
    WebTcpipShutdown(hWeb0);
  end TWebRecv;
Parent topic: Web TCP/IP Functions
Related reference
WebTcpipConnect Function
WebTcpipSend Function
WebTcpipRecvExact Function
WebTcpipRecvClose Function
WebTcpipRecvPackets Function
WebTcpipRecvPacketsUntilData Function
WebTcpipRecvProto Function
WebTcpipRecvUntil Function
WebTcpipRecvProtoEx Function
WebTcpipRecvUntilIdle Function


WebTcpipRecvExact Function

Action

Receives an exact number of data bytes from a remote host unless an error occurs or the connection is closed by the server.

Include file

WebAPI.bdh

Syntax

WebTcpipRecvExact( in  hWeb      : number,
                   out sData     : string optional,
                   in  nData     : number optional,
                   out nReceived : number optional ): boolean;

Return value

  • true if the exact number of bytes was received

  • false otherwise

Parameter | Description
hWeb | Valid handle to a Web connection that was created by WebTcpipConnect
sData | Buffer to store the received data (optional). If this parameter is set to NULL, internal buffers are used for retrieval. In this case, the received data cannot be parsed
nData | Amount of data bytes to receive (optional). Make sure to set nData <= size of sData
nReceived | Parameter that receives the actual amount of data received from the server (optional)

Example

dcltrans
  transaction TWeb
  var
    hWeb      : number;
    sHdr      : string;
    sSize     : string(20);
    nReceived : number;
  begin
    WebTcpipConnect(hWeb, "lab3", 80);
    sHdr := "GET /file5k.html HTTP/1.1\r\n"
            "Host: lab3\r\n\r\n";
    // send HTTP  request header
    WebTcpipSend(hWeb, sHdr);
    // receive HTTP response header
    WebTcpipRecvUntil(hWeb, sHdr, STRING_COMPLETE, nReceived, "\r\n\r\n");
    // receive document
    StrSearchDelimited(sSize, STRING_COMPLETE, sHdr,
                        "Content-Length: ", 1, "\r\n",
                        1, STR_SEARCH_FIRST);
    WebTcpipRecvExact(hWeb, NULL, number(sSize));
    // reset the persistent connection
    WebTcpipShutdown(hWeb, WEB_SHUTDOWN_RESET);
  end TWeb;

Sample scripts

WebTcpipHttp01.bdf, WebTcpipImap401.bdf

Parent topic: Web TCP/IP Functions
Related reference
WebTcpipConnect Function
WebTcpipSend Function
WebTcpipRecv Function
WebTcpipRecvClose Function
WebTcpipRecvPackets Function
WebTcpipRecvPacketsUntilData Function
WebTcpipRecvProto Function
WebTcpipRecvUntil Function
WebTcpipRecvProtoEx Function
WebTcpipRecvUntilIdle Function


WebTcpipRecvClose Function

Action

Retrieves data from the remote host until the connection is closed by the server. Only the first nMaxData bytes are stored into the buffer sData. If sData is set to NULL only the internal buffers are used for retrieval.

Include file

WebAPI.bdh

Syntax

WebTcpipRecvClose( in  hWeb      : number,
                   out sData     : string optional,
                   in  nMaxData  : number optional,
                   out nReceived : number optional): boolean;

Return value

  • true if the server sent data and closed the connection gently

  • false otherwise

Parameter | Description
hWeb | Valid handle to a Web connection that was created by WebTcpipConnect.
sData | Buffer to store the received data (optional). This field also can be set to NULL to use only internal buffers, for example, if data is not to be parsed.
nMaxData | Maximum amount of bytes to store into sData (optional). Specify STRING_COMPLETE to get all received data. This value has no affect if sData = NULL.
nReceived | Parameter that receives the actual amount of data received from the server (optional). Use NULL if value is not needed.

Example

dcltrans
  transaction TWebApplevel
  var
    hWeb : number;
    nRecv : number;
  begin
    // Get the root HTML page of the Web server defined
    // by standardhost with a custom client header
    WebTcpipConnect(hWeb, "standardhost", WEB_PORT_HTTP);
    WebTcpipSend(hWeb, "GET / HTTP/1.0\r\n"
       "User-Agent: CustomClient/1.0\r\n"
       "Accept: */*\r\n\r\n");
    WebTcpipRecvClose(hWeb, 0, 0, nRecv);
    WebTcpipShutdown(hWeb);
  end TWebApplevel;

Sample scripts

WebFileUpload01.bdf, WebMulti01.bdf, WebSecure01.bdf, WebTcpipHttp01.bdf, WebTcpipWebStone01.bdf

Parent topic: Web TCP/IP Functions
Related reference
WebTcpipConnect Function
WebTcpipSend Function
WebTcpipRecv Function
WebTcpipRecvExact Function
WebTcpipRecvPackets Function
WebTcpipRecvPacketsUntilData Function
WebTcpipRecvProto Function
WebTcpipRecvUntil Function
WebTcpipRecvProtoEx Function
WebTcpipRecvUntilIdle Function


WebTcpipRecvPackets Function

Action

Receives individual or multiple in-coming packets from an open connection. A packet is defined as a TCP/IP packet or a part of an in-bound data stream that is separated by a specific packet boundary.

Include file

WebAPI.bdh

Syntax

WebTcpipRecvPackets(    in  hWeb             : number,
                        out sRecv            : string optional,
                        in  iPackets         : number optional,
                        out uPacketsReceived : number optional,
                        out iBytesReceived   : number optional ): boolean;

Return value

  • true if the operation was successful (connection did not break down or time out).

  • false otherwise

Parameter | Description
hWeb | Valid handle to a Web connection created by WebTcpipConnect.
sRecv | Output buffer for data that has been received (optional).
iPackets | Number of packets to be received (optional). When this parameter is omitted only one packet is received (default).
uPacketsReceived | The number of received packets is placed in this parameter (optional). Except in instances where the connection was closed or broken, this should equate to iPackets.
iBytesReceived | Sum of all received data is put into this numeric variable if passed as a parameter (optional).

Example

dcltrans
  transaction TInit
  begin
    StrSetHostCP(28591); // 28591 (ISO 8859-1 Latin I)
  end TInit;

  transaction   TMain
  var
    hWeb0     : number;
    sBuffer   : string;
    sBoundary : string;
    nOption   : number;
  begin
    WebTcpipConnect(hWeb0, "My.TelnetHost.IP", WEB_PORT_TELNET);
    WebTcpipSetTelnetMode(hWeb0, TERMINAL_TYPE_ANSI, 80, 24, true, TELNET_MODEOPT_SYNC);
    WebTcpipGetOptions(hWeb0, nOption);
    if nOption <> TELNET_MODEOPT_RFC_1576 then
      WebTcpipSetOptions(hWeb0, TELNET_MODEOPT_RFC_1576);
    end;
    WebTelnetRecvCommand(hWeb0, TELNET_CMD_DO, TELNET_OPT_TerminalType);
    WebTelnetRecvCommand(hWeb0, TELNET_CMD_DO, TELNET_OPT_TerminalSpeed);
    WebTelnetRecvCommand(hWeb0, TELNET_CMD_DO, TELNET_OPT_XDisplayLocation);
    WebTelnetRecvCommand(hWeb0, TELNET_CMD_DO, TELNET_OPT_NewEnvironment);
    WebTelnetSendCommand(hWeb0, TELNET_CMD_WILL, TELNET_OPT_TerminalType);
    WebTelnetSendCommand(hWeb0, TELNET_CMD_WONT, TELNET_OPT_TerminalSpeed);
    WebTelnetSendCommand(hWeb0, TELNET_CMD_WONT, TELNET_OPT_XDisplayLocation);
    WebTelnetSendCommand(hWeb0, TELNET_CMD_WONT, TELNET_OPT_NewEnvironment);
    WebTelnetRecvSubNegotiation(hWeb0, TELNET_OPT_TerminalType);
    WebTelnetSendTerminalType(hWeb0, "vt100");
    WebTelnetRecvCommand(hWeb0, TELNET_CMD_WILL, TELNET_OPT_SuppressGoAhead);
    WebTelnetRecvCommand(hWeb0, TELNET_CMD_DO, TELNET_OPT_Echo);
    WebTelnetRecvCommand(hWeb0, TELNET_CMD_DO, TELNET_OPT_NegotiateWindowSize);
    WebTelnetRecvCommand(hWeb0, TELNET_CMD_WILL, TELNET_OPT_Status);
    WebTelnetRecvCommand(hWeb0, TELNET_CMD_DO, TELNET_OPT_RemoteFlowControl);
    WebTelnetSendCommand(hWeb0, TELNET_CMD_DO, TELNET_OPT_SuppressGoAhead);
    WebTelnetSendCommand(hWeb0, TELNET_CMD_WONT, TELNET_OPT_Echo);
    WebTelnetSendCommand(hWeb0, TELNET_CMD_WILL, TELNET_OPT_NegotiateWindowSize);
    WebTelnetSendSubNegotiation(hWeb0, TELNET_OPT_NegotiateWindowSize, "\h00500018");
    WebTelnetSendCommand(hWeb0, TELNET_CMD_DONT, TELNET_OPT_Status);
    WebTelnetSendCommand(hWeb0, TELNET_CMD_WONT, TELNET_OPT_RemoteFlowControl);
    WebTelnetRecvCommand(hWeb0, TELNET_CMD_WILL, TELNET_OPT_Echo);
    WebTcpipGetPacketBoundary(hWeb0, sBoundary);
    WebTcpipRecvPacketsUntilData(hWeb0, "login: ");
    WebTelnetTypeKeys(hWeb0, StrToHostCP("leo"), 359.3, TELNET_FLAG_CASE_SENSITIVE);
    WebTcpipSendBin(hWeb0, "\h0D00");
    WebTcpipRecvExact(hWeb0, NULL, 390);
    WebTcpipSetPacketBoundary(hWeb0, sBoundary);
    WebTcpipRecvUntilIdle(hWeb0, NULL, 5000);
    WebTcpipSendBin(hWeb0, "\h0D000D0A");
    WebTcpipRecvPackets(hWeb0, NULL, 3);
    WebTcpipSendBin(hWeb0, "\h0D00");
    WebTcpipSendPacket(hWeb0, StrToHostCP("8") + "\h0D00");
    WebTcpipRecvClose(hWeb0, NULL);
    WebTcpipShutdown(hWeb0);
  end TMain;
Parent topic: Web TCP/IP Functions
Related reference
WebTcpipConnect Function
WebTcpipSetPacketBoundary Function
WebTcpipSendPacket Function
WebTcpipSend Function
WebTcpipRecv Function
WebTcpipRecvExact Function
WebTcpipRecvClose Function
WebTcpipRecvPacketsUntilData Function
WebTcpipRecvProto Function
WebTcpipRecvUntil Function
WebTcpipRecvProtoEx Function
WebTcpipRecvUntilIdle Function


WebTcpipRecvPacketsUntilData Function

Action

Receives data from Telnet server until a packet with specified data arrives.

Include file

WebAPI.bdh

Syntax

WebTcpipRecvPacketsUntilData(
    in hWeb           : number,
    in sData          : string,
    in nOptions       : number optional,
    out sDataReceived : string optional ) : boolean;

Return value

  • true if the operation was successful

  • false otherwise

Parameter | Description
hWeb | Valid handle to a Web connection created by WebTcpipConnect. Web connection must be in Telnet mode (by a previous WebTcpipSetTelnetMode function call) and have a screen renderer associated with it.
sData | Data to be looked for in received packets.
nOptions

Comparison options; this is a case-insensitive "contains" by default, or may be one of the following:

  • TELNET_FLAG_EQUAL: Lengths of both values must match.

  • TELNET_FLAG_CASE_SENSITIVE: Comparison is performed case-sensitively.

  • TELNET_FLAG_IS_DIFFERENT: Negates the logical comparison.

  • TELNET_FLAG_IGNORE_WHITE_SPACE: All whitespaces in both compared strings are cut before comparison is performed.

  • TELNET_FLAG_CONTAINS: sText must occur within rendered screen text. (default)

  • TELNET_FLAG_FROM_LEFT: comparison is performed from the left side.

  • TELNET_FLAG_TRIM_LEFT: Leading blank spaces are trimmed from received data before comparison is performed.

  • TELNET_FLAG_TRIM_RIGHT: Trailing blanks are trimmed from received data before comparison is performed.

  • TELNET_FLAG_TRIM_BOTH: Status value is trimmed from both sides of content before comparison is performed.

  • TELNET_FLAG_FROM_RIGHT: Comparison is performed beginning from the right side.
sDataReceived | Optional output data buffer where all received packets, including the matching packet, are to be placed (optional).

Example

dcltrans
  transaction TInit
  begin
    StrSetHostCP(28591); // 28591 (ISO 8859-1 Latin I)
  end TInit;

  transaction   TMain
  var
    hWeb0     : number;
    sBuffer   : string;
    sBoundary : string;
    nOption   : number;
  begin
    WebTcpipConnect(hWeb0, "My.TelnetHost.IP", WEB_PORT_TELNET);
    WebTcpipSetTelnetMode(hWeb0, TERMINAL_TYPE_ANSI, 80, 24, true, TELNET_MODEOPT_SYNC);
    WebTcpipGetOptions(hWeb0, nOption);
    if nOption <> TELNET_MODEOPT_RFC_1576 then
      WebTcpipSetOptions(hWeb0, TELNET_MODEOPT_RFC_1576);
    end;
    WebTelnetRecvCommand(hWeb0, TELNET_CMD_DO, TELNET_OPT_TerminalType);
    WebTelnetRecvCommand(hWeb0, TELNET_CMD_DO, TELNET_OPT_TerminalSpeed);
    WebTelnetRecvCommand(hWeb0, TELNET_CMD_DO, TELNET_OPT_XDisplayLocation);
    WebTelnetRecvCommand(hWeb0, TELNET_CMD_DO, TELNET_OPT_NewEnvironment);
    WebTelnetSendCommand(hWeb0, TELNET_CMD_WILL, TELNET_OPT_TerminalType);
    WebTelnetSendCommand(hWeb0, TELNET_CMD_WONT, TELNET_OPT_TerminalSpeed);
    WebTelnetSendCommand(hWeb0, TELNET_CMD_WONT, TELNET_OPT_XDisplayLocation);
    WebTelnetSendCommand(hWeb0, TELNET_CMD_WONT, TELNET_OPT_NewEnvironment);
    WebTelnetRecvSubNegotiation(hWeb0, TELNET_OPT_TerminalType);
    WebTelnetSendTerminalType(hWeb0, "vt100");
    WebTelnetRecvCommand(hWeb0, TELNET_CMD_WILL, TELNET_OPT_SuppressGoAhead);
    WebTelnetRecvCommand(hWeb0, TELNET_CMD_DO, TELNET_OPT_Echo);
    WebTelnetRecvCommand(hWeb0, TELNET_CMD_DO, TELNET_OPT_NegotiateWindowSize);
    WebTelnetRecvCommand(hWeb0, TELNET_CMD_WILL, TELNET_OPT_Status);
    WebTelnetRecvCommand(hWeb0, TELNET_CMD_DO, TELNET_OPT_RemoteFlowControl);
    WebTelnetSendCommand(hWeb0, TELNET_CMD_DO, TELNET_OPT_SuppressGoAhead);
    WebTelnetSendCommand(hWeb0, TELNET_CMD_WONT, TELNET_OPT_Echo);
    WebTelnetSendCommand(hWeb0, TELNET_CMD_WILL, TELNET_OPT_NegotiateWindowSize);
    WebTelnetSendSubNegotiation(hWeb0, TELNET_OPT_NegotiateWindowSize, "\h00500018");
    WebTelnetSendCommand(hWeb0, TELNET_CMD_DONT, TELNET_OPT_Status);
    WebTelnetSendCommand(hWeb0, TELNET_CMD_WONT, TELNET_OPT_RemoteFlowControl);
    WebTelnetRecvCommand(hWeb0, TELNET_CMD_WILL, TELNET_OPT_Echo);
    WebTcpipGetPacketBoundary(hWeb0, sBoundary);
    WebTcpipRecvPacketsUntilData(hWeb0, "login: ");
    WebTelnetTypeKeys(hWeb0, StrToHostCP("leo"), 359.3, TELNET_FLAG_CASE_SENSITIVE);
    WebTcpipSendBin(hWeb0, "\h0D00");
    WebTcpipRecvExact(hWeb0, NULL, 390);
    WebTcpipSetPacketBoundary(hWeb0, sBoundary);
    WebTcpipRecvUntilIdle(hWeb0, NULL, 5000);
    WebTcpipSendBin(hWeb0, "\h0D000D0A");
    WebTcpipRecvPackets(hWeb0, NULL, 3);
    WebTcpipSendBin(hWeb0, "\h0D00");
    WebTcpipSendPacket(hWeb0, StrToHostCP("8") + "\h0D00");
    WebTcpipRecvClose(hWeb0, NULL);
    WebTcpipShutdown(hWeb0);
  end TMain;
Parent topic: Web TCP/IP Functions
Related reference
WebTcpipConnect Function
WebTcpipSend Function
WebTcpipRecv Function
WebTcpipRecvExact Function
WebTcpipRecvClose Function
WebTcpipRecvPackets Function
WebTcpipRecvProto Function
WebTcpipRecvUntil Function
WebTcpipRecvProtoEx Function
WebTcpipRecvUntilIdle Function


WebTcpipRecvProto Function

Action

Retrieves a calculated amount of data from the remote host. The protocol specification parameters define the performed calculation. If for example every tcp packet contains its length specification at a fixed position (e.g. first two bytes) these packets can be easily received with the WebTcpipRecvProto function.

Only the first nMaxData bytes are stored into the buffer sData. If sData is set to NULL, internal buffers are used for retrieval.

Include file

WebAPI.bdh

Syntax

WebTcpipRecvProto( in  hWeb         : number,
                   in  nProtoStart  : number,
                   in  nProtoLength : number,
                   in  nOption      : number optional,
                   out sData        : string optional,
                   in  nMaxData     : number optional,
                   out nReceived    : number optional): boolean;

Return value

  • true if the receive operation succeeded

  • false otherwise

Parameter | Description
hWeb | Valid handle to a Web connection that was created by WebTcpipConnect.
nProtoStart | Starting byte of the packet-length specification.
nProtoLength | Length of the packet-length specification.
nOption

Specify any combination of following flags (optional):

  • TCP_FLAG_LITTLE_ENDIAN. Specifies the byte order of the packet-length section. Little-endian means, that the most significant byte is at the end. Big-endian (default) means, that the most significant byte is at the front of the packet-length section.

  • TCP_FLAG_INCLUDE_PROTO. Specify this flag to signal, that the bytes of the protocol header (ending with the specified packet-length section) are included in the calculated packet-length. If this flag is not set, the receive operation of the calculated packet-length starts after the protocol header.

  • TCP_FLAG_TextProto. Specify this option if the length specification is provided as a string (readable value). By default this value will be interpreted as a decimal number. Use TCP_FLAG_TextProtoHex for a hexadecimal number or TCP_FLAG_TextProtoOct for an octal representation.

  • TCP_FLAG_TextProtoNumberOnly. Specify this flag in combination with TCP_FLAG_TextProto if the length specification consists of an unknown number of digits and if the header is not included in the specified length (TCP_FLAG_INCLUDE_PROTO must not be specified). If specified the body starts after the last digit of the length specification.

  • TCP_FLAG_TextProtoHex. Use this flag in combination with the TCP_FLAG_TextProto option to interpret the length specification as a hexadecimal number.

  • TCP_FLAG_TextProtoOct. Use this flag in combination with the TCP_FLAG_TextProto option to interpret the length specification as an octal number.
sData | Buffer to store the received data(optional). This field also can be set to NULL (default) to use only internal buffers, for example, if data is not to be parsed.
nMaxData

Maximum amount of bytes to store into sData (optional). Specify STRING_COMPLETE to get all received data.

This value has no effect when sData is set to NULL. If this parameter is omitted only internal buffers are used.
nReceived | Parameter that receives the actual amount of data received from the server (optional).

Example

dcltrans
  transaction TWeb
  var
    hWeb      : number;
    sHdr      : string(2000);
    sSize     : string(20);
    nReceived : number;
  begin
    WebTcpipConnect(hWeb, "lab3", 80);

    WebTcpipSend(hWeb, "Start\r\n");

    WebTcpipRecvProto(hWeb, 0, 2, TCP_FLAG_INCLUDE_PROTO | TCP_FLAG_LITTLE_ENDIAN, sHdr, STRING_COMPLETE, nReceived);

    StrSearchDelimited(sSize, STRING_COMPLETE, sHdr,
                       "Age: ", 1, "\r\n",
                       1, STR_SEARCH_FIRST);

    WebTcpipShutdown(hWeb, WEB_SHUTDOWN_RESET);
  end TWeb;
Parent topic: Web TCP/IP Functions
Related reference
WebTcpipConnect Function
WebTcpipSend Function
WebTcpipRecv Function
WebTcpipRecvExact Function
WebTcpipRecvClose Function
WebTcpipRecvPackets Function
WebTcpipRecvPacketsUntilData Function
WebTcpipRecvUntil Function
WebTcpipRecvProtoEx Function
WebTcpipRecvUntilIdle Function


WebTcpipRecvUntil Function

Action

Retrieves a response from the remote host until the pattern sPattern is found. Only the first nMaxData bytes are stored into the buffer sData. If sData is set to NULL, internal buffers are used for retrieval.

Include file

WebAPI.bdh

Syntax

WebTcpipRecvUntil( in  hWeb      : number,
                   out sData     : string allownull,
                   in  nMaxData  : number,
                   out nReceived : number allownull,
                   in  sPattern  : string,
                   in  nLength   : number optional ): boolean;

Return value

  • true if the end of response is found

  • false otherwise

Parameter | Description
hWeb | Valid handle to a Web connection that was created by WebTcpipConnect
sData

Buffer to store the received data.

This field also can be set to NULL to use only internal buffers, for example, if data is not to be parsed
nMaxData

Maximum amount of bytes to store into sData. Specify STRING_COMPLETE to get all received data.

This value has no effect when sData is set to NULL.
nReceived | Parameter that receives the actual amount of data received from the server
sPattern

The termination string. Predefined constants are:

  • WEB_CRLF ("\r\n")

  • WEB_CRLFCRLF ( "\r\n\r\n")

  • WEB_CRLFDOTCRLF ("\r\n.\r\n")

  • WEB_CRNULL ("\h0D00")

  • WEB_LFNULL ("\h0A00")

This may also be binary data. For using all available binary data specify STRING_COMPLETE for nLength and use the bin() operator for sData (see example).
nLength | The length of the binary pattern (optional). Omit this parameter to use all available data.

Example

dcltrans
  transaction TWeb
  var
    hWeb      : number;
    sHdr      : string;
    sSize     : string(20);
    nReceived : number;
    sPattern  : string;
  begin
    WebTcpipConnect(hWeb, "lab3", 80);
    sHdr := "GET /file5k.html HTTP/1.1\r\n"
                 "Host: lab3\r\n\r\n";

    // send HTTP request header
    WebTcpipSend(hWeb, sHdr);

    // receive HTTP response header
    WebTcpipRecvUntil(hWeb, sHdr, STRING_COMPLETE, nReceived, "\r\n\r\n");
    SPattern := "\r\n";
    WebTcpipRecvUntil(hWeb, sHdr, STRING_COMPLETE, nReceived, "\r\n\r\n");

    // receive document
    StrSearchDelimited(sSize, STRING_COMPLETE, sHdr, "Content-Length: ", 1, "\r\n",
                      1, STR_SEARCH_FIRST);
    WebTcpipRecvExact(hWeb, NULL, number(sSize));

    // reset the persistent connection
    WebTcpipShutdown(hWeb, WEB_SHUTDOWN_RESET);
  end TWeb;

Sample scripts

WebTcpipHttp01.bdf, WebTcpipImap401.bdf

Parent topic: Web TCP/IP Functions
Related reference
WebTcpipConnect Function
WebTcpipSend Function
WebTcpipRecv Function
WebTcpipRecvExact Function
WebTcpipRecvClose Function
WebTcpipRecvPackets Function
WebTcpipRecvPacketsUntilData Function
WebTcpipRecvProto Function
WebTcpipRecvProtoEx Function
WebTcpipRecvUntilIdle Function


WebTcpipRecvProtoEx Function

Action

Like the WebTcpipRecvProto function, but with the additional possibility to verify a fixed portion of the tcp packet (by specifying its starting position and length), and two additional parameters to define the performed packet-length calculation (multiplication and addition). If the verification fails an error is raised.

Include file

WebAPI.bdh

Syntax

WebTcpipRecvProtoEx( in  hWeb          : number,
                     in  nProtoStart   : number,
                     in  nProtoLength  : number,
                     in  nOption       : number optional,
                     out sData         : string optional,
                     in  nMaxData      : number optional,
                     out nReceived     : number optional,
                     in  sVerify       : string optional,
                     in  nVerifyStart  : number optional,
                     in  nVerifyLength : number optional,
                     in  nMultiply     : number optional,
                     in  nAdd          : number optional ): boolean;

Return value

  • true if the receive operation succeeded

  • false otherwise

Parameter | Description
hWeb | Valid handle to a Web connection that was created by WebTcpipConnect.
nProtoStart | Starting byte of the packet-length specification.
nProtoLength | Length of the packet-length specification.
nOption

Specify any combination of following flags (optional):

  • TCP_FLAG_LITTLE_ENDIAN. Specifies the byte order of the packet-length section. Little-endian means, that the most significant byte is at the end. Big-endian (default) means, that the most significant byte is at the front of the packet-length section.

  • TCP_FLAG_INCLUDE_PROTO. Specify this flag to signal, that the bytes of the protocol header (ending with the specified packet-length section) are included in the calculated packet-length. If this flag is not set, the receive operation of the calculated packet-length starts after the protocol header.

  • TCP_FLAG_TextProto. Specify this option if the length specification is provided as a string (readable value). By default this value will be interpreted as a decimal number. Use TCP_FLAG_TextProtoHex for a hexadecimal number or TCP_FLAG_TextProtoOct for an octal representation.

  • TCP_FLAG_TextProtoNumberOnly. Specify this flag in combination with TCP_FLAG_TextProto if the length specification consists of an unknown number of digits and if the header is not included in the specified length (TCP_FLAG_INCLUDE_PROTO must not be specified). If specified the body starts after the last digit of the length specification.

  • TCP_FLAG_TextProtoHex. Use this flag in combination with the TCP_FLAG_TextProto option to interpret the length specification as a hexadecimal number.

  • TCP_FLAG_TextProtoOct. Use this flag in combination with the TCP_FLAG_TextProto option to interpret the length specification as an octal number.
sData

Buffer to store the received data (optional).

This field also can be set to NULL (default) to use only internal buffers, for example, if data is not to be parsed.
nMaxData

Maximum amount of bytes to store into sData (optional). Specify STRING_COMPLETE to get all received data.

This value has no effect when sData is set to NULL. If this parameter is omitted only internal buffers are used.
nReceived | Parameter that receives the actual amount of data received from the server (optional).
sVerify | Binary pattern to verify (optional). If this parameter is omitted no verification is performed.
nVerifyStart | Starting position of the pattern verification (optional). If this parameter is omitted the verification starts at the beginning.
nVerifyLength | Length of the verification pattern (optional). If this parameter is omitted no verification is performed.
nMultiply | The parsed packet-length (specified by the nProtoStart, nProtoLength and bLittleEndian parameters) is multiplied by nMultiply and finally nSum is added (optional). If this parameter is omitted no multiplication is performed.
nAdd | The parsed packet-length (specified by the nProtoStart, nProtoLength and bLittleEndian parameters) is multiplied by nMultiply and finally nAdd is added (optional). If this parameter is omitted no addition is performed.

Example

dcltrans
  transaction TWeb
  var
    hWeb      : number;
    sHdr      : string(2000);
    sSize     : string(20);
    nReceived : number;
  begin
    WebTcpipConnect(hWeb, "lab3", 80);

    WebTcpipSend(hWeb, "Start\r\n");

    WebTcpipRecvProtoEx(hWeb, 0, 2, TCP_FLAG_INCLUDE_PROTO | TCP_FLAG_LITTLE_ENDIAN, sHdr, STRING_COMPLETE, nReceived,
                        "WIDECHARS", 2, 9, 2, 18);

    StrSearchDelimited(sSize, STRING_COMPLETE, sHdr,
                       "Age: ", 1, "\r\n",
                       1, STR_SEARCH_FIRST);

    WebTcpipShutdown(hWeb, WEB_SHUTDOWN_RESET);
  end TWeb;
Parent topic: Web TCP/IP Functions
Related reference
WebTcpipConnect Function
WebTcpipSend Function
WebTcpipRecv Function
WebTcpipRecvExact Function
WebTcpipRecvClose Function
WebTcpipRecvPackets Function
WebTcpipRecvPacketsUntilData Function
WebTcpipRecvProto Function
WebTcpipRecvUntil Function
WebTcpipRecvUntilIdle Function


WebTcpipRecvUntilIdle Function

Action

Receives data from a connection until the connection remains idle for a specified period of time.

Include file

WebAPI.bdh

Syntax

WebTcpipRecvUntilIdle(
    in hWeb      : number,
    out sDataRecv : string optional,
    in  nIdleTime : number optional,
    in  sTimer    : string optional ) : boolean;

Return value

  • true if the operation received any data

  • false otherwise

Parameter | Description
hWeb | Valid handle to a Web connection created by WebTcpipConnect.
sDataRecv | Optional output binary string variable where the received data is placed.
nIdleTime | Timeout period (in milliseconds) for which the connection must remain idle.
sTimer | Name of the timer returning the sum of response times of the function call (optional). If this parameter is omitted, no measurements are performed.

Example

dcltrans
  transaction TInit
  begin
    StrSetHostCP(28591); // 28591 (ISO 8859-1 Latin I)
  end TInit;

  transaction   TMain
  var
    hWeb0     : number;
    sBuffer   : string;
    sBoundary : string;
    nOption   : number;
  begin
    WebTcpipConnect(hWeb0, "My.TelnetHost.IP", WEB_PORT_TELNET);
    WebTcpipSetTelnetMode(hWeb0, TERMINAL_TYPE_ANSI, 80, 24, true, TELNET_MODEOPT_SYNC);
    WebTcpipGetOptions(hWeb0, nOption);
    if nOption <> TELNET_MODEOPT_RFC_1576 then
      WebTcpipSetOptions(hWeb0, TELNET_MODEOPT_RFC_1576);
    end;
    WebTelnetRecvCommand(hWeb0, TELNET_CMD_DO, TELNET_OPT_TerminalType);
    WebTelnetRecvCommand(hWeb0, TELNET_CMD_DO, TELNET_OPT_TerminalSpeed);
    WebTelnetRecvCommand(hWeb0, TELNET_CMD_DO, TELNET_OPT_XDisplayLocation);
    WebTelnetRecvCommand(hWeb0, TELNET_CMD_DO, TELNET_OPT_NewEnvironment);
    WebTelnetSendCommand(hWeb0, TELNET_CMD_WILL, TELNET_OPT_TerminalType);
    WebTelnetSendCommand(hWeb0, TELNET_CMD_WONT, TELNET_OPT_TerminalSpeed);
    WebTelnetSendCommand(hWeb0, TELNET_CMD_WONT, TELNET_OPT_XDisplayLocation);
    WebTelnetSendCommand(hWeb0, TELNET_CMD_WONT, TELNET_OPT_NewEnvironment);
    WebTelnetRecvSubNegotiation(hWeb0, TELNET_OPT_TerminalType);
    WebTelnetSendTerminalType(hWeb0, "vt100");
    WebTelnetRecvCommand(hWeb0, TELNET_CMD_WILL, TELNET_OPT_SuppressGoAhead);
    WebTelnetRecvCommand(hWeb0, TELNET_CMD_DO, TELNET_OPT_Echo);
    WebTelnetRecvCommand(hWeb0, TELNET_CMD_DO, TELNET_OPT_NegotiateWindowSize);
    WebTelnetRecvCommand(hWeb0, TELNET_CMD_WILL, TELNET_OPT_Status);
    WebTelnetRecvCommand(hWeb0, TELNET_CMD_DO, TELNET_OPT_RemoteFlowControl);
    WebTelnetSendCommand(hWeb0, TELNET_CMD_DO, TELNET_OPT_SuppressGoAhead);
    WebTelnetSendCommand(hWeb0, TELNET_CMD_WONT, TELNET_OPT_Echo);
    WebTelnetSendCommand(hWeb0, TELNET_CMD_WILL, TELNET_OPT_NegotiateWindowSize);
    WebTelnetSendSubNegotiation(hWeb0, TELNET_OPT_NegotiateWindowSize, "\h00500018");
    WebTelnetSendCommand(hWeb0, TELNET_CMD_DONT, TELNET_OPT_Status);
    WebTelnetSendCommand(hWeb0, TELNET_CMD_WONT, TELNET_OPT_RemoteFlowControl);
    WebTelnetRecvCommand(hWeb0, TELNET_CMD_WILL, TELNET_OPT_Echo);
    WebTcpipGetPacketBoundary(hWeb0, sBoundary);
    WebTcpipRecvPacketsUntilData(hWeb0, "login: ");
    WebTelnetTypeKeys(hWeb0, StrToHostCP("leo"), 359.3, TELNET_FLAG_CASE_SENSITIVE);
    WebTcpipSendBin(hWeb0, "\h0D00");
    WebTcpipRecvExact(hWeb0, NULL, 390);
    WebTcpipSetPacketBoundary(hWeb0, sBoundary);
    WebTcpipRecvUntilIdle(hWeb0, NULL, 5000);
    WebTcpipSendBin(hWeb0, "\h0D000D0A");
    WebTcpipRecvPackets(hWeb0, NULL, 3);
    WebTcpipSendBin(hWeb0, "\h0D00");
    WebTcpipSendPacket(hWeb0, StrToHostCP("8") + "\h0D00");
    WebTcpipRecvClose(hWeb0, NULL);
    WebTcpipShutdown(hWeb0);
  end TMain;
Parent topic: Web TCP/IP Functions
Related reference
WebTcpipConnect Function
WebTcpipSend Function
WebTcpipRecv Function
WebTcpipRecvExact Function
WebTcpipRecvClose Function
WebTcpipRecvPackets Function
WebTcpipRecvPacketsUntilData Function
WebTcpipRecvProto Function
WebTcpipRecvUntil Function
WebTcpipRecvProtoEx Function


WebTcpipScreenRecvPacketsUntilCursor Function

Action

Receives packets from a Telnet server until cursor is detected at a specified position.

Include file

WebAPI.bdh

Syntax

WebTcpipScreenRecvPacketsUntilCursor(
    in hWeb  : number,
    in nCol  : number,
    in nRow  : number,
    out sRecv : string ): boolean;

Return value

  • true if the operation was successful

  • false otherwise

Parameter | Description
hObject | Valid handle to a Web connection created by WebTcpipConnect. Web connection must be in Telnet mode (by a previous WebTcpipSetTelnetMode function call) and have a screen renderer associated with it.
nCol | 1-based horizontal cursor position.
nRow | 1-based vertical cursor position.
sRecv | Optional output buffer variable for all received binary data, including the matching packet.

Example

dcltrans
  transaction TInit
  begin
    StrSetHostCP(28591); // 28591 (ISO 8859-1 Latin I)
  end TInit;

  transaction   TMain
  var
    hWeb0     : number;
    sBuffer   : string;
    sBoundary : string;
    nOption   : number;
  begin
    WebTcpipConnect(hWeb0, "My.TelnetHost.IP", WEB_PORT_TELNET);
    WebTcpipSetTelnetMode(hWeb0, TERMINAL_TYPE_ANSI, 80, 24, true, TELNET_MODEOPT_RFC_1576);
    WebTelnetRecvCommand(hWeb0, TELNET_CMD_DO, TELNET_OPT_TerminalType);
    WebTelnetRecvCommand(hWeb0, TELNET_CMD_DO, TELNET_OPT_TerminalSpeed);
    WebTelnetRecvCommand(hWeb0, TELNET_CMD_DO, TELNET_OPT_XDisplayLocation);
    WebTelnetRecvCommand(hWeb0, TELNET_CMD_DO, TELNET_OPT_NewEnvironment);
    WebTelnetSendCommand(hWeb0, TELNET_CMD_WILL, TELNET_OPT_TerminalType);
    WebTelnetSendCommand(hWeb0, TELNET_CMD_WONT, TELNET_OPT_TerminalSpeed);
    WebTelnetSendCommand(hWeb0, TELNET_CMD_WONT, TELNET_OPT_XDisplayLocation);
    WebTelnetSendCommand(hWeb0, TELNET_CMD_WONT, TELNET_OPT_NewEnvironment);
    WebTelnetRecvSubNegotiation(hWeb0, TELNET_OPT_TerminalType);
    WebTelnetSendTerminalType(hWeb0, "vt100");
    WebTelnetRecvCommand(hWeb0, TELNET_CMD_WILL, TELNET_OPT_SuppressGoAhead);
    WebTelnetRecvCommand(hWeb0, TELNET_CMD_DO, TELNET_OPT_Echo);
    WebTelnetRecvCommand(hWeb0, TELNET_CMD_DO, TELNET_OPT_NegotiateWindowSize);
    WebTelnetRecvCommand(hWeb0, TELNET_CMD_WILL, TELNET_OPT_Status);
    WebTelnetRecvCommand(hWeb0, TELNET_CMD_DO, TELNET_OPT_RemoteFlowControl);
    WebTelnetSendCommand(hWeb0, TELNET_CMD_DO, TELNET_OPT_SuppressGoAhead);
    WebTelnetSendCommand(hWeb0, TELNET_CMD_WONT, TELNET_OPT_Echo);
    WebTelnetSendCommand(hWeb0, TELNET_CMD_WILL, TELNET_OPT_NegotiateWindowSize);
    WebTelnetSendSubNegotiation(hWeb0, TELNET_OPT_NegotiateWindowSize, "\h00500018");
    WebTelnetSendCommand(hWeb0, TELNET_CMD_DONT, TELNET_OPT_Status);
    WebTelnetSendCommand(hWeb0, TELNET_CMD_WONT, TELNET_OPT_RemoteFlowControl);
    WebTelnetRecvCommand(hWeb0, TELNET_CMD_WILL, TELNET_OPT_Echo);
    WebTcpipGetPacketBoundary(hWeb0, sBoundary);
    WebTcpipRecvPacketsUntilData(hWeb0, "login: ");
    WebTelnetTypeKeys(hWeb0, StrToHostCP("leo"), 359.3, TELNET_FLAG_CASE_SENSITIVE);
    WebTcpipSendBin(hWeb0, "\h0D00");
    WebTcpipScreenRecvPacketsUntilCursor(hWeb0, 1, 21, sBuffer);
    WebTcpipSendBin(hWeb0, "\h0D000D0A");
    WebTcpipRecvPackets(hWeb0, NULL, 3);
    WebTcpipSendBin(hWeb0, "\h0D00");
    WebTcpipSendPacket(hWeb0, StrToHostCP("8") + "\h0D00");
    WebTcpipRecvClose(hWeb0, NULL);
    WebTcpipShutdown(hWeb0);
  end TMain;
Parent topic: Web TCP/IP Functions
Related reference
WebTcpipConnect Function
WebTcpipSetTelnetMode Function


WebTcpipScreenRecvPacketsUntilField Function

Action

Receives data from a given connection until the rendered screen contains a specified field. This function is only valid on open connections that have a screen renderer associated with them and define fields via an underlying protocol, as is the case with Telnet connections.

Include file

WebAPI.bdh

Syntax

WebTcpipScreenRecvPacketsUntilField(    in  hWeb        : number,
                                        in  nFieldIndex : number,
                                        in  sText       : string,
                                        in  nOptions    : number optional,
                                        in  nMaxLen     : number optional,
                                        out sRecv       : string optional ) : boolean;

Return value

  • true if the operation was successful and data was received until given text was found in give field

  • false otherwise

Parameter | Description
hWeb | Valid handle to a Web connection created by WebTcpipConnect. Web connection must be in Telnet mode (by a previous WebTcpipSetTelnetMode function call) and have a screen renderer associated with it.
nFieldIndex | Field index to which content from sText should be compared (1 based).
sText | Text value that should be compared against the field value.
nOptions

By default the retrieved content has to be equal with the compared sVerify string, case-insensitively (optional). Comparison options are:

  • TELNET_FLAG_EQUAL: Comparison is made against both whole strings. (default)

  • TELNET_FLAG_CASE_SENSITIVE: Perform comparison case-sensitively.

  • TELNET_FLAG_IS_DIFFERENT: Negates the logical comparison.

  • TELNET_FLAG_IGNORE_WHITE_SPACE: All whitespaces in both compared strings are cut before comparison is performed.

  • TELNET_FLAG_CONTAINS: Compared string must occur within the retrieved content.

  • TELNET_FLAG_FROM_LEFT: The retrieved content only has to begin with the compared string.

  • TELNET_FLAG_TRIM_LEFT: Leading blanks are trimmed from retrieved content before comparison.

  • TELNET_FLAG_TRIM_RIGHT: Trailing blanks are trimmed from retrieved content before comparison.

  • TELNET_FLAG_TRIM_BOTH: Rendered text is trimmed from both sides before comparison.

  • TELNET_FLAG_FROM_RIGHT: Comparison is made from the right of the retrieved content.
nMaxLen | Maximum field value length for comparison (optional). This is generally the length of sText.
sRecv | Output buffer for all binary data received from the connection until sText matches the rendered field, including the last received packet that produces the desired screen content (optional).

Example

dcltrans
transaction TInit
  begin
    StrSetHostCP(1148);
// 1148  (IBM EBCDIC - International (500 + Euro))
  end TInit;
   transaction TMain
  var
    hWeb0     : number;
    iFieldPos : number;
  begin
    WebTcpipConnect(hWeb0, "My.TelnetHost.IP", WEB_PORT_TELNET);
// Port: 23
    WebTcpipSetTelnetMode(hWeb0, TERMINAL_TYPE_3270, 80, 24, true, TELNET_MODEOPT_RFC_1576 | TELNET_MODEOPT_AUTO_RECV);
    WebTelnetRecvCommand(hWeb0, TELNET_CMD_DO, TELNET_OPT_TerminalType);
    WebTelnetSendCommand(hWeb0, TELNET_CMD_WILL, TELNET_OPT_TerminalType);
    WebTelnetRecvSubNegotiation(hWeb0, TELNET_OPT_TerminalType);
    WebTelnetSendTerminalType(hWeb0, "IBM-3278-2-E");
    WebTelnetRecvCommand(hWeb0, TELNET_CMD_DO, TELNET_OPT_EndOfRecord);
    WebTelnetRecvCommand(hWeb0, TELNET_CMD_WILL, TELNET_OPT_EndOfRecord);
    WebTelnetRecvCommand(hWeb0, TELNET_CMD_DO, TELNET_OPT_TransmitBinary);
    WebTelnetRecvCommand(hWeb0, TELNET_CMD_WILL, TELNET_OPT_TransmitBinary);
    WebTelnetSendCommand(hWeb0, TELNET_CMD_WILL, TELNET_OPT_EndOfRecord);
    WebTelnetSendCommand(hWeb0, TELNET_CMD_DO, TELNET_OPT_EndOfRecord);
    WebTelnetSendCommand(hWeb0, TELNET_CMD_WILL, TELNET_OPT_TransmitBinary);
    WebTelnetSendCommand(hWeb0, TELNET_CMD_DO, TELNET_OPT_TransmitBinary);
    WebTelnetRecvCommand(hWeb0, TELNET_CMD_DO, TELNET_OPT_TransmitBinary);
    WebTelnetRecvCommand(hWeb0, TELNET_CMD_WILL, TELNET_OPT_TransmitBinary);
    WebTelnetRecvRecord(hWeb0);
    WebTelnetRecvRecord(hWeb0);
    WebTelnetSendRecord(hWeb0,
      "\h88001181A600000B0100005000180050" // ····¦······P···P 00000000

      "\h001800168186000800F4F1F1F2F2F3F3" // ·········ôññòòóó 00000010

      "\hF4F4F5F5F6F6F7F7000D81870400F0F1" // ôôõõöö÷÷······ðñ 00000020

      "\hF1F2F2F4F40007818800010200178181" // ñòòôô··········· 00000030

      "\h01000050001801000100030004000909" // ···P············ 00000040

      "\h0C0780001B81858200090C0000000007" // ················ 00000050

      "\h00000002B900250100F103C301360006" // ····¹·%··ñ·Ã·6·· 00000060

      "\h81990000001281970000080008000101" // ················ 00000070

      "\h000B0401C0C1000981A80200F0FFFFFF" // ····ÀÁ···¨··ð··· 00000080

      "\hFF000C81950000081108110101000F81" // ················ 00000090

      "\h80A687888185869997A89580");  // ·¦·······¨··     000000A0
    WebTelnetRecvRecord(hWeb0);
    WebTcpipRecvPackets(hWeb0);
    WebTelnetRecvRecord(hWeb0);
    WebTelnetSendRecord(hWeb0, "\h7D5B6F115B6F" + StrToHostCP("1"));
    WebTcpipScreenRecvPacketsUntilStatus(hWeb0, "Keyboard Locked", "false");
    WebTelnetSendRecord(hWeb0, "\h7D5BF0115BF0" + StrToHostCP("12"));
    WebTcpipScreenRecvPacketsUntilText(hWeb0, 6, 22, "Choice: ");
    WebTelnetSendRecord(hWeb0, "\h7D5A5E115A5E" + StrToHostCP("12"));
    WebTcpipSetPacketBoundary(hWeb0, "\nFFEF");
    WebTcpipScreenRecvPacketsUntilField(hWeb0, 1, " ");
    iFieldPos := WebTelnetScreenGetFieldIndex(hWeb0,16, 22);
    if iFieldPos = 1 then
    WebTcpipShutdown(hWeb0);
    end;
  end TMain;
Parent topic: Web TCP/IP Functions
Related reference
WebTcpipConnect Function
WebTcpipSetTelnetMode Function


WebTcpipScreenRecvPacketsUntilStatus Function

Action

Receives data from a given connection until rendered screen signals a specified status. This function is only valid on open connections that have a screen renderer associated with them and define statuses by an underlying protocol, as is the case with Telnet connections.

Include file

WebAPI.bdh

Syntax

WebTcpipScreenRecvPacketsUntilStatus(    in  hWeb         : number,
                                         in  sStatusName  : string,
                                         in  sStatusValue : string,
                                         in  nOptions     : number optional,
                                         in  nMaxLen      : number optional,
                                         out sRecv        : string optional ) : boolean;

Return value

  • true if the operation was successful and data was received until specified status value was found

  • false otherwise

Parameter | Description
hWeb | Valid handle to a Web connection created by WebTcpipConnect. Web connection must be in Telnet mode (by a previous WebTcpipSetTelnetMode function call) and have a screen renderer associated with it.
sStatusName | Status identifier against which the content of sStatusValue should be compared. The only supported status is "Keyboard Locked".
sStatusValue | String value that the status value should be compared against. Valid strings are "true" and "false".
nOptions

By default the retrieved content has to be equal with the compared sVerify string, case-insensitively (optional). Comparison options are:

  • TELNET_FLAG_EQUAL: Comparison is made against both whole strings. (default)

  • TELNET_FLAG_CASE_SENSITIVE: Perform comparison case-sensitively.

  • TELNET_FLAG_IS_DIFFERENT: Negates the logical comparison.

  • TELNET_FLAG_IGNORE_WHITE_SPACE: All whitespaces in both compared strings are cut before comparison is performed.

  • TELNET_FLAG_CONTAINS: Compared string must occur within the retrieved content.

  • TELNET_FLAG_FROM_LEFT: The retrieved content only has to begin with the compared string.

  • TELNET_FLAG_TRIM_LEFT: Leading blanks are trimmed from retrieved content before comparison.

  • TELNET_FLAG_TRIM_RIGHT: Trailing blanks are trimmed from retrieved content before comparison.

  • TELNET_FLAG_TRIM_BOTH: Rendered text is trimmed from both sides before comparison.

  • TELNET_FLAG_FROM_RIGHT: Comparison is made from the right of the retrieved content.
nMaxLen | Maximum string length of the value to be compared (optional).
sRecv | Output buffer for all binary data received from the connection until sStatusValue matches the rendered field, including the last received packet that has the desired status value (optional).

Example

dcltrans
  transaction TInit
  begin
    StrSetHostCP(1148); // 1148  (IBM EBCDIC - International (500 + Euro))
  end TInit;

  transaction TMain
  var
    hWeb0     : number;
    iFieldPos : number;
  begin
    WebTcpipConnect(hWeb0, "My.TelnetHost.IP", WEB_PORT_TELNET); // Port: 23
    WebTcpipSetTelnetMode(hWeb0, TERMINAL_TYPE_3270, 80, 24, true, TELNET_MODEOPT_RFC_1576 | TELNET_MODEOPT_AUTO_RECV);
    WebTelnetRecvCommand(hWeb0, TELNET_CMD_DO, TELNET_OPT_TerminalType);
    WebTelnetSendCommand(hWeb0, TELNET_CMD_WILL, TELNET_OPT_TerminalType);
    WebTelnetRecvSubNegotiation(hWeb0, TELNET_OPT_TerminalType);
    WebTelnetSendTerminalType(hWeb0, "IBM-3278-2-E");
    WebTelnetRecvCommand(hWeb0, TELNET_CMD_DO, TELNET_OPT_EndOfRecord);
    WebTelnetRecvCommand(hWeb0, TELNET_CMD_WILL, TELNET_OPT_EndOfRecord);
    WebTelnetRecvCommand(hWeb0, TELNET_CMD_DO, TELNET_OPT_TransmitBinary);
    WebTelnetRecvCommand(hWeb0, TELNET_CMD_WILL, TELNET_OPT_TransmitBinary);
    WebTelnetSendCommand(hWeb0, TELNET_CMD_WILL, TELNET_OPT_EndOfRecord);
    WebTelnetSendCommand(hWeb0, TELNET_CMD_DO, TELNET_OPT_EndOfRecord);
    WebTelnetSendCommand(hWeb0, TELNET_CMD_WILL, TELNET_OPT_TransmitBinary);
    WebTelnetSendCommand(hWeb0, TELNET_CMD_DO, TELNET_OPT_TransmitBinary);
    WebTelnetRecvCommand(hWeb0, TELNET_CMD_DO, TELNET_OPT_TransmitBinary);
    WebTelnetRecvCommand(hWeb0, TELNET_CMD_WILL, TELNET_OPT_TransmitBinary);
    WebTelnetRecvRecord(hWeb0);
    WebTelnetRecvRecord(hWeb0);
    WebTelnetSendRecord(hWeb0,
      "\h88001181A600000B0100005000180050" // ····¦······P···P 00000000

      "\h001800168186000800F4F1F1F2F2F3F3" // ·········ôññòòóó 00000010

      "\hF4F4F5F5F6F6F7F7000D81870400F0F1" // ôôõõöö÷÷······ðñ 00000020

      "\hF1F2F2F4F40007818800010200178181" // ñòòôô··········· 00000030

      "\h01000050001801000100030004000909" // ···P············ 00000040

      "\h0C0780001B81858200090C0000000007" // ················ 00000050

      "\h00000002B900250100F103C301360006" // ····¹·%··ñ·Ã·6·· 00000060

      "\h81990000001281970000080008000101" // ················ 00000070

      "\h000B0401C0C1000981A80200F0FFFFFF" // ····ÀÁ···¨··ð··· 00000080
      "\hFF000C81950000081108110101000F81" // ················ 00000090

      "\h80A687888185869997A89580"); // ·¦·······¨·· 000000A0
    WebTelnetRecvRecord(hWeb0);
    WebTcpipRecvPackets(hWeb0);
    WebTelnetRecvRecord(hWeb0);
    WebTelnetSendRecord(hWeb0, "\h7D5B6F115B6F" + StrToHostCP("1"));
    WebTcpipScreenRecvPacketsUntilStatus(hWeb0, "Keyboard Locked", "false");
    WebTelnetSendRecord(hWeb0, "\h7D5BF0115BF0" + StrToHostCP("12"));
    WebTcpipScreenRecvPacketsUntilText(hWeb0, 6, 22, "Choice: ");
    WebTelnetSendRecord(hWeb0, "\h7D5A5E115A5E" + StrToHostCP("12"));
    WebTcpipSetPacketBoundary(hWeb0, "\nFFEF");
    WebTcpipScreenRecvPacketsUntilField(hWeb0, 1, " ");
    iFieldPos := WebTelnetScreenGetFieldIndex(hWeb0,16, 22);
    if iFieldPos = 1 then
     WebTcpipShutdown(hWeb0);
    end;
  end TMain;
Parent topic: Web TCP/IP Functions
Related reference
WebTcpipConnect Function
WebTcpipSetTelnetMode Function


WebTcpipScreenRecvPacketsUntilText Function

Action

Receives data from a given connection until rendered screen contains specified text. This function is only valid on open connections that have a screen renderer associated with them, as is the case with Telnet connections.

Include file

WebAPI.bdh

Syntax

WebTcpipScreenRecvPacketsUntilText(    in  hWeb        : number,
                                       in  nCol        : number,
                                       in  nRow        : number,
                                       in  sText       : string,
                                       in  nOptions    : number optional,
                                       in  nTextLength : number optional,
                                       out sRecv       : dstring optional ): boolean;

Return value

  • true if the operation was successful and data was received until specified text was rendered on screen

  • false otherwise

Parameter | Description
hWeb | Valid handle to a Web connection created by WebTcpipConnect. Web connection must be in Telnet mode (by a previous WebTcpipSetTelnetMode function call) and have a screen renderer associated with it.
nCol | Column on rendered screen at which position the text should be compared.
nRow | Row on rendered screen at which position the text should be compared.
sText | Text value that should be compared against the rendered screen.
nOptions

By default the retrieved content has to be equal with the compared sVerify string, case-insensitively (optional). Comparison options are:

  • TELNET_FLAG_EQUAL: Comparison is made against both whole strings. (default)

  • TELNET_FLAG_CASE_SENSITIVE: Perform comparison case-sensitively.

  • TELNET_FLAG_IS_DIFFERENT: Negates the logical comparison.

  • TELNET_FLAG_IGNORE_WHITE_SPACE: All whitespaces in both compared strings are cut before comparison is performed.

  • TELNET_FLAG_CONTAINS: Compared string must occur within the retrieved content.

  • TELNET_FLAG_FROM_LEFT: The retrieved content only has to begin with the compared string.

  • TELNET_FLAG_TRIM_LEFT: Leading blanks are trimmed from retrieved content before comparison.

  • TELNET_FLAG_TRIM_RIGHT: Trailing blanks are trimmed from retrieved content before comparison.

  • TELNET_FLAG_TRIM_BOTH: Rendered text is trimmed from both sides before comparison.

  • TELNET_FLAG_FROM_RIGHT: Comparison is made from the right of the retrieved content.
nTextLength | Length of rendered text that is to be compared (optional). By default this means the length of sText.
sRecv | Output buffer for all binary data received from the connection until sText matches rendered screen portion including the last received packet which produced the desired screen content (optional).

Example

dcltrans
  transaction TInit
  begin
    StrSetHostCP(1148);// 1148  (IBM EBCDIC - International(500 + Euro))
  end TInit;

  transaction TMain
  var
    hWeb0     : number;
    iFieldPos : number;
  begin
    WebTcpipConnect(hWeb0, "My.TelnetHost.IP", WEB_PORT_TELNET); // Port: 23
    WebTcpipSetTelnetMode(hWeb0, TERMINAL_TYPE_3270, 80, 24, true,TELNET_MODEOPT_RFC_1576 | TELNET_MODEOPT_AUTO_RECV);
    WebTelnetRecvCommand(hWeb0, TELNET_CMD_DO, TELNET_OPT_TerminalType);
    WebTelnetSendCommand(hWeb0, TELNET_CMD_WILL, TELNET_OPT_TerminalType);
    WebTelnetRecvSubNegotiation(hWeb0, TELNET_OPT_TerminalType);
    WebTelnetSendTerminalType(hWeb0, "IBM-3278-2-E");
    WebTelnetRecvCommand(hWeb0, TELNET_CMD_DO, TELNET_OPT_EndOfRecord);
    WebTelnetRecvCommand(hWeb0, TELNET_CMD_WILL, TELNET_OPT_EndOfRecord);
    WebTelnetRecvCommand(hWeb0, TELNET_CMD_DO, TELNET_OPT_TransmitBinary);
    WebTelnetRecvCommand(hWeb0, TELNET_CMD_WILL, TELNET_OPT_TransmitBinary);
    WebTelnetSendCommand(hWeb0, TELNET_CMD_WILL, TELNET_OPT_EndOfRecord);
    WebTelnetSendCommand(hWeb0, TELNET_CMD_DO, TELNET_OPT_EndOfRecord);
    WebTelnetSendCommand(hWeb0, TELNET_CMD_WILL, TELNET_OPT_TransmitBinary);
    WebTelnetSendCommand(hWeb0, TELNET_CMD_DO, TELNET_OPT_TransmitBinary);
    WebTelnetRecvCommand(hWeb0, TELNET_CMD_DO, TELNET_OPT_TransmitBinary);
    WebTelnetRecvCommand(hWeb0, TELNET_CMD_WILL, TELNET_OPT_TransmitBinary);
    WebTelnetRecvRecord(hWeb0);
    WebTelnetRecvRecord(hWeb0);
    WebTelnetSendRecord(hWeb0,

      "\h88001181A600000B0100005000180050" // ····¦······P···P 00000000

      "\h001800168186000800F4F1F1F2F2F3F3" // ·········ôññòòóó 00000010

      "\hF4F4F5F5F6F6F7F7000D81870400F0F1" // ôôõõöö÷÷······ðñ 00000020

      "\hF1F2F2F4F40007818800010200178181" // ñòòôô··········· 00000030

      "\h01000050001801000100030004000909" // ···P············ 00000040

      "\h0C0780001B81858200090C0000000007" // ················ 00000050

      "\h00000002B900250100F103C301360006" // ····¹·%··ñ·Ã·6·· 00000060

      "\h81990000001281970000080008000101" // ················ 00000070

      "\h000B0401C0C1000981A80200F0FFFFFF" // ····ÀÁ···¨··ð··· 00000080

      "\hFF000C81950000081108110101000F81" // ················ 00000090

      "\h80A687888185869997A89580");      // ·¦·······¨··    000000A0
    WebTelnetRecvRecord(hWeb0);
    WebTcpipRecvPackets(hWeb0);
    WebTelnetRecvRecord(hWeb0);
    WebTelnetSendRecord(hWeb0, "\h7D5B6F115B6F" + StrToHostCP("1"));
    WebTcpipScreenRecvPacketsUntilStatus(hWeb0, "Keyboard Locked", "false");
    WebTelnetSendRecord(hWeb0, "\h7D5BF0115BF0" + StrToHostCP("12"));
    WebTcpipScreenRecvPacketsUntilText(hWeb0, 6, 22, "Choice:");
    WebTelnetSendRecord(hWeb0, "\h7D5A5E115A5E" + StrToHostCP("12"));
    WebTcpipSetPacketBoundary(hWeb0, "\nFFEF");
    WebTcpipScreenRecvPacketsUntilField(hWeb0, 1, "");
    iFieldPos := WebTelnetScreenGetFieldIndex(hWeb0,16, 22);

    if iFieldPos = 1 then
      WebTcpipShutdown(hWeb0);
    end;
  end TMain;
Parent topic: Web TCP/IP Functions
Related reference
WebTcpipConnect Function
WebTcpipSetTelnetMode Function


WebTcpipSelect Function

Action

Checks if a subsequent WebTcpipRecv operation on the provided connection handle will block, or succeed immediately. If the timeout parameter is provided the function call waits until the subsequent WebTcpipRecv function will not block anymore or the timeout expires. A WebTcpipRecv operation succeeds, if data is available or the connection has been closed by the remote host.

Include file

WebAPI.bdh

Syntax

WebTcpipSelect( in hWeb     : number,
                in fTimeout : float ): boolean;

Return value

  • true if a subsequent WebTcpipRecv operation will not block.

  • false if the timeout expires.

Parameter | Description
hWeb | Valid handle to a Web connection that was created by WebTcpipConnect.
fTimeout | Time in seconds the WebTcpipSelect function will wait until the described condition occurs. If this condition cannot be met in the specified time, false is returned. (Default is 0, which means, that the WebTcpipSelect function will not block, regardless if it returns true or false). Specify TIMEOUT_INFINITE if you do not want a timeout to occur.

Example

dcltrans
  transaction TMain
  var
    hWeb : number;
    sResponse : string(1000);
  begin
    WebTcpipConnect(hWeb, "server", 80);
    WebTcpipSend(hWeb, "GET / HTTP/1.0\r\n\r\n");
    while not WebTcpipSelect(hWeb, 1.0) do
      print("no data yet ");
    end;
    WebTcpipRecvClose(hWeb, sResponse);
    WebTcpipShutdown(hWeb);
  end TMain;
Parent topic: Web TCP/IP Functions
Related reference
WebTcpipConnect Function


WebTcpipSend Function

Action

Sends a string to the remote host. Before WebTcpipSend can be used, a valid connection has to be established with WebTcpipConnect.

Include file

WebAPI.bdh

Syntax

WebTcpipSend( in hWeb          : number,
              in sStringToSend : string ): boolean;

Return value

  • true if the string is sent successfully

  • false otherwise

Parameter | Description
hWeb | Valid handle to a Web connection that was created by WebTcpipConnect
sStringToSend | String to send to the remote host

Example

dcltrans
  transaction TWebApplevel
  var
    hWeb : number;
    nRecv : number;
  begin
    // Get the root HTML page of the Web server defined
    // by standardhost with a custom client header
    WebTcpipConnect(hWeb, "standardhost", WEB_PORT_HTTP);
    WebTcpipSend(hWeb, "GET / HTTP/1.0\r\n"
                     "User-Agent: CustomClient/1.0\r\n"
                     "Accept: */*\r\n\r\n");
    WebTcpipRecvClose(hWeb, 0, 0, nRecv);
    WebTcpipShutdown(hWeb);
  end TWebApplevel;

Sample scripts

WebFileUpload01.bdf, WebMulti01.bdf, WebSecure01.bdf, WebTcpipHttp01.bdf, WebTcpipWebStone01.bdf

Parent topic: Web TCP/IP Functions
Related reference
WebTcpipConnect Function
WebTcpipRecv Function
WebTcpipRecvExact Function
WebTcpipRecvClose Function
WebTcpipRecvPackets Function
WebTcpipRecvPacketsUntilData Function
WebTcpipRecvProto Function
WebTcpipRecvUntil Function
WebTcpipRecvProtoEx Function
WebTcpipRecvUntilIdle Function


WebTcpipSendFile Function

Action

Sends the data of a file in binary mode to the remote host. Before WebTcpipSendFile can be used, a valid connection has to be established with WebTcpipConnect.

Include file

WebAPI.bdh

Syntax

WebTcpipSendFile( in hWeb      : number,
                  in sFileName : string ): boolean;

Return value

  • true if the file was sent successfully

  • false otherwise

Parameter | Description
hWeb | Valid handle to a Web connection that was created by WebTcpipConnect
sFileName | File to send to the server. The file is opened in binary mode and sent until end of file.

Example

dcltrans
transaction TWebApplevel
  var
    hWeb: number;
  begin
    WebTcpipConnect(hWeb, "standardhost", WEB_PORT_HTTP);
    WebTcpipSendFile(hWeb, "c:\\temp\\archive.zip");
    WebTcpipShutdown(hWeb);
  end TWebApplevel;

Sample scripts

WebFileUpload01.bdf

Parent topic: Web TCP/IP Functions
Related reference
WebTcpipConnect Function


WebTcpipSendBin Function

Action

Sends a string/buffer containing binary data to the remote host. Before WebTcpipSendBin can be used, a valid connection has to be established with WebTcpipConnect.

Include file

WebAPI.bdh

Syntax

WebTcpipSendBin ( in hWeb     : number,
                  in sData    : string,
                  in nDataLen : number optional ): boolean;

Return value

  • true if the data is sent successfully

  • false otherwise

Parameter | Description
hWeb | Valid handle to a Web connection that was created by WebTcpipConnect.
sData | String containing the data. For posting all available binary data specify STRING_COMPLETE for nDataLength and use the bin() operator for sData (see example).
nDataLen | Number of bytes to send to the server (optional) . Specify STRING_COMPLETE or omit this parameter to post all available data.

Example

dcltrans
  transaction TWebApplevel
  var
    hWeb  : number;
    sData : string;
  begin
    sData := "\h00010203040506070809101112131415";
    WebTcpipConnect(hWeb, "standardhost", 6644);
    WebTcpipSendBin(hWeb, bin(sData));
    WebTcpipShutdown(hWeb);
  end TWebApplevel;
Parent topic: Web TCP/IP Functions
Related reference
WebTcpipConnect Function


WebTcpipSendPacket Function

Action

Sends a single out-going packet to an open connection. A packet is defined as a TCP/IP packet (which equates to WebTcpipSend()) or as data terminated by a packet boundary, which is set by WebTcpipSetPacketBoundary()).

Include file

WebAPI.bdh

Syntax

WebTcpipSendPacket(    in hWeb  : number,
                       in sSend : string ): boolean;

Return value

  • true if the operation was successful and the data was sent

  • false otherwise

Parameter | Description
hWeb | Valid handle to a Web connection created by WebTcpipConnect.
sSend | Binary data to be sent to an open connection.

Example

dcltrans
  transaction TInit
  begin
    StrSetHostCP(28591); // 28591
(ISO 8859-1 Latin I)
  end TInit;   transaction   TMain
  var
    hWeb0     : number;
    sBuffer   : string;
    sBoundary : string;
    nOption   : number;
  begin
    WebTcpipConnect(hWeb0, "My.TelnetHost.IP", WEB_PORT_TELNET);
    WebTcpipSetTelnetMode(hWeb0, TERMINAL_TYPE_ANSI, 80, 24, true,
      TELNET_MODEOPT_RFC_1576 | TELNET_MODEOPT_AUTO_RECV);
    WebTelnetRecvCommand(hWeb0, TELNET_CMD_DO, TELNET_OPT_TerminalType);
    WebTelnetRecvCommand(hWeb0, TELNET_CMD_DO, TELNET_OPT_TerminalSpeed);
    WebTelnetRecvCommand(hWeb0, TELNET_CMD_DO, TELNET_OPT_XDisplayLocation);
    WebTelnetRecvCommand(hWeb0, TELNET_CMD_DO, TELNET_OPT_NewEnvironment);
    WebTelnetSendCommand(hWeb0, TELNET_CMD_WILL, TELNET_OPT_TerminalType);
    WebTelnetSendCommand(hWeb0, TELNET_CMD_WONT, TELNET_OPT_TerminalSpeed);
    WebTelnetSendCommand(hWeb0, TELNET_CMD_WONT, TELNET_OPT_XDisplayLocation);
    WebTelnetSendCommand(hWeb0, TELNET_CMD_WONT, TELNET_OPT_NewEnvironment);
    WebTelnetRecvSubNegotiation(hWeb0, TELNET_OPT_TerminalType);
    WebTelnetSendTerminalType(hWeb0, "vt100");
    WebTelnetRecvCommand(hWeb0, TELNET_CMD_WILL, TELNET_OPT_SuppressGoAhead);
    WebTelnetRecvCommand(hWeb0, TELNET_CMD_DO, TELNET_OPT_Echo);
    WebTelnetRecvCommand(hWeb0, TELNET_CMD_DO, TELNET_OPT_NegotiateWindowSize);
    WebTelnetRecvCommand(hWeb0, TELNET_CMD_WILL, TELNET_OPT_Status);
    WebTelnetRecvCommand(hWeb0, TELNET_CMD_DO, TELNET_OPT_RemoteFlowControl);
    WebTelnetSendCommand(hWeb0, TELNET_CMD_DO, TELNET_OPT_SuppressGoAhead);
    WebTelnetSendCommand(hWeb0, TELNET_CMD_WONT, TELNET_OPT_Echo);
    WebTelnetSendCommand(hWeb0, TELNET_CMD_WILL, TELNET_OPT_NegotiateWindowSize);
    WebTelnetSendSubNegotiation(hWeb0, TELNET_OPT_NegotiateWindowSize, "\h00500018");
    WebTelnetSendCommand(hWeb0, TELNET_CMD_DONT, TELNET_OPT_Status);
    WebTelnetSendCommand(hWeb0, TELNET_CMD_WONT, TELNET_OPT_RemoteFlowControl);
    WebTelnetRecvCommand(hWeb0, TELNET_CMD_WILL, TELNET_OPT_Echo);
    WebTcpipGetPacketBoundary(hWeb0, sBoundary);
    WebTcpipRecvPacketsUntilData(hWeb0, "login: ");
    WebTelnetTypeKeys(hWeb0, StrToHostCP("leo"), 359.3, TELNET_FLAG_CASE_SENSITIVE);
    WebTcpipSendBin(hWeb0, "\h0D00");
    WebTcpipRecvExact(hWeb0, NULL, 390);
    WebTcpipSetPacketBoundary(hWeb0, sBoundary);
    WebTcpipRecvUntilIdle(hWeb0,NULL, 5000);
    WebTcpipSendBin(hWeb0, "\h0D000D0A");
    WebTcpipRecvPackets(hWeb0, NULL, 3);
    WebTcpipSendBin(hWeb0, "\h0D00");
    WebTcpipSendPacket(hWeb0, StrToHostCP("8") + "\h0D00");
    WebTcpipRecvClose(hWeb0, NULL);
    WebTcpipShutdown(hWeb0);
  end TMain;
Parent topic: Web TCP/IP Functions
Related reference
WebTcpipConnect Function
WebTcpipSetPacketBoundary Function
WebTcpipRecvPackets Function
WebTcpipSend Function


WebTcpipSetOptions Function

Action

Sets a TCP/IP connection’s specific options.

Include file

WebAPI.bdh

Syntax

WebTcpipSetOptions(    in hWeb           : number,
                       in nOptions       : number,
                       in bEnable        : boolean optional,
                       in sAutoReplyData : string optional ): boolean;

Return value

  • true if the operation succeeded

  • false otherwise

Parameter | Description
hWeb | Valid handle to a Web connection created by WebTcpipConnect.
nOptions

Connection behavior settings, which may be any bitwise combination of the following:

  • TELNET_MODEOPT_FILTER_NOPS := 0x0001;

  • TELNET_MODEOPT_AUTOANSWER_TM := 0x0002;

  • TELNET_MODEOPT_FILTER_TM := 0x0004;

  • TELNET_MODEOPT_RFC_1576 := 0x0007;

  • TELNET_MODEOPT_AUTO_RECV := 0x0018;

  • TELNET_MODEOPT_SYNC := 0x0020;

  • TELNET_MODEOPT_3270E_AUTO_REPLY := 0x0040;

See WebTcpipSetTelnetMode for details.
bEnable | In case this parameter is present, a single option can be turned on/off without affecting the other options (optional). In case this parameter is omitted, the nOptions parameter sets all available options according to its bitmask.
sAutoReplyData | In combination with TELNET_MODEOPT_3270E_AUTO_REPLY an auto-reply string to the server may be specified here, which is by default a NULL byte - 0x0 (optional).

Example

dcltrans
  transaction TInit
  begin
    StrSetHostCP(28591); // 28591
(ISO 8859-1 Latin I)
  end TInit;   transaction   TMain
  var
    hWeb0     : number;
    sBuffer   : string;
    sBoundary : string;
    nOption   : number;
  begin
    WebTcpipConnect(hWeb0, "My.TelnetHost.IP", WEB_PORT_TELNET);
    WebTcpipSetTelnetMode(hWeb0, TERMINAL_TYPE_ANSI, 80, 24, true,
      TELNET_MODEOPT_AUTO_RECV);
    WebTcpipGetOptions(hWeb0, nOption);
    if nOption <> TELNET_MODEOPT_RFC_1576 then
      WebTcpipSetOptions(hWeb0, TELNET_MODEOPT_RFC_1576);
    end;
    WebTelnetRecvCommand(hWeb0, TELNET_CMD_DO, TELNET_OPT_TerminalType);
    WebTelnetRecvCommand(hWeb0, TELNET_CMD_DO, TELNET_OPT_TerminalSpeed);
    WebTelnetRecvCommand(hWeb0, TELNET_CMD_DO, TELNET_OPT_XDisplayLocation);
    WebTelnetRecvCommand(hWeb0, TELNET_CMD_DO, TELNET_OPT_NewEnvironment);
    WebTelnetSendCommand(hWeb0, TELNET_CMD_WILL, TELNET_OPT_TerminalType);
    WebTelnetSendCommand(hWeb0, TELNET_CMD_WONT, TELNET_OPT_TerminalSpeed);
    WebTelnetSendCommand(hWeb0, TELNET_CMD_WONT, TELNET_OPT_XDisplayLocation);
    WebTelnetSendCommand(hWeb0, TELNET_CMD_WONT, TELNET_OPT_NewEnvironment);
    WebTelnetRecvSubNegotiation(hWeb0, TELNET_OPT_TerminalType);
    WebTelnetSendTerminalType(hWeb0, "vt100");
    WebTelnetRecvCommand(hWeb0, TELNET_CMD_WILL, TELNET_OPT_SuppressGoAhead);
    WebTelnetRecvCommand(hWeb0, TELNET_CMD_DO, TELNET_OPT_Echo);
    WebTelnetRecvCommand(hWeb0, TELNET_CMD_DO, TELNET_OPT_NegotiateWindowSize);
    WebTelnetRecvCommand(hWeb0, TELNET_CMD_WILL, TELNET_OPT_Status);
    WebTelnetRecvCommand(hWeb0, TELNET_CMD_DO, TELNET_OPT_RemoteFlowControl);
    WebTelnetSendCommand(hWeb0, TELNET_CMD_DO, TELNET_OPT_SuppressGoAhead);
    WebTelnetSendCommand(hWeb0, TELNET_CMD_WONT, TELNET_OPT_Echo);
    WebTelnetSendCommand(hWeb0, TELNET_CMD_WILL, TELNET_OPT_NegotiateWindowSize);
    WebTelnetSendSubNegotiation(hWeb0, TELNET_OPT_NegotiateWindowSize, "\h00500018");
    WebTelnetSendCommand(hWeb0, TELNET_CMD_DONT, TELNET_OPT_Status);
    WebTelnetSendCommand(hWeb0, TELNET_CMD_WONT, TELNET_OPT_RemoteFlowControl);
    WebTelnetRecvCommand(hWeb0, TELNET_CMD_WILL, TELNET_OPT_Echo);
    WebTcpipGetPacketBoundary(hWeb0, sBoundary);
    WebTcpipRecvPacketsUntilData(hWeb0, "login: ");
    WebTelnetTypeKeys(hWeb0, StrToHostCP("leo"), 359.3, TELNET_FLAG_CASE_SENSITIVE);
    WebTcpipSendBin(hWeb0, "\h0D00");
    WebTcpipRecvExact(hWeb0, NULL, 390);
    WebTcpipSetPacketBoundary(hWeb0, sBoundary);
    WebTcpipRecvUntilIdle(hWeb0, NULL, 5000);
    WebTcpipSendBin(hWeb0, "\h0D000D0A");
    WebTcpipRecvPackets(hWeb0, NULL, 3);
    WebTcpipSendBin(hWeb0, "\h0D00");
    WebTcpipSendPacket(hWeb0, StrToHostCP("8") + "\h0D00");
    WebTcpipRecvClose(hWeb0, NULL);
    WebTcpipShutdown(hWeb0);
  end TMain;
Parent topic: Web TCP/IP Functions
Related reference
WebTcpipConnect Function
WebTcpipGetOptions Function
WebTcpipSetTelnetMode Function


WebTcpipSetPacketBoundary Function

Action

Sets a packet boundary for an existing connection and is used to split in-coming and out-going data when using WebTcpipRecvPackets and WebTcpipSendPacket functions. By default, each “packet” consists of a TCP/IP packet. So, in effect, the packet boundary is set to NULL.

Include file

WebAPI.bdh

Syntax

WebTcpipSetPacketBoundary(    in hWeb      : number,
                              in sBoundary : string ): boolean;

Return value

  • true if the operation was successful

  • false otherwise

Parameter | Description
hWeb | Valid handle to a Web connection created by WebTcpipConnect.
sBoundary | Binary string representing the new packet boundary. If NULL is passed as a parameter, a raw TCP/IP packet is recognized as a packet.

Example

dcltrans
  transaction TInit
  begin
    StrSetHostCP(28591); // 28591 (ISO 8859-1 Latin I)
  end TInit;
transaction   TMain
  var
    hWeb0     : number;
    sBuffer   : string;
    sBoundary : string;
    nOption   : number;
  begin
    WebTcpipConnect(hWeb0, "My.TelnetHost.IP", WEB_PORT_TELNET);
    WebTcpipSetTelnetMode(hWeb0, TERMINAL_TYPE_ANSI, 80, 24, true,
      TELNET_MODEOPT_RFC_1576);

    WebTelnetRecvCommand(hWeb0, TELNET_CMD_DO, TELNET_OPT_TerminalType);
    WebTelnetRecvCommand(hWeb0, TELNET_CMD_DO, TELNET_OPT_TerminalSpeed);
    WebTelnetRecvCommand(hWeb0, TELNET_CMD_DO, TELNET_OPT_XDisplayLocation);
    WebTelnetRecvCommand(hWeb0, TELNET_CMD_DO, TELNET_OPT_NewEnvironment);
    WebTelnetSendCommand(hWeb0, TELNET_CMD_WILL, TELNET_OPT_TerminalType);
    WebTelnetSendCommand(hWeb0, TELNET_CMD_WONT, TELNET_OPT_TerminalSpeed);
    WebTelnetSendCommand(hWeb0, TELNET_CMD_WONT, TELNET_OPT_XDisplayLocation);
    WebTelnetSendCommand(hWeb0, TELNET_CMD_WONT, TELNET_OPT_NewEnvironment);
    WebTelnetRecvSubNegotiation(hWeb0, TELNET_OPT_TerminalType);
    WebTelnetSendTerminalType(hWeb0, "vt100");
    WebTelnetRecvCommand(hWeb0, TELNET_CMD_WILL, TELNET_OPT_SuppressGoAhead);
    WebTelnetRecvCommand(hWeb0, TELNET_CMD_DO, TELNET_OPT_Echo);
    WebTelnetRecvCommand(hWeb0, TELNET_CMD_DO, TELNET_OPT_NegotiateWindowSize);
    WebTelnetRecvCommand(hWeb0, TELNET_CMD_WILL, TELNET_OPT_Status);
    WebTelnetRecvCommand(hWeb0, TELNET_CMD_DO, TELNET_OPT_RemoteFlowControl);
    WebTelnetSendCommand(hWeb0, TELNET_CMD_DO, TELNET_OPT_SuppressGoAhead);
    WebTelnetSendCommand(hWeb0, TELNET_CMD_WONT, TELNET_OPT_Echo);
    WebTelnetSendCommand(hWeb0, TELNET_CMD_WILL, TELNET_OPT_NegotiateWindowSize);
    WebTelnetSendSubNegotiation(hWeb0, TELNET_OPT_NegotiateWindowSize, "\h00500018");
    WebTelnetSendCommand(hWeb0, TELNET_CMD_DONT, TELNET_OPT_Status);
    WebTelnetSendCommand(hWeb0, TELNET_CMD_WONT, TELNET_OPT_RemoteFlowControl);
    WebTelnetRecvCommand(hWeb0, TELNET_CMD_WILL, TELNET_OPT_Echo);
    WebTcpipGetPacketBoundary(hWeb0, sBoundary);
    WebTcpipRecvPacketsUntilData(hWeb0, "login: ");
    WebTelnetTypeKeys(hWeb0, StrToHostCP("leo"), 359.3, TELNET_FLAG_CASE_SENSITIVE);
    WebTcpipSendBin(hWeb0, "\h0D00");
    WebTcpipRecvExact(hWeb0, NULL, 390);
    WebTcpipRecvUntilIdle(hWeb0, NULL, 5000);
    WebTcpipSendBin(hWeb0, "\h0D000D0A");
    WebTcpipRecvPackets(hWeb0, NULL, 3);
    WebTcpipSendBin(hWeb0, "\h0D00");
    WebTcpipSetPacketBoundary(hWeb0, "\h0D00");
    WebTcpipSendPacket(hWeb0, StrToHostCP("8") + "\h0D00");
    WebTcpipSetPacketBoundary(hWeb0, sBoundary);
    WebTcpipRecvClose(hWeb0, NULL);
    WebTcpipShutdown(hWeb0);
  end TMain;
Parent topic: Web TCP/IP Functions
Related reference
WebTcpipConnect Function
WebTcpipGetPacketBoundary Function
WebTcpipRecvPackets Function
WebTcpipSendPacket Function


WebTcpipSetTelnetMode Function

Action

Switches pure TCP/IP connection mode to Telnet connection mode. Telnet connections allow several Telnet protocol-specific BDL operations for terminal emulation support.

Include file

WebAPI.bdh

Syntax

WebTcpipSetTelnetMode(    in hWeb        : number,
                          in sRendererId : string,
                          in nCols       : number optional,
                          in nRows       : number optional,
                          in bUseColor   : number optional,
                          in nOptions    : number optional ): boolean;

Return value

  • true if the operation was successful

  • false otherwise

Parameter | Description
hWeb | Valid handle to a Web connection created by WebTcpipConnect.
sRendererId

ID of a renderer that should be used when handling high-level Telnet functions. Currently defined rendererIds are:

  • TELNET_RENDERER_3270: Connection drives a 3270 terminal service renderer.

  • TELNET_RENDERER_5250: Connection drives a 5250 terminal service renderer.

  • TELNET_RENDERER_ANSI: Connection drives an ANSI terminal service renderer (VT100 Terminal Client Series).

  • TELNET_RENDERER_VT200: Connection drives an ANSI terminal service renderer (VT200 Terminal Client Series).
nCols | Rendered screen width (optional). Default (0) value is read from profile settings.
nRows | Rendered screen height (optional). Default (0) value is read from profile settings.
bUseColors | Specifies if rendered screen should be displayed in color (optional). Default is false.
nOptions

Specific Telnet service protocol option (optional). Currently the following options are available and can be ORed (+ operator):

  • TELNET_MODEOPT_FILTER_NOPS: According to RFC 1576, a host server periodically sends an IAC NOP sequence to test its connection status. These operations may be auto-filtered before getting to further BDL operations because in most cases they are sent periodically and not in the same command sequence order.

  • TELNET_MODEOPT_AUTOANSWER_TM: According to RFC 1576, a host server may periodically send an IAC DO TimingMark sequence, awaiting a IAC WONT TimingMark response, for checking availability of the telnet client. Because these signals are sent periodically and not in a defined sequence order, they may be filtered and auto-answered in the background by the connection itself.

  • TELNET_MODEOPT_RFC_1576: This option is an OR-combination of both TELNET_MODEOPT_FILTER_NOPS and TELNET_MODEOPT_AUTOANSWER_TM.

  • TELNET_MODEOPT_AUTO_RECV: For writing more robust scripts for telnet servers sending time-dependent dynamic information (e.g., server time), each send operation empties the receive buffer.

  • TELNET_MODEOPT_SYNC: For writing more robust scripts for telnet servers sending negotiating Telnet options in a non- or partly deterministic manner, expected commands, option negotiation or data may be noted. All expected data is then verified at next sending function and prepended to the data of the next receiving function. See WebTelnetSyncCommand, WebTelnetSyncSubNegotiation, and WebTelnetSyncData for details.

  • TELNET_MODEOPT_3270E_AUTO_REPLY: Enable this option for writing more robust scripts for Telnet servers using the 3270E protocol. Such servers require a client confirmation after each response, which may be individually set using WebTcpipSetOptions.

Example

dcltrans
  transaction TInit
  begin
    StrSetHostCP(28591); // 28591 (ISO 8859-1 Latin I)
  end TInit;
transaction TMain
  var
    hWeb0     : number;
    sBuffer   : string;
    sBoundary : string;
    nOption   : number;
  begin
    WebTcpipConnect(hWeb0, "My.TelnetHost.IP", WEB_PORT_TELNET);
    WebTcpipSetTelnetMode(hWeb0, TERMINAL_TYPE_ANSI, 80, 24, true,
      TELNET_MODEOPT_RFC_1576 | TELNET_MODEOPT_AUTO_RECV);

    WebTelnetRecvCommand(hWeb0, TELNET_CMD_DO, TELNET_OPT_TerminalType);
    WebTelnetRecvCommand(hWeb0, TELNET_CMD_DO, TELNET_OPT_TerminalSpeed);
    WebTelnetRecvCommand(hWeb0, TELNET_CMD_DO, TELNET_OPT_XDisplayLocation);
    WebTelnetRecvCommand(hWeb0, TELNET_CMD_DO, TELNET_OPT_NewEnvironment);
    WebTelnetSendCommand(hWeb0, TELNET_CMD_WILL, TELNET_OPT_TerminalType);
    WebTelnetSendCommand(hWeb0, TELNET_CMD_WONT, TELNET_OPT_TerminalSpeed);
    WebTelnetSendCommand(hWeb0, TELNET_CMD_WONT, TELNET_OPT_XDisplayLocation);
    WebTelnetSendCommand(hWeb0, TELNET_CMD_WONT, TELNET_OPT_NewEnvironment);
    WebTelnetRecvSubNegotiation(hWeb0, TELNET_OPT_TerminalType);
    WebTelnetSendTerminalType(hWeb0, "vt100");
    WebTelnetRecvCommand(hWeb0, TELNET_CMD_WILL, TELNET_OPT_SuppressGoAhead);
    WebTelnetRecvCommand(hWeb0, TELNET_CMD_DO, TELNET_OPT_Echo);
    WebTelnetRecvCommand(hWeb0, TELNET_CMD_DO, TELNET_OPT_NegotiateWindowSize);
    WebTelnetRecvCommand(hWeb0, TELNET_CMD_WILL, TELNET_OPT_Status);
    WebTelnetRecvCommand(hWeb0, TELNET_CMD_DO, TELNET_OPT_RemoteFlowControl);
    WebTelnetSendCommand(hWeb0, TELNET_CMD_DO, TELNET_OPT_SuppressGoAhead);
    WebTelnetSendCommand(hWeb0, TELNET_CMD_WONT, TELNET_OPT_Echo);
    WebTelnetSendCommand(hWeb0, TELNET_CMD_WILL, TELNET_OPT_NegotiateWindowSize);
    WebTelnetSendSubNegotiation(hWeb0, TELNET_OPT_NegotiateWindowSize, "\h00500018");
    WebTelnetSendCommand(hWeb0, TELNET_CMD_DONT, TELNET_OPT_Status);
    WebTelnetSendCommand(hWeb0, TELNET_CMD_WONT, TELNET_OPT_RemoteFlowControl);
    WebTelnetRecvCommand(hWeb0, TELNET_CMD_WILL, TELNET_OPT_Echo);
    WebTcpipGetPacketBoundary(hWeb0, sBoundary);
    WebTcpipRecvPacketsUntilData(hWeb0, "login: ");
    WebTelnetTypeKeys(hWeb0, StrToHostCP("leo"), 359.3, TELNET_FLAG_CASE_SENSITIVE);
    WebTcpipSendBin(hWeb0, "\h0D00");
    WebTcpipRecvExact(hWeb0, NULL, 390);
    WebTcpipSetPacketBoundary(hWeb0, sBoundary);
    WebTcpipRecvUntilIdle(hWeb0, NULL, 5000);
    WebTcpipSendBin(hWeb0, "\h0D000D0A");
    WebTcpipRecvPackets(hWeb0, NULL, 3);
    WebTcpipSendBin(hWeb0, "\h0D00");
    WebTcpipSendPacket(hWeb0, StrToHostCP("8") + "\h0D00");
    WebTcpipRecvClose(hWeb0, NULL);
    WebTcpipShutdown(hWeb0);
  end TMain;
Parent topic: Web TCP/IP Functions
Related reference
WebTcpipConnect Function


WebTcpipShutdown Function

Action

Shuts down the connection established by WebTcpipConnect.

Include file

WebAPI.bdh

Syntax

WebTcpipShutdown( inout hWeb  : number,
                  in    nMode : number optional ): boolean;

Return value

  • true if the shutdown succeeded

  • false otherwise

Parameter | Description
hWeb | Valid handle to a Web connection that was created by WebTcpipConnect
nMode

Determines the shutdown mode (optional). Any of the following options is possible:

  • WEB_SHUTDOWN_GRACEFUL. Initiates a graceful shutdown: first closes and then resets the connection

  • WEB_SHUTDOWN_IMMEDIATE. Initiates a standard connection close (default)

  • WEB_SHUTDOWN_RESET. Resets the connection

Example

dcltrans
  transaction TWeb
  var
    hWeb      : number;
    sHdr      : string;
    sSize     : string(20);
    nReceived : number;
  begin    WebTcpipConnect(hWeb, "lab3", 80);
    sHdr := "GET /file5k.html HTTP/1.1\r\n"
                  "Host: lab3\r\n\r\n";

    // send HTTP request header
    WebTcpipSend(hWeb, sHdr);

    // receive HTTP response header
    WebTcpipRecvUntil(hWeb, sHdr, STRING_COMPLETE,
                      nReceived, "\r\n\r\n");

    // receive document
    StrSearchDelimited(sSize, STRING_COMPLETE, sHdr,
                       "Content-Length: ",1,"\r\n",
                       1, STR_SEARCH_FIRST);
    WebTcpipRecvExact(hWeb, NULL, number(sSize));

    // reset the persistent connection
    WebTcpipShutdown(hWeb, WEB_SHUTDOWN_RESET);
  end TWeb;

Sample scripts

WebFileUpload01.bdf, WebMulti01.bdf, WebSecure01.bdf, WebTcpipHttp11.bdf, WebTcpipWebStone01.bdf

Parent topic: Web TCP/IP Functions
Related reference
WebTcpipConnect Function


WebTcpipSSLHandshake Function

Action

Performs a secure handshake on an open connection. This function can be used if some insecure communication has to be done before the connection should turn into a secure connection (e.g. secure traffic over a http proxy).

Include file

WebAPI.bdh

Syntax

WebTcpipSSLHandshake( in hWeb : number ): boolean;

Return value

  • true if the function succeeds.

  • false otherwise.

Parameter | Description
hWeb | Valid handle to a Web connection that was created by WebTcpipConnect.

Example

dcltrans
  transaction TMain
  var
    hWeb      : number;
    sResponse : string;
    nRecvd    : number;
  begin
    WebTcpipConnect(hWeb, "proxy", 8080);
    WebTcpipSend(hWeb, "CONNECT lab3:443\r\n\r\n");
    WebTcpipRecvUntil(hWeb, sResponse, STRING_COMPLETE, nRecvd, WEB_CRLFCRLF);
    WebTcpipSSLHandshake(hWeb);    WebTcpipSend(hWeb, "GET / HTTP/1.0\r\n\r\n");
    WebTcpipRecvClose(hWeb);
    WebTcpipShutdown(hWeb);
  end TMain;
Parent topic: Web TCP/IP Functions
Related reference
WebTcpipConnect Function


Web Telnet Functions

Silk Performer provides functions for testing applications that use the Web telnet protocol.

  • WebTelnetRecvCommand Function
    Receives a Telnet command from a Telnet connection.
  • WebTelnetRecvRecord Function
    Receives a Telnet record sequence from a terminal service server, which is a shortcut to <BinaryData> IAC EOR.
  • WebTelnetRecvRecordsUntilClose Function
    Receives data (packets terminated by IAC EOR) from a given connection until the Telnet connection is closed.
  • WebTelnetRecvRecordsUntilData Function
    Receives records (data terminated by IAC EOR) from a Telnet server until a record contains expected data.
  • WebTelnetRecvSubNegotiation Function
    Receives a Telnet option sub-negotiation sequence from a terminal service server, which is a shortcut to IAC SB <Option> <Data> IAC SE.
  • WebTelnetScreenGetCursor Function
    Queries cursor position on a rendered screen in an active Telnet connection.
  • WebTelnetScreenGetField Function
    Queries a rendered screen’s field value in an active Telnet connection.
  • WebTelnetScreenGetFieldCount Function
    Returns total number of fields in currently rendered screen in an active Telnet connection.
  • WebTelnetScreenGetFieldIndex Function
    Returns the index of a field in an open Telnet connection at a given position.
  • WebTelnetScreenGetFieldProperties Function
    Queries a rendered field’s attributes in an active Telnet connection.
  • WebTelnetScreenGetSize Function
    Queries rendered screen’s size in an active Telnet connection.
  • WebTelnetScreenGetStatus Function
    Queries rendered screen’s status value in an active Telnet connection.
  • WebTelnetScreenGetText Function
    Queries rendered screen content in an active Telnet connection.
  • WebTelnetScreenRecvRecordsUntilCursor Function
    Receives records (data terminated by IAC EOR) from a Telnet server until cursor is detected at a specified position.
  • WebTelnetScreenRecvRecordsUntilField Function
    Receives data (packets terminated by IAC EOR) from a given connection until the rendered screen contains a specified field.
  • WebTelnetScreenRecvRecordsUntilStatus Function
    Receives data (packets terminated by IAC EOR) from a given connection until the rendered screen contains a specified status.
  • WebTelnetScreenRecvRecordsUntilText Function
    Receives data (packets terminated by IAC EOR) from a given connection until the rendered screen contains specified text.
  • WebTelnetScreenVerifyCursor Function
    Verifies cursor position in a rendered screen in an active Telnet connection.
  • WebTelnetScreenVerifyField Function
    Verifies field content in a rendered screen in an active Telnet connection.
  • WebTelnetScreenVerifyStatus Function
    Verifies the status value of a rendered screen in an active Telnet connection.
  • WebTelnetScreenVerifyText Function
    Verifies rendered screen content in an active Telnet connection.
  • WebTelnetSendCommand Function
    Sends a Telnet command to a Telnet connection.
  • WebTelnetSendRecord Function
    Sends a Telnet record sequence to a terminal service server, which is a shortcut to <BinaryData> IAC EOR.
  • WebTelnetSendRecordExecute Function
    Sends a Telnet record to a terminal services server.
  • WebTelnetSendRecordPrepare Function
    Prepares a Telnet recording session consisting of binary data and text fields for later transmission to a terminal services server.
  • WebTelnetSendSubNegotiation Function
    Sends a Telnet option sub-negotiation sequence to a terminal service server, which is a shortcut to IAC SB <Option> <Data> IAC SE.
  • WebTelnetSendTerminalType Function
    Sends simulated terminal type identification code to a Telnet server, which is a shortcut to IAC SB TT IS <TerminalTypeId> IAC SE.
  • WebTelnetSetRecordString Function
    Sets the string value of a field in a data record that is being prepared for transmission to a terminal services server.
  • WebTelnetSyncCommand Function
    Notes a Telnet command to be verified as received on next sending operation in a Telnet connection.
  • WebTelnetSetTerminalConfigString Function
    Configures the behavior of a simulated ANSI or VT terminal in an active Telnet connection.
  • WebTelnetSyncData Function
    Notes binary data like VT100 escape sequences to be verified as received on next sending operation in a Telnet connection.
  • WebTelnetSyncSubNegotiation Function
    Notes a Telnet option sub-negotiation to be verified as received on next sending operation in a Telnet connection.
  • WebTelnetTypeKeys Function
    Simulates a user input to a Telnet server.
Parent topic: TCP/IP Functions Reference


WebTelnetRecvCommand Function

Action

Receives a Telnet command from a Telnet connection.

Include file

WebAPI.bdh

Syntax

WebTelnetRecvCommand(    in  hWeb     : number,
    in  iCmd     : number optional,
    in  iOpt     : number optional,
    out iRecvCmd : number optional,
    out iRecvOpt : number optional ): boolean;

Return value

  • true if the operation was successful

  • false otherwise

Parameter | Description
hWeb | Valid handle to a Web connection created by WebTcpipConnect and set to Telnet mode using WebTcpipSetTelnetMode.
iCmd | Telnet command to be received from the server (optional). If omitted or set -1 then no verification will be performed. See constants in WebTelnetSendCommand for valid values.
iOpt | Telnet option for WILL/WONT/DO/DONT and SB Telnet commands (optional). See constants in WebTelnetSendCommand for valid values. If omitted or set to -1 no verification will be performed.
iRecvCmd | An optional variable may be passed to this function to obtain a Telnet command received from the server (optional).
iRecvOpt | An optional variable may be passed to this function to obtain a received Telnet command option (optional).

Example

dcltrans
  transaction TInit
  begin
    StrSetHostCP(28591); // 28591 (ISO 8859-1 Latin I)
  end TInit;
  transaction   TMain
  var
    hWeb0     : number;
    sBuffer   : string;
    sBoundary : string;
    nOption   : number;
  begin
    WebTcpipConnect(hWeb0, "My.TelnetHost.IP", WEB_PORT_TELNET);
    WebTcpipSetTelnetMode(hWeb0, TERMINAL_TYPE_ANSI, 80, 24, true,
      TELNET_MODEOPT_RFC_1576);

    WebTelnetRecvCommand(hWeb0, TELNET_CMD_DO, TELNET_OPT_TerminalType);
    WebTelnetRecvCommand(hWeb0, TELNET_CMD_DO, TELNET_OPT_TerminalSpeed);
    WebTelnetRecvCommand(hWeb0, TELNET_CMD_DO, TELNET_OPT_XDisplayLocation);
    WebTelnetRecvCommand(hWeb0, TELNET_CMD_DO, TELNET_OPT_NewEnvironment);
    WebTelnetSendCommand(hWeb0, TELNET_CMD_WILL, TELNET_OPT_TerminalType);
    WebTelnetSendCommand(hWeb0, TELNET_CMD_WONT, TELNET_OPT_TerminalSpeed);
    WebTelnetSendCommand(hWeb0, TELNET_CMD_WONT, TELNET_OPT_XDisplayLocation);
    WebTelnetSendCommand(hWeb0, TELNET_CMD_WONT, TELNET_OPT_NewEnvironment);
    WebTelnetRecvSubNegotiation(hWeb0, TELNET_OPT_TerminalType);
    WebTelnetSendTerminalType(hWeb0, "vt100");
    WebTelnetRecvCommand(hWeb0, TELNET_CMD_WILL, TELNET_OPT_SuppressGoAhead);
    WebTelnetRecvCommand(hWeb0, TELNET_CMD_DO, TELNET_OPT_Echo);
    WebTelnetRecvCommand(hWeb0, TELNET_CMD_DO, TELNET_OPT_NegotiateWindowSize);
    WebTelnetRecvCommand(hWeb0, TELNET_CMD_WILL, TELNET_OPT_Status);
    WebTelnetRecvCommand(hWeb0, TELNET_CMD_DO, TELNET_OPT_RemoteFlowControl);
    WebTelnetSendCommand(hWeb0, TELNET_CMD_DO, TELNET_OPT_SuppressGoAhead);
    WebTelnetSendCommand(hWeb0, TELNET_CMD_WONT, TELNET_OPT_Echo);
    WebTelnetSendCommand(hWeb0, TELNET_CMD_WILL, TELNET_OPT_NegotiateWindowSize);
    WebTelnetSendSubNegotiation(hWeb0, TELNET_OPT_NegotiateWindowSize, "\h00500018");
    WebTelnetSendCommand(hWeb0, TELNET_CMD_DONT, TELNET_OPT_Status);
    WebTelnetSendCommand(hWeb0, TELNET_CMD_WONT, TELNET_OPT_RemoteFlowControl);
    WebTelnetRecvCommand(hWeb0, TELNET_CMD_WILL, TELNET_OPT_Echo);
    WebTcpipGetPacketBoundary(hWeb0, sBoundary);
    WebTcpipRecvPacketsUntilData(hWeb0, "login: ");
    WebTelnetTypeKeys(hWeb0, StrToHostCP("leo"), 359.3, TELNET_FLAG_CASE_SENSITIVE);
    WebTcpipSendBin(hWeb0, "\h0D00");
    WebTcpipRecvExact(hWeb0, NULL, 390);
    WebTcpipSetPacketBoundary(hWeb0, sBoundary);
    WebTcpipRecvUntilIdle(hWeb0, NULL, 5000);
    WebTcpipSendBin(hWeb0, "\h0D000D0A");
    WebTcpipRecvPackets(hWeb0, NULL, 3);
    WebTcpipSendBin(hWeb0, "\h0D00");
    WebTcpipSendPacket(hWeb0, StrToHostCP("8") + "\h0D00");
    WebTcpipRecvClose(hWeb0, NULL);
    WebTcpipShutdown(hWeb0);
  end TMain;
Parent topic: Web Telnet Functions
Related reference
WebTelnetSendCommand Function
WebTcpipSetTelnetMode Function
WebTcpipConnect Function


WebTelnetRecvRecord Function

Action

Receives a Telnet record sequence from a terminal service server, which is a shortcut to <BinaryData> IAC EOR.

Include file

WebAPI.bdh

Syntax

WebTelnetRecvRecord(    in hWeb           : number,
                        in sDataRequired  : string optional,
                        out sDataRecv     : string optional ): boolean;

Return value

  • true if the operation was successful

  • false otherwise

Parameter | Description
hWeb | Valid handle to a Web connection created by WebTcpipConnect and set to Telnet mode using WebTcpipSetTelnetMode.
sDataRequired | Optional binary data expected from a terminal server without the terminating IAC EOR. When omitted or set to NULL, no verification is performed (optional).
sDataRecv | Where optional output data (including the terminating IAC EOR) is to be placed (optional).

Example

dcltrans
  transaction TInit
  begin
    StrSetHostCP(1148);
    // 1148  (IBM EBCDIC - International (500 + Euro))
  end TInit;
  transaction TMain
  var
    hWeb0     : number;
    iFieldPos : number;
  begin
    WebTcpipConnect(hWeb0, "My.TelnetHost.IP", WEB_PORT_TELNET); // Port: 23
    WebTcpipSetTelnetMode(hWeb0, TERMINAL_TYPE_3270, 80, 24, true, TELNET_MODEOPT_RFC_1576 | TELNET_MODEOPT_AUTO_RECV);

    WebTelnetRecvCommand(hWeb0, TELNET_CMD_DO, TELNET_OPT_TerminalType);
    WebTelnetSendCommand(hWeb0, TELNET_CMD_WILL, TELNET_OPT_TerminalType);
    WebTelnetRecvSubNegotiation(hWeb0, TELNET_OPT_TerminalType);
    WebTelnetSendTerminalType(hWeb0, "IBM-3278-2-E");
    WebTelnetRecvCommand(hWeb0, TELNET_CMD_DO, TELNET_OPT_EndOfRecord);
    WebTelnetRecvCommand(hWeb0, TELNET_CMD_WILL, TELNET_OPT_EndOfRecord);
    WebTelnetRecvCommand(hWeb0, TELNET_CMD_DO, TELNET_OPT_TransmitBinary);
    WebTelnetRecvCommand(hWeb0, TELNET_CMD_WILL, TELNET_OPT_TransmitBinary);
    WebTelnetSendCommand(hWeb0, TELNET_CMD_WILL, TELNET_OPT_EndOfRecord);
    WebTelnetSendCommand(hWeb0, TELNET_CMD_DO, TELNET_OPT_EndOfRecord);
    WebTelnetSendCommand(hWeb0, TELNET_CMD_WILL, TELNET_OPT_TransmitBinary);
    WebTelnetSendCommand(hWeb0, TELNET_CMD_DO, TELNET_OPT_TransmitBinary);
    WebTelnetRecvCommand(hWeb0, TELNET_CMD_DO, TELNET_OPT_TransmitBinary);
    WebTelnetRecvCommand(hWeb0, TELNET_CMD_WILL, TELNET_OPT_TransmitBinary);
    WebTelnetRecvRecord(hWeb0);
    WebTelnetRecvRecord(hWeb0);
    WebTelnetSendRecord(hWeb0,

      "\h88001181A600000B0100005000180050" // ····¦······P···P 00000000

      "\h001800168186000800F4F1F1F2F2F3F3" // ·········ôññòòóó 00000010

      "\hF4F4F5F5F6F6F7F7000D81870400F0F1" // ôôõõöö÷÷······ðñ 00000020

      "\hF1F2F2F4F40007818800010200178181" // ñòòôô··········· 00000030

      "\h01000050001801000100030004000909" // ···P············ 00000040

      "\h0C0780001B81858200090C0000000007" // ················ 00000050

      "\h00000002B900250100F103C301360006" // ····¹·%··ñ·Ã·6·· 00000060

      "\h81990000001281970000080008000101" // ················ 00000070

      "\h000B0401C0C1000981A80200F0FFFFFF" // ····ÀÁ···¨··ð··· 00000080

      "\hFF000C81950000081108110101000F81" // ················ 00000090

      "\h80A687888185869997A89580"); // ·¦·······¨·· 000000A0

    WebTelnetRecvRecord(hWeb0);
    WebTcpipRecvPackets(hWeb0);
    WebTelnetRecvRecord(hWeb0);
    WebTelnetSendRecord(hWeb0, "\h7D5B6F115B6F" + StrToHostCP("1"));
    WebTcpipScreenRecvPacketsUntilStatus(hWeb0, "Keyboard Locked", "false");
    WebTelnetSendRecord(hWeb0, "\h7D5BF0115BF0" + StrToHostCP("12"));
    WebTcpipScreenRecvPacketsUntilText(hWeb0, 6, 22, "Choice: ");
    WebTelnetSendRecord(hWeb0, "\h7D5A5E115A5E" + StrToHostCP("12"));
    WebTcpipSetPacketBoundary(hWeb0, "\nFFEF");
    WebTcpipScreenRecvPacketsUntilField(hWeb0, 1, "");
    iFieldPos := WebTelnetScreenGetFieldIndex(hWeb0,16, 22);
    if iFieldPos = 1 then
     WebTcpipShutdown(hWeb0);
    end;
  end TMain;
Parent topic: Web Telnet Functions
Related reference
WebTcpipSetTelnetMode Function
WebTcpipConnect Function


WebTelnetRecvRecordsUntilClose Function

Action

Receives data (packets terminated by IAC EOR) from a given connection until the Telnet connection is closed. This function is only valid on open Telnet connections.

Include file

WebAPI.bdh

Syntax

WebTelnetRecvRecordsUntilClose(    in  hWeb  : number,
                                   out sRecv : string optional ): boolean;

Return value

  • true if the operation succeeded

  • false otherwise

Parameter | Description
hWeb | Valid handle to a Web connection created by WebTcpipConnect and set to Telnet mode using WebTcpipSetTelnetMode.
sRecv | Optional string variable where all received binary data is to be placed until connection is closed.

Example

dcltrans
  transaction TInit
  begin
    StrSetHostCP(1047); // 1047
 (IBM EBCDIC - Latin-1/Open System)
  end TInit;

  transaction   TMain
  var
    hWeb0     : number;
    sBuffer   : string;
    sBoundary : string;
    nOption   : number;
  begin
    WebTcpipConnect(hWeb0, "My.TelnetHost.IP", WEB_PORT_TELNET);
    WebTcpipSetTelnetMode(hWeb0, TERMINAL_TYPE_3270, 80, 24, true,
      TELNET_MODEOPT_RFC_1576 | TELNET_MODEOPT_AUTO_RECV | TELNET_MODEOPT_3270E_AUTO_REPLY);

    WebTelnetRecvCommand(hWeb0, TELNET_CMD_DO, TELNET_OPT_TN3270E);
    WebTelnetSendCommand(hWeb0, TELNET_CMD_WILL, TELNET_OPT_TN3270E);
    WebTelnetRecvSubNegotiation(hWeb0, TELNET_OPT_TN3270E);
    WebTelnetSendSubNegotiation(hWeb0, TELNET_OPT_TN3270E, TN3270E_CMD_DEVICE_TYPE + TN3270E_CMD_REQUEST + "IBM-3278-2-E");
    WebTelnetRecvSubNegotiation(hWeb0, TELNET_OPT_TN3270E);
    WebTelnetSendSubNegotiation(hWeb0, TELNET_OPT_TN3270E, TN3270E_CMD_FUNCTIONS + TN3270E_CMD_REQUEST + TN3270E_FUNC_BIND_IMAGE
      + TN3270E_FUNC_RESPONSES + TN3270E_FUNC_SYSREQ);
    WebTelnetRecvSubNegotiation(hWeb0, TELNET_OPT_TN3270E);
    WebTelnetScreenRecvRecordsUntilStatus(hWeb0, "Keyboard locked", "False");
    WebTelnetRecvRecord(hWeb0);
    WebTelnetRecvRecord(hWeb0);
    WebTelnetSendRecord(hWeb0, "\h00000000007DD4D2"); // ·····}ÔÒ
    WebTelnetScreenRecvRecordsUntilStatus(hWeb0, "Keyboard locked", "False");
    WebTelnetSendRecord(hWeb0, "\h00000000017D4040"); // ·····}@@
    WebTelnetScreenRecvRecordsUntilCursor(hWeb0, 57, 24);
    WebTelnetSendRecord(hWeb0, "\h00000000027D5DE9115DE8" + StrToHostCP("1___________________"));
    WebTelnetScreenRecvRecordsUntilStatus(hWeb0, "Keyboard locked", "False");
    WebTelnetSendRecord(hWeb0, "\h00000000037D5D6C"); // ·····}]l
    WebTelnetScreenRecvRecordsUntilStatus(hWeb0, "Keyboard locked", "False");
    WebTelnetSendRecord(hWeb0, "\h00000000047D5DE9115DE8" + StrToHostCP("3___________________"));
    WebTelnetScreenRecvRecordsUntilStatus(hWeb0, "Keyboard locked", "False");
    WebTelnetSendRecord(hWeb0, "\h00000000057D50F311C77E" + StrToHostCP("p") + "\h11506E" + StrToHostCP(
      "hello_____________________________________"));

    WebTelnetScreenRecvRecordsUntilStatus(hWeb0, "Keyboard locked", "False");
    WebTelnetSendRecord(hWeb0, "\h0000000006F35D6A"); // ·····ó]j
    WebTelnetScreenRecvRecordsUntilStatus(hWeb0, "Keyboard locked", "False");
    WebTelnetSendRecord(hWeb0, "\h0000000007F3C77E"); // ·····óÇ~
    WebTelnetScreenRecvRecordsUntilStatus(hWeb0, "Keyboard locked", "False");
    WebTelnetSendRecord(hWeb0, "\h0000000008F35DE8"); // ·····ó]è
    WebTelnetScreenRecvRecordsUntilStatus(hWeb0, "Keyboard locked", "False");
    WebTelnetSendRecord(hWeb0, "\h0000000009F35DE8"); // ·····ó]è
    WebTelnetScreenRecvRecordsUntilStatus(hWeb0, "Keyboard locked", "False");
    WebTelnetRecvRecord(hWeb0);
    WebTelnetRecvRecord(hWeb0);
    WebTelnetSendRecord(hWeb0, "\h000000000AF3D4D2"); // ·····óÔÒ
    WebTelnetRecvRecordsUntilClose(hWeb0);

    WebTcpipShutdown(hWeb0)
  end TMain;
Parent topic: Web Telnet Functions
Related reference
WebTcpipSetTelnetMode Function
WebTcpipConnect Function


WebTelnetRecvRecordsUntilData Function

Action

Receives records (data terminated by IAC EOR) from a Telnet server until a record contains expected data.

Include file

WebAPI.bdh

Syntax

WebTelnetRecvRecordsUntilData(    in  hWeb          : number,
    in  sDataExpected : string,
    in  nOptions      : number optional,
    out sDataReceived : string optional ): boolean;

Return value

  • true if the operation succeeded

  • false otherwise

Parameter | Description
hWeb | Valid handle to a Web connection created by WebTcpipConnect and set to Telnet mode using WebTcpipSetTelnetMode.
sDataExpected | Binary string that is to be looked for in received records.
nOptions

Comparison options; this is a case-insensitive "contains" by default, or may be one of the following:

  • TELNET_FLAG_EQUAL: Lengths of both values must match.

  • TELNET_FLAG_CASE_SENSITIVE: Comparison is performed case-sensitively.

  • TELNET_FLAG_IS_DIFFERENT: Negates the logical comparison.

  • TELNET_FLAG_IGNORE_WHITE_SPACE: All whitespaces in both compared strings are cut before comparison is performed.

  • TELNET_FLAG_CONTAINS: sText must occur within rendered screen text. (default)

  • TELNET_FLAG_FROM_LEFT: comparison is performed from the left side.

  • TELNET_FLAG_TRIM_LEFT: Leading blank spaces are trimmed from received data before comparison is performed.

  • TELNET_FLAG_TRIM_RIGHT: Trailing blanks are trimmed from received data before comparison is performed.

  • TELNET_FLAG_TRIM_BOTH: Status value is trimmed from both sides of content before comparison is performed.

  • TELNET_FLAG_FROM_RIGHT: Comparison is performed beginning from the right side.
sDataReceived | Optional string variable where all received binary data is to be placed until comparison succeeds (up to and including the last received record).

Example

dcltrans  transaction TInit
  begin
    StrSetHostCP(1148);
// 1148  (IBM EBCDIC - International
(500 + Euro))
  end TInit;
   transaction TMain
  var
    hWeb0     : number;
    iFieldPos : number;
  begin
    WebTcpipConnect(hWeb0, "My.TelnetHost.IP", WEB_PORT_TELNET);
// Port: 23
    WebTcpipSetTelnetMode(hWeb0, TERMINAL_TYPE_3270, 80, 24, true,
      TELNET_MODEOPT_RFC_1576 | TELNET_MODEOPT_AUTO_RECV);
    WebTelnetRecvCommand(hWeb0, TELNET_CMD_DO, TELNET_OPT_TerminalType);
    WebTelnetSendCommand(hWeb0, TELNET_CMD_WILL, TELNET_OPT_TerminalType);
    WebTelnetRecvSubNegotiation(hWeb0, TELNET_OPT_TerminalType);
    WebTelnetSendTerminalType(hWeb0, "IBM-3278-2-E");
    WebTelnetRecvCommand(hWeb0, TELNET_CMD_DO, TELNET_OPT_EndOfRecord);
    WebTelnetRecvCommand(hWeb0, TELNET_CMD_WILL, TELNET_OPT_EndOfRecord);
    WebTelnetRecvCommand(hWeb0, TELNET_CMD_DO, TELNET_OPT_TransmitBinary);
    WebTelnetRecvCommand(hWeb0, TELNET_CMD_WILL, TELNET_OPT_TransmitBinary);
    WebTelnetSendCommand(hWeb0, TELNET_CMD_WILL, TELNET_OPT_EndOfRecord);
    WebTelnetSendCommand(hWeb0, TELNET_CMD_DO, TELNET_OPT_EndOfRecord);
    WebTelnetSendCommand(hWeb0, TELNET_CMD_WILL, TELNET_OPT_TransmitBinary);
    WebTelnetSendCommand(hWeb0, TELNET_CMD_DO, TELNET_OPT_TransmitBinary);
    WebTelnetRecvCommand(hWeb0, TELNET_CMD_DO, TELNET_OPT_TransmitBinary);
    WebTelnetRecvCommand(hWeb0, TELNET_CMD_WILL, TELNET_OPT_TransmitBinary);
    WebTelnetRecvRecord(hWeb0);
    WebTelnetRecvRecord(hWeb0);
    WebTelnetSendRecord(hWeb0,

      "\h88001181A600000B0100005000180050" // ····¦······P···P 00000000

      "\h001800168186000800F4F1F1F2F2F3F3" // ·········ôññòòóó 00000010

      "\hF4F4F5F5F6F6F7F7000D81870400F0F1" // ôôõõöö÷÷······ðñ 00000020

      "\hF1F2F2F4F40007818800010200178181" // ñòòôô··········· 00000030

      "\h01000050001801000100030004000909" // ···P············ 00000040

      "\h0C0780001B81858200090C0000000007" // ················ 00000050

      "\h00000002B900250100F103C301360006" // ····¹·%··ñ·Ã·6·· 00000060

      "\h81990000001281970000080008000101" // ················ 00000070

      "\h000B0401C0C1000981A80200F0FFFFFF" // ····ÀÁ···¨··ð··· 00000080

      "\hFF000C81950000081108110101000F81" // ················ 00000090

      "\h80A687888185869997A89580"); // ·¦·······¨·· 000000A0

    WebTelnetRecvRecordsUntilData(hWeb0, "\h4040405C");
    if not WebTelnetScreenVerifyCursor(hWeb0, 16, 23, SEVERITY_SUCCESS) then
      WebTcpipShutdown(hWeb0);
    else
      WebTelnetSendRecord(hWeb0, "\h7D5B6F115B6F" + StrToHostCP("1"));
      WebTelnetScreenRecvRecordsUntilStatus(hWeb0, "Keyboard Locked", "false");
      WebTelnetSendRecord(hWeb0, "\h7D5BF0115BF0" + StrToHostCP("12"));
      WebTelnetScreenRecvRecordsUntilText(hWeb0, 6, 22, "Choice: ");
      WebTelnetSendRecord(hWeb0, "\h7D5A5E115A5E" + StrToHostCP("12"));
      WebTelnetScreenRecvRecordsUntilField(hWeb0, 1, "");
      WebTcpipShutdown(hWeb0);    end;
  end TMain;
Parent topic: Web Telnet Functions
Related reference
WebTcpipSetTelnetMode Function
WebTcpipConnect Function


WebTelnetRecvSubNegotiation Function

Action

Receives a Telnet option sub-negotiation sequence from a terminal service server, which is a shortcut to IAC SB <Option> <Data> IAC SE.

Include file

WebAPI.bdh

Syntax

WebTelnetRecvSubNegotiation(    in  hWeb          : number,
                                in iOpt           : number optional,
                                in sDataExpected  : string optional,
                                out iOptReceived  : number optional,
                                in sDataReceived  : string optional ): boolean;

Return value

  • true if the operation was successful

  • false otherwise

Parameter | Description
hWeb | Valid handle to a Web connection created by WebTcpipConnect and set to Telnet mode using WebTcpipSetTelnetMode.
iOpt | Optional Telnet sub-negotiation option that is expected from the server (optional). See constants in WebTelnetSendCommand for valid values. Set -1 when no validation is to be performed.
sDataExpected | Binary sub-negotiation data string expected from the server (optional). Set to NULL if no validation is to be performed.
iOptReceived | Optional variable where the sub-negotiation option received from the server is to be placed (optional).
sDataReceived | Optional output string buffer where data received from the server is to be placed (optional).

Example

dcltrans
  transaction TInit
  begin
    StrSetHostCP(28591); // 28591
(ISO 8859-1 Latin I)
  end TInit;   transaction   TMain
  var
    hWeb0     : number;
    sBuffer   : string;
    sBoundary : string;
    nOption   : number;
  begin
    WebTcpipConnect(hWeb0, "My.TelnetHost.IP", WEB_PORT_TELNET);
    WebTcpipSetTelnetMode(hWeb0, TERMINAL_TYPE_ANSI, 80, 24, true,
      TELNET_MODEOPT_SYNC);
    WebTcpipGetOptions(hWeb0, nOption);
    if nOption <> TELNET_MODEOPT_RFC_1576 then
      WebTcpipSetOptions(hWeb0, TELNET_MODEOPT_RFC_1576);
    end;

    WebTelnetRecvCommand(hWeb0, TELNET_CMD_DO, TELNET_OPT_TerminalType);
    WebTelnetRecvCommand(hWeb0, TELNET_CMD_DO, TELNET_OPT_TerminalSpeed);
    WebTelnetRecvCommand(hWeb0, TELNET_CMD_DO, TELNET_OPT_XDisplayLocation);
    WebTelnetRecvCommand(hWeb0, TELNET_CMD_DO, TELNET_OPT_NewEnvironment);
    WebTelnetSendCommand(hWeb0, TELNET_CMD_WILL, TELNET_OPT_TerminalType);
    WebTelnetSendCommand(hWeb0, TELNET_CMD_WONT, TELNET_OPT_TerminalSpeed);
    WebTelnetSendCommand(hWeb0, TELNET_CMD_WONT, TELNET_OPT_XDisplayLocation);
    WebTelnetSendCommand(hWeb0, TELNET_CMD_WONT, TELNET_OPT_NewEnvironment);
    WebTelnetRecvSubNegotiation(hWeb0, TELNET_OPT_TerminalType);
    WebTelnetSendTerminalType(hWeb0, "vt100");
    WebTelnetRecvCommand(hWeb0, TELNET_CMD_WILL, TELNET_OPT_SuppressGoAhead);
    WebTelnetRecvCommand(hWeb0, TELNET_CMD_DO, TELNET_OPT_Echo);
    WebTelnetRecvCommand(hWeb0, TELNET_CMD_DO, TELNET_OPT_NegotiateWindowSize);
    WebTelnetRecvCommand(hWeb0, TELNET_CMD_WILL, TELNET_OPT_Status);
    WebTelnetRecvCommand(hWeb0, TELNET_CMD_DO, TELNET_OPT_RemoteFlowControl);
    WebTelnetSendCommand(hWeb0, TELNET_CMD_DO, TELNET_OPT_SuppressGoAhead);
    WebTelnetSendCommand(hWeb0, TELNET_CMD_WONT, TELNET_OPT_Echo);
    WebTelnetSendCommand(hWeb0, TELNET_CMD_WILL, TELNET_OPT_NegotiateWindowSize);
    WebTelnetSendSubNegotiation(hWeb0, TELNET_OPT_NegotiateWindowSize, "\h00500018");
    WebTelnetSendCommand(hWeb0, TELNET_CMD_DONT, TELNET_OPT_Status);
    WebTelnetSendCommand(hWeb0, TELNET_CMD_WONT, TELNET_OPT_RemoteFlowControl);
    WebTelnetRecvCommand(hWeb0, TELNET_CMD_WILL, TELNET_OPT_Echo);
    WebTcpipGetPacketBoundary(hWeb0, sBoundary);
    WebTcpipRecvPacketsUntilData(hWeb0, "login: ");
    WebTelnetTypeKeys(hWeb0, StrToHostCP("leo"), 359.3, TELNET_FLAG_CASE_SENSITIVE);
    WebTcpipSendBin(hWeb0, "\h0D00");
    WebTcpipRecvExact(hWeb0, NULL, 390);
    WebTcpipSetPacketBoundary(hWeb0, sBoundary);
    WebTcpipRecvUntilIdle(hWeb0, NULL, 5000);
    WebTcpipSendBin(hWeb0, "\h0D000D0A");
    WebTcpipRecvPackets(hWeb0, NULL, 3);
    WebTcpipSendBin(hWeb0, "\h0D00");
    WebTcpipSendPacket(hWeb0, StrToHostCP("8") + "\h0D00");
    WebTcpipRecvClose(hWeb0, NULL);
    WebTcpipShutdown(hWeb0);
  end TMain;
Parent topic: Web Telnet Functions
Related reference
WebTcpipSetTelnetMode Function
WebTcpipConnect Function


WebTelnetScreenGetCursor Function

Action

Queries cursor position on a rendered screen in an active Telnet connection.

Include file

WebAPI.bdh

Syntax

WebTelnetScreenGetCursor(    in  hWeb : number,
    out nCol : number optional,
    out nRow : number optional ): boolean;

Return value

  • true if the operation succeeded

  • false otherwise

Parameter | Description
hWeb | Valid handle to a Web connection created by WebTcpipConnect and set to Telnet mode using WebTcpipSetTelnetMode.
nCol | Optional numeric variable, where cursor’s 1-based column is to be placed on a rendered screen (optional).
nRow | Optional numeric variable where cursor’s 1-based row is to be placed on a rendered screen (optional).

Example

dcltrans  transaction TInit
  begin
    StrSetHostCP(1148);
// 1148  (IBM EBCDIC - International
(500 + Euro))
  end TInit;
   transaction TMain
  var
    hWeb0      : number;
    iFieldPos  : number;
    nCursorCol : number;
    nCursorRow : number;
  begin
    WebTcpipConnect(hWeb0, "My.TelnetHost.IP", WEB_PORT_TELNET); // Port: 23
    WebTcpipSetTelnetMode(hWeb0, TERMINAL_TYPE_3270, 80, 24, true, TELNET_MODEOPT_RFC_1576 | TELNET_MODEOPT_AUTO_RECV);
    WebTelnetRecvCommand(hWeb0, TELNET_CMD_DO, TELNET_OPT_TerminalType);
    WebTelnetSendCommand(hWeb0, TELNET_CMD_WILL, TELNET_OPT_TerminalType);
    WebTelnetRecvSubNegotiation(hWeb0, TELNET_OPT_TerminalType);
    WebTelnetSendTerminalType(hWeb0, "IBM-3278-2-E");
    WebTelnetRecvCommand(hWeb0, TELNET_CMD_DO, TELNET_OPT_EndOfRecord);
    WebTelnetRecvCommand(hWeb0, TELNET_CMD_WILL, TELNET_OPT_EndOfRecord);
    WebTelnetRecvCommand(hWeb0, TELNET_CMD_DO, TELNET_OPT_TransmitBinary);
    WebTelnetRecvCommand(hWeb0, TELNET_CMD_WILL, TELNET_OPT_TransmitBinary);
    WebTelnetSendCommand(hWeb0, TELNET_CMD_WILL, TELNET_OPT_EndOfRecord);
    WebTelnetSendCommand(hWeb0, TELNET_CMD_DO, TELNET_OPT_EndOfRecord);
    WebTelnetSendCommand(hWeb0, TELNET_CMD_WILL, TELNET_OPT_TransmitBinary);
    WebTelnetSendCommand(hWeb0, TELNET_CMD_DO, TELNET_OPT_TransmitBinary);
    WebTelnetRecvCommand(hWeb0, TELNET_CMD_DO, TELNET_OPT_TransmitBinary);
    WebTelnetRecvCommand(hWeb0, TELNET_CMD_WILL, TELNET_OPT_TransmitBinary);
    WebTelnetRecvRecord(hWeb0);
    WebTelnetRecvRecord(hWeb0);
    WebTelnetSendRecord(hWeb0,

      "\h88001181A600000B0100005000180050" // ····¦······P···P 00000000

      "\h001800168186000800F4F1F1F2F2F3F3" // ·········ôññòòóó 00000010

      "\hF4F4F5F5F6F6F7F7000D81870400F0F1" // ôôõõöö÷÷······ðñ 00000020

      "\hF1F2F2F4F40007818800010200178181" // ñòòôô··········· 00000030

      "\h01000050001801000100030004000909" // ···P············ 00000040

      "\h0C0780001B81858200090C0000000007" // ················ 00000050

      "\h00000002B900250100F103C301360006" // ····¹·%··ñ·Ã·6·· 00000060

      "\h81990000001281970000080008000101" // ················ 00000070

      "\h000B0401C0C1000981A80200F0FFFFFF" // ····ÀÁ···¨··ð··· 00000080

      "\hFF000C81950000081108110101000F81" // ················ 00000090

      "\h80A687888185869997A89580"); // ·¦·······¨·· 000000A0

    WebTelnetRecvRecordsUntilData(hWeb0, "\h4040405C");
    WebTelnetScreenGetCursor(hWeb0, nCursorCol, nCursorRow);
    if (nCursorCol <> 16) and (nCursorCol <> 23) then
      WebTcpipShutdown(hWeb0);
    else
      WebTelnetSendRecord(hWeb0, "\h7D5B6F115B6F" + StrToHostCP("1"));
      WebTelnetScreenRecvRecordsUntilStatus(hWeb0, "Keyboard Locked", "false");
      WebTelnetSendRecord(hWeb0, "\h7D5BF0115BF0" + StrToHostCP("12"));
      WebTelnetScreenRecvRecordsUntilText(hWeb0, 6, 22, "Choice: ");
      WebTelnetSendRecord(hWeb0, "\h7D5A5E115A5E" + StrToHostCP("12"));
      WebTelnetScreenRecvRecordsUntilField(hWeb0, 1, " ");
      WebTcpipShutdown(hWeb0);
    end;
  end TMain;
Parent topic: Web Telnet Functions
Related reference
WebTcpipSetTelnetMode Function
WebTcpipConnect Function


WebTelnetScreenGetField Function

Action

Queries a rendered screen’s field value in an active Telnet connection.

Include file

WebAPI.bdh

Syntax

WebTelnetScreenGetField(    in hWeb        : number,
                            in nFieldIndex : number,
                            in nOptions    : number optional,
                            in nMaxLen     : number optional ) : string;

Return value

String representing the field’s value

Parameter | Description
hWeb | Valid handle to a Web connection created by WebTcpipConnect and set to Telnet mode using WebTcpipSetTelnetMode.
nFieldIndex | 1-based field’s index of the value that is to be queried.
nOptions

Optionally specifies output string value pre-processing; may be any of following values (optional):

  • TELNET_FLAG_TRIM_LEFT: Leading blank spaces are trimmed from field’s value.

  • TELNET_FLAG_TRIM_RIGHT: Trailing blank spaces are trimmed from field’s value.

  • TELNET_FLAG_TRIM_BOTH: Rendered field’s value is trimmed from both sides.

  • TELNET_FLAG_UPPERCASE: Output value will be converted to upper case.

  • TELNET_FLAG_LOWERCASE: Output value will be converted to lower case.
nMaxLen | Maximum length of output value, which by default is the whole string (optional).

Example

dcltrans
  transaction TInit
  begin
    StrSetHostCP(1148);
    // 1148  (IBM EBCDIC - International (500 + Euro))
  end TInit;

  transaction TMain
  var
    hWeb0     : number;
    iFieldPos : number;
    sRecv     : string;
  begin
    WebTcpipConnect(hWeb0, "My.TelnetHost.IP", WEB_PORT_TELNET); // Port: 23
    WebTcpipSetTelnetMode(hWeb0, TERMINAL_TYPE_3270, 80, 24, true, TELNET_MODEOPT_RFC_1576 | TELNET_MODEOPT_AUTO_RECV);
    WebTelnetRecvCommand(hWeb0, TELNET_CMD_DO, TELNET_OPT_TerminalType);
    WebTelnetSendCommand(hWeb0, TELNET_CMD_WILL, TELNET_OPT_TerminalType);
    WebTelnetRecvSubNegotiation(hWeb0, TELNET_OPT_TerminalType);
    WebTelnetSendTerminalType(hWeb0, "IBM-3278-2-E");
    WebTelnetRecvCommand(hWeb0, TELNET_CMD_DO, TELNET_OPT_EndOfRecord);
    WebTelnetRecvCommand(hWeb0, TELNET_CMD_WILL, TELNET_OPT_EndOfRecord);
    WebTelnetRecvCommand(hWeb0, TELNET_CMD_DO, TELNET_OPT_TransmitBinary);
    WebTelnetRecvCommand(hWeb0, TELNET_CMD_WILL, TELNET_OPT_TransmitBinary);
    WebTelnetSendCommand(hWeb0, TELNET_CMD_WILL, TELNET_OPT_EndOfRecord);
    WebTelnetSendCommand(hWeb0, TELNET_CMD_DO, TELNET_OPT_EndOfRecord);
    WebTelnetSendCommand(hWeb0, TELNET_CMD_WILL, TELNET_OPT_TransmitBinary);
    WebTelnetSendCommand(hWeb0, TELNET_CMD_DO, TELNET_OPT_TransmitBinary);
    WebTelnetRecvCommand(hWeb0, TELNET_CMD_DO, TELNET_OPT_TransmitBinary);
    WebTelnetRecvCommand(hWeb0, TELNET_CMD_WILL, TELNET_OPT_TransmitBinary);
    WebTelnetRecvRecord(hWeb0);
    WebTelnetRecvRecord(hWeb0);
    WebTelnetSendRecord(hWeb0,

      "\h88001181A600000B0100005000180050" // ····¦······P···P 00000000

      "\h001800168186000800F4F1F1F2F2F3F3" // ·········ôññòòóó 00000010

      "\hF4F4F5F5F6F6F7F7000D81870400F0F1" // ôôõõöö÷÷······ðñ 00000020

      "\hF1F2F2F4F40007818800010200178181" // ñòòôô··········· 00000030

      "\h01000050001801000100030004000909" // ···P············ 00000040

      "\h0C0780001B81858200090C0000000007" // ················ 00000050

      "\h00000002B900250100F103C301360006" // ····¹·%··ñ·Ã·6·· 00000060

      "\h81990000001281970000080008000101" // ················ 00000070

      "\h000B0401C0C1000981A80200F0FFFFFF" // ····ÀÁ···¨··ð··· 00000080

      "\hFF000C81950000081108110101000F81" // ················ 00000090

      "\h80A687888185869997A89580") // ·¦·······¨·· 000000A0

    WebTelnetScreenRecvRecordsUntilCursor(hWeb0, 16, 23, sRecv);
    sRecv := WebTelnetScreenGetField(hWeb0, 1);
    WebTelnetSendRecord(hWeb0, "\h7D5B6F115B6F" + StrToHostCP("1"));
    if (not WebTelnetScreenVerifyField(hWeb0, 1, StrToHostCP("1"))) or (sRecv = "") then
    WebTcpipShutdown(hWeb0);
    else
      WebTelnetSendRecord(hWeb0, "\h7D5B6F115B6F" + StrToHostCP("1"));
      WebTelnetScreenRecvRecordsUntilStatus(hWeb0, "Keyboard Locked", "false");
      WebTelnetSendRecord(hWeb0, "\h7D5BF0115BF0" + StrToHostCP("12"));
      WebTelnetScreenRecvRecordsUntilText(hWeb0, 6, 22, "Choice:");
      WebTelnetSendRecord(hWeb0, "\h7D5A5E115A5E" + StrToHostCP("12"));
      WebTelnetScreenRecvRecordsUntilField(hWeb0, 1, "");
      WebTcpipShutdown(hWeb0);
    end;
  end TMain;
Parent topic: Web Telnet Functions
Related reference
WebTcpipSetTelnetMode Function
WebTcpipConnect Function


WebTelnetScreenGetFieldCount Function

Action

Returns total number of fields in currently rendered screen in an active Telnet connection.

Include file

WebAPI.bdh

Syntax

WebTelnetScreenGetFieldCount(in hWeb : number ): number;

Return value

  • -1 on error

  • Positive number or 0 representing total number of currently rendered fields

Parameter | Description
hWeb | Valid handle to a Web connection created by WebTcpipConnect and set to Telnet mode using WebTcpipSetTelnetMode.

Example

dcltrans  transaction TInit
  begin
    StrSetHostCP(1148);
    // 1148  (IBM EBCDIC - International (500 + Euro))
  end TInit;

  transaction TMain
  var
    hWeb0       : number;
    nFieldPos   : number;
    nFieldCount : number;
    nFieldCol   : number;
    nFieldRow   : number;
    nScrRows    : number;
    nScrCols    : number;

  begin
    WebTcpipConnect(hWeb0, "My.TelnetHost.IP", WEB_PORT_TELNET); // Port: 23
    WebTcpipSetTelnetMode(hWeb0, TERMINAL_TYPE_3270, 80, 24, true, TELNET_MODEOPT_RFC_1576 | TELNET_MODEOPT_AUTO_RECV);
    WebTelnetRecvCommand(hWeb0, TELNET_CMD_DO, TELNET_OPT_TerminalType);
    WebTelnetSendCommand(hWeb0, TELNET_CMD_WILL, TELNET_OPT_TerminalType);
    WebTelnetRecvSubNegotiation(hWeb0, TELNET_OPT_TerminalType);
    WebTelnetSendTerminalType(hWeb0, "IBM-3278-2-E");
    WebTelnetRecvCommand(hWeb0, TELNET_CMD_DO, TELNET_OPT_EndOfRecord);
    WebTelnetRecvCommand(hWeb0, TELNET_CMD_WILL, TELNET_OPT_EndOfRecord);
    WebTelnetRecvCommand(hWeb0, TELNET_CMD_DO, TELNET_OPT_TransmitBinary);
    WebTelnetRecvCommand(hWeb0, TELNET_CMD_WILL, TELNET_OPT_TransmitBinary);
    WebTelnetSendCommand(hWeb0, TELNET_CMD_WILL, TELNET_OPT_EndOfRecord);
    WebTelnetSendCommand(hWeb0, TELNET_CMD_DO, TELNET_OPT_EndOfRecord);
    WebTelnetSendCommand(hWeb0, TELNET_CMD_WILL, TELNET_OPT_TransmitBinary);
    WebTelnetSendCommand(hWeb0, TELNET_CMD_DO, TELNET_OPT_TransmitBinary);
    WebTelnetRecvCommand(hWeb0, TELNET_CMD_DO, TELNET_OPT_TransmitBinary);
    WebTelnetRecvCommand(hWeb0, TELNET_CMD_WILL, TELNET_OPT_TransmitBinary);
    WebTelnetRecvRecord(hWeb0);
    WebTelnetRecvRecord(hWeb0);
    WebTelnetSendRecord(hWeb0,

      "\h88001181A600000B0100005000180050" // ····¦······P···P 00000000

      "\h001800168186000800F4F1F1F2F2F3F3" // ·········ôññòòóó 00000010

      "\hF4F4F5F5F6F6F7F7000D81870400F0F1" // ôôõõöö÷÷······ðñ 00000020

      "\hF1F2F2F4F40007818800010200178181" // ñòòôô··········· 00000030

      "\h01000050001801000100030004000909" // ···P············ 00000040

      "\h0C0780001B81858200090C0000000007" // ················ 00000050

      "\h00000002B900250100F103C301360006" // ····¹·%··ñ·Ã·6·· 00000060

      "\h81990000001281970000080008000101" // ················ 00000070

      "\h000B0401C0C1000981A80200F0FFFFFF" // ····ÀÁ···¨··ð··· 00000080

      "\hFF000C81950000081108110101000F81" // ················ 00000090

      "\h80A687888185869997A89580"); // ·¦·······¨··     000000A0

    WebTelnetRecvRecord(hWeb0);
    WebTelnetRecvRecord(hWeb0);

    WebTelnetSendRecord(hWeb0, "\h7D5B6F115B6F" +StrToHostCP("1"));
    WebTelnetScreenRecvRecordsUntilStatus(hWeb0, "Keyboard Locked", "false");
    WebTelnetSendRecord(hWeb0, "\h7D5BF0115BF0" + StrToHostCP("12"));
    WebTelnetScreenRecvRecordsUntilText(hWeb0, 6, 22, "Choice:");
    WebTelnetSendRecord(hWeb0, "\h7D5A5E115A5E" + StrToHostCP("12"));
    WebTelnetScreenRecvRecordsUntilField(hWeb0, 1, "");
    nFieldCount := WebTelnetScreenGetFieldCount(hWeb0);

    if nFieldCount = 1 then
      WebTelnetScreenGetFieldProperties(hWeb0, 1, nFieldCol, nFieldRow, 0);
      if (nScrCols >= nFieldCol) and (nScrRows >= nFieldRow) then
        nFieldPos := WebTelnetScreenGetFieldIndex(hWeb0,nFieldCol, nFieldRow);
        if nFieldPos = 1 then
          WebTcpipShutdown(hWeb0);
        end;
      end;
   end;
  end TMain;
Parent topic: Web Telnet Functions
Related reference
WebTcpipSetTelnetMode Function
WebTcpipConnect Function


WebTelnetScreenGetFieldIndex Function

Action

Returns the index of a field in an open Telnet connection at a given position. The index returned may be used for further data retrieval and comparison.

Include file

WebAPI.bdh

Syntax

WebTelnetScreenGetFieldIndex(    in hWeb : number,
                                 in nCol : number,
                                 in nRow : number ) : number;

Return value

  • 1-based index of the rendered field at a given position.

  • 0 on error

Parameter | Description
hWeb | Valid handle to a Web connection created by WebTcpipConnect and set to Telnet mode using WebTcpipSetTelnetMode.
nCol | 1-based column of the searched field.
nRow | 1-based row of the searched field.

Example

dcltrans  transaction TInit
  begin
    StrSetHostCP(1148); // 1148  (IBM EBCDIC - International (500 + Euro))
  end TInit;

  transaction TMain
  var
    hWeb0     : number;
    iFieldPos : number;
  begin
    WebTcpipConnect(hWeb0, "My.TelnetHost.IP", WEB_PORT_TELNET); // Port: 23
    WebTcpipSetTelnetMode(hWeb0, TERMINAL_TYPE_3270, 80, 24, true, TELNET_MODEOPT_RFC_1576 | TELNET_MODEOPT_AUTO_RECV);
    WebTelnetRecvCommand(hWeb0, TELNET_CMD_DO, TELNET_OPT_TerminalType);
    WebTelnetSendCommand(hWeb0, TELNET_CMD_WILL, TELNET_OPT_TerminalType);
    WebTelnetRecvSubNegotiation(hWeb0, TELNET_OPT_TerminalType);
    WebTelnetSendTerminalType(hWeb0, "IBM-3278-2-E");
    WebTelnetRecvCommand(hWeb0, TELNET_CMD_DO, TELNET_OPT_EndOfRecord);
    WebTelnetRecvCommand(hWeb0, TELNET_CMD_WILL, TELNET_OPT_EndOfRecord);
    WebTelnetRecvCommand(hWeb0, TELNET_CMD_DO, TELNET_OPT_TransmitBinary);
    WebTelnetRecvCommand(hWeb0, TELNET_CMD_WILL, TELNET_OPT_TransmitBinary);
    WebTelnetSendCommand(hWeb0, TELNET_CMD_WILL, TELNET_OPT_EndOfRecord);
    WebTelnetSendCommand(hWeb0, TELNET_CMD_DO, TELNET_OPT_EndOfRecord);
    WebTelnetSendCommand(hWeb0, TELNET_CMD_WILL, TELNET_OPT_TransmitBinary);
    WebTelnetSendCommand(hWeb0, TELNET_CMD_DO, TELNET_OPT_TransmitBinary);
    WebTelnetRecvCommand(hWeb0, TELNET_CMD_DO, TELNET_OPT_TransmitBinary);
    WebTelnetRecvCommand(hWeb0, TELNET_CMD_WILL, TELNET_OPT_TransmitBinary);
    WebTelnetRecvRecord(hWeb0);
    WebTelnetRecvRecord(hWeb0);
    WebTelnetSendRecord(hWeb0,
      "\h88001181A600000B0100005000180050" // ····¦······P···P 00000000

      "\h001800168186000800F4F1F1F2F2F3F3" // ·········ôññòòóó 00000010

      "\hF4F4F5F5F6F6F7F7000D81870400F0F1" // ôôõõöö÷÷······ðñ 00000020

      "\hF1F2F2F4F40007818800010200178181" // ñòòôô··········· 00000030

      "\h01000050001801000100030004000909" // ···P············ 00000040

      "\h0C0780001B81858200090C0000000007" // ················ 00000050

      "\h00000002B900250100F103C301360006" // ····¹·%··ñ·Ã·6·· 00000060

      "\h81990000001281970000080008000101" // ················ 00000070

      "\h000B0401C0C1000981A80200F0FFFFFF" // ····ÀÁ···¨··ð··· 00000080

      "\hFF000C81950000081108110101000F81"  // ················ 00000090

      "\h80A687888185869997A89580");  // ·¦·······¨··  000000A0
    WebTelnetRecvRecord(hWeb0);
    WebTcpipRecvPackets(hWeb0);
    WebTelnetRecvRecord(hWeb0);
    WebTelnetSendRecord(hWeb0, "\h7D5B6F115B6F" + StrToHostCP("1"));
    WebTcpipScreenRecvPacketsUntilStatus(hWeb0, "Keyboard Locked", "false");
    WebTelnetSendRecord(hWeb0, "\h7D5BF0115BF0" + StrToHostCP("12"));
    WebTcpipScreenRecvPacketsUntilText(hWeb0, 6, 22, "Choice:");
    WebTelnetSendRecord(hWeb0, "\h7D5A5E115A5E" + StrToHostCP("12"));
    WebTcpipSetPacketBoundary(hWeb0, "\nFFEF");
    WebTcpipScreenRecvPacketsUntilField(hWeb0, 1, "");
    iFieldPos := WebTelnetScreenGetFieldIndex(hWeb0,16, 22);
    if iFieldPos = 1 then
    WebTcpipShutdown(hWeb0);
    end;
  end TMain;
Parent topic: Web Telnet Functions
Related reference
WebTcpipSetTelnetMode Function
WebTcpipConnect Function


WebTelnetScreenGetFieldProperties Function

Action

Queries a rendered field’s attributes in an active Telnet connection.

Include file

WebAPI.bdh

Syntax

WebTelnetScreenGetFieldProperties(    in  hWeb        : number,
                                      in  nFieldIndex : number,
                                      out nCol        : number optional,
                                      out nRow        : number optional,
                                      out nLength     : number optional ) : boolean;

Return value

  • true if the operation succeeded

  • false otherwise

Parameter | Description
hWeb | Valid handle to a Web connection created by WebTcpipConnect and set to Telnet mode using WebTcpipSetTelnetMode.
nFieldIndex | 1-based screen field index of the attributes that are to be queried.
nCol | Optional numeric variable where field’s 1-based column is to be placed (optional).
nRow | Optional numeric variable where field’s 1-based row is to be placed (optional).
nLength | Optional numeric variable where field’s length is to be placed (optional).

Example

dcltrans
  transaction TInit
  begin
    StrSetHostCP(1148); // 1148  (IBM EBCDIC - International (500 + Euro))
  end TInit;
  transaction TMain
  var
    hWeb0       : number;
    nFieldPos   : number;
    nFieldCount : number;
    nFieldCol   : number;
    nFieldRow   : number;
    nScrRows    : number;
    nScrCols    : number;
  begin
    WebTcpipConnect(hWeb0, "My.TelnetHost.IP", WEB_PORT_TELNET); // Port: 23
    WebTcpipSetTelnetMode(hWeb0, TERMINAL_TYPE_3270, 80, 24, true,
      TELNET_MODEOPT_RFC_1576 | TELNET_MODEOPT_AUTO_RECV);
    WebTelnetRecvCommand(hWeb0, TELNET_CMD_DO, TELNET_OPT_TerminalType);
    WebTelnetSendCommand(hWeb0, TELNET_CMD_WILL, TELNET_OPT_TerminalType);
    WebTelnetRecvSubNegotiation(hWeb0, TELNET_OPT_TerminalType);
    WebTelnetSendTerminalType(hWeb0, "IBM-3278-2-E");
    WebTelnetRecvCommand(hWeb0, TELNET_CMD_DO, TELNET_OPT_EndOfRecord);
    WebTelnetRecvCommand(hWeb0, TELNET_CMD_WILL, TELNET_OPT_EndOfRecord);
    WebTelnetRecvCommand(hWeb0, TELNET_CMD_DO, TELNET_OPT_TransmitBinary);
    WebTelnetRecvCommand(hWeb0, TELNET_CMD_WILL, TELNET_OPT_TransmitBinary);
    WebTelnetSendCommand(hWeb0, TELNET_CMD_WILL, TELNET_OPT_EndOfRecord);
    WebTelnetSendCommand(hWeb0, TELNET_CMD_DO, TELNET_OPT_EndOfRecord);
    WebTelnetSendCommand(hWeb0, TELNET_CMD_WILL, TELNET_OPT_TransmitBinary);
    WebTelnetSendCommand(hWeb0, TELNET_CMD_DO, TELNET_OPT_TransmitBinary);
    WebTelnetRecvCommand(hWeb0, TELNET_CMD_DO, TELNET_OPT_TransmitBinary);
    WebTelnetRecvCommand(hWeb0, TELNET_CMD_WILL, TELNET_OPT_TransmitBinary);
    WebTelnetRecvRecord(hWeb0);
    WebTelnetRecvRecord(hWeb0);
    WebTelnetSendRecord(hWeb0,

      "\h88001181A600000B0100005000180050" // ····¦······P···P 00000000

      "\h001800168186000800F4F1F1F2F2F3F3" // ·········ôññòòóó 00000010

      "\hF4F4F5F5F6F6F7F7000D81870400F0F1" // ôôõõöö÷÷······ðñ 00000020

      "\hF1F2F2F4F40007818800010200178181" // ñòòôô··········· 00000030

      "\h01000050001801000100030004000909" // ···P············ 00000040

      "\h0C0780001B81858200090C0000000007" // ················ 00000050

      "\h00000002B900250100F103C301360006" // ····¹·%··ñ·Ã·6·· 00000060

      "\h81990000001281970000080008000101" // ················ 00000070

      "\h000B0401C0C1000981A80200F0FFFFFF" // ····ÀÁ···¨··ð··· 00000080

      "\hFF000C81950000081108110101000F81" // ················ 00000090

      "\h80A687888185869997A89580");    // ·¦·······¨·· 000000A0

    WebTelnetRecvRecord(hWeb0);
    WebTelnetRecvRecord(hWeb0);
    WebTelnetSendRecord(hWeb0, "\h7D5B6F115B6F" + StrToHostCP("1"));
    WebTelnetScreenRecvRecordsUntilStatus(hWeb0, "Keyboard Locked", "false");
    WebTelnetSendRecord(hWeb0, "\h7D5BF0115BF0" + StrToHostCP("12"));
    WebTelnetScreenRecvRecordsUntilText(hWeb0, 6, 22, "Choice: ");
    WebTelnetSendRecord(hWeb0, "\h7D5A5E115A5E" + StrToHostCP("12"));
    WebTelnetScreenRecvRecordsUntilField(hWeb0, 1, " ");
    nFieldCount := WebTelnetScreenGetFieldCount(hWeb0);
    if nFieldCount = 1 then
      WebTelnetScreenGetFieldProperties(hWeb0, 1, nFieldCol, nFieldRow, 0);
      if (nScrCols >= nFieldCol) and (nScrRows >= nFieldRow) then
        nFieldPos := WebTelnetScreenGetFieldIndex(hWeb0,nFieldCol, nFieldRow);
        if nFieldPos = 1 then
          WebTcpipShutdown(hWeb0);
        end;
      end;
    end;
  end TMain;
Parent topic: Web Telnet Functions
Related reference
WebTcpipSetTelnetMode Function
WebTcpipConnect Function


WebTelnetScreenGetSize Function

Action

Queries rendered screen’s size in an active Telnet connection.

Include file

WebAPI.bdh

Syntax

WebTelnetScreenGetSize(    in  hWeb  : number,
                           out nCols : number optional,
                           out nRows : number optional ): boolean;

Return value

  • true if the operation succeeded

  • false otherwise

Parameter | Description
hWeb | Valid handle to a Web connection created by WebTcpipConnect and set to Telnet mode using WebTcpipSetTelnetMode.
nCols | Optional numeric variable, where rendered screen’s width is to be placed (optional).
nRows | Optional numeric variable, where to put rendered screen’s height is to be placed (optional).

Example

dcltrans
  transaction TInit
  begin
    StrSetHostCP(1148); // 1148  (IBM EBCDIC - International (500 + Euro))
  end TInit;

  transaction TMain
  var
    hWeb0       : number;
    nFieldPos   : number;
    nFieldCount : number;
    nFieldCol   : number;
    nFieldRow   : number;
    nScrRows    : number;
    nScrCols    : number;
  begin
    WebTcpipConnect(hWeb0, "My.TelnetHost.IP", WEB_PORT_TELNET); // Port: 23
    WebTcpipSetTelnetMode(hWeb0, TERMINAL_TYPE_3270, 80, 24, true,
      TELNET_MODEOPT_RFC_1576 | TELNET_MODEOPT_AUTO_RECV);
    WebTelnetRecvCommand(hWeb0, TELNET_CMD_DO, TELNET_OPT_TerminalType);
    WebTelnetSendCommand(hWeb0, TELNET_CMD_WILL, TELNET_OPT_TerminalType);
    WebTelnetRecvSubNegotiation(hWeb0, TELNET_OPT_TerminalType);
    WebTelnetSendTerminalType(hWeb0, "IBM-3278-2-E");
    WebTelnetRecvCommand(hWeb0, TELNET_CMD_DO, TELNET_OPT_EndOfRecord);
    WebTelnetRecvCommand(hWeb0, TELNET_CMD_WILL, TELNET_OPT_EndOfRecord);
    WebTelnetRecvCommand(hWeb0, TELNET_CMD_DO, TELNET_OPT_TransmitBinary);
    WebTelnetRecvCommand(hWeb0, TELNET_CMD_WILL, TELNET_OPT_TransmitBinary);
    WebTelnetSendCommand(hWeb0, TELNET_CMD_WILL, TELNET_OPT_EndOfRecord);
    WebTelnetSendCommand(hWeb0, TELNET_CMD_DO, TELNET_OPT_EndOfRecord);
    WebTelnetSendCommand(hWeb0, TELNET_CMD_WILL, TELNET_OPT_TransmitBinary);
    WebTelnetSendCommand(hWeb0, TELNET_CMD_DO, TELNET_OPT_TransmitBinary);
    WebTelnetRecvCommand(hWeb0, TELNET_CMD_DO, TELNET_OPT_TransmitBinary);
    WebTelnetRecvCommand(hWeb0, TELNET_CMD_WILL,TELNET_OPT_TransmitBinary);
    WebTelnetScreenGetSize(hWeb0, nScrCols,nScrRows);
    WebTelnetRecvRecord(hWeb0);
    WebTelnetRecvRecord(hWeb0);
    WebTelnetSendRecord(hWeb0,

      "\h88001181A600000B0100005000180050" // ····¦······P···P 00000000

      "\h001800168186000800F4F1F1F2F2F3F3" // ·········ôññòòóó 00000010

      "\hF4F4F5F5F6F6F7F7000D81870400F0F1" // ôôõõöö÷÷······ðñ 00000020

      "\hF1F2F2F4F40007818800010200178181" // ñòòôô··········· 00000030

      "\h01000050001801000100030004000909" // ···P············ 00000040

      "\h0C0780001B81858200090C0000000007" // ················ 00000050

      "\h00000002B900250100F103C301360006" // ····¹·%··ñ·Ã·6·· 00000060

      "\h81990000001281970000080008000101" // ················ 00000070

      "\h000B0401C0C1000981A80200F0FFFFFF" // ····ÀÁ···¨··ð··· 00000080

      "\hFF000C81950000081108110101000F81" // ················ 00000090

      "\h80A687888185869997A89580"); // ·¦·······¨·· 000000A0

    WebTelnetRecvRecord(hWeb0);
    WebTelnetRecvRecord(hWeb0);
    WebTelnetSendRecord(hWeb0, "\h7D5B6F115B6F" + StrToHostCP("1"));
    WebTelnetScreenRecvRecordsUntilStatus(hWeb0, "Keyboard Locked", "false");
    WebTelnetSendRecord(hWeb0, "\h7D5BF0115BF0" + StrToHostCP("12"));
    WebTelnetScreenRecvRecordsUntilText(hWeb0, 6, 22, "Choice: ");
    WebTelnetSendRecord(hWeb0, "\h7D5A5E115A5E" + StrToHostCP("12"));
    WebTelnetScreenRecvRecordsUntilField(hWeb0, 1, " ");
    nFieldCount := WebTelnetScreenGetFieldCount(hWeb0);
    if nFieldCount = 1 then
      WebTelnetScreenGetFieldProperties(hWeb0, 1, nFieldCol, nFieldRow, 0);
      if (nScrCols >= nFieldCol) and (nScrRows >= nFieldRow) then
        nFieldPos := WebTelnetScreenGetFieldIndex(hWeb0,nFieldCol, nFieldRow);
        if nFieldPos = 1 then
          WebTcpipShutdown(hWeb0);
        end;
      end;
    end;
  end TMain;
Parent topic: Web Telnet Functions
Related reference
WebTcpipSetTelnetMode Function
WebTcpipConnect Function


WebTelnetScreenGetStatus Function

Action

Queries rendered screen’s status value in an active Telnet connection.

Include file

WebAPI.bdh

Syntax

WebTelnetScreenGetStatus(    in hWeb        : number,
                             in sStatusName : string,
                             in nOptions    : number optional,
                             in nMaxLen     : number optional ) : string;

Return value

  • String representing the status value

Parameter | Description
hWeb | Valid handle to a Web connection created by WebTcpipConnect and set to Telnet mode using WebTcpipSetTelnetMode.
sStatusName | Status identifier name (e.g., "Keyboard Locked").
nOptions

Optionally specifies output string value pre-processing; may be any of following values.

  • TELNET_FLAG_TRIM_LEFT: Leading blank spaces are trimmed from status’ value.

  • TELNET_FLAG_TRIM_RIGHT: Trailing blank spaces are trimmed from status’ value.

  • TELNET_FLAG_TRIM_BOTH: Rendered status’ value is trimmed from both sides.

  • TELNET_FLAG_UPPERCASE: Output value will be converted to upper case.

  • TELNET_FLAG_LOWERCASE: Output value will be converted to lower case.
nMaxLen | Maximum length of output value, which is by default the whole string.

Example

dcltrans
  transaction TInit
  begin
    StrSetHostCP(1148); // 1148  (IBM EBCDIC - International (500 + Euro))
  end TInit;

  transaction TMain
  var
    hWeb0     : number;
    iFieldPos : number;
    sRecv     : string;
  begin
    WebTcpipConnect(hWeb0, "My.TelnetHost.IP", WEB_PORT_TELNET); // Port: 23
    WebTcpipSetTelnetMode(hWeb0, TERMINAL_TYPE_3270, 80, 24, true,
      TELNET_MODEOPT_RFC_1576 | TELNET_MODEOPT_AUTO_RECV);
    WebTelnetRecvCommand(hWeb0, TELNET_CMD_DO, TELNET_OPT_TerminalType);
    WebTelnetSendCommand(hWeb0, TELNET_CMD_WILL, TELNET_OPT_TerminalType);
    WebTelnetRecvSubNegotiation(hWeb0, TELNET_OPT_TerminalType);
    WebTelnetSendTerminalType(hWeb0, "IBM-3278-2-E");
    WebTelnetRecvCommand(hWeb0, TELNET_CMD_DO, TELNET_OPT_EndOfRecord);
    WebTelnetRecvCommand(hWeb0, TELNET_CMD_WILL, TELNET_OPT_EndOfRecord);
    WebTelnetRecvCommand(hWeb0, TELNET_CMD_DO, TELNET_OPT_TransmitBinary);
    WebTelnetRecvCommand(hWeb0, TELNET_CMD_WILL, TELNET_OPT_TransmitBinary);
    WebTelnetSendCommand(hWeb0, TELNET_CMD_WILL, TELNET_OPT_EndOfRecord);
    WebTelnetSendCommand(hWeb0, TELNET_CMD_DO, TELNET_OPT_EndOfRecord);
    WebTelnetSendCommand(hWeb0, TELNET_CMD_WILL, TELNET_OPT_TransmitBinary);
    WebTelnetSendCommand(hWeb0, TELNET_CMD_DO, TELNET_OPT_TransmitBinary);
    WebTelnetRecvCommand(hWeb0, TELNET_CMD_DO, TELNET_OPT_TransmitBinary);
    WebTelnetRecvCommand(hWeb0, TELNET_CMD_WILL, TELNET_OPT_TransmitBinary);
    WebTelnetRecvRecord(hWeb0);
    WebTelnetRecvRecord(hWeb0);
    WebTelnetSendRecord(hWeb0,
      "\h88001181A600000B0100005000180050" // ····¦······P···P 00000000

      "\h001800168186000800F4F1F1F2F2F3F3" // ·········ôññòòóó 00000010

      "\hF4F4F5F5F6F6F7F7000D81870400F0F1" // ôôõõöö÷÷······ðñ 00000020

      "\hF1F2F2F4F40007818800010200178181" // ñòòôô··········· 00000030

      "\h01000050001801000100030004000909" // ···P············ 00000040

      "\h0C0780001B81858200090C0000000007" // ················ 00000050

      "\h00000002B900250100F103C301360006" // ····¹·%··ñ·Ã·6·· 00000060

      "\h81990000001281970000080008000101" // ················ 00000070

      "\h000B0401C0C1000981A80200F0FFFFFF" // ····ÀÁ···¨··ð··· 00000080

      "\hFF000C81950000081108110101000F81" // ················ 00000090

      "\h80A687888185869997A89580"); // ·¦·······¨··  000000A0

    WebTelnetScreenRecvRecordsUntilCursor(hWeb0, 16, 23, sRecv);
    sRecv := WebTelnetScreenGetStatus(hWeb0, "Keyboard Locked");
    if sRecv = "false" then
      WebTelnetSendRecord(hWeb0, "\h7D5B6F115B6F" + StrToHostCP("1"));
      WebTelnetScreenRecvRecordsUntilStatus(hWeb0, "Keyboard Locked", "false");
      WebTelnetSendRecord(hWeb0, "\h7D5BF0115BF0" + StrToHostCP("12"));
      WebTelnetScreenRecvRecordsUntilText(hWeb0, 6, 22, "Choice: ");
      WebTelnetSendRecord(hWeb0, "\h7D5A5E115A5E" + StrToHostCP("12"));
      WebTelnetScreenRecvRecordsUntilField(hWeb0, 1, " ");
      WebTcpipShutdown(hWeb0);
    else
      WebTcpipShutdown(hWeb0);
    end;
  end TMain;
Parent topic: Web Telnet Functions
Related reference
WebTcpipSetTelnetMode Function
WebTcpipConnect Function


WebTelnetScreenGetText Function

Action

Queries rendered screen content in an active Telnet connection.

Include file

WebAPI.bdh

Syntax

WebTelnetScreenGetText(    in hWeb     : number,
                           in nCol     : number,
                           in nRow     : number,
                           in nLength  : number optional,
                           in nOptions : number optional ) : string;

Return value

  • String representing the screen content

Parameter | Description
hWeb | Valid handle to a Web connection created by WebTcpipConnect and set to Telnet mode using WebTcpipSetTelnetMode.
nCol | 1-based screen column where reading of screen content is to begin.
nRow | 1-based screen row from where reading screen content is to begin.
nLength | Length of screen portion to be queried (optional). If omitted, all remaining screen content from given position will be returned.
nOptions

Optionally specifies output string value pre-processing; may be any of following values (optional):

  • TELNET_FLAG_TRIM_LEFT: Leading blank spaces are trimmed from rendered screen text.

  • TELNET_FLAG_TRIM_RIGHT: Trailing blank spaces are trimmed from rendered screen text.

  • TELNET_FLAG_TRIM_BOTH: Rendered text is trimmed from both sides of screen content.

  • TELNET_FLAG_UPPERCASE: Output value will be converted to upper case.

  • TELNET_FLAG_LOWERCASE: Output value will be converted to lower case.

Example

dcltrans
  transaction TInit
  begin
    StrSetHostCP(1148); // 1148  (IBM EBCDIC - International (500 + Euro))
  end TInit;

  transaction TMain
  var
    hWeb0     : number;
    iFieldPos : number;
    sRecv     : string;
  begin
    WebTcpipConnect(hWeb0, "My.TelnetHost.IP", WEB_PORT_TELNET); // Port: 23
    WebTcpipSetTelnetMode(hWeb0, TERMINAL_TYPE_3270, 80, 24, true,
      TELNET_MODEOPT_RFC_1576 | TELNET_MODEOPT_AUTO_RECV);
    WebTelnetRecvCommand(hWeb0, TELNET_CMD_DO, TELNET_OPT_TerminalType);
    WebTelnetSendCommand(hWeb0, TELNET_CMD_WILL, TELNET_OPT_TerminalType);
    WebTelnetRecvSubNegotiation(hWeb0, TELNET_OPT_TerminalType);
    WebTelnetSendTerminalType(hWeb0, "IBM-3278-2-E");
    WebTelnetRecvCommand(hWeb0, TELNET_CMD_DO, TELNET_OPT_EndOfRecord);
    WebTelnetRecvCommand(hWeb0, TELNET_CMD_WILL, TELNET_OPT_EndOfRecord);
    WebTelnetRecvCommand(hWeb0, TELNET_CMD_DO, TELNET_OPT_TransmitBinary);
    WebTelnetRecvCommand(hWeb0, TELNET_CMD_WILL, TELNET_OPT_TransmitBinary);
    WebTelnetSendCommand(hWeb0, TELNET_CMD_WILL, TELNET_OPT_EndOfRecord);
    WebTelnetSendCommand(hWeb0, TELNET_CMD_DO, TELNET_OPT_EndOfRecord);
    WebTelnetSendCommand(hWeb0, TELNET_CMD_WILL, TELNET_OPT_TransmitBinary);
    WebTelnetSendCommand(hWeb0, TELNET_CMD_DO, TELNET_OPT_TransmitBinary);
    WebTelnetRecvCommand(hWeb0, TELNET_CMD_DO, TELNET_OPT_TransmitBinary);
    WebTelnetRecvCommand(hWeb0, TELNET_CMD_WILL, TELNET_OPT_TransmitBinary);
    WebTelnetRecvRecord(hWeb0);
    WebTelnetRecvRecord(hWeb0);
    WebTelnetSendRecord(hWeb0,
      "\h88001181A600000B0100005000180050" // ····¦······P···P 00000000

      "\h001800168186000800F4F1F1F2F2F3F3" // ·········ôññòòóó 00000010

      "\hF4F4F5F5F6F6F7F7000D81870400F0F1" // ôôõõöö÷÷······ðñ 00000020

      "\hF1F2F2F4F40007818800010200178181" // ñòòôô··········· 00000030

      "\h01000050001801000100030004000909" // ···P············ 00000040

      "\h0C0780001B81858200090C0000000007" // ················ 00000050

      "\h00000002B900250100F103C301360006" // ····¹·%··ñ·Ã·6·· 00000060

      "\h81990000001281970000080008000101" // ················ 00000070

      "\h000B0401C0C1000981A80200F0FFFFFF" // ····ÀÁ···¨··ð··· 00000080

      "\hFF000C81950000081108110101000F81" // ················ 00000090

      "\h80A687888185869997A89580");  // ·¦·······¨·· 000000A0

    WebTelnetScreenRecvRecordsUntilCursor(hWeb0, 16, 23, sRecv);
    sRecv := WebTelnetScreenGetText(hWeb0, 7, 22, 8);
    if sRecv = "Comments" then
      WebTelnetSendRecord(hWeb0, "\h7D5B6F115B6F" + StrToHostCP("1"));
      WebTelnetScreenRecvRecordsUntilStatus(hWeb0, "Keyboard Locked", "false");
      WebTelnetSendRecord(hWeb0, "\h7D5BF0115BF0" + StrToHostCP("12"));
      WebTelnetScreenRecvRecordsUntilText(hWeb0, 6, 22, "Choice: ");
      WebTelnetSendRecord(hWeb0, "\h7D5A5E115A5E" + StrToHostCP("12"));
      WebTelnetScreenRecvRecordsUntilField(hWeb0, 1, " ");
      WebTcpipShutdown(hWeb0);
    else
      WebTcpipShutdown(hWeb0);
    end;
  end TMain;
Parent topic: Web Telnet Functions
Related reference
WebTcpipSetTelnetMode Function
WebTcpipConnect Function


WebTelnetScreenRecvRecordsUntilCursor Function

Action

Receives records (data terminated by IAC EOR) from a Telnet server until cursor is detected at a specified position.

Include file

WebAPI.bdh

Syntax

WebTelnetScreenRecvRecordsUntilCursor( in hWeb  : number,
    in  nCol  : number,
    in  nRow  : number,
    out sRecv : string ) : boolean;

Return value

  • true if the operation succeeded

  • false otherwise

Parameter | Description
hWeb | Valid handle to a Web connection created by WebTcpipConnect and set to Telnet mode using WebTcpipSetTelnetMode.
nCol | 1-based horizontal cursor position.
nRow | 1-based vertical cursor position.
sRecv | Optional output buffer variable for all received binary data, including the matching packet (optional).

Example

dcltrans
  transaction TInit
  begin
    StrSetHostCP(1148); // 1148  (IBM EBCDIC - International (500 + Euro))
  end TInit;
   transaction TMain
  var
    hWeb0     : number;
    iFieldPos : number;
    sRecv     : string;
  begin
    WebTcpipConnect(hWeb0, "My.TelnetHost.IP", WEB_PORT_TELNET); // Port: 23
    WebTcpipSetTelnetMode(hWeb0, TERMINAL_TYPE_3270, 80, 24, true,
      TELNET_MODEOPT_RFC_1576 | TELNET_MODEOPT_AUTO_RECV);
    WebTelnetRecvCommand(hWeb0, TELNET_CMD_DO, TELNET_OPT_TerminalType);
    WebTelnetSendCommand(hWeb0, TELNET_CMD_WILL, TELNET_OPT_TerminalType);
    WebTelnetRecvSubNegotiation(hWeb0, TELNET_OPT_TerminalType);
    WebTelnetSendTerminalType(hWeb0, "IBM-3278-2-E");
    WebTelnetRecvCommand(hWeb0, TELNET_CMD_DO, TELNET_OPT_EndOfRecord);
    WebTelnetRecvCommand(hWeb0, TELNET_CMD_WILL, TELNET_OPT_EndOfRecord);
    WebTelnetRecvCommand(hWeb0, TELNET_CMD_DO, TELNET_OPT_TransmitBinary);
    WebTelnetRecvCommand(hWeb0, TELNET_CMD_WILL, TELNET_OPT_TransmitBinary);
    WebTelnetSendCommand(hWeb0, TELNET_CMD_WILL, TELNET_OPT_EndOfRecord);
    WebTelnetSendCommand(hWeb0, TELNET_CMD_DO, TELNET_OPT_EndOfRecord);
    WebTelnetSendCommand(hWeb0, TELNET_CMD_WILL, TELNET_OPT_TransmitBinary);
    WebTelnetSendCommand(hWeb0, TELNET_CMD_DO, TELNET_OPT_TransmitBinary);
    WebTelnetRecvCommand(hWeb0, TELNET_CMD_DO, TELNET_OPT_TransmitBinary);
    WebTelnetRecvCommand(hWeb0, TELNET_CMD_WILL, TELNET_OPT_TransmitBinary);
    WebTelnetRecvRecord(hWeb0);
    WebTelnetRecvRecord(hWeb0);
    WebTelnetSendRecord(hWeb0,

      "\h88001181A600000B0100005000180050" // ····¦······P···P 00000000

      "\h001800168186000800F4F1F1F2F2F3F3" // ·········ôññòòóó 00000010

      "\hF4F4F5F5F6F6F7F7000D81870400F0F1" // ôôõõöö÷÷······ðñ 00000020

      "\hF1F2F2F4F40007818800010200178181" // ñòòôô··········· 00000030

      "\h01000050001801000100030004000909" // ···P············ 00000040

      "\h0C0780001B81858200090C0000000007" // ················ 00000050

      "\h00000002B900250100F103C301360006" // ····¹·%··ñ·Ã·6·· 00000060

      "\h81990000001281970000080008000101" // ················ 00000070

      "\h000B0401C0C1000981A80200F0FFFFFF" // ····ÀÁ···¨··ð··· 00000080

      "\hFF000C81950000081108110101000F81" // ················ 00000090

      "\h80A687888185869997A89580");   // ·¦·······¨··   000000A0

    WebTelnetScreenRecvRecordsUntilCursor(hWeb0, 16, 23, sRecv);
    sRecv := WebTelnetScreenGetStatus(hWeb0, "Keyboard Locked");
    if sRecv = "false" then
      WebTelnetSendRecord(hWeb0, "\h7D5B6F115B6F" + StrToHostCP("1"));
      WebTelnetScreenRecvRecordsUntilStatus(hWeb0, "Keyboard Locked", "false");
      WebTelnetSendRecord(hWeb0, "\h7D5BF0115BF0" + StrToHostCP("12"));
      WebTelnetScreenRecvRecordsUntilText(hWeb0, 6, 22, "Choice:");
      WebTelnetSendRecord(hWeb0, "\h7D5A5E115A5E" + StrToHostCP("12"));
      WebTelnetScreenRecvRecordsUntilField(hWeb0, 1, " ");
      WebTcpipShutdown(hWeb0);
    else
      WebTcpipShutdown(hWeb0);
    end;
  end TMain;
Parent topic: Web Telnet Functions
Related reference
WebTcpipSetTelnetMode Function
WebTcpipConnect Function


WebTelnetScreenRecvRecordsUntilField Function

Action

Receives data (packets terminated by IAC EOR) from a given connection until the rendered screen contains a specified field. This function is only valid on open connections that have a screen renderer associated with them and define fields via an underlying protocol, as is the case with Telnet 3270 connections.

Include file

WebAPI.bdh

Syntax

WebTelnetScreenRecvRecordsUntilField(    in  hWeb        : number,
                                         in  nFieldIndex : number,
                                         in  sText       : string,
                                         in nOptions     : number optional,
                                         in nMaxLen      : number optional,
                                         out sRecv       : string optional ) : boolean;

Return value

  • true if the operation succeeded

  • false otherwise

Parameter | Description
hWeb | Valid handle to a Web connection created by WebTcpipConnect and set to Telnet mode using WebTcpipSetTelnetMode.
nFieldIndex | Field index to which content from sText should be compared (1 based).
sText | Text value that should be compared against the field value.
nOptions

By default the retrieved content has to be equal with the compared sVerify string, case-insensitively (optional). Comparison options are:

  • TELNET_FLAG_EQUAL: Comparison is made against both whole strings. (default)

  • TELNET_FLAG_CASE_SENSITIVE: Perform comparison case-sensitively.

  • TELNET_FLAG_IS_DIFFERENT: Negates the logical comparison.

  • TELNET_FLAG_IGNORE_WHITE_SPACE: All whitespaces in both compared strings are cut before comparison is performed.

  • TELNET_FLAG_CONTAINS: Compared string must occur within the retrieved content.

  • TELNET_FLAG_FROM_LEFT: The retrieved content only has to begin with the compared string.

  • TELNET_FLAG_TRIM_LEFT: Leading blanks are trimmed from retrieved content before comparison.

  • TELNET_FLAG_TRIM_RIGHT: Trailing blanks are trimmed from retrieved content before comparison.

  • TELNET_FLAG_TRIM_BOTH: Rendered text is trimmed from both sides before comparison.

  • TELNET_FLAG_FROM_RIGHT: Comparison is made from the right of the retrieved content.
nMaxLen | Length of screen portion to be compared with sText (optional). If omitted or 0, the length of sText is taken.
sRecv | Optional string variable where all received binary data is to be placed until comparison succeeds (optional).

Example

dcltrans
  transaction TInit
  begin
    StrSetHostCP(1148); // 1148  (IBM EBCDIC - International (500 + Euro))
  end TInit;
  transaction TMain
  var
    hWeb0     : number;
    iFieldPos : number;
    sRecv     : string;
  begin
    WebTcpipConnect(hWeb0, "My.TelnetHost.IP", WEB_PORT_TELNET); // Port: 23
    WebTcpipSetTelnetMode(hWeb0, TERMINAL_TYPE_3270, 80, 24, true,
      TELNET_MODEOPT_RFC_1576 | TELNET_MODEOPT_AUTO_RECV);
    WebTelnetRecvCommand(hWeb0, TELNET_CMD_DO, TELNET_OPT_TerminalType);
    WebTelnetSendCommand(hWeb0, TELNET_CMD_WILL, TELNET_OPT_TerminalType);
    WebTelnetRecvSubNegotiation(hWeb0, TELNET_OPT_TerminalType);
    WebTelnetSendTerminalType(hWeb0, "IBM-3278-2-E");
    WebTelnetRecvCommand(hWeb0, TELNET_CMD_DO, TELNET_OPT_EndOfRecord);
    WebTelnetRecvCommand(hWeb0, TELNET_CMD_WILL, TELNET_OPT_EndOfRecord);
    WebTelnetRecvCommand(hWeb0, TELNET_CMD_DO, TELNET_OPT_TransmitBinary);
    WebTelnetRecvCommand(hWeb0, TELNET_CMD_WILL, TELNET_OPT_TransmitBinary);
    WebTelnetSendCommand(hWeb0, TELNET_CMD_WILL, TELNET_OPT_EndOfRecord);
    WebTelnetSendCommand(hWeb0, TELNET_CMD_DO, TELNET_OPT_EndOfRecord);
    WebTelnetSendCommand(hWeb0, TELNET_CMD_WILL, TELNET_OPT_TransmitBinary);
    WebTelnetSendCommand(hWeb0, TELNET_CMD_DO, TELNET_OPT_TransmitBinary);
    WebTelnetRecvCommand(hWeb0, TELNET_CMD_DO, TELNET_OPT_TransmitBinary);
    WebTelnetRecvCommand(hWeb0, TELNET_CMD_WILL, TELNET_OPT_TransmitBinary);
    WebTelnetRecvRecord(hWeb0);
    WebTelnetRecvRecord(hWeb0);
    WebTelnetSendRecord(hWeb0,
      "\h88001181A600000B0100005000180050" // ····¦······P···P 00000000

      "\h001800168186000800F4F1F1F2F2F3F3" // ·········ôññòòóó 00000010

      "\hF4F4F5F5F6F6F7F7000D81870400F0F1" // ôôõõöö÷÷······ðñ 00000020

      "\hF1F2F2F4F40007818800010200178181" // ñòòôô··········· 00000030

      "\h01000050001801000100030004000909" // ···P············ 00000040

      "\h0C0780001B81858200090C0000000007" // ················ 00000050

      "\h00000002B900250100F103C301360006" // ····¹·%··ñ·Ã·6·· 00000060

      "\h81990000001281970000080008000101" // ················ 00000070

      "\h000B0401C0C1000981A80200F0FFFFFF" // ····ÀÁ···¨··ð··· 00000080

      "\hFF000C81950000081108110101000F81"  // ················ 00000090

      "\h80A687888185869997A89580");   // ·¦·······¨·· 000000A0

    WebTelnetScreenRecvRecordsUntilCursor(hWeb0, 16, 23, sRecv);
    sRecv := WebTelnetScreenGetStatus(hWeb0, "Keyboard Locked");
    if sRecv = "false" then
      WebTelnetSendRecord(hWeb0, "\h7D5B6F115B6F" + StrToHostCP("1"));
      WebTelnetScreenRecvRecordsUntilStatus(hWeb0, "Keyboard Locked", "false");
      WebTelnetSendRecord(hWeb0, "\h7D5BF0115BF0" + StrToHostCP("12"));
      WebTelnetScreenRecvRecordsUntilText(hWeb0, 6, 22, "Choice:");
      WebTelnetSendRecord(hWeb0, "\h7D5A5E115A5E" + StrToHostCP("12"));
      WebTelnetScreenRecvRecordsUntilField(hWeb0, 1, " ");
      WebTcpipShutdown(hWeb0);
    else
      WebTcpipShutdown(hWeb0);
    end;
  end TMain;
Parent topic: Web Telnet Functions
Related reference
WebTcpipSetTelnetMode Function
WebTcpipConnect Function


WebTelnetScreenRecvRecordsUntilStatus Function

Action

Receives data (packets terminated by IAC EOR) from a given connection until the rendered screen contains a specified status. This function is only valid on open connections that have a screen renderer associated with them and define statuses via an underlying protocol, as is the case with Telnet 3270 connections.

Include file

WebAPI.bdh

Syntax

WebTelnetScreenRecvRecordsUntilStatus(    in hWeb        : number,
                                          in sStatusName : string,
                                          in sText       : string,
                                          in nOptions    : number optional,
                                          in nTextLength : number optional,
                                          out sRecv       : string optional ) : boolean;

Return value

  • true if the operation succeeded

  • false otherwise

Parameter | Description
hWeb | Valid handle to a Web connection created by WebTcpipConnect and set to Telnet mode using WebTcpipSetTelnetMode.
sStatusName | Identifies the status of the value that is to be compared. The only supported status is "Keyboard Locked".
sText | String value that the status should be compared against. Valid strings are "true" and "false".
nOptions

By default the retrieved content has to be equal with the compared sVerify string, case-insensitively (optional). Comparison options are:

  • TELNET_FLAG_EQUAL: Comparison is made against both whole strings. (default)

  • TELNET_FLAG_CASE_SENSITIVE: Perform comparison case-sensitively.

  • TELNET_FLAG_IS_DIFFERENT: Negates the logical comparison.

  • TELNET_FLAG_IGNORE_WHITE_SPACE: All whitespaces in both compared strings are cut before comparison is performed.

  • TELNET_FLAG_CONTAINS: Compared string must occur within the retrieved content.

  • TELNET_FLAG_FROM_LEFT: The retrieved content only has to begin with the compared string.

  • TELNET_FLAG_TRIM_LEFT: Leading blanks are trimmed from retrieved content before comparison.

  • TELNET_FLAG_TRIM_RIGHT: Trailing blanks are trimmed from retrieved content before comparison.

  • TELNET_FLAG_TRIM_BOTH: Rendered text is trimmed from both sides before comparison.

  • TELNET_FLAG_FROM_RIGHT: Comparison is made from the right of the retrieved content.
nTextLength | Defines how many characters of sText are taken for comparison with sText (optional). If omitted or 0, the length of sText is taken.
sRecv | String variable where all received binary data is to be placed until comparison succeeds. (optional)

Example

dcltrans
  transaction TInit
  begin
    StrSetHostCP(1148); // 1148  (IBM EBCDIC - International (500 + Euro))
  end TInit;
  transaction TMain
  var
    hWeb0     : number;
    iFieldPos : number;
    sRecv     : string;
  begin
    WebTcpipConnect(hWeb0, "My.TelnetHost.IP", WEB_PORT_TELNET); // Port: 23
    WebTcpipSetTelnetMode(hWeb0, TERMINAL_TYPE_3270, 80, 24, true,
      TELNET_MODEOPT_RFC_1576 | TELNET_MODEOPT_AUTO_RECV);
    WebTelnetRecvCommand(hWeb0, TELNET_CMD_DO, TELNET_OPT_TerminalType);
    WebTelnetSendCommand(hWeb0, TELNET_CMD_WILL, TELNET_OPT_TerminalType);
    WebTelnetRecvSubNegotiation(hWeb0, TELNET_OPT_TerminalType);
    WebTelnetSendTerminalType(hWeb0, "IBM-3278-2-E");
    WebTelnetRecvCommand(hWeb0, TELNET_CMD_DO, TELNET_OPT_EndOfRecord);
    WebTelnetRecvCommand(hWeb0, TELNET_CMD_WILL, TELNET_OPT_EndOfRecord);
    WebTelnetRecvCommand(hWeb0, TELNET_CMD_DO, TELNET_OPT_TransmitBinary);
    WebTelnetRecvCommand(hWeb0, TELNET_CMD_WILL, TELNET_OPT_TransmitBinary);
    WebTelnetSendCommand(hWeb0, TELNET_CMD_WILL, TELNET_OPT_EndOfRecord);
    WebTelnetSendCommand(hWeb0, TELNET_CMD_DO, TELNET_OPT_EndOfRecord);
    WebTelnetSendCommand(hWeb0, TELNET_CMD_WILL, TELNET_OPT_TransmitBinary);
    WebTelnetSendCommand(hWeb0, TELNET_CMD_DO, TELNET_OPT_TransmitBinary);
    WebTelnetRecvCommand(hWeb0, TELNET_CMD_DO, TELNET_OPT_TransmitBinary);
    WebTelnetRecvCommand(hWeb0, TELNET_CMD_WILL, TELNET_OPT_TransmitBinary);
    WebTelnetRecvRecord(hWeb0);
    WebTelnetRecvRecord(hWeb0);
    WebTelnetSendRecord(hWeb0,

      "\h88001181A600000B0100005000180050" // ····¦······P···P 00000000

      "\h001800168186000800F4F1F1F2F2F3F3" // ·········ôññòòóó 00000010

      "\hF4F4F5F5F6F6F7F7000D81870400F0F1" // ôôõõöö÷÷······ðñ 00000020

      "\hF1F2F2F4F40007818800010200178181" // ñòòôô··········· 00000030

      "\h01000050001801000100030004000909" // ···P············ 00000040

      "\h0C0780001B81858200090C0000000007" // ················ 00000050

      "\h00000002B900250100F103C301360006" // ····¹·%··ñ·Ã·6·· 00000060

      "\h81990000001281970000080008000101" // ················ 00000070

      "\h000B0401C0C1000981A80200F0FFFFFF" // ····ÀÁ···¨··ð··· 00000080

      "\hFF000C81950000081108110101000F81" // ················ 00000090

      "\h80A687888185869997A89580");  // ·¦·······¨·· 000000A0

    WebTelnetScreenRecvRecordsUntilCursor(hWeb0, 16, 23, sRecv);
    sRecv := WebTelnetScreenGetStatus(hWeb0, "Keyboard Locked");
    if sRecv = "false"then
      WebTelnetSendRecord(hWeb0, "\h7D5B6F115B6F" + StrToHostCP("1"));
      WebTelnetScreenRecvRecordsUntilStatus(hWeb0, "Keyboard Locked", "false");
      WebTelnetSendRecord(hWeb0, "\h7D5BF0115BF0" + StrToHostCP("12"));
      WebTelnetScreenRecvRecordsUntilText(hWeb0, 6, 22, "Choice: ");
      WebTelnetSendRecord(hWeb0, "\h7D5A5E115A5E" + StrToHostCP("12"));
      WebTelnetScreenRecvRecordsUntilField(hWeb0, 1, " ");
      WebTcpipShutdown(hWeb0);
    else
      WebTcpipShutdown(hWeb0);
    end;
  end TMain;
Parent topic: Web Telnet Functions
Related reference
WebTcpipSetTelnetMode Function
WebTcpipConnect Function


WebTelnetScreenRecvRecordsUntilText Function

Action

Receives data (packets terminated by IAC EOR) from a given connection until the rendered screen contains specified text. This function is only valid on open connections that have a screen renderer associated with them, as is the case with Telnet connections.

Include file

WebAPI.bdh

Syntax

WebTelnetScreenRecvRecordsUntilText(    in  hWeb        : number,
                                        in nCol         : number,
                                        in nRow         : number,
                                        in sText        : string,
                                        in nOptions     : number optional,
                                        in nTextLength  : number optional,
                                        out sRecv       : string optional ) : boolean;

Return value

  • true if the operation succeeded

  • false otherwise

Parameter | Description
hWeb | Valid handle to a Web connection created by WebTcpipConnect and set to Telnet mode using WebTcpipSetTelnetMode.
nCol | 1-based screen column where text comparison is to be performed.
nRow | 1-based screen row where text comparison is to be performed.
sText | Text to be compared.
nOptions

By default the retrieved content has to be equal with the compared sVerify string, case-insensitively (optional). Comparison options are:

  • TELNET_FLAG_EQUAL: Comparison is made against both whole strings. (default)

  • TELNET_FLAG_CASE_SENSITIVE: Perform comparison case-sensitively.

  • TELNET_FLAG_IS_DIFFERENT: Negates the logical comparison.

  • TELNET_FLAG_IGNORE_WHITE_SPACE: All whitespaces in both compared strings are cut before comparison is performed.

  • TELNET_FLAG_CONTAINS: Compared string must occur within the retrieved content.

  • TELNET_FLAG_FROM_LEFT: The retrieved content only has to begin with the compared string.

  • TELNET_FLAG_TRIM_LEFT: Leading blanks are trimmed from retrieved content before comparison.

  • TELNET_FLAG_TRIM_RIGHT: Trailing blanks are trimmed from retrieved content before comparison.

  • TELNET_FLAG_TRIM_BOTH: Rendered text is trimmed from both sides before comparison.

  • TELNET_FLAG_FROM_RIGHT: Comparison is made from the right of the retrieved content.
nTextLength | Length of screen portion to be compared with sText (optional). If omitted or 0, the length of sText is compared.
sRecv | Optional string variable where all received binary data is to be placed until comparison succeeds.

Example

dcltrans
  transaction TInit
  begin
    StrSetHostCP(1148); // 1148  (IBM EBCDIC - International (500 + Euro))
  end TInit;

  transaction TMain
  var
    hWeb0     : number;
    iFieldPos : number;
    sRecv     : string;
  begin
    WebTcpipConnect(hWeb0, "My.TelnetHost.IP", WEB_PORT_TELNET); // Port: 23
    WebTcpipSetTelnetMode(hWeb0, TERMINAL_TYPE_3270, 80, 24, true,
      TELNET_MODEOPT_RFC_1576 | TELNET_MODEOPT_AUTO_RECV);
    WebTelnetRecvCommand(hWeb0, TELNET_CMD_DO, TELNET_OPT_TerminalType);
    WebTelnetSendCommand(hWeb0, TELNET_CMD_WILL, TELNET_OPT_TerminalType);
    WebTelnetRecvSubNegotiation(hWeb0, TELNET_OPT_TerminalType);
    WebTelnetSendTerminalType(hWeb0, "IBM-3278-2-E");
    WebTelnetRecvCommand(hWeb0, TELNET_CMD_DO, TELNET_OPT_EndOfRecord);
    WebTelnetRecvCommand(hWeb0, TELNET_CMD_WILL, TELNET_OPT_EndOfRecord);
    WebTelnetRecvCommand(hWeb0, TELNET_CMD_DO, TELNET_OPT_TransmitBinary);
    WebTelnetRecvCommand(hWeb0, TELNET_CMD_WILL, TELNET_OPT_TransmitBinary);
    WebTelnetSendCommand(hWeb0, TELNET_CMD_WILL, TELNET_OPT_EndOfRecord);
    WebTelnetSendCommand(hWeb0, TELNET_CMD_DO, TELNET_OPT_EndOfRecord);
    WebTelnetSendCommand(hWeb0, TELNET_CMD_WILL, TELNET_OPT_TransmitBinary);
    WebTelnetSendCommand(hWeb0, TELNET_CMD_DO, TELNET_OPT_TransmitBinary);
    WebTelnetRecvCommand(hWeb0, TELNET_CMD_DO, TELNET_OPT_TransmitBinary);
    WebTelnetRecvCommand(hWeb0, TELNET_CMD_WILL, TELNET_OPT_TransmitBinary);
    WebTelnetRecvRecord(hWeb0);
    WebTelnetRecvRecord(hWeb0);
    WebTelnetSendRecord(hWeb0,
      "\h88001181A600000B0100005000180050" // ····¦······P···P 00000000

      "\h001800168186000800F4F1F1F2F2F3F3" // ·········ôññòòóó 00000010

      "\hF4F4F5F5F6F6F7F7000D81870400F0F1" // ôôõõöö÷÷······ðñ 00000020

      "\hF1F2F2F4F40007818800010200178181" // ñòòôô··········· 00000030

      "\h01000050001801000100030004000909" // ···P············ 00000040

      "\h0C0780001B81858200090C0000000007" // ················ 00000050

      "\h00000002B900250100F103C301360006" // ····¹·%··ñ·Ã·6·· 00000060

      "\h81990000001281970000080008000101" // ················ 00000070

      "\h000B0401C0C1000981A80200F0FFFFFF" // ····ÀÁ···¨··ð··· 00000080

      "\hFF000C81950000081108110101000F81" // ················ 00000090

      "\h80A687888185869997A89580"); // ·¦·······¨·· 000000A0

    WebTelnetScreenRecvRecordsUntilCursor(hWeb0, 16, 23, sRecv);
    sRecv := WebTelnetScreenGetStatus(hWeb0, "Keyboard Locked");
    if sRecv = "false" then
      WebTelnetSendRecord(hWeb0, "\h7D5B6F115B6F" + StrToHostCP("1"));
      WebTelnetScreenRecvRecordsUntilStatus(hWeb0, "Keyboard Locked", "false");
      WebTelnetSendRecord(hWeb0, "\h7D5BF0115BF0" + StrToHostCP("12"));
      WebTelnetScreenRecvRecordsUntilText(hWeb0, 6, 22, "Choice:");
      WebTelnetSendRecord(hWeb0, "\h7D5A5E115A5E" + StrToHostCP("12"));
      WebTelnetScreenRecvRecordsUntilField(hWeb0, 1, " ");
      WebTcpipShutdown(hWeb0);
    else
      WebTcpipShutdown(hWeb0);
    end;
  end TMain;
Parent topic: Web Telnet Functions
Related reference
WebTcpipSetTelnetMode Function
WebTcpipConnect Function


WebTelnetScreenVerifyCursor Function

Action

Verifies cursor position in a rendered screen in an active Telnet connection.

Include file

WebAPI.bdh

Syntax

WebTelnetScreenVerifyCursor( in  hWeb      : number,
                             in nCol       : number,
                             in nRow       : number,
                             in nSeverity  : number optional := SEVERITY_ERROR,
                             out nActCol   : number optional,
                             out nActRow   : number optional ) : boolean;

Return value

  • true if the operation succeeded

  • false otherwise

Parameter | Description
hWeb | Valid handle to a Web connection created by WebTcpipConnect and set to Telnet mode using WebTcpipSetTelnetMode.
nCol | Expected 1-based horizontal cursor position.
nRow | Expected 1-based vertical cursor position.
nSeverity Optional: Severity of the error that is raised if the verification fails. Can be one of the following values:
  • SEVERITY_SUCCESS: Success; no error (numerical value: 0)
  • SEVERITY_INFORMATIONAL: Informational; no error (numerical value: 1)
  • SEVERITY_WARNING: Warning; no error (numerical value: 2)
  • SEVERITY_ERROR: (Default) Error; simulation continues (numerical value: 3)
  • SEVERITY_TRANS_EXIT: Error; the active transaction is aborted (numerical value: 4)
  • SEVERITY_PROCESS_EXIT: Error; the simulation is aborted (numerical value: 5)
nActCol | Optional numeric variable indicating where actual cursor column is to be placed (optional).
nActRow | Optional numeric variable indicating where actual cursor row is to be placed (optional).

Example

dcltrans  transaction TInit
  begin
    StrSetHostCP(1148); // 1148  (IBM EBCDIC - International (500 + Euro))
  end TInit;
   transaction TMain
  var
    hWeb0     : number;
    iFieldPos : number;
  begin
    WebTcpipConnect(hWeb0, "My.TelnetHost.IP", WEB_PORT_TELNET); // Port: 23
    WebTcpipSetTelnetMode(hWeb0, TERMINAL_TYPE_3270, 80, 24, true,
      TELNET_MODEOPT_RFC_1576 | TELNET_MODEOPT_AUTO_RECV);
    WebTelnetRecvCommand(hWeb0, TELNET_CMD_DO, TELNET_OPT_TerminalType);
    WebTelnetSendCommand(hWeb0, TELNET_CMD_WILL, TELNET_OPT_TerminalType);
    WebTelnetRecvSubNegotiation(hWeb0, TELNET_OPT_TerminalType);
    WebTelnetSendTerminalType(hWeb0, "IBM-3278-2-E");
    WebTelnetRecvCommand(hWeb0, TELNET_CMD_DO, TELNET_OPT_EndOfRecord);
    WebTelnetRecvCommand(hWeb0, TELNET_CMD_WILL, TELNET_OPT_EndOfRecord);
    WebTelnetRecvCommand(hWeb0, TELNET_CMD_DO, TELNET_OPT_TransmitBinary);
    WebTelnetRecvCommand(hWeb0, TELNET_CMD_WILL, TELNET_OPT_TransmitBinary);
    WebTelnetSendCommand(hWeb0, TELNET_CMD_WILL, TELNET_OPT_EndOfRecord);
    WebTelnetSendCommand(hWeb0, TELNET_CMD_DO, TELNET_OPT_EndOfRecord);
    WebTelnetSendCommand(hWeb0, TELNET_CMD_WILL, TELNET_OPT_TransmitBinary);
    WebTelnetSendCommand(hWeb0, TELNET_CMD_DO, TELNET_OPT_TransmitBinary);
    WebTelnetRecvCommand(hWeb0, TELNET_CMD_DO, TELNET_OPT_TransmitBinary);
    WebTelnetRecvCommand(hWeb0, TELNET_CMD_WILL, TELNET_OPT_TransmitBinary);
    WebTelnetRecvRecord(hWeb0);
    WebTelnetRecvRecord(hWeb0);
    WebTelnetSendRecord(hWeb0,
      "\h88001181A600000B0100005000180050" // ····¦······P···P 00000000

      "\h001800168186000800F4F1F1F2F2F3F3" // ·········ôññòòóó 00000010

      "\hF4F4F5F5F6F6F7F7000D81870400F0F1" // ôôõõöö÷÷······ðñ 00000020

      "\hF1F2F2F4F40007818800010200178181" // ñòòôô··········· 00000030

      "\h01000050001801000100030004000909" // ···P············ 00000040

      "\h0C0780001B81858200090C0000000007" // ················ 00000050

      "\h00000002B900250100F103C301360006" // ····¹·%··ñ·Ã·6·· 00000060

      "\h81990000001281970000080008000101" // ················ 00000070

      "\h000B0401C0C1000981A80200F0FFFFFF" // ····ÀÁ···¨··ð··· 00000080

      "\hFF000C81950000081108110101000F81" // ················ 00000090

      "\h80A687888185869997A89580");  // ·¦·······¨··  000000A0

    WebTelnetRecvRecordsUntilData(hWeb0, "\h4040405C");
    if not WebTelnetScreenVerifyCursor(hWeb0, 16, 23, SEVERITY_SUCCESS) then
      WebTcpipShutdown(hWeb0);
    else
      WebTelnetSendRecord(hWeb0, "\h7D5B6F115B6F" + StrToHostCP("1"));
      WebTelnetScreenRecvRecordsUntilStatus(hWeb0, "Keyboard Locked", "false");
      WebTelnetSendRecord(hWeb0, "\h7D5BF0115BF0" + StrToHostCP("12"));
      WebTelnetScreenRecvRecordsUntilText(hWeb0, 6, 22, "Choice:");
      WebTelnetSendRecord(hWeb0, "\h7D5A5E115A5E" + StrToHostCP("12"));
      WebTelnetScreenRecvRecordsUntilField(hWeb0, 1, "");
      WebTcpipShutdown(hWeb0);
    end;
  end TMain;
Parent topic: Web Telnet Functions
Related reference
WebTcpipSetTelnetMode Function
WebTcpipConnect Function


WebTelnetScreenVerifyField Function

Action

Verifies field content in a rendered screen in an active Telnet connection.

Include file

WebAPI.bdh

Syntax

WebTelnetScreenVerifyField( in  hWeb        : number,
                            in  nFieldIndex : number,
                            in  sVerify     : string,
                            in  nOptions    : number optional,
                            in  nSeverity   : number optional := SEVERITY_ERROR,
                            in  nTextLength : number optional,
                            out sRecv       : string optional ) : boolean;

Return value

  • true if the operation succeeded

  • false otherwise

Parameter | Description
hWeb | Valid handle to a Web connection created by WebTcpipConnect and set to Telnet mode using WebTcpipSetTelnetMode.
nFieldIndex | 1-based screen field index of which value should be used for comparison.
sVerify | Text to be compared.
nOptions By default the retrieved content has to be equal with the compared sVerify string, case-insensitively (optional). Comparison options are:

  • TELNET_FLAG_EQUAL: Comparison is made against both whole strings. (default)

  • TELNET_FLAG_CASE_SENSITIVE: Perform comparison case-sensitively.

  • TELNET_FLAG_IS_DIFFERENT: Negates the logical comparison.

  • TELNET_FLAG_IGNORE_WHITE_SPACE: All whitespaces in both compared strings are cut before comparison is performed.

  • TELNET_FLAG_CONTAINS: Compared string must occur within the retrieved content.

  • TELNET_FLAG_FROM_LEFT: The retrieved content only has to begin with the compared string.

  • TELNET_FLAG_TRIM_LEFT: Leading blanks are trimmed from retrieved content before comparison.

  • TELNET_FLAG_TRIM_RIGHT: Trailing blanks are trimmed from retrieved content before comparison.

  • TELNET_FLAG_TRIM_BOTH: Rendered text is trimmed from both sides before comparison.

  • TELNET_FLAG_FROM_RIGHT: Comparison is made from the right of the retrieved content.

nSeverity Optional: Severity of the error that is raised if the verification fails. Can be one of the following values:
  • SEVERITY_SUCCESS: Success; no error (numerical value: 0)
  • SEVERITY_INFORMATIONAL: Informational; no error (numerical value: 1)
  • SEVERITY_WARNING: Warning; no error (numerical value: 2)
  • SEVERITY_ERROR: (Default) Error; simulation continues (numerical value: 3)
  • SEVERITY_TRANS_EXIT: Error; the active transaction is aborted (numerical value: 4)
  • SEVERITY_PROCESS_EXIT: Error; the simulation is aborted (numerical value: 5)
nTextLength | Length of screen portion to be compared with sVerify (optional). If omitted or 0, the length of sVerify is taken.
sRecv | Optional string variable where field content is placed (optional).

Example

dcltrans
  transaction TInit
  begin
    StrSetHostCP(1148); // 1148  (IBM EBCDIC - International (500 + Euro))
  end TInit;
  transaction TMain
  var
    hWeb0     : number;
    iFieldPos : number;
    sRecv     : string;
  begin
    WebTcpipConnect(hWeb0, "My.TelnetHost.IP", WEB_PORT_TELNET); // Port: 23
    WebTcpipSetTelnetMode(hWeb0, TERMINAL_TYPE_3270, 80, 24, true, TELNET_MODEOPT_RFC_1576 | TELNET_MODEOPT_AUTO_RECV);
    WebTelnetRecvCommand(hWeb0, TELNET_CMD_DO, TELNET_OPT_TerminalType);
    WebTelnetSendCommand(hWeb0, TELNET_CMD_WILL, TELNET_OPT_TerminalType);
    WebTelnetRecvSubNegotiation(hWeb0, TELNET_OPT_TerminalType);
    WebTelnetSendTerminalType(hWeb0, "IBM-3278-2-E");
    WebTelnetRecvCommand(hWeb0, TELNET_CMD_DO, TELNET_OPT_EndOfRecord);
    WebTelnetRecvCommand(hWeb0, TELNET_CMD_WILL, TELNET_OPT_EndOfRecord);
    WebTelnetRecvCommand(hWeb0, TELNET_CMD_DO, TELNET_OPT_TransmitBinary);
    WebTelnetRecvCommand(hWeb0, TELNET_CMD_WILL, TELNET_OPT_TransmitBinary);
    WebTelnetSendCommand(hWeb0, TELNET_CMD_WILL, TELNET_OPT_EndOfRecord);
    WebTelnetSendCommand(hWeb0, TELNET_CMD_DO, TELNET_OPT_EndOfRecord);
    WebTelnetSendCommand(hWeb0, TELNET_CMD_WILL, TELNET_OPT_TransmitBinary);
    WebTelnetSendCommand(hWeb0, TELNET_CMD_DO, TELNET_OPT_TransmitBinary);
    WebTelnetRecvCommand(hWeb0, TELNET_CMD_DO, TELNET_OPT_TransmitBinary);
    WebTelnetRecvCommand(hWeb0, TELNET_CMD_WILL, TELNET_OPT_TransmitBinary);
    WebTelnetRecvRecord(hWeb0);
    WebTelnetRecvRecord(hWeb0);
    WebTelnetSendRecord(hWeb0,
      "\h88001181A600000B0100005000180050" // ····¦······P···P 00000000

      "\h001800168186000800F4F1F1F2F2F3F3" // ·········ôññòòóó 00000010

      "\hF4F4F5F5F6F6F7F7000D81870400F0F1" // ôôõõöö÷÷······ðñ 00000020

      "\hF1F2F2F4F40007818800010200178181" // ñòòôô··········· 00000030

      "\h01000050001801000100030004000909" // ···P············ 00000040

      "\h0C0780001B81858200090C0000000007" // ················ 00000050

      "\h00000002B900250100F103C301360006" // ····¹·%··ñ·Ã·6·· 00000060

      "\h81990000001281970000080008000101" // ················ 00000070

      "\h000B0401C0C1000981A80200F0FFFFFF" // ····ÀÁ···¨··ð··· 00000080

      "\hFF000C81950000081108110101000F81" // ················ 00000090

      "\h80A687888185869997A89580"); // ·¦·······¨··  000000A0

    WebTelnetScreenRecvRecordsUntilCursor(hWeb0, 16, 23, sRecv);
    sRecv := WebTelnetScreenGetField(hWeb0, 1);
    WebTelnetSendRecord(hWeb0, "\h7D5B6F115B6F" + StrToHostCP("1"));
    if (not WebTelnetScreenVerifyField(hWeb0, 1, StrToHostCP("1"))) or (sRecv = "") then
      WebTcpipShutdown(hWeb0);    else
      WebTelnetSendRecord(hWeb0, "\h7D5B6F115B6F" + StrToHostCP("1"));
      WebTelnetScreenRecvRecordsUntilStatus(hWeb0, "Keyboard Locked", "false");
      WebTelnetSendRecord(hWeb0, "\h7D5BF0115BF0" + StrToHostCP("12"));
      WebTelnetScreenRecvRecordsUntilText(hWeb0, 6, 22, "Choice: ");
      WebTelnetSendRecord(hWeb0, "\h7D5A5E115A5E" + StrToHostCP("12"));
      WebTelnetScreenRecvRecordsUntilField(hWeb0, 1, " ");
      WebTcpipShutdown(hWeb0);
    end;
  end TMain;
Parent topic: Web Telnet Functions
Related reference
WebTcpipSetTelnetMode Function
WebTcpipConnect Function


WebTelnetScreenVerifyStatus Function

Action

Verifies the status value of a rendered screen in an active Telnet connection.

Include file

WebAPI.bdh

Syntax

WebTelnetScreenVerifyStatus( in  hWeb        : number,
                             in  sStatusName : string,
                             in  sVerify     : string,
                             in  nOptions    : number optional,
                             in  nSeverity   : number optional := SEVERITY_ERROR,
                             in  nTextLength : number optional,
                             out sRecv       : string optional ) : boolean;

Return value

  • true if the operation succeeded

  • false otherwise

Parameter | Description
hWeb | Valid handle to a Web connection created by WebTcpipConnect and set to Telnet mode using WebTcpipSetTelnetMode.
sStatusName | Identifies the status of the value that is to be verified. The only supported status is "Keyboard Locked".
sVerify | String value that the status value should be compared against. Valid strings are "true" and "false".
nOptions

By default the retrieved content has to be equal with the compared sVerify string, case-insensitively (optional). Comparison options are:

  • TELNET_FLAG_EQUAL: Comparison is made against both whole strings. (default)

  • TELNET_FLAG_CASE_SENSITIVE: Perform comparison case-sensitively.

  • TELNET_FLAG_IS_DIFFERENT: Negates the logical comparison.

  • TELNET_FLAG_IGNORE_WHITE_SPACE: All whitespaces in both compared strings are cut before comparison is performed.

  • TELNET_FLAG_CONTAINS: Compared string must occur within the retrieved content.

  • TELNET_FLAG_FROM_LEFT: The retrieved content only has to begin with the compared string.

  • TELNET_FLAG_TRIM_LEFT: Leading blanks are trimmed from retrieved content before comparison.

  • TELNET_FLAG_TRIM_RIGHT: Trailing blanks are trimmed from retrieved content before comparison.

  • TELNET_FLAG_TRIM_BOTH: Rendered text is trimmed from both sides before comparison.

  • TELNET_FLAG_FROM_RIGHT: Comparison is made from the right of the retrieved content.

nSeverity Optional: Severity of the error that is raised if the verification fails. Can be one of the following values:
  • SEVERITY_SUCCESS: Success; no error (numerical value: 0)
  • SEVERITY_INFORMATIONAL: Informational; no error (numerical value: 1)
  • SEVERITY_WARNING: Warning; no error (numerical value: 2)
  • SEVERITY_ERROR: (Default) Error; simulation continues (numerical value: 3)
  • SEVERITY_TRANS_EXIT: Error; the active transaction is aborted (numerical value: 4)
  • SEVERITY_PROCESS_EXIT: Error; the simulation is aborted (numerical value: 5)
nTextLength | Defines how many characters of sVerify are taken for comparison with sVerify (optional). If omitted or 0, the length of sVerify is taken.
sRecv | Optional string variable where the current status value is placed (optional).

Example

dcltrans
  transaction TInit
  begin
    StrSetHostCP(1148); // 1148  (IBM EBCDIC - International (500 + Euro))
  end TInit;
  transaction TMain
  var
    hWeb0     : number;
    iFieldPos : number;
    sRecv     : string;
  begin
    WebTcpipConnect(hWeb0, "My.TelnetHost.IP", WEB_PORT_TELNET); // Port: 23
    WebTcpipSetTelnetMode(hWeb0, TERMINAL_TYPE_3270, 80, 24, true,
      TELNET_MODEOPT_RFC_1576 | TELNET_MODEOPT_AUTO_RECV);
    WebTelnetRecvCommand(hWeb0, TELNET_CMD_DO, TELNET_OPT_TerminalType);
    WebTelnetSendCommand(hWeb0, TELNET_CMD_WILL, TELNET_OPT_TerminalType);
    WebTelnetRecvSubNegotiation(hWeb0, TELNET_OPT_TerminalType);
    WebTelnetSendTerminalType(hWeb0, "IBM-3278-2-E");
    WebTelnetRecvCommand(hWeb0, TELNET_CMD_DO, TELNET_OPT_EndOfRecord);
    WebTelnetRecvCommand(hWeb0, TELNET_CMD_WILL, TELNET_OPT_EndOfRecord);
    WebTelnetRecvCommand(hWeb0, TELNET_CMD_DO, TELNET_OPT_TransmitBinary);
    WebTelnetRecvCommand(hWeb0, TELNET_CMD_WILL, TELNET_OPT_TransmitBinary);
    WebTelnetSendCommand(hWeb0, TELNET_CMD_WILL, TELNET_OPT_EndOfRecord);
    WebTelnetSendCommand(hWeb0, TELNET_CMD_DO, TELNET_OPT_EndOfRecord);
    WebTelnetSendCommand(hWeb0, TELNET_CMD_WILL, TELNET_OPT_TransmitBinary);
    WebTelnetSendCommand(hWeb0, TELNET_CMD_DO, TELNET_OPT_TransmitBinary);
    WebTelnetRecvCommand(hWeb0, TELNET_CMD_DO, TELNET_OPT_TransmitBinary);
    WebTelnetRecvCommand(hWeb0, TELNET_CMD_WILL, TELNET_OPT_TransmitBinary);
    WebTelnetRecvRecord(hWeb0);
    WebTelnetRecvRecord(hWeb0);
    WebTelnetSendRecord(hWeb0,
      "\h88001181A600000B0100005000180050" // ····¦······P···P 00000000

      "\h001800168186000800F4F1F1F2F2F3F3" // ·········ôññòòóó 00000010

      "\hF4F4F5F5F6F6F7F7000D81870400F0F1" // ôôõõöö÷÷······ðñ 00000020

      "\hF1F2F2F4F40007818800010200178181" // ñòòôô··········· 00000030

      "\h01000050001801000100030004000909" // ···P············ 00000040

      "\h0C0780001B81858200090C0000000007" // ················ 00000050

      "\h00000002B900250100F103C301360006" // ····¹·%··ñ·Ã·6·· 00000060

      "\h81990000001281970000080008000101" // ················ 00000070

      "\h000B0401C0C1000981A80200F0FFFFFF" // ····ÀÁ···¨··ð··· 00000080

      "\hFF000C81950000081108110101000F81" // ················ 00000090

      "\h80A687888185869997A89580");  // ·¦·······¨··   000000A0

    WebTelnetScreenRecvRecordsUntilCursor(hWeb0, 16, 23, sRecv);
    if WebTelnetScreenVerifyStatus(hWeb0,"Keyboard Locked","false" ) then
      WebTelnetSendRecord(hWeb0, "\h7D5B6F115B6F" + StrToHostCP("1"));
      WebTelnetScreenRecvRecordsUntilStatus(hWeb0, "Keyboard Locked", "false");
      WebTelnetSendRecord(hWeb0, "\h7D5BF0115BF0" + StrToHostCP("12"));
      WebTelnetScreenRecvRecordsUntilText(hWeb0, 6, 22, "Choice: ");
      WebTelnetSendRecord(hWeb0, "\h7D5A5E115A5E" + StrToHostCP("12"));
      WebTelnetScreenRecvRecordsUntilField(hWeb0, 1, " ");
      WebTcpipShutdown(hWeb0);
    else
      WebTcpipShutdown(hWeb0);
    end;
  end TMain;
Parent topic: Web Telnet Functions
Related reference
WebTcpipSetTelnetMode Function
WebTcpipConnect Function


WebTelnetScreenVerifyText Function

Action

Verifies rendered screen content in an active Telnet connection.

Include file

WebAPI.bdh

Syntax

WebTelnetScreenVerifyText(    in  hWeb      : number,
                              in  nCol      : number,
                              in  nRow      : number,
                              in  sVerify   : string,
                              in  nOptions  : number optional,
                              in  nSeverity : number optional := SEVERITY_ERROR,
                              in  nLength   : number optional,
                              out sRecv     : string optional ) : boolean;

Return value

  • true if the operation succeeded

  • false otherwise

Parameter | Description
hWeb | Valid handle to a Web connection created by WebTcpipConnect and set to Telnet mode using WebTcpipSetTelnetMode.
nCol | 1-based screen column from where to perform the text comparison.
nRow | 1-based screen row from where to perform the text comparison.
sVerify | Text to compare.
nOptions

By default the retrieved content has to be equal with the compared sVerify string, case-insensitively (optional). Comparison options are:

  • TELNET_FLAG_EQUAL: Comparison is made against both whole strings. (default)

  • TELNET_FLAG_CASE_SENSITIVE: Perform comparison case-sensitively.

  • TELNET_FLAG_IS_DIFFERENT: Negates the logical comparison.

  • TELNET_FLAG_IGNORE_WHITE_SPACE: All whitespaces in both compared strings are cut before comparison is performed.

  • TELNET_FLAG_CONTAINS: Compared string must occur within the retrieved content.

  • TELNET_FLAG_FROM_LEFT: The retrieved content only has to begin with the compared string.

  • TELNET_FLAG_TRIM_LEFT: Leading blanks are trimmed from retrieved content before comparison.

  • TELNET_FLAG_TRIM_RIGHT: Trailing blanks are trimmed from retrieved content before comparison.

  • TELNET_FLAG_TRIM_BOTH: Rendered text is trimmed from both sides before comparison.

  • TELNET_FLAG_FROM_RIGHT: Comparison is made from the right of the retrieved content.

nSeverity Optional: Severity of the error that is raised if the verification fails. Can be one of the following values:
  • SEVERITY_SUCCESS: Success; no error (numerical value: 0)
  • SEVERITY_INFORMATIONAL: Informational; no error (numerical value: 1)
  • SEVERITY_WARNING: Warning; no error (numerical value: 2)
  • SEVERITY_ERROR: (Default) Error; simulation continues (numerical value: 3)
  • SEVERITY_TRANS_EXIT: Error; the active transaction is aborted (numerical value: 4)
  • SEVERITY_PROCESS_EXIT: Error; the simulation is aborted (numerical value: 5)
nTextLength | Length of screen portion to compare with sVerify (optional). If omitted or 0, the length of sVerify is compared.
sRecv | Optional string variable indicating given position where screen portion is to be placed (optional).

Example

dcltrans
  transaction TInit
  begin
    StrSetHostCP(1148); // 1148  (IBM EBCDIC - International (500 + Euro))
  end TInit;
  transaction TMain
  var
    hWeb0     : number;
    iFieldPos : number;
    sRecv     : string;
  begin
    WebTcpipConnect(hWeb0, "My.TelnetHost.IP", WEB_PORT_TELNET); // Port: 23
    WebTcpipSetTelnetMode(hWeb0, TERMINAL_TYPE_3270, 80, 24, true,
      TELNET_MODEOPT_RFC_1576 | TELNET_MODEOPT_AUTO_RECV);
    WebTelnetRecvCommand(hWeb0, TELNET_CMD_DO, TELNET_OPT_TerminalType);
    WebTelnetSendCommand(hWeb0, TELNET_CMD_WILL, TELNET_OPT_TerminalType);
    WebTelnetRecvSubNegotiation(hWeb0, TELNET_OPT_TerminalType);
    WebTelnetSendTerminalType(hWeb0, "IBM-3278-2-E");
    WebTelnetRecvCommand(hWeb0, TELNET_CMD_DO, TELNET_OPT_EndOfRecord);
    WebTelnetRecvCommand(hWeb0, TELNET_CMD_WILL, TELNET_OPT_EndOfRecord);
    WebTelnetRecvCommand(hWeb0, TELNET_CMD_DO, TELNET_OPT_TransmitBinary);
    WebTelnetRecvCommand(hWeb0, TELNET_CMD_WILL, TELNET_OPT_TransmitBinary);
    WebTelnetSendCommand(hWeb0, TELNET_CMD_WILL, TELNET_OPT_EndOfRecord);
    WebTelnetSendCommand(hWeb0, TELNET_CMD_DO, TELNET_OPT_EndOfRecord);
    WebTelnetSendCommand(hWeb0, TELNET_CMD_WILL, TELNET_OPT_TransmitBinary);
    WebTelnetSendCommand(hWeb0, TELNET_CMD_DO, TELNET_OPT_TransmitBinary);
    WebTelnetRecvCommand(hWeb0, TELNET_CMD_DO, TELNET_OPT_TransmitBinary);
    WebTelnetRecvCommand(hWeb0, TELNET_CMD_WILL, TELNET_OPT_TransmitBinary);
    WebTelnetRecvRecord(hWeb0);
    WebTelnetRecvRecord(hWeb0);
    WebTelnetSendRecord(hWeb0,
      "\h88001181A600000B0100005000180050" // ····¦······P···P 00000000

      "\h001800168186000800F4F1F1F2F2F3F3" // ·········ôññòòóó 00000010

      "\hF4F4F5F5F6F6F7F7000D81870400F0F1" // ôôõõöö÷÷······ðñ 00000020

      "\hF1F2F2F4F40007818800010200178181" // ñòòôô··········· 00000030

      "\h01000050001801000100030004000909" // ···P············ 00000040

      "\h0C0780001B81858200090C0000000007" // ················ 00000050

      "\h00000002B900250100F103C301360006" // ····¹·%··ñ·Ã·6·· 00000060

      "\h81990000001281970000080008000101" // ················ 00000070

      "\h000B0401C0C1000981A80200F0FFFFFF" // ····ÀÁ···¨··ð··· 00000080

      "\hFF000C81950000081108110101000F81" // ················ 00000090

      "\h80A687888185869997A89580"); // ·¦·······¨·· 000000A0

    WebTelnetScreenRecvRecordsUntilCursor(hWeb0, 16, 23, sRecv);
    if WebTelnetScreenVerifyText(hWeb0, 7, 22, "Comments") then
      WebTelnetSendRecord(hWeb0, "\h7D5B6F115B6F" + StrToHostCP("1"));
      WebTelnetScreenRecvRecordsUntilStatus(hWeb0, "Keyboard Locked", "false");
      WebTelnetSendRecord(hWeb0, "\h7D5BF0115BF0" + StrToHostCP("12"));
      WebTelnetScreenVerifyText(hWeb0, 6, 22, "Choice:");
      WebTelnetSendRecord(hWeb0, "\h7D5A5E115A5E" + StrToHostCP("12"));
      WebTelnetScreenRecvRecordsUntilField(hWeb0, 1, " ");
      WebTcpipShutdown(hWeb0);
    else
      WebTcpipShutdown(hWeb0);
    end;
  end TMain;
Parent topic: Web Telnet Functions
Related reference
WebTcpipSetTelnetMode Function
WebTcpipConnect Function


WebTelnetSendCommand Function

Action

Sends a Telnet command to a Telnet connection.

Include file

WebAPI.bdh

Syntax

WebTelnetSendCommand(    in hWeb : number,
                         in iCmd : number,
                         in iOpt : number optional ) : boolean;

Return value

  • true if the operation was successful

  • false otherwise

Parameter | Description
hWeb | Valid handle to a Web connection created by WebTcpipConnect and set to Telnet mode using WebTcpipSetTelnetMode.
iCmd

Telnet command to be sent to server. May be:

  • TELNET_CMD_SE: End of sub-negotiation parameters.

  • TELNET_CMD_NOP: No operation.

  • TELNET_CMD_DataMark: The data stream portion of a synch. This should always be accompanied by an urgent TCP notification.

  • TELNET_CMD_Break: NVT character BRK.

  • TELNET_CMD_InterruptProcess: The function IP.

  • TELNET_CMD_AbortOutput: The function AO.

  • TELNET_CMD_AreYouThere: The function AYT.

  • TELNET_CMD_EraseCharacter: The function EC.

  • TELNET_CMD_EraseLine: The function EL.

  • TELNET_CMD_GoAhead: The GA signal.

  • TELNET_CMD_SB: Indicates that what follows is sub-negotiation of the indicated option.

  • TELNET_CMD_WILL: Indicates the desire to begin performing (or is confirmation that you are now performing) the indicated option.

  • TELNET_CMD_WONT: Indicates the refusal to perform (or continue performing) the indicated option.

  • TELNET_CMD_DO: Indicates the request that the other party perform (or confirmation that you are expecting the other party to perform) the indicated option.

  • TELNET_CMD_DONT: Indicates the demand that the other party stop performing (or confirmation that you are no longer expecting the other party to perform) the indicated option.

  • TELNET_CMD_EOF: End of file

  • TELNET_CMD_SUSP: Suspend current process

  • TELNET_CMD_ABORT: Abort process

  • TELNET_CMD_EOR: End of record (RFC 885)
iOpt

Optional Telnet command option (optional). Only valid for commands WILL/WONT/DO/DONT and SB.

For a complete list of telnet options, please refer to http://www.iana.org/assignments/telnet-options.

The following predefined constants are available, however (due to the nature of Telnet options) are not mandatory:

  • TELNET_OPT_TransmitBinary: Binary transmission [RFC856, RFC1576]

  • TELNET_OPT_Echo: Echo [RFC857, RFC1576]

  • TELNET_OPT_Reconnection: Reconnection [NIC50005]

  • TELNET_OPT_SuppressGoAhead: Suppress go ahead [RFC858, RFC1576]

  • TELNET_OPT_ApproxMsgSizeNegotiation: Approx message size negotiation [ETHERNET]

  • TELNET_OPT_Status: Status [RFC859, RFC1576]

  • TELNET_OPT_TimingMark: Timing mark [RFC860, RFC1576]

  • TELNET_OPT_RemoteContrTransAndEcho: Remote controlled trans and echo [RFC726]

  • TELNET_OPT_OutputLineWidth: Output line width [NIC50005]

  • TELNET_OPT_OutputPageSize: Output page size [NIC50005]

  • TELNET_OPT_OutputCRDisp: Output carriage-return disposition [RFC652]

  • TELNET_OPT_OutputHorTabStops: Output horizontal tab stops [RFC653]

  • TELNET_OPT_OutputHorTabDisp: Output horizontal tab disposition [RFC654]

  • TELNET_OPT_OutputFFDisp: Output form-feed disposition [RFC655]

  • TELNET_OPT_OutputVerTabStops: Output vertical tab stops [RFC656]

  • TELNET_OPT_OutputVerTabDisp: Output vertical tab disposition [RFC657]

  • TELNET_OPT_OutputLFDisp: Output line-feed disposition [RFC658]

  • TELNET_OPT_ExtendedASCII: Extended ASCII [RFC698]

  • TELNET_OPT_Logout: Logout [RFC727]

  • TELNET_OPT_ByteMacro: Byte macro [RFC735]

  • TELNET_OPT_DataEntryTerminal: Data entry terminal [RFC1043, RFC732]

  • TELNET_OPT_SupDup: SUPDUP [RFC736, RFC734]

  • TELNET_OPT_SupDupOutput: SUPDUP output [RFC749]

  • TELNET_OPT_SendLocation: Send location [RFC779]

  • TELNET_OPT_TerminalType: Terminal type [RFC1091, RFC930, RFC1576]

  • TELNET_OPT_EndOfRecord: End of record [RFC885, RFC1576]

  • TELNET_OPT_TacacsUserId: TACACS user identification [RFC927]

  • TELNET_OPT_OutputMarking: Output marking [RFC933]

  • TELNET_OPT_TerminalLocNr: Terminal location number [RFC946]

  • TELNET_OPT_3270Regime: Telnet 3270 regime [RFC1041, RFC1576]

  • TELNET_OPT_X3PAD: X.3 PAD [RFC1053]

  • TELNET_OPT_NegotiateWindowSize: Negotiate about window size [RFC1073]

  • TELNET_OPT_TerminalSpeed: Terminal speed [RFC1079]

  • TELNET_OPT_RemoteFlowControl: Remote flow control [RFC1372]

  • TELNET_OPT_LineMode: Line mode [RFC1184]

  • TELNET_OPT_XDisplayLocation: X display location [RFC1096]

  • TELNET_OPT_Environment: Environment option [RFC1408]

  • TELNET_OPT_Authentication: Authentication option [RFC2941]

  • TELNET_OPT_Encryption: Encryption option [RFC2946]

  • TELNET_OPT_NewEnvironment: New environment option [RFC1572]

  • TELNET_OPT_TN3270E: TN3270E [RFC1647]

  • TELNET_OPT_XAUTH: XAUTH [Earhart]

  • TELNET_OPT_CHARSET: CHARSET [RFC2066]

  • TELNET_OPT_RemoteSerialPort: Telnet remote serial port (RSP) [Barnes]

  • TELNET_OPT_ComPortControl: Com port control option [RFC2217]

  • TELNET_OPT_SuppressLocalEcho: Telnet suppress local echo [Atmar]

  • TELNET_OPT_StartTLS: Telnet start TLS [Boe]

  • TELNET_OPT_Kermit: KERMIT [RFC2840]

  • TELNET_OPT_SendUrl: SEND-URL [Croft]

  • TELNET_OPT_ForwardX: FORWARD_X [Altman]

  • TELNET_OPT_PragmaLogon: TELOPT PRAGMA LOGON [McGregory]

  • TELNET_OPT_SspiLogon: TELOPT SSPI LOGON [McGregory]

  • TELNET_OPT_PragmaHeartbeat: TELOPT PRAGMA HEARTBEAT [McGregory]

  • TELNET_OPT_EXOPL: Extended options list [RFC861]

Example

dcltrans
  transaction TInit
  begin
    StrSetHostCP(28591); // 28591 (ISO 8859-1 Latin I)
  end TInit;
  transaction   TMain
  var
    hWeb0     : number;
    sBuffer   : string;
    sBoundary : string;
    nOption   : number;
  begin
    WebTcpipConnect(hWeb0, "My.TelnetHost.IP", WEB_PORT_TELNET);
    WebTcpipSetTelnetMode(hWeb0, TERMINAL_TYPE_ANSI, 80, 24, true,
      TELNET_MODEOPT_SYNC);
    WebTcpipGetOptions(hWeb0, nOption);
    if nOption <> TELNET_MODEOPT_RFC_1576 then
      WebTcpipSetOptions(hWeb0, TELNET_MODEOPT_RFC_1576);
    end;
    WebTelnetRecvCommand(hWeb0, TELNET_CMD_DO, TELNET_OPT_TerminalType);
    WebTelnetRecvCommand(hWeb0, TELNET_CMD_DO, TELNET_OPT_TerminalSpeed);
    WebTelnetRecvCommand(hWeb0, TELNET_CMD_DO, TELNET_OPT_XDisplayLocation);
    WebTelnetRecvCommand(hWeb0, TELNET_CMD_DO, TELNET_OPT_NewEnvironment);
    WebTelnetSendCommand(hWeb0, TELNET_CMD_WILL, TELNET_OPT_TerminalType);
    WebTelnetSendCommand(hWeb0, TELNET_CMD_WONT, TELNET_OPT_TerminalSpeed);
    WebTelnetSendCommand(hWeb0, TELNET_CMD_WONT, TELNET_OPT_XDisplayLocation);
    WebTelnetSendCommand(hWeb0, TELNET_CMD_WONT, TELNET_OPT_NewEnvironment);
    WebTelnetRecvSubNegotiation(hWeb0, TELNET_OPT_TerminalType);
    WebTelnetSendTerminalType(hWeb0, "vt100");
    WebTelnetRecvCommand(hWeb0, TELNET_CMD_WILL, TELNET_OPT_SuppressGoAhead);
    WebTelnetRecvCommand(hWeb0, TELNET_CMD_DO, TELNET_OPT_Echo);
    WebTelnetRecvCommand(hWeb0, TELNET_CMD_DO, TELNET_OPT_NegotiateWindowSize);
    WebTelnetRecvCommand(hWeb0, TELNET_CMD_WILL, TELNET_OPT_Status);
    WebTelnetRecvCommand(hWeb0, TELNET_CMD_DO, TELNET_OPT_RemoteFlowControl);
    WebTelnetSendCommand(hWeb0, TELNET_CMD_DO, TELNET_OPT_SuppressGoAhead);
    WebTelnetSendCommand(hWeb0, TELNET_CMD_WONT, TELNET_OPT_Echo);
    WebTelnetSendCommand(hWeb0, TELNET_CMD_WILL, TELNET_OPT_NegotiateWindowSize);
    WebTelnetSendSubNegotiation(hWeb0, TELNET_OPT_NegotiateWindowSize, "\h00500018");
    WebTelnetSendCommand(hWeb0, TELNET_CMD_DONT, TELNET_OPT_Status);
    WebTelnetSendCommand(hWeb0, TELNET_CMD_WONT, TELNET_OPT_RemoteFlowControl);
    WebTelnetRecvCommand(hWeb0, TELNET_CMD_WILL, TELNET_OPT_Echo);
    WebTcpipGetPacketBoundary(hWeb0, sBoundary);
    WebTcpipRecvPacketsUntilData(hWeb0, "login: ");
    WebTelnetTypeKeys(hWeb0, StrToHostCP("leo"), 359.3, TELNET_FLAG_CASE_SENSITIVE);
    WebTcpipSendBin(hWeb0, "\h0D00");
    WebTcpipRecvExact(hWeb0, NULL, 390);
    WebTcpipSetPacketBoundary(hWeb0, sBoundary);
    WebTcpipRecvUntilIdle(hWeb0, NULL, 5000);
    WebTcpipSendBin(hWeb0, "\h0D000D0A");
    WebTcpipRecvPackets(hWeb0, NULL, 3);
    WebTcpipSendBin(hWeb0, "\h0D00");
    WebTcpipSendPacket(hWeb0, StrToHostCP("8") + "\h0D00");
    WebTcpipRecvClose(hWeb0, NULL);
    WebTcpipShutdown(hWeb0);
  end TMain;
Parent topic: Web Telnet Functions
Related reference
WebTcpipSetTelnetMode Function
WebTcpipConnect Function


WebTelnetSendRecord Function

Action

Sends a Telnet record sequence to a terminal service server, which is a shortcut to <BinaryData> IAC EOR.

Include file

WebAPI.bdh

Syntax

WebTelnetSendRecord(    in hWeb  : number,
                        in sData : string ) : boolean;

Return value

  • true if the operation was successful

  • false otherwise

Parameter | Description
hWeb | Valid handle to a Web connection created by WebTcpipConnect and set to Telnet mode using WebTcpipSetTelnetMode.
sData | Binary data to be sent to a terminal server.

Example

dcltrans  transaction TInit
  begin
    StrSetHostCP(1148);
// 1148  (IBM EBCDIC - International
(500 + Euro))
  end TInit;
   transaction TMain
  var
    hWeb0     : number;
    iFieldPos : number;
  begin
    WebTcpipConnect(hWeb0, "My.TelnetHost.IP", WEB_PORT_TELNET);
// Port: 23
    WebTcpipSetTelnetMode(hWeb0, TERMINAL_TYPE_3270, 80, 24, true, TELNET_MODEOPT_RFC_1576 | TELNET_MODEOPT_AUTO_RECV);
    WebTelnetRecvCommand(hWeb0, TELNET_CMD_DO, TELNET_OPT_TerminalType);
    WebTelnetSendCommand(hWeb0, TELNET_CMD_WILL, TELNET_OPT_TerminalType);
    WebTelnetRecvSubNegotiation(hWeb0, TELNET_OPT_TerminalType);
    WebTelnetSendTerminalType(hWeb0, "IBM-3278-2-E");
    WebTelnetRecvCommand(hWeb0, TELNET_CMD_DO, TELNET_OPT_EndOfRecord);
    WebTelnetRecvCommand(hWeb0, TELNET_CMD_WILL, TELNET_OPT_EndOfRecord);
    WebTelnetRecvCommand(hWeb0, TELNET_CMD_DO, TELNET_OPT_TransmitBinary);
    WebTelnetRecvCommand(hWeb0, TELNET_CMD_WILL, TELNET_OPT_TransmitBinary);
    WebTelnetSendCommand(hWeb0, TELNET_CMD_WILL, TELNET_OPT_EndOfRecord);
    WebTelnetSendCommand(hWeb0, TELNET_CMD_DO, TELNET_OPT_EndOfRecord);
    WebTelnetSendCommand(hWeb0, TELNET_CMD_WILL, TELNET_OPT_TransmitBinary);
    WebTelnetSendCommand(hWeb0, TELNET_CMD_DO, TELNET_OPT_TransmitBinary);
    WebTelnetRecvCommand(hWeb0, TELNET_CMD_DO, TELNET_OPT_TransmitBinary);
    WebTelnetRecvCommand(hWeb0, TELNET_CMD_WILL, TELNET_OPT_TransmitBinary);
    WebTelnetRecvRecord(hWeb0);
    WebTelnetRecvRecord(hWeb0);
    WebTelnetSendRecord(hWeb0,
      "\h88001181A600000B0100005000180050" // ····¦······P···P 00000000

      "\h001800168186000800F4F1F1F2F2F3F3" // ·········ôññòòóó 00000010

      "\hF4F4F5F5F6F6F7F7000D81870400F0F1" // ôôõõöö÷÷······ðñ 00000020

      "\hF1F2F2F4F40007818800010200178181" // ñòòôô··········· 00000030

      "\h01000050001801000100030004000909" // ···P············ 00000040

      "\h0C0780001B81858200090C0000000007" // ················ 00000050

      "\h00000002B900250100F103C301360006" // ····¹·%··ñ·Ã·6·· 00000060

      "\h81990000001281970000080008000101" // ················ 00000070

      "\h000B0401C0C1000981A80200F0FFFFFF" // ····ÀÁ···¨··ð··· 00000080

      "\hFF000C81950000081108110101000F81" // ················ 00000090

      "\h80A687888185869997A89580");    // ·¦·······¨··    000000A0
    WebTelnetRecvRecord(hWeb0);
    WebTcpipRecvPackets(hWeb0);
    WebTelnetRecvRecord(hWeb0);
    WebTelnetSendRecord(hWeb0, "\h7D5B6F115B6F" + StrToHostCP("1"));
    WebTcpipScreenRecvPacketsUntilStatus(hWeb0, "Keyboard Locked", "false");
    WebTelnetSendRecord(hWeb0, "\h7D5BF0115BF0" + StrToHostCP("12"));
    WebTcpipScreenRecvPacketsUntilText(hWeb0, 6, 22, "Choice: ");
    WebTelnetSendRecord(hWeb0, "\h7D5A5E115A5E" + StrToHostCP("12"));
    WebTcpipSetPacketBoundary(hWeb0, "\nFFEF");
    WebTcpipScreenRecvPacketsUntilField(hWeb0, 1, "");
    iFieldPos := WebTelnetScreenGetFieldIndex(hWeb0,16, 22);
    if iFieldPos = 1 then
      WebTcpipShutdown(hWeb0);
    end;
  end TMain;
Parent topic: Web Telnet Functions
Related reference
WebTcpipSetTelnetMode Function
WebTcpipConnect Function


WebTelnetSendRecordExecute Function

Action

Sends a Telnet record to a terminal services server. The data record is dynamically composed from a record previously specified in the corresponding WebTelnetSendRecordPrepare command, with field values specified in one or more WebTelnetSetRecordString commands.

Include file

WebAPI.bdh

Syntax

WebTelnetSendRecordExecute( in hWeb : number,
  in hHandle : number ) : boolean;

Return value

  • true if the operation was successful

  • false otherwise

Parameter | Description
hWeb | Valid handle to a Web connection created by WebTcpipConnect and set to Telnet mode using WebTcpipSetTelnetMode.
sData | Valid handle to a data record that is being prepared, from a previous WebTelnetSendRecordPrepare command

Example

dcltrans
  transaction TInit
  begin
    StrSetHostCP(37); // 37    (IBM EBCDIC - U.S./Canada)
    ErrorAdd(FACILITY_WINSOCK, 18, SEVERITY_TRANS_EXIT);
  end TInit;

  transaction TMain
  var
    hHandle0 : number;
    hWeb0    : number;
  begin
    WebTcpipConnect(hWeb0, "My.Telnet.Host.IP", 5558);
    WebTcpipSetTelnetMode(hWeb0, TERMINAL_TYPE_3270, 80, 24, true, TELNET_MODEOPT_RFC_1576 | TELNET_MODEOPT_AUTO_RECV |
      TELNET_MODEOPT_3270E_AUTO_REPLY);
    WebTelnetRecvCommand(hWeb0, TELNET_CMD_DO, TELNET_OPT_TN3270E);
    WebTelnetSendCommand(hWeb0, TELNET_CMD_WILL, TELNET_OPT_TN3270E);
    WebTelnetRecvSubNegotiation(hWeb0, TELNET_OPT_TN3270E);
    WebTelnetSendSubNegotiation(hWeb0, TELNET_OPT_TN3270E, TN3270E_CMD_DEVICE_TYPE + TN3270E_CMD_REQUEST + "IBM-3278-2-E");
    WebTelnetRecvSubNegotiation(hWeb0, TELNET_OPT_TN3270E);
    WebTelnetSendSubNegotiation(hWeb0, TELNET_OPT_TN3270E, TN3270E_CMD_FUNCTIONS + TN3270E_CMD_REQUEST + TN3270E_FUNC_BIND_IMAGE
       + TN3270E_FUNC_SYSREQ);
    WebTelnetRecvSubNegotiation(hWeb0, TELNET_OPT_TN3270E);
    WebTelnetSendSubNegotiation(hWeb0, TELNET_OPT_TN3270E, TN3270E_CMD_FUNCTIONS + TN3270E_CMD_IS);
    WebTelnetScreenRecvRecordsUntilCursor(hWeb0, 26, 10);

    ThinkTime(8.7);
    WebTelnetSendRecordPrepare(hHandle0, "\h00000000007D4C7E1140C4" + StrToHostCP("1") + "\h114BE9" + "%s1" + "\h114CC3" + "%s2"
       + "\h114CF9" + "%s3" + "\h114EC9" + "%s4" + "\h1150E9" + "%s5" + "\h115B61" + StrToHostCP(
      "Please type your userid.                                                       "));
    WebTelnetSetRecordString(hHandle0, "%s1", StrToHostCP("USER1   "));
    WebTelnetSetRecordString(hHandle0, "%s2", StrToHostCP("        "));
    WebTelnetSetRecordString(hHandle0, "%s3", StrToHostCP("USER1   "));
    WebTelnetSetRecordString(hHandle0, "%s4", StrToHostCP("   "));
    WebTelnetSetRecordString(hHandle0, "%s5", StrToHostCP("        "));
    WebTelnetSendRecordExecute(hWeb0, hHandle0);
    WebTelnetScreenRecvRecordsUntilStatus(hWeb0, "Keyboard locked", "False");

    ThinkTime(2.3);
    WebTelnetSendRecordPrepare(hHandle0, "\h00000000007D40C4" + StrToHostCP(
      "acctE0012I Signon complete at V00F, for user USER1. Local security is disabled. 13:17:29"));
    WebTelnetSendRecordExecute(hWeb0, hHandle0);
    WebTelnetScreenRecvRecordsUntilStatus(hWeb0, "Keyboard locked", "False");

    WebTelnetSendRecordPrepare(hHandle0, "\h00000000007D4AF3114AD5" + "%s3" + "\h114AE2" + "%s4");
    WebTelnetSetRecordString(hHandle0, "%s3", StrToHostCP("d"));
    WebTelnetSetRecordString(hHandle0, "%s4", StrToHostCP("12345"));
    WebTelnetSendRecordExecute(hWeb0, hHandle0);
    WebTelnetScreenRecvRecordsUntilStatus(hWeb0, "Keyboard locked", "False");

    ThinkTime(9.9);
    WebTelnetSendRecord(hWeb0, "\h00000000006D"); // •••••m
    WebTelnetRecvRecord(hWeb0);

    ThinkTime(2.1);
    WebTelnetSendRecordPrepare(hHandle0, "\h00000000007D40C4" + StrToHostCP("exit"));
    WebTelnetSendRecordExecute(hWeb0, hHandle0);
    WebTelnetRecvRecordsUntilClose(hWeb0);
    WebTcpipShutdown(hWeb0);
end TMain;
Parent topic: Web Telnet Functions
Related reference
WebTelnetSendRecordPrepare Function
WebTelnetSetRecordString Function


WebTelnetSendRecordPrepare Function

Action

Prepares a Telnet recording session consisting of binary data and text fields for later transmission to a terminal services server.

Include file

WebAPI.bdh

Syntax

WebTelnetSendRecordPrepare( out hHandle : number,
  in sData : string ) : boolean;

Return value

  • true if the operation was successful

  • false otherwise

Parameter | Description
hHandle | Variable receiving the handle to the data record being prepared, to be used following commands WebTelnetSendRecordString and WebTelnetSendRecordExecute.
sData | The binary data containing text fields that is to be prepared for later transmission to a terminal services server.

Example

dcltrans
  transaction TInit
  begin
    StrSetHostCP(37); // 37    (IBM EBCDIC - U.S./Canada)
    ErrorAdd(FACILITY_WINSOCK, 18, SEVERITY_TRANS_EXIT);
  end TInit;

  transaction TMain
  var
    hHandle0 : number;
    hWeb0    : number;
  begin
    WebTcpipConnect(hWeb0, "My.Telnet.Host.IP", 5558);
    WebTcpipSetTelnetMode(hWeb0, TERMINAL_TYPE_3270, 80, 24, true, TELNET_MODEOPT_RFC_1576 | TELNET_MODEOPT_AUTO_RECV |
      TELNET_MODEOPT_3270E_AUTO_REPLY);
    WebTelnetRecvCommand(hWeb0, TELNET_CMD_DO, TELNET_OPT_TN3270E);
    WebTelnetSendCommand(hWeb0, TELNET_CMD_WILL, TELNET_OPT_TN3270E);
    WebTelnetRecvSubNegotiation(hWeb0, TELNET_OPT_TN3270E);
    WebTelnetSendSubNegotiation(hWeb0, TELNET_OPT_TN3270E, TN3270E_CMD_DEVICE_TYPE + TN3270E_CMD_REQUEST + "IBM-3278-2-E");
    WebTelnetRecvSubNegotiation(hWeb0, TELNET_OPT_TN3270E);
    WebTelnetSendSubNegotiation(hWeb0, TELNET_OPT_TN3270E, TN3270E_CMD_FUNCTIONS + TN3270E_CMD_REQUEST + TN3270E_FUNC_BIND_IMAGE
       + TN3270E_FUNC_SYSREQ);
    WebTelnetRecvSubNegotiation(hWeb0, TELNET_OPT_TN3270E);
    WebTelnetSendSubNegotiation(hWeb0, TELNET_OPT_TN3270E, TN3270E_CMD_FUNCTIONS + TN3270E_CMD_IS);
    WebTelnetScreenRecvRecordsUntilCursor(hWeb0, 26, 10);

    ThinkTime(8.7);
    WebTelnetSendRecordPrepare(hHandle0, "\h00000000007D4C7E1140C4" + StrToHostCP("1") + "\h114BE9" + "%s1" + "\h114CC3" + "%s2"
       + "\h114CF9" + "%s3" + "\h114EC9" + "%s4" + "\h1150E9" + "%s5" + "\h115B61" + StrToHostCP(
      "Please type your userid.                                                       "));
    WebTelnetSetRecordString(hHandle0, "%s1", StrToHostCP("USER1   "));
    WebTelnetSetRecordString(hHandle0, "%s2", StrToHostCP("        "));
    WebTelnetSetRecordString(hHandle0, "%s3", StrToHostCP("USER1   "));
    WebTelnetSetRecordString(hHandle0, "%s4", StrToHostCP("   "));
    WebTelnetSetRecordString(hHandle0, "%s5", StrToHostCP("        "));
    WebTelnetSendRecordExecute(hWeb0, hHandle0);
    WebTelnetScreenRecvRecordsUntilStatus(hWeb0, "Keyboard locked", "False");

    ThinkTime(2.3);
    WebTelnetSendRecordPrepare(hHandle0, "\h00000000007D40C4" + StrToHostCP(
      "acctE0012I Signon complete at V00F, for user USER1. Local security is disabled. 13:17:29"));
    WebTelnetSendRecordExecute(hWeb0, hHandle0);
    WebTelnetScreenRecvRecordsUntilStatus(hWeb0, "Keyboard locked", "False");

    WebTelnetSendRecordPrepare(hHandle0, "\h00000000007D4AF3114AD5" + "%s3" + "\h114AE2" + "%s4");
    WebTelnetSetRecordString(hHandle0, "%s3", StrToHostCP("d"));
    WebTelnetSetRecordString(hHandle0, "%s4", StrToHostCP("12345"));
    WebTelnetSendRecordExecute(hWeb0, hHandle0);
    WebTelnetScreenRecvRecordsUntilStatus(hWeb0, "Keyboard locked", "False");

    ThinkTime(9.9);
    WebTelnetSendRecord(hWeb0, "\h00000000006D"); // •••••m
    WebTelnetRecvRecord(hWeb0);

    ThinkTime(2.1);
    WebTelnetSendRecordPrepare(hHandle0, "\h00000000007D40C4" + StrToHostCP("exit"));
    WebTelnetSendRecordExecute(hWeb0, hHandle0);
    WebTelnetRecvRecordsUntilClose(hWeb0);
    WebTcpipShutdown(hWeb0);
end TMain;
Parent topic: Web Telnet Functions
Related reference
WebTelnetSetRecordString Function
WebTelnetSendRecordExecute Function


WebTelnetSendSubNegotiation Function

Action

Sends a Telnet option sub-negotiation sequence to a terminal service server, which is a shortcut to IAC SB <Option> <Data> IAC SE.

Include file

WebAPI.bdh

Syntax

WebTelnetSendSubNegotiation(    in hWeb : number,
                                in iOpt : number,
                                in sSub : string ) : boolean;

Return value

  • true if the operation was successful

  • false otherwise

Parameter | Description
hWeb | Valid handle to a Web connection created by WebTcpipConnect and set to Telnet mode using WebTcpipSetTelnetMode.
iOpt | Telnet option to sub-negotiate with server. See constants in WebTelnetSendCommand for valid values.
sSub | Binary sub-negotiation data string to be sent to server.

Example

dcltrans
  transaction TInit
  begin
    StrSetHostCP(28591); // 28591 (ISO 8859-1 Latin I)
  end TInit;
  transaction   TMain
  var
    hWeb0     : number;
    sBuffer   : string;
    sBoundary : string;
    nOption   : number;
  begin
    WebTcpipConnect(hWeb0, "My.TelnetHost.IP", WEB_PORT_TELNET);
    WebTcpipSetTelnetMode(hWeb0, TERMINAL_TYPE_ANSI, 80, 24, true,
      TELNET_MODEOPT_SYNC);
    WebTcpipGetOptions(hWeb0, nOption);
    if nOption <> TELNET_MODEOPT_RFC_1576 then
      WebTcpipSetOptions(hWeb0, TELNET_MODEOPT_RFC_1576);
    end;
    WebTelnetRecvCommand(hWeb0, TELNET_CMD_DO, TELNET_OPT_TerminalType);
    WebTelnetRecvCommand(hWeb0, TELNET_CMD_DO, TELNET_OPT_TerminalSpeed);
    WebTelnetRecvCommand(hWeb0, TELNET_CMD_DO, TELNET_OPT_XDisplayLocation);
    WebTelnetRecvCommand(hWeb0, TELNET_CMD_DO, TELNET_OPT_NewEnvironment);
    WebTelnetSendCommand(hWeb0, TELNET_CMD_WILL, TELNET_OPT_TerminalType);
    WebTelnetSendCommand(hWeb0, TELNET_CMD_WONT, TELNET_OPT_TerminalSpeed);
    WebTelnetSendCommand(hWeb0, TELNET_CMD_WONT, TELNET_OPT_XDisplayLocation);
    WebTelnetSendCommand(hWeb0, TELNET_CMD_WONT, TELNET_OPT_NewEnvironment);
    WebTelnetRecvSubNegotiation(hWeb0, TELNET_OPT_TerminalType);
    WebTelnetSendTerminalType(hWeb0, "vt100");
    WebTelnetRecvCommand(hWeb0, TELNET_CMD_WILL, TELNET_OPT_SuppressGoAhead);
    WebTelnetRecvCommand(hWeb0, TELNET_CMD_DO, TELNET_OPT_Echo);
    WebTelnetRecvCommand(hWeb0, TELNET_CMD_DO, TELNET_OPT_NegotiateWindowSize);
    WebTelnetRecvCommand(hWeb0, TELNET_CMD_WILL, TELNET_OPT_Status);
    WebTelnetRecvCommand(hWeb0, TELNET_CMD_DO, TELNET_OPT_RemoteFlowControl);
    WebTelnetSendCommand(hWeb0, TELNET_CMD_DO, TELNET_OPT_SuppressGoAhead);
    WebTelnetSendCommand(hWeb0, TELNET_CMD_WONT, TELNET_OPT_Echo);
    WebTelnetSendCommand(hWeb0, TELNET_CMD_WILL, TELNET_OPT_NegotiateWindowSize);
    WebTelnetSendSubNegotiation(hWeb0, TELNET_OPT_NegotiateWindowSize, "\h00500018");
    WebTelnetSendCommand(hWeb0, TELNET_CMD_DONT, TELNET_OPT_Status);
    WebTelnetSendCommand(hWeb0, TELNET_CMD_WONT, TELNET_OPT_RemoteFlowControl);
    WebTelnetRecvCommand(hWeb0, TELNET_CMD_WILL, TELNET_OPT_Echo);
    WebTcpipGetPacketBoundary(hWeb0, sBoundary);
    WebTcpipRecvPacketsUntilData(hWeb0, "login: ");
    WebTelnetTypeKeys(hWeb0, StrToHostCP("leo"), 359.3, TELNET_FLAG_CASE_SENSITIVE);
    WebTcpipSendBin(hWeb0, "\h0D00");
    WebTcpipRecvExact(hWeb0, NULL, 390);
    WebTcpipSetPacketBoundary(hWeb0, sBoundary);
    WebTcpipRecvUntilIdle(hWeb0, NULL, 5000);
    WebTcpipSendBin(hWeb0, "\h0D000D0A");
    WebTcpipRecvPackets(hWeb0, NULL, 3);
    WebTcpipSendBin(hWeb0, "\h0D00");
    WebTcpipSendPacket(hWeb0, StrToHostCP("8") + "\h0D00");
    WebTcpipRecvClose(hWeb0, NULL);
    WebTcpipShutdown(hWeb0);
  end TMain;
Parent topic: Web Telnet Functions
Related reference
WebTelnetSendCommand Function
WebTcpipSetTelnetMode Function
WebTcpipConnect Function


WebTelnetSendTerminalType Function

Action

Sends simulated terminal type identification code to a Telnet server, which is a shortcut to IAC SB TT IS <TerminalTypeId> IAC SE.

Include file

WebAPI.bdh

Syntax

WebTelnetSendTerminalType(    in hWeb          : number,
                        in sTerminalType : string ) : boolean;

Return value

  • true if the operation was successful

  • false otherwise

Parameter | Description
hWeb | Valid handle to a Web connection created by WebTcpipConnect and set to Telnet mode using WebTcpipSetTelnetMode.
sTerminalType | Terminal type identification string to be sent to a Telnet server.

Example

dcltrans
  transaction TInit
  begin
    StrSetHostCP(28591); // 28591 (ISO 8859-1 Latin I)
  end TInit;
  transaction   TMain
  var
    hWeb0     : number;
    sBuffer   : string;
    sBoundary : string;
    nOption   : number;
  begin
    WebTcpipConnect(hWeb0, "My.TelnetHost.IP", WEB_PORT_TELNET);
    WebTcpipSetTelnetMode(hWeb0, TERMINAL_TYPE_ANSI, 80, 24, true,
      TELNET_MODEOPT_SYNC);
    WebTcpipGetOptions(hWeb0, nOption);
    if nOption <> TELNET_MODEOPT_RFC_1576 then
      WebTcpipSetOptions(hWeb0, TELNET_MODEOPT_RFC_1576);
    end;
    WebTelnetRecvCommand(hWeb0, TELNET_CMD_DO, TELNET_OPT_TerminalType);
    WebTelnetRecvCommand(hWeb0, TELNET_CMD_DO, TELNET_OPT_TerminalSpeed);
    WebTelnetRecvCommand(hWeb0, TELNET_CMD_DO, TELNET_OPT_XDisplayLocation);
    WebTelnetRecvCommand(hWeb0, TELNET_CMD_DO, TELNET_OPT_NewEnvironment);
    WebTelnetSendCommand(hWeb0, TELNET_CMD_WILL, TELNET_OPT_TerminalType);
    WebTelnetSendCommand(hWeb0, TELNET_CMD_WONT, TELNET_OPT_TerminalSpeed);
    WebTelnetSendCommand(hWeb0, TELNET_CMD_WONT, TELNET_OPT_XDisplayLocation);
    WebTelnetSendCommand(hWeb0, TELNET_CMD_WONT, TELNET_OPT_NewEnvironment);
    WebTelnetRecvSubNegotiation(hWeb0, TELNET_OPT_TerminalType);
    WebTelnetSendTerminalType(hWeb0, "vt100");
    WebTelnetRecvCommand(hWeb0, TELNET_CMD_WILL, TELNET_OPT_SuppressGoAhead);
    WebTelnetRecvCommand(hWeb0, TELNET_CMD_DO, TELNET_OPT_Echo);
    WebTelnetRecvCommand(hWeb0, TELNET_CMD_DO, TELNET_OPT_NegotiateWindowSize);
    WebTelnetRecvCommand(hWeb0, TELNET_CMD_WILL, TELNET_OPT_Status);
    WebTelnetRecvCommand(hWeb0, TELNET_CMD_DO, TELNET_OPT_RemoteFlowControl);
    WebTelnetSendCommand(hWeb0, TELNET_CMD_DO, TELNET_OPT_SuppressGoAhead);
    WebTelnetSendCommand(hWeb0, TELNET_CMD_WONT, TELNET_OPT_Echo);
    WebTelnetSendCommand(hWeb0, TELNET_CMD_WILL, TELNET_OPT_NegotiateWindowSize);
    WebTelnetSendSubNegotiation(hWeb0, TELNET_OPT_NegotiateWindowSize, "\h00500018");
    WebTelnetSendCommand(hWeb0, TELNET_CMD_DONT, TELNET_OPT_Status);
    WebTelnetSendCommand(hWeb0, TELNET_CMD_WONT, TELNET_OPT_RemoteFlowControl);
    WebTelnetRecvCommand(hWeb0, TELNET_CMD_WILL, TELNET_OPT_Echo);
    WebTcpipGetPacketBoundary(hWeb0, sBoundary);
    WebTcpipRecvPacketsUntilData(hWeb0, "login: ");
    WebTelnetTypeKeys(hWeb0, StrToHostCP("leo"), 359.3, TELNET_FLAG_CASE_SENSITIVE);
    WebTcpipSendBin(hWeb0, "\h0D00");
    WebTcpipRecvExact(hWeb0, NULL, 390);
    WebTcpipSetPacketBoundary(hWeb0, sBoundary);
    WebTcpipRecvUntilIdle(hWeb0, NULL, 5000);
    WebTcpipSendBin(hWeb0, "\h0D000D0A");
    WebTcpipRecvPackets(hWeb0, NULL, 3);
    WebTcpipSendBin(hWeb0, "\h0D00");
    WebTcpipSendPacket(hWeb0, StrToHostCP("8") + "\h0D00");
    WebTcpipRecvClose(hWeb0, NULL);
    WebTcpipShutdown(hWeb0);
  end TMain;
Parent topic: Web Telnet Functions
Related reference
WebTcpipSetTelnetMode Function
WebTcpipConnect Function


WebTelnetSetRecordString Function

Action

Sets the string value of a field in a data record that is being prepared for transmission to a terminal services server.

Include file

WebAPI.bdh

Syntax

WebTelnetSetRecordString( in hHandle : number,
  in sFieldname : string,
  in sValue : string,
  in iLen : number optional ) : boolean;

Return value

  • true if the operation was successful

  • false otherwise

Parameter | Description
hHandle | Valid handle to a data record that is being prepared, from a previous WebTelnetSendRecordPrepare command.
sFieldname | Name of the field. Must match one of the field names embedded in the data record previously specified in a WebTelnetSendRecordPrepare command, in the format: “%s###”, such as “%s1”.
sValue | Value to be assigned to the field specified by sFieldname. This string value will be dynamically inserted in the data record when it is transmitted to the terminal server.
iLen | Length of the value to insert (optional). If sValue is longer than iLen, it will be cut off at iLen. If not specified, the value is zero, meaning that sValue can be of any length.

Example

dcltrans
  transaction TInit
  begin
    StrSetHostCP(37); // 37    (IBM EBCDIC - U.S./Canada)
    ErrorAdd(FACILITY_WINSOCK, 18, SEVERITY_TRANS_EXIT);
  end TInit;

  transaction TMain
  var
    hHandle0 : number;
    hWeb0    : number;
  begin
    WebTcpipConnect(hWeb0, "My.Telnet.Host.IP", 5558);
    WebTcpipSetTelnetMode(hWeb0, TERMINAL_TYPE_3270, 80, 24, true, TELNET_MODEOPT_RFC_1576 | TELNET_MODEOPT_AUTO_RECV |
      TELNET_MODEOPT_3270E_AUTO_REPLY);
    WebTelnetRecvCommand(hWeb0, TELNET_CMD_DO, TELNET_OPT_TN3270E);
    WebTelnetSendCommand(hWeb0, TELNET_CMD_WILL, TELNET_OPT_TN3270E);
    WebTelnetRecvSubNegotiation(hWeb0, TELNET_OPT_TN3270E);
    WebTelnetSendSubNegotiation(hWeb0, TELNET_OPT_TN3270E, TN3270E_CMD_DEVICE_TYPE + TN3270E_CMD_REQUEST + "IBM-3278-2-E");
    WebTelnetRecvSubNegotiation(hWeb0, TELNET_OPT_TN3270E);
    WebTelnetSendSubNegotiation(hWeb0, TELNET_OPT_TN3270E, TN3270E_CMD_FUNCTIONS + TN3270E_CMD_REQUEST + TN3270E_FUNC_BIND_IMAGE
       + TN3270E_FUNC_SYSREQ);
    WebTelnetRecvSubNegotiation(hWeb0, TELNET_OPT_TN3270E);
    WebTelnetSendSubNegotiation(hWeb0, TELNET_OPT_TN3270E, TN3270E_CMD_FUNCTIONS + TN3270E_CMD_IS);
    WebTelnetScreenRecvRecordsUntilCursor(hWeb0, 26, 10);

    ThinkTime(8.7);
    WebTelnetSendRecordPrepare(hHandle0, "\h00000000007D4C7E1140C4" + StrToHostCP("1") + "\h114BE9" + "%s1" + "\h114CC3" + "%s2"
       + "\h114CF9" + "%s3" + "\h114EC9" + "%s4" + "\h1150E9" + "%s5" + "\h115B61" + StrToHostCP(
      "Please type your userid.                                                       "));
    WebTelnetSetRecordString(hHandle0, "%s1", StrToHostCP("USER1   "));
    WebTelnetSetRecordString(hHandle0, "%s2", StrToHostCP("        "));
    WebTelnetSetRecordString(hHandle0, "%s3", StrToHostCP("USER1   "));
    WebTelnetSetRecordString(hHandle0, "%s4", StrToHostCP("   "));
    WebTelnetSetRecordString(hHandle0, "%s5", StrToHostCP("        "));
    WebTelnetSendRecordExecute(hWeb0, hHandle0);
    WebTelnetScreenRecvRecordsUntilStatus(hWeb0, "Keyboard locked", "False");

    ThinkTime(2.3);
    WebTelnetSendRecordPrepare(hHandle0, "\h00000000007D40C4" + StrToHostCP(
      "acctE0012I Signon complete at V00F, for user USER1. Local security is disabled. 13:17:29"));
    WebTelnetSendRecordExecute(hWeb0, hHandle0);
    WebTelnetScreenRecvRecordsUntilStatus(hWeb0, "Keyboard locked", "False");

    WebTelnetSendRecordPrepare(hHandle0, "\h00000000007D4AF3114AD5" + "%s3" + "\h114AE2" + "%s4");
    WebTelnetSetRecordString(hHandle0, "%s3", StrToHostCP("d"));
    WebTelnetSetRecordString(hHandle0, "%s4", StrToHostCP("12345"));
    WebTelnetSendRecordExecute(hWeb0, hHandle0);
    WebTelnetScreenRecvRecordsUntilStatus(hWeb0, "Keyboard locked", "False");

    ThinkTime(9.9);
    WebTelnetSendRecord(hWeb0, "\h00000000006D"); // •••••m
    WebTelnetRecvRecord(hWeb0);

    ThinkTime(2.1);
    WebTelnetSendRecordPrepare(hHandle0, "\h00000000007D40C4" + StrToHostCP("exit"));
    WebTelnetSendRecordExecute(hWeb0, hHandle0);
    WebTelnetRecvRecordsUntilClose(hWeb0);
    WebTcpipShutdown(hWeb0);
end TMain;
Parent topic: Web Telnet Functions
Related reference
WebTelnetSendRecordPrepare Function
WebTelnetSendRecordExecute Function


WebTelnetSyncCommand Function

Action

Notes a Telnet command to be verified as received on next sending operation in a Telnet connection. This asynchronous function helps building more robust scripts because some Telnet servers mix Telnet command sequences with regular output data. The received data itself will be prepended to data in the order it was received in the next subsequently received function call.

Include file

WebAPI.bdh

Syntax

WebTelnetSyncCommand(    in hWeb : number,
    in iCmd : number,
    in iOpt : number optional ) : boolean;

Return value

  • true if the operation was successful

  • false otherwise

Parameter | Description
hWeb | Valid handle to a Web connection created by WebTcpipConnect and set to Telnet mode using WebTcpipSetTelnetMode. The connection must be in “Sync-Mode” (set option TELNET_MODEOPT_SYNC).
iCmd | Telnet command to be received from the server (optional). If omitted or set -1 then no verification will be performed. See constants in WebTelnetSendCommand for valid values.
iOpt | Telnet option for WILL/WONT/DO/DONT and SB Telnet commands (optional). See constants in WebTelnetSendCommand for valid values. If omitted or set to -1 no verification will be performed.

Example

dcltrans
  transaction TInit
  begin
    StrSetHostCP(28591); // 28591 (ISO 8859-1 Latin I)
  end TInit;

  transaction   TMain
  var
    hWeb0     : number;
    sBuffer   : string;
    sBoundary : string;
    nOption   : number;
  begin
    WebTcpipConnect(hWeb0, "My.TelnetHost.IP", WEB_PORT_TELNET);
    WebTcpipSetTelnetMode(hWeb0, TERMINAL_TYPE_ANSI, 80, 24, true,
      TELNET_MODEOPT_RFC_1576 | TELNET_MODEOPT_SYNC);
    WebTelnetSetTerminalConfigString(hWeb0, "AutoWrap=false 8Bit=false Tab=9*");

    WebTelnetSyncCommand(hWeb0, TELNET_CMD_DO, TELNET_OPT_TerminalType);
    WebTelnetSyncCommand(hWeb0, TELNET_CMD_DO, TELNET_OPT_NegotiateWindowSize);
    WebTelnetSyncCommand(hWeb0, TELNET_CMD_DO, TELNET_OPT_RemoteFlowControl);
    WebTelnetSyncCommand(hWeb0, TELNET_CMD_DO, TELNET_OPT_SendLocation);
    WebTelnetSyncCommand(hWeb0, TELNET_CMD_WILL, TELNET_OPT_Echo);
    WebTelnetSyncCommand(hWeb0, TELNET_CMD_WILL, TELNET_OPT_SuppressGoAhead);
    WebTelnetSyncCommand(hWeb0, TELNET_CMD_DO, TELNET_OPT_TerminalSpeed);
    WebTelnetSyncCommand(hWeb0, TELNET_CMD_DO, TELNET_OPT_XDisplayLocation);

    // commands above are verified here
    WebTelnetSendCommand(hWeb0, TELNET_CMD_WILL, TELNET_OPT_TerminalType);
    WebTelnetSendCommand(hWeb0, TELNET_CMD_WILL, TELNET_OPT_NegotiateWindowSize);
    WebTelnetSendSubNegotiation(hWeb0, TELNET_OPT_NegotiateWindowSize, "\h00500018"); //•P••
    WebTelnetSendCommand(hWeb0, TELNET_CMD_WONT, TELNET_OPT_RemoteFlowControl);
    WebTelnetSendCommand(hWeb0, TELNET_CMD_WONT, TELNET_OPT_SendLocation);
    WebTelnetSendCommand(hWeb0, TELNET_CMD_DO, TELNET_OPT_Echo);
    WebTelnetSendCommand(hWeb0, TELNET_CMD_DO, TELNET_OPT_SuppressGoAhead);
    WebTelnetSendCommand(hWeb0, TELNET_CMD_WONT, TELNET_OPT_TerminalSpeed);
    WebTelnetSendCommand(hWeb0, TELNET_CMD_WONT, TELNET_OPT_XDisplayLocation);
    WebTelnetSyncSubNegotiation(hWeb0, TELNET_OPT_TerminalType);
    WebTelnetSyncCommand(hWeb0, TELNET_CMD_DONT, TELNET_OPT_RemoteFlowControl);
    WebTelnetSyncCommand(hWeb0, TELNET_CMD_DONT, TELNET_OPT_SendLocation);
    WebTelnetSyncCommand(hWeb0, TELNET_CMD_DONT, TELNET_OPT_TerminalSpeed);
    WebTelnetSyncCommand(hWeb0, TELNET_CMD_DONT, TELNET_OPT_XDisplayLocation);
    // sync commands above are verified here
    WebTelnetSendTerminalType(hWeb0, "vt100");
    // sync commands above are received here
    WebTcpipRecvClose(hWeb0, NULL);
    WebTcpipShutdown(hWeb0);
  end TMain;
Parent topic: Web Telnet Functions
Related reference
WebTelnetSendCommand Function
WebTcpipSetTelnetMode Function
WebTcpipConnect Function


WebTelnetSetTerminalConfigString Function

Action

Configures the behavior of a simulated ANSI or VT terminal in an active Telnet connection.

Include file

WebAPI.bdh

Syntax

WebTelnetSetTerminalConfigString(    in hWeb          : number,
                                     in sConfigString : string ) :boolean;

Return value

  • true if the operation succeeded

  • false otherwise

Parameter | Description
hWeb | Valid handle to a Web connection created by WebTcpipConnect and set to Telnet mode using WebTcpipSetTelnetMode.
sConfigString

The default configuration string is set when choosing a terminal type. The configurable name describes the behavior of the terminal emulation. Configurations can be separated with semicolons, commas, or blank spaces. The available names are:

  • AutoWrap: If false, the screen waits for a new line command when the cursor position is at the right screen border.

  • 8Bit: If true, the screen parses 8bit and 7bit commands. If false, the parser only parses 7bit commands (which are required for double-byte interpretation).

  • Tabs: Tab length used.

Example

dcltrans
  transaction TInit
  begin
    StrSetHostCP(28591); // 28591 (ISO 8859-1 Latin I)
  end TInit;

  transaction   TMain
  var
    hWeb0     : number;
    sBuffer   : string;
    sBoundary : string;
    nOption   : number;
  begin
    WebTcpipConnect(hWeb0, "My.TelnetHost.IP", WEB_PORT_TELNET);
    WebTcpipSetTelnetMode(hWeb0, TERMINAL_TYPE_ANSI, 80, 24, true, TELNET_MODEOPT_RFC_1576);
    WebTelnetSetTerminalConfigString(hWeb0, "AutoWrap=false 8Bit=true");
    WebTelnetRecvCommand(hWeb0, TELNET_CMD_DO, TELNET_OPT_TerminalType);
    WebTelnetRecvCommand(hWeb0, TELNET_CMD_DO, TELNET_OPT_TerminalSpeed);
    WebTelnetRecvCommand(hWeb0, TELNET_CMD_DO, TELNET_OPT_XDisplayLocation);
    WebTelnetRecvCommand(hWeb0, TELNET_CMD_DO, TELNET_OPT_NewEnvironment);
    WebTelnetSendCommand(hWeb0, TELNET_CMD_WILL, TELNET_OPT_TerminalType);
    WebTelnetSendCommand(hWeb0, TELNET_CMD_WONT, TELNET_OPT_TerminalSpeed);
    WebTelnetSendCommand(hWeb0, TELNET_CMD_WONT, TELNET_OPT_XDisplayLocation);
    WebTelnetSendCommand(hWeb0, TELNET_CMD_WONT, TELNET_OPT_NewEnvironment);
    WebTelnetRecvSubNegotiation(hWeb0, TELNET_OPT_TerminalType);
    WebTelnetSendTerminalType(hWeb0, "vt100");
    WebTelnetRecvCommand(hWeb0, TELNET_CMD_WILL, TELNET_OPT_SuppressGoAhead);
    WebTelnetRecvCommand(hWeb0, TELNET_CMD_DO, TELNET_OPT_Echo);
    WebTelnetRecvCommand(hWeb0, TELNET_CMD_DO, TELNET_OPT_NegotiateWindowSize);
    WebTelnetRecvCommand(hWeb0, TELNET_CMD_WILL, TELNET_OPT_Status);
    WebTelnetRecvCommand(hWeb0, TELNET_CMD_DO, TELNET_OPT_RemoteFlowControl);
    WebTelnetSendCommand(hWeb0, TELNET_CMD_DO, TELNET_OPT_SuppressGoAhead);
    WebTelnetSendCommand(hWeb0, TELNET_CMD_WONT, TELNET_OPT_Echo);
    WebTelnetSendCommand(hWeb0, TELNET_CMD_WILL, TELNET_OPT_NegotiateWindowSize);
    WebTelnetSendSubNegotiation(hWeb0, TELNET_OPT_NegotiateWindowSize, "\h00500018");
    WebTelnetSendCommand(hWeb0, TELNET_CMD_DONT, TELNET_OPT_Status);
    WebTelnetSendCommand(hWeb0, TELNET_CMD_WONT, TELNET_OPT_RemoteFlowControl);
    WebTelnetRecvCommand(hWeb0, TELNET_CMD_WILL, TELNET_OPT_Echo);
    WebTcpipGetPacketBoundary(hWeb0, sBoundary);
    WebTcpipRecvPacketsUntilData(hWeb0, "login: ");
    WebTelnetTypeKeys(hWeb0, StrToHostCP("leo"), 359.3, TELNET_FLAG_CASE_SENSITIVE);
    WebTcpipSendBin(hWeb0, "\h0D00");
    WebTcpipRecvExact(hWeb0, NULL, 390);
    WebTcpipSetPacketBoundary(hWeb0, sBoundary);
    WebTcpipRecvUntilIdle(hWeb0, NULL, 5000);
    WebTcpipSendBin(hWeb0, "\h0D000D0A");
    WebTcpipRecvPackets(hWeb0, NULL, 3);
    WebTcpipSendBin(hWeb0, "\h0D00");
    WebTcpipSendPacket(hWeb0, StrToHostCP("8") + "\h0D00");
    WebTcpipRecvClose(hWeb0, NULL);
    WebTcpipShutdown(hWeb0);
  end TMain;
Parent topic: Web Telnet Functions
Related reference
WebTcpipSetTelnetMode Function
WebTcpipConnect Function


WebTelnetSyncData Function

Action

Notes binary data like VT100 escape sequences to be verified as received on next sending operation in a Telnet connection. This asynchronous function helps building more robust scripts because some Telnet servers mix Telnet command sequences with regular output data. The received data itself will be prepended to data in the order it was received in the next subsequently received function call.

Include file

WebAPI.bdh

Syntax

WebTelnetSyncData(    in hWeb  : number,
                      in sData : string ) : boolean;

Return value

  • true if the operation was successful

  • false otherwise

Parameter | Description
hWeb | Valid handle to a Web connection created by WebTcpipConnect and set to Telnet mode using WebTcpipSetTelnetMode. The connection must be in “Sync-Mode” (set option TELNET_MODEOPT_SYNC).
sData | Binary data string expected from the server.

Example

dcltrans
  transaction TInit
  begin
    StrSetHostCP(28591); // 28591 (ISO 8859-1 Latin I)
  end TInit;   transaction   TMain
  var
    hWeb0     : number;
    sBuffer   : string;
    sBoundary : string;
    nOption   : number;
  begin
    WebTcpipConnect(hWeb0, "My.TelnetHost.IP", WEB_PORT_TELNET);
    WebTcpipSetTelnetMode(hWeb0, TERMINAL_TYPE_ANSI, 80, 24, true,
      TELNET_MODEOPT_RFC_1576 | TELNET_MODEOPT_SYNC);
    WebTelnetSetTerminalConfigString(hWeb0, "AutoWrap=false 8Bit=false Tab=9*");

    WebTelnetSyncCommand(hWeb0, TELNET_CMD_DO, TELNET_OPT_TerminalType);
    WebTelnetSyncCommand(hWeb0, TELNET_CMD_DO, TELNET_OPT_NegotiateWindowSize);
    WebTelnetSyncCommand(hWeb0, TELNET_CMD_DO, TELNET_OPT_RemoteFlowControl);
    WebTelnetSyncCommand(hWeb0, TELNET_CMD_DO, TELNET_OPT_SendLocation);
    WebTelnetSyncCommand(hWeb0, TELNET_CMD_WILL, TELNET_OPT_Echo);
    WebTelnetSyncCommand(hWeb0, TELNET_CMD_WILL, TELNET_OPT_SuppressGoAhead);
    WebTelnetSyncCommand(hWeb0, TELNET_CMD_DO, TELNET_OPT_TerminalSpeed);
    WebTelnetSyncCommand(hWeb0, TELNET_CMD_DO, TELNET_OPT_XDisplayLocation);

    // commands above are verified here
    WebTelnetSendCommand(hWeb0, TELNET_CMD_WILL, TELNET_OPT_TerminalType);
    WebTelnetSendCommand(hWeb0, TELNET_CMD_WILL, TELNET_OPT_NegotiateWindowSize);
    WebTelnetSendSubNegotiation(hWeb0, TELNET_OPT_NegotiateWindowSize, "\h00500018"); // •P••
    WebTelnetSendCommand(hWeb0, TELNET_CMD_WONT, TELNET_OPT_RemoteFlowControl);
    WebTelnetSendCommand(hWeb0, TELNET_CMD_WONT, TELNET_OPT_SendLocation);
    WebTelnetSendCommand(hWeb0, TELNET_CMD_DO, TELNET_OPT_Echo);
    WebTelnetSendCommand(hWeb0, TELNET_CMD_DO, TELNET_OPT_SuppressGoAhead);
    WebTelnetSendCommand(hWeb0, TELNET_CMD_WONT, TELNET_OPT_TerminalSpeed);
    WebTelnetSendCommand(hWeb0, TELNET_CMD_WONT, TELNET_OPT_XDisplayLocation);
    WebTelnetSyncSubNegotiation(hWeb0, TELNET_OPT_TerminalType);
    WebTelnetSyncCommand(hWeb0, TELNET_CMD_DONT, TELNET_OPT_RemoteFlowControl);
    WebTelnetSyncCommand(hWeb0, TELNET_CMD_DONT, TELNET_OPT_SendLocation);
    WebTelnetSyncCommand(hWeb0, TELNET_CMD_DONT, TELNET_OPT_TerminalSpeed);
    WebTelnetSyncCommand(hWeb0, TELNET_CMD_DONT, TELNET_OPT_XDisplayLocation);
    // sync commands above are verified here
    WebTelnetSendTerminalType(hWeb0, "vt100");
    WebTelnetTypeKeys(hWeb0, StrToHostCP("guest") + WEB_CRNULL, 294.1, TELNET_FLAG_CASE_SENSITIVE);
    WebTelnetSyncData(hWeb0, "\h0D0A1B5B63"); // •••[c
    // sync data above is verified here
    WebTcpipSend(hWeb0, "\h1B5B3F313B3063"); // •[?1;0c
    WebTelnetSyncData(hWeb0, "\h5B366E1B38"); // [6n•8
    // sync data above is verified here
    WebTcpipSend(hWeb0, "\h1B5B32343B383052"); // •[24;80R
    // received sync data is prepended to received data here
    WebTcpipScreenRecvPacketsUntilCursor(hWeb0, 40, 23);
    WebTcpipShutdown(hWeb0);
  end TMain;
Parent topic: Web Telnet Functions
Related reference
WebTcpipSetTelnetMode Function
WebTcpipConnect Function


WebTelnetSyncSubNegotiation Function

Action

Notes a Telnet option sub-negotiation to be verified as received on next sending operation in a Telnet connection. This asynchronous function helps building more robust scripts because some Telnet servers mix Telnet command sequences with regular output data. The received data itself will be prepended to data in the order it was received in the next subsequently received function call.

Include file

WebAPI.bdh

Syntax

WebTelnetSyncSubNegotiation(    in hWeb          : number,
                                in iOpt          : number,
                                in sDataExpected : number optional ) : boolean;

Return value

  • true if the operation was successful

  • false otherwise

Parameter | Description
hWeb | Valid handle to a Web connection created by WebTcpipConnect and set to Telnet mode using WebTcpipSetTelnetMode. The connection must be in “Sync-Mode” (set option TELNET_MODEOPT_SYNC).
iOpt | Telnet sub-negotiation option that is expected from the server. See constants in WebTelnetSendCommand for valid values.
sDataExpected | Binary sub-negotiation data string expected from the server (optional). Set to NULL if no validation is to be performed.

Example

dcltrans
  transaction TInit
  begin
    StrSetHostCP(28591); // 28591 (ISO 8859-1 Latin I)
  end TInit;   transaction   TMain
  var
    hWeb0     : number;
    sBuffer   : string;
    sBoundary : string;
    nOption   : number;
  begin
    WebTcpipConnect(hWeb0, "My.TelnetHost.IP", WEB_PORT_TELNET);
    WebTcpipSetTelnetMode(hWeb0, TERMINAL_TYPE_ANSI, 80, 24, true,
      TELNET_MODEOPT_RFC_1576 | TELNET_MODEOPT_SYNC);
    WebTelnetSetTerminalConfigString(hWeb0, "AutoWrap=false 8Bit=false Tab=9*");

    WebTelnetSyncCommand(hWeb0, TELNET_CMD_DO, TELNET_OPT_TerminalType);
    WebTelnetSyncCommand(hWeb0, TELNET_CMD_DO, TELNET_OPT_NegotiateWindowSize);
    WebTelnetSyncCommand(hWeb0, TELNET_CMD_DO, TELNET_OPT_RemoteFlowControl);
    WebTelnetSyncCommand(hWeb0, TELNET_CMD_DO, TELNET_OPT_SendLocation);
    WebTelnetSyncCommand(hWeb0, TELNET_CMD_WILL, TELNET_OPT_Echo);
    WebTelnetSyncCommand(hWeb0, TELNET_CMD_WILL, TELNET_OPT_SuppressGoAhead);
    WebTelnetSyncCommand(hWeb0, TELNET_CMD_DO, TELNET_OPT_TerminalSpeed);
    WebTelnetSyncCommand(hWeb0, TELNET_CMD_DO, TELNET_OPT_XDisplayLocation);

    // commands above are verified here
    WebTelnetSendCommand(hWeb0, TELNET_CMD_WILL, TELNET_OPT_TerminalType);
    WebTelnetSendCommand(hWeb0, TELNET_CMD_WILL, TELNET_OPT_NegotiateWindowSize);
    WebTelnetSendSubNegotiation(hWeb0, TELNET_OPT_NegotiateWindowSize, "\h00500018"); // •P••
    WebTelnetSendCommand(hWeb0, TELNET_CMD_WONT, TELNET_OPT_RemoteFlowControl);
    WebTelnetSendCommand(hWeb0, TELNET_CMD_WONT, TELNET_OPT_SendLocation);
    WebTelnetSendCommand(hWeb0, TELNET_CMD_DO, TELNET_OPT_Echo);
    WebTelnetSendCommand(hWeb0, TELNET_CMD_DO, TELNET_OPT_SuppressGoAhead);
    WebTelnetSendCommand(hWeb0, TELNET_CMD_WONT, TELNET_OPT_TerminalSpeed);
    WebTelnetSendCommand(hWeb0, TELNET_CMD_WONT, TELNET_OPT_XDisplayLocation);
    WebTelnetSyncSubNegotiation(hWeb0, TELNET_OPT_TerminalType);
    WebTelnetSyncCommand(hWeb0, TELNET_CMD_DONT, TELNET_OPT_RemoteFlowControl);
    WebTelnetSyncCommand(hWeb0, TELNET_CMD_DONT, TELNET_OPT_SendLocation);
    WebTelnetSyncCommand(hWeb0, TELNET_CMD_DONT, TELNET_OPT_TerminalSpeed);
    WebTelnetSyncCommand(hWeb0, TELNET_CMD_DONT, TELNET_OPT_XDisplayLocation);
    // sync commands above are verified here
    WebTelnetSendTerminalType(hWeb0, "vt100");
    WebTelnetTypeKeys(hWeb0, StrToHostCP("guest") + WEB_CRNULL, 294.1, TELNET_FLAG_CASE_SENSITIVE);
    WebTelnetSyncData(hWeb0, "\h0D0A1B5B63"); // •••[c
    // sync data above is verified here
    WebTcpipSend(hWeb0, "\h1B5B3F313B3063"); // •[?1;0c
    WebTelnetSyncData(hWeb0, "\h5B366E1B38"); // [6n•8
    // sync data above is verified here
    WebTcpipSend(hWeb0, "\h1B5B32343B383052"); // •[24;80R
    // received sync data is prepended to received data here
    WebTcpipScreenRecvPacketsUntilCursor(hWeb0, 40, 23);
    WebTcpipShutdown(hWeb0);
  end TMain;
Parent topic: Web Telnet Functions
Related reference
WebTelnetSendCommand Function
WebTcpipSetTelnetMode Function
WebTcpipConnect Function


WebTelnetTypeKeys Function

Action

Simulates a user input to a Telnet server. This function sends alphanumeric character data that is specified at a specific rate and optionally verifies data echoed by the server.

Include file

WebAPI.bdh

Syntax

WebTelnetTypeKeys(    in hWeb            : number,
                      in sData           : string,
                      in nCharsPerMinute : float optional,
                      in nEchoOptions    : number optional,
                      in sPassswordChar  : string optional,
                      out sEchoReceived   : string optional ) : boolean;

Return value

  • true if the operation was successful

  • false otherwise

Parameter | Description
hWeb | Valid handle to a Web connection created by WebTcpipConnect and set to Telnet mode using WebTcpipSetTelnetMode.
sData | Data to be sent.
nCharsPerMinute | Optional typematic rate (characters-per-minute). If omitted or set to 0, all of the data is sent immediately.
nEchoOption

If specified, you may define how received data is to be compared (optional). The default setting is ‘no’ verification, but you can set one of the following constants:

  • TELNET_FLAG_NOECHO: Do not receive echoed data.

  • TELNET_FLAG_ECHO: Received characters are to be compared against expected data case-insensitively.

  • TELNET_FLAG_PASSWORD: Receive as many characters from server as were sent to a Telnet server. All received characters must have the same value.

  • TELNET_FLAG_CASE_SENSITIVE: Received characters are to be compared against expected data case-sensitively.
sPasswordChar | If TELNET_FLAG_PASSWORD is used, an expected reply character may be specified in this parameter (optional). If omitted then the first character received is used for verification.
sEchoReceived | Defines the variable for storing the echoed data from the server (optional).

Example

dcltrans
  transaction TInit
  begin
    StrSetHostCP(28591); // 28591 (ISO 8859-1 Latin I)
  end TInit;
  transaction TMain
  var
    hWeb0     : number;
    sBuffer   : string;
    sBoundary : string;
    nOption   : number;
    WebTcpipConnect(hWeb0, "My.TelnetHost.IP", WEB_PORT_TELNET);
    WebTcpipSetTelnetMode(hWeb0, TERMINAL_TYPE_ANSI, 80, 24, true,
      TELNET_MODEOPT_SYNC);
    WebTcpipGetOptions(hWeb0, nOption);
    if nOption <> TELNET_MODEOPT_RFC_1576 then
      WebTcpipSetOptions(hWeb0, TELNET_MODEOPT_RFC_1576);
    end;
    WebTelnetRecvCommand(hWeb0, TELNET_CMD_DO, TELNET_OPT_TerminalType);
    WebTelnetRecvCommand(hWeb0, TELNET_CMD_DO, TELNET_OPT_TerminalSpeed);
    WebTelnetRecvCommand(hWeb0, TELNET_CMD_DO, TELNET_OPT_XDisplayLocation);
    WebTelnetRecvCommand(hWeb0, TELNET_CMD_DO, TELNET_OPT_NewEnvironment);
    WebTelnetSendCommand(hWeb0, TELNET_CMD_WILL, TELNET_OPT_TerminalType);
    WebTelnetSendCommand(hWeb0, TELNET_CMD_WONT, TELNET_OPT_TerminalSpeed);
    WebTelnetSendCommand(hWeb0, TELNET_CMD_WONT, TELNET_OPT_XDisplayLocation);
    WebTelnetSendCommand(hWeb0, TELNET_CMD_WONT, TELNET_OPT_NewEnvironment);
    WebTelnetRecvSubNegotiation(hWeb0, TELNET_OPT_TerminalType);
    WebTelnetSendTerminalType(hWeb0, "vt100");
    WebTelnetRecvCommand(hWeb0, TELNET_CMD_WILL, TELNET_OPT_SuppressGoAhead);
    WebTelnetRecvCommand(hWeb0, TELNET_CMD_DO, TELNET_OPT_Echo);
    WebTelnetRecvCommand(hWeb0, TELNET_CMD_DO, TELNET_OPT_NegotiateWindowSize);
    WebTelnetRecvCommand(hWeb0, TELNET_CMD_WILL, TELNET_OPT_Status);
    WebTelnetRecvCommand(hWeb0, TELNET_CMD_DO, TELNET_OPT_RemoteFlowControl);
    WebTelnetSendCommand(hWeb0, TELNET_CMD_DO, TELNET_OPT_SuppressGoAhead);
    WebTelnetSendCommand(hWeb0, TELNET_CMD_WONT, TELNET_OPT_Echo);
    WebTelnetSendCommand(hWeb0, TELNET_CMD_WILL, TELNET_OPT_NegotiateWindowSize);
    WebTelnetSendSubNegotiation(hWeb0, TELNET_OPT_NegotiateWindowSize, "\h00500018");
    WebTelnetSendCommand(hWeb0, TELNET_CMD_DONT, TELNET_OPT_Status);
    WebTelnetSendCommand(hWeb0, TELNET_CMD_WONT, TELNET_OPT_RemoteFlowControl);
    WebTelnetRecvCommand(hWeb0, TELNET_CMD_WILL, TELNET_OPT_Echo);
    WebTcpipGetPacketBoundary(hWeb0, sBoundary);
    WebTcpipRecvPacketsUntilData(hWeb0, "login: ");
    WebTelnetTypeKeys(hWeb0, StrToHostCP("leo"),359.3, TELNET_FLAG_CASE_SENSITIVE);
    WebTcpipSendBin(hWeb0, "\h0D00");
    WebTcpipRecvExact(hWeb0, NULL, 390);
    WebTcpipSetPacketBoundary(hWeb0, sBoundary);
    WebTcpipRecvUntilIdle(hWeb0, NULL, 5000);
    WebTcpipSendBin(hWeb0, "\h0D000D0A");
    WebTcpipRecvPackets(hWeb0, NULL, 3);
    WebTcpipSendBin(hWeb0, "\h0D00");
    WebTcpipSendPacket(hWeb0, StrToHostCP("8") + "\h0D00");
    WebTcpipRecvClose(hWeb0, NULL);
    WebTcpipShutdown(hWeb0);
  end TMain;
Parent topic: Web Telnet Functions
Related reference
WebTcpipSetTelnetMode Function
WebTcpipConnect Function


UDP Functions Reference

  • WebUdpCreate Function
    Creates an UDP handle, which can be used in subsequent calls to WebUdpXXX functions.
  • WebUdpGetBindInfo Function
    Receives the IP address and the port to which the specified UDP socket is bound.
  • WebUdpSendTo Function
    Sends a string or binary data to the specified host port combination using the UDP protocol.
  • WebUdpRecvFrom Function
    Receives data using the UDP protocol.
  • WebUdpClose Function
    Closes an UDP handle, which has been created by a call to the WebUdpCreate function.
Parent topic: Internet Functions


WebUdpCreate Function

Action

Creates an UDP handle, which can be used in subsequent calls to WebUdpXXX functions. If this handle is no longer used, call WebUdpClose to free all associated system resources. The optional IP and port parameters can be used to explicitly bind the UDP socket to a single IP and/or port. This has to be done if a WebUdpRecvFrom function is called before a WebUdpSendTo. If the socket is not bound, the latter function automatically binds it to a system generated port. This port can be queried by the WebUdpGetBindInfo function.

Include file

WebAPI.bdh

Syntax

WebUdpCreate( out hUdp  : number,
              in sIp   : string optional,
              in nPort : number optional ): boolean;

Return value

  • true if the handle has been created successfully

  • false otherwise

Parameter | Description
hUdp | UDP handle, that has to be created.
sIp | IP address to bind the UDP socket to (optional). Must be a valid IP address for the local machine. If this parameter is omitted, or a null value is specified no specific IP address is bound. Therefore data can be sent to (and read from) any valid IP of the local host.
nPort | Port to bind the UDP socket to (optional). Specify this parameter to assign a special port to the UDP socket. If this parameter is omitted no special port is assigned and the next WebUdpSendTo function will bind the socket to a system generated port. If this parameter is omitted calls to WebUdpRecvFrom will fail unless the first WebUdpSendTo function is called.

Example

dcltrans
  transaction TWeb
    var
      nUdp  : number;
      sBuf  : string;
      sIp   : string;
      nPort : number;
  begin
    WebUdpCreate(nUdp, null, 9999);
    WebUdpRecvFrom(nUdp, sBuf, 300, sIp, nPort);
      print("got data from "+sIp+" : "+string(nPort));
    WebUdpClose(nUdp);
      print(sBuf);
  end TWeb;
Parent topic: UDP Functions Reference
Related reference
WebUdpClose Function
WebUdpGetBindInfo Function
WebUdpRecvFrom Function
WebUdpSendTo Function


WebUdpGetBindInfo Function

Action

Receives the IP address and the port to which the specified UDP socket is bound. If the socket has been bound by the optional parameters of the WebUdpCreate function, the function would simply return these values. If the port has not explicitly been specified, then the function would retrieve the value, which has been automatically set by the system during the first WebUdpSendTo function. If the socket is not bound to a specific IP address a value of “0.0.0.0” is returned. If the socket is not bound to a specifically port yet a value of 0 is returned.

Include file

WebAPI.bdh

Syntax

WebUdpGetBindInfo( in  hUdp  : number,
                   out sIp   : string,
                   out nPort : number ): boolean;

Return value

  • true if the bind information has been queried successfully

  • false otherwise

Parameter | Description
hUdp | Valid UDP handle, that has been created by WebUdpCreate.
sIp | String that receives the IP address to which the specified socket is bound. “0.0.0.0” is returned if the socket is not bound to a specific IP address.
nPort | Variable that receives the port number to which the specified socket is bound. If the socket is not bound yet a 0 is returned.

Example

dcltrans
  transaction TWeb
  var
    nUdp  : number;
    sBuf  : string;
    sIp   : string;
    nPort : number;
  begin
    WebUdpCreate(nUdp);
    WebUdpSendTo(nUdp, "10.5.2.103", 9998, "1234567890");
    WebUdpGetBindInfo(nUdp, sIp, nPort);
    print("bound to "+sIp+" : "+string(nPort));
    WebUdpRecvFrom(nUdp, sBuf, STRING_COMPLETE, sIp, nPort);
    print("got data from "+sIp+" : "+string(nPort));
    WebUdpClose(nUdp);    print(sBuf);
  end TWeb;
Parent topic: UDP Functions Reference
Related reference
WebUdpClose Function
WebUdpCreate Function
WebUdpRecvFrom Function
WebUdpSendTo Function


WebUdpSendTo Function

Action

Sends a string or binary data to the specified host port combination using the UDP protocol. In contrary to the TCP protocol UDP is an unreliable communication where no logical connection has to be established, but before WebUdpSendTo can be used, a valid handle has to be created with the WebUdpCreate command. This handle can be used in subsequent calls to the WebUdpRecvFrom function to receive reply data. If the UDP socket (represented by the handle) has not been bound to a specific port by the WebUdpCreate function, the system automatically assigns a free port during the WebUdpSendTo function. This port can subsequently be queried by a call to the WebUdpGetBinfInfo function.

Include file

WebAPI.bdh

Syntax

WebUdpSendTo( in hUdp     : number,
              in sHost    : string,
              in nPort    : number,
              in sData    : string,
              in nDataLen : number optional ): boolean;

Return value

  • true if the data is sent successfully

  • false otherwise

Parameter | Description
hUdp | Valid UDP handle, that has been created by WebUdpCreate.
sHost | Host name or IP address, for example, "box1.hostname.com" or "192.231.34.1".
nPort | Port to send the data to.
sData | Data that should be sent.
nDataLen | Number of bytes to send to the server (optional). If this parameter is omitted all available data is sent.

Example

dcltrans
  transaction TWeb
    var
    nUdp  : number;
      sBuf  : string;
      sIp   : string;
    nPort : number;
  begin
    WebUdpCreate(nUdp);
    WebUdpSendTo(nUdp, "10.5.2.103", 9998, "1234567890");
    WebUdpGetBindInfo(nUdp, sIp, nPort);
    print("bound to "+sIp+" : "+string(nPort));
    WebUdpRecvFrom(nUdp, sBuf, STRING_COMPLETE, sIp, nPort);
    print("got data from "+sIp+" : "+string(nPort));
    WebUdpClose(nUdp);
    print(sBuf);
  end TWeb;
Parent topic: UDP Functions Reference
Related reference
WebUdpClose Function
WebUdpCreate Function
WebUdpGetBindInfo Function
WebUdpRecvFrom Function


WebUdpRecvFrom Function

Action

Receives data using the UDP protocol. In contrary to the TCP protocol UDP is an unreliable communication where no logical connection has to be established, but before WebUdpRecvFrom can be used, a valid handle has to be created with the WebUdpCreate command. If the UDP socket (represented by the handle) has not been bound to a specific port by the WebUdpCreate function, calls to WebUdpRecvFrom will fail until the first WebUdpSendTo function is called, which assigns a system generated port.

Include file

WebAPI.bdh

Syntax

WebUdpRecvFrom( in  hUdp      : number,
                out sData     : string optional,
                in  nMaxData  : number optional,
                out sFromIp   : string optional,
                out nFromPort : number optional): boolean;

Return value

  • true if the data has been received successfully

  • false otherwise

Parameter | Description
hUdp | Valid UDP handle, that has been created by WebUdpCreate.
sData | String where the received data should be stored (optional). If this parameter is omitted the received data is discarded.
nMaxData | The maximum number of bytes that should be read (optional). Omit this parameter or specify STRING_COMPLETE to receive as much data as is available.
sFromIp | String that will receive the IP address of the host, which sent the data (optional).
nFromPort | Variable, that will receive the source port (optional).

Example

dcltrans
  transaction TWeb
    var
      nUdp  : number;
      sBuf  : string;
      sIp   : string;
      nPort : number;
  begin
    WebUdpCreate(nUdp);
    WebUdpSendTo(nUdp, "10.5.2.103", 9998, "1234567890");
    WebUdpGetBindInfo(nUdp, sIp, nPort);
    print("bound to "+sIp+" : "+string(nPort));
    WebUdpRecvFrom(nUdp, sBuf, STRING_COMPLETE, sIp, nPort);
    print("got data from "+sIp+" : "+string(nPort));
    WebUdpClose(nUdp);
    print(sBuf);
  end TWeb;
Parent topic: UDP Functions Reference
Related reference
WebUdpClose Function
WebUdpCreate Function
WebUdpGetBindInfo Function
WebUdpSendTo Function


WebUdpClose Function

Action

Closes an UDP handle, which has been created by a call to the WebUdpCreate function. Every handle created with the WebUdpCreate function must be closed by using this function in order to free all allocated system resources.

Include file

WebAPI.bdh

Syntax

WebUdpClose( inout hUdp : number ): boolean;

Return value

  • true if the handle has been closed successfully

  • false otherwise

Parameter | Description
hUdp | Valid UDP handle, that has been created by WebUdpCreate.

Example

dcltrans
  transaction TWeb
    var
      nUdp  : number;
      sBuf  : string;
      sIp   : string;
      nPort : number;
  begin
    WebUdpCreate(nUdp);
    WebUdpSendTo(nUdp, "10.5.2.103", 9998, "1234567890");
    WebUdpGetBindInfo(nUdp, sIp, nPort);
    print("bound to "+sIp+" : "+string(nPort));
    WebUdpRecvFrom(nUdp, sBuf, STRING_COMPLETE, sIp, nPort);
    print("got data from "+sIp+" : "+string(nPort));
    WebUdpClose(nUdp);
    print(sBuf);
  end TWeb;
Parent topic: UDP Functions Reference
Related reference
WebUdpCreate Function
WebUdpGetBindInfo Function
WebUdpRecvFrom Function
WebUdpSendTo Function


Web Functions Reference

  • Document Cache Emulation
    The Silk Performer replay engine provides emulation of Web browser document cache.
  • General Web Functions
  • Browser Settings
  • Low-Level Web Functions
  • Page-Level Web Functions Overview
    The page-level web functions focus on Web pages rather than on single documents.
  • Asynchronous Communication Functions
  • Page Statistic Functions
  • Cookie Database Functions Overview
    Under HTTP (HyperText Transfer Protocol), cookies are the means by which a server or a script can maintain state information on the client workstation.
  • Parsing Functions
    HTML parsing functions allow for the parsing of HTML content that can be viewed in Web browsers. Data parsing functions can be applied to response data returned by servers.
  • Response Verification Functions
  • MMS Functions
Parent topic: Internet Functions


Document Cache Emulation

The Silk Performer replay engine provides emulation of Web browser document cache. A real Web browser stores cached Web documents in files in a central document cache. To save memory and optimize performance, Silk Performer stores just references to the documents in the physical memory, without writing them to the hard drive. Each virtual user has its own independent document cache and does not store any files to the disk.

Caching is basically meant to reduce network traffic; to reuse recently downloaded documents and render them again in your Web client. A Web surfer who enables document caching in his/her client will therefore experience more timely responses in his/her online sessions, as the time for updating the Web browser's content can be reduced to a minimum. Logically, most browsers will be operated with one of the following caching options:

  • Once per session

  • Every time

  • Never

What we need to be concerned with when choosing one of these caching strategies, is the resulting HTTP traffic - which may vary dramatically depending on the cache strategy used. We are also interested in the type of documents that can be cached.

Images are the best example of documents that can be cached. Also, static HTML documents which may have the file extension .htm or .html. In regards to the HTML generated by Active Server Pages or servlets, it doesn't make sense to cache the response data of Active Server Pages or JSP pages, since it is dynamically generated content. To find out whether a document may be cached or not, the Web client has to examine the HTTP response header of each response.

When to use the document cache emulation:

  • The document cache is recommended when replaying traffic with the page-level web function (the functions with the WebPage prefix). The page-level web functions parse HTML and use the document cache emulation to filter out duplicate requests of a single document, just like a real Web browser does.

  • The document cache emulation can also be used with the low-level replay web functions. However, it is not recommended to do so since the SilkRecorder does not include documents cached by the browser in the script. Besides, document cache emulation can decrease the performance of the low-level replay.

Document cache emulation functions

WebSetUserBehavior
Specifies whether the user resets his browser after each transaction.
WebSetDocumentCache
Specifies whether Silk Performer simulates a document cache.
WebBrowserReset
Specifies whether the user resets his browser after each transaction.
WebDeleteCacheEntry
This function is used to delete a cache entry in the browser cache of a user.
WebSuspendCache
This function is used to disable the browser cache or influence its behavior.
WebResumeCache
This function is used to restore the normal cache behaviour.

Combinations

User behavior/Cache strategy | Never | Once per session | Every time
Disable | 1 | 2 | 3
First time user | 4 | 5 | 6
Revisiting user | 7 | 8 | 9

  1. The user never clears document cache and never resets the cookie database throughout all transactions. No conditional requests for already cached documents.

  2. The user never clears document cache and never resets the cookie database throughout all transactions. During one execution cycle of a transaction request, only one conditional request will be sent if the document can be found in cache.

  3. Similar to 1., but conditional requests will be sent to the server if the document can be found in the cache.

  4. Documents will be retrieved from the cache unless they are expired. Each time a virtual user is done with a transaction, Silk Performer clears the cookie database and document cache. Persistent cookies cannot be maintained over the execution of transactions.

  5. Select this combination for Web applications that have to deal with a large or increasing number of new customers; e.g. search engines, or online shopping malls approaching a high-volume retail season.

  6. As 5.

  7. When the transaction is done, the virtual user simply clears the non-persistent cookies and closes all connections. You can compare the returning user to someone who simply closes the browser when he/she is done with the transaction and returns some random time later.

  8. and 9. The only difference to 7. is the frequency of conditional requests.

As you can see with Silk Performer, you can design your tests to simulate many different caching strategies. For example, a search engine may experience many new users after running a successful advertisement. Well-known service providers or online stores will have to face a great number of returning users.

Parent topic: Web Functions Reference
Related reference
WebSetUserBehavior Function
WebSetDocumentCache Function
WebBrowserReset Function
WebDeleteCacheEntry Function
WebSuspendCache Function
WebResumeCache Function


General Web Functions

  • WebBrowserReset Function
    Emulates a Web browser restart.
  • WebDeleteCacheEntry Function
    This function is used to delete a cache entry in the browser cache of a user.
  • WebSuspendCache Function
    This function is used to disable the browser cache or (if the option parameter is provided) influence its behavior.
  • WebResumeCache Function
    Restores the normal cache behavior, changed by a prior call to the WebSuspendCache function.
  • WebSetCacheLimit Function
    This function allows you to implement different cache resizing strategies.
  • WebSetCacheLimitIE Function
    Use this function (usually at the beginning of your script - Init transaction) to enable the emulation of the cache size limit similar to IE.
  • WebCacheGetSize Function
    Returns the actual size of the cache in bytes.
  • WebCacheReSize Function
    Resizes the cache by deleting cache entries, beginning by the oldest entries, to the specified size.
  • WebThreadWait Function
    Waits until all threads of the user are ready.
  • WebIgnoreServerError Function
    Modifies the error severity of a specified server error for the subsequent web function call.
  • WebPing Function
    Checks the availability of a specified host by sending an ICMP echo request (ping).
  • WebBase64Decode Function
    Converts ASCII-encoded data into unsigned binary data.
  • WebBase64DecodeEx function
    Converts ASCII-encoded data into unsigned binary data.
  • WebBase64Encode Function
    Converts unsigned binary input into ASCII-encoded, printable characters.
  • WebBase64EncodeEx Function
    Converts unsigned binary input into ASCII-encoded, printable characters.
  • WebMD5Encode Function
    Encodes a string using the MD5 algorithm.
  • WebFormUrlDecode Function
    Decodes encoded strings included in URLs.
  • WebFormUrlEncode Function
    Encodes any unsafe characters included in URLs in order to comply with the Uniform Resource Locators specification.
  • WebFormDefineEncodeCustom Function
    Defines how the encoding type ENCODE_CUSTOM encodes individual characters.
  • WebCancelAllRules Function
    Disables all existing verification and parsing rules that have been set by prior calls of verification or parsing functions with the WEB_FLAG_RULE flag set.
  • FlashRemotingTransformation Function
    This function enables the transformation from binary AMF to a textual XML-based representation.
  • WebSetBrowserSim Function
    This functions allows to adjust the advanced options for the browser simulation.
  • WebSetHttpTag Function
    This functions allows to add an unique HTTP header tag to every web request of a loadtest.
  • WebGetHttpTag Function
  • WebSetDiagnostics Function
    Sets appropriate HTTP headers for a diagnostics tool.
  • WebSetUserSim Function
    Adjusts the advanced options for the user tolerance simulation.
Parent topic: Web Functions Reference


WebBrowserReset Function

Action

Emulates a Web browser restart. This function closes all persistent connections and clears the document cache, the document history, all persistent cookies, the authentication databases, and the SSL context cache of the user’s browser.

Include file

WebAPI.bdh

Syntax

WebBrowserReset( in nMode : number optional ) : boolean;

Return value

  • true if successful

  • false otherwise

Parameter Description
nMode

Specifies whether to complete reset the browser or to keep persistent cookies and the document cache (optional). This parameter must be one of the following values:

WEB_RESET_ALL
Emulates closing and opening the Web browser, and clears the document cache and the cookie database.
WEB_RESET_NONPERSIST
Emulates closing and opening the browser without clearing the document cache and deleting persistent cookies.

If this parameter is omitted, Silk Performer simulates the behavior specified in the Simulation tab of the Profile Settings - Web dialog.

Example

dcltrans
  transaction TInit
  begin
    WebSetUserBehavior(WEB_USERBEHAVIOR_REVISITING);
    WebSetDocumentCache(true, WEB_CACHE_CHECK_ALWAYS);
  end TInit;

  transaction TMain
  begin
    WebPageUrl("standardhost");
    WebBrowserReset(WEB_RESET_ALL);
    WebPageUrl("standardhost");
  end TMain;
Parent topic: General Web Functions
Related reference
WebSetUserBehavior Function
WebSetDocumentCache Function


WebDeleteCacheEntry Function

Action

This function is used to delete a cache entry in the browser cache of a user. If a URL that is going to be requested from the server, cannot be found in the browser cache a full request is performed (no cache hit or conditional request).

Include file

WebAPI.bdh

Syntax

WebDeleteCacheEntry( in sUrl : string ): boolean;

Return value

  • true if the cache entry has been deleted successfully.

  • false otherwise.

Parameter | Description
sUrl | Absolute URL of the cache entry to be deleted.

Example

dcltrans
  transaction TMain
  var
    sResult : string(100);
  begin
    WebPageUrl("http://standardhost/shopit/", "ShopIt - Greetings");
    WebDeleteCacheEntry("http://standardhost/shopit/images/arrowBrown.gif");
    WebPageUrl("http://standardhost/shopit/",
"ShopIt - Greetings");
  end TMain;
Parent topic: General Web Functions


WebSuspendCache Function

Action

This function is used to disable the browser cache or (if the option parameter is provided) influence its behavior.

Include file

WebAPI.bdh

Syntax

WebSuspendCache( in nOption : number optional );

Return value

  • none

Parameter Description
nOption

If this parameter is omitted the cache will be disabled (no cache hits at all). If it is provided it can be one of the following values:

WEB_CACHE_NO_FULL_HIT
Documents, that would normally be a full cache hit (no request to the server) will be requested conditionally (if-modified-since header)
WEB_CACHE_FULL_HIT_ONLY_IN_PAGE
Identical with the WEB_CACHE_NO_FULL_HIT option with the exception, that duplicate embedded objects in a page are requested just once (what normally a browser does)

Example

dcltrans
  transaction TMain
  begin
    WebSuspendCache();
    WebPageUrl("http://lab3/shopit/", "ShopIt - Greetings");
    WebSuspendCache(WEB_CACHE_FULL_HIT_ONLY_IN_PAGE);
    WebPageUrl("http://lab3/", "homepage");
    WebResumeCache();
  end TMain;
Parent topic: General Web Functions


WebResumeCache Function

Action

This function is used to restore the normal cache behavior, changed by a prior call to the WebSuspendCache function.

Include file

WebAPI.bdh

Syntax

WebResumeCache();

Return value

  • none

Example

dcltrans
  transaction TMain
  begin
    WebSuspendCache();
    WebPageUrl("http://lab3/shopit/","ShopIt - Greetings");
    WebResumeCache();
    WebPageUrl("http://lab3/","home page");
  end TMain;
Parent topic: General Web Functions
Related reference
WebSuspendCache Function


WebSetCacheLimit Function

Action

This function allows you to implement different cache resizing strategies. You can use this function (usually at the beginning of your script - Init transaction) to enable the emulation of a cache size limit. Without specifying this function the cache size will not be limited. When you specify this function Silk Performer's cache manager will automatically check the cache size on every write operation to the cache. If the size exceeds the size specified by the nMaxSize parameter it deletes cache entries, beginning with the oldest entries, till the cache size drops below nReducedSize or no more documents older (or of equal age) than nSeconds are available.

Note: That it never deletes entries which are younger than nSeconds seconds.

Include file

WebApi.bdh

Syntax

WebSetCacheLimit( in nMaxSize     : number,
                  in nReducedSize : number optional,
                  in nSeconds     : number optional );
Parameter | Description
nMaxSize | Cache limit in bytes.
nReducedSize | If the cache manager gets triggered (nMaxSize exceeded) it starts to delete cache entries (beginning with the oldest) which are older (or of equal age) than nSecond seconds, in order to reach a cache size of below nReducedSize bytes (optional). Omit this parameter (or specify 0) to delete all cache entries, which fulfil the age restriction.
nSeconds | Specifies the minimum age which a document must have to be able to get cleared by the cache manager (only if the specified nMaxSize is exceeded) (optional). Omit this parameter to disable the age calculation (force the achievement of the specified size).

Example

dcltrans
  transaction TInit
  begin
    WebSetCacheLimit(1000000, 500000, 10 );
  end TInit;

 transaction TWeb
 begin
    WebPageUrl("http://lab3/stadyn_file500k.html");
    print(string(WebCacheGetSize()));
    Wait 3.0;

    WebPageUrl("http://lab3/stadyn_file500k.html?x=1");
    print(string(WebCacheGetSize()));
    Wait 3.0;

    WebPageUrl("http://lab3/stadyn_file500k.html?x=2");
    print(string(WebCacheGetSize()));
    Wait 3.0;

    WebPageUrl("http://lab3/stadyn_file500k.html?x=3");
    print(string(WebCacheGetSize()));
    Wait 3.0;

    WebPageUrl("http://lab3/stadyn_file500k.html?x=4");
    print(string(WebCacheGetSize()));

  end TWeb;

Output

512000
1024000
1536000
1536000
512000
Parent topic: General Web Functions
Related reference
WebSetCacheLimitIE Function
WebCacheGetSize Function
WebCacheReSize Function


WebSetCacheLimitIE Function

Action

Use this function (usually at the beginning of your script - Init transaction) to enable the emulation of the cache size limit similar to IE. When you specify this function Silk Performer's cache manager will automatically remove entries out of the cache when the cache size gets larger than the specified value of fMaxSize according to IE's caching strategy.

Include file

WebApi.bdh

Syntax

WebSetCacheLimitIE( in fMaxSize : float );
Parameter | Description
fMaxSize | Cache limit in MB.

Example

dcltrans
  transaction TInit
  begin
    WebSetCacheLimitIE(1.0);
  end TInit;

  transaction TWeb
  begin
    WebPageUrl("http://lab3/stadyn_file500k.html");
    print(string(WebCacheGetSize()));
    Wait 180.0;

    WebPageUrl("http://lab3/stadyn_file500k.html?x=1");
    print(string(WebCacheGetSize()));
    Wait 180.0;

    WebPageUrl("http://lab3/stadyn_file500k.html?x=2");
    print(string(WebCacheGetSize()));
    Wait 180.0;

    WebPageUrl("http://lab3/stadyn_file500k.html?x=3");
    print(string(WebCacheGetSize()));
    Wait 180.0;

    WebPageUrl("http://lab3/stadyn_file500k.html?x=4");
    print(string(WebCacheGetSize()));

  end TWeb;

Output

512000
1024000
1536000
2048000
2048000
Parent topic: General Web Functions
Related reference
WebSetCacheLimit Function
WebCacheGetSize Function
WebCacheReSize Function


WebCacheGetSize Function

Action

Returns the actual size of the cache in bytes.

Include file

WebApi.bdh

Syntax

WebCacheGetSize(): number;

Return value

Actual size of the cache.

Example

dcltrans
  transaction TWeb
  begin
    WebPageUrl("http://lab3/stadyn_file500k.html");
    writeln(WebCacheGetSize());
    WebPageUrl("http://lab3/stadyn_file500k.html?x=1");
    writeln(WebCacheGetSize());
    WebPageUrl("http://lab3/stadyn_file50k.html");
    writeln(WebCacheGetSize());
    WebPageUrl("http://lab3/stadyn_file50k.html?x=1");
    writeln(WebCacheGetSize());
    WebPageUrl("http://lab3/stadyn_file5k.html");
    writeln(WebCacheGetSize());
  end TWeb;

Output

512000
1024000
1075200
1126400
1131520
Parent topic: General Web Functions
Related reference
WebSetCacheLimit Function
WebSetCacheLimitIE Function
WebCacheReSize Function


WebCacheReSize Function

Action

Resizes the cache by deleting cache entries, beginning by the oldest entries, to the specified size. It will only drop elements that have been stored (or last accessed) at or before the specified date/time. Omit the second parameter to force the achievement of the specified size (regardless of the age of the cache entries).

Include file

WebApi.bdh

Syntax

WebCacheReSize( in nSize     : number,
                in nEdgeTime : number optional );

Return value

  • true if successful

  • false otherwise

Parameter | Description
nSize | Size which should be reached by deleting the oldest cache entries (if they are old enough - see nEdgeTime param).
nEdgeTime | Specifies the edge time of cache entries to delete (optional). If entries are younger then the specified time, they must not be deleted! A negative value specifies the actual time minus the specified seconds (-4 means actual time minus 4 seconds). A positive value specifies an exact date/time in the format seconds elapsed since midnight (00:00:00), January 1, 1970 as GMT (use number(GetTimeStamp(TIMESTAMP_GMT | TIMESTAMP_IN_SEC)) to get the actual time).Omit this parameter to disable the age calculation.

Example

dcltrans
  transaction TWeb
  begin
    WebPageUrl("http://lab3/stadyn_file5k.html");
    writeln(WebCacheGetSize());
    Wait 3.0;
    WebPageUrl("http://lab3/stadyn_file5k.html?x=1");
    writeln(WebCacheGetSize());
    Wait 3.0;
    WebPageUrl("http://lab3/stadyn_file5k.html?x=2");
    writeln(WebCacheGetSize());
    Wait 3.0;
    WebPageUrl("http://lab3/stadyn_file5k.html?x=3");
    writeln(WebCacheGetSize());
    Wait 3.0;
    WebPageUrl("http://lab3/stadyn_file5k.html?x=4");
    writeln(WebCacheGetSize());
    Wait 3.0;

    WebCacheReSize(0, -31);
    writeln(WebCacheGetSize());

  end TWeb;

Output

5120
10240
15360
20480
25600
25600
Parent topic: General Web Functions
Related reference
WebSetCacheLimit Function
WebSetCacheLimitIE Function
WebCacheGetSize Function


WebThreadWait Function

Action

Waits until all threads of the user are ready. This function is used to synchronize multiple threads.

Include file

WebAPI.bdh

Syntax

WebThreadWait( in nFlag: number optional ) : boolean;

Return value

  • true if successful

  • false otherwise

Parameter Description
nFlag

Flag used to specify the following additional option (optional):

  • WAIT_CLOSECONNECTIONS. Close all open connections, for example, if the Keep-Alive semantics is enabled

Example

dcltrans
  transaction TMain
  begin
    WebUrl("http://www.MyCompany.com");
    // do anything more
    ...
    WebThreadWait();
  end TMain;
Parent topic: General Web Functions


WebIgnoreServerError Function

Action

Modifies the error severity of a specified server error for the subsequent web function call. This can be done for a specified amount of server errors or for all.

Include file

WebAPI.bdh

Syntax

WebIgnoreServerError( in nStatusCode : number,
                      in nSeverity   : number optional := SEVERITY_SUCCESS,
                      in nCount      : number optional );

Return value

  • none

Parameter | Description
nStatusCode | Server status code to ignore or change the severity for (e.g. 404).
nSeverity Optional: Severity of the error that is raised if the verification fails. Can be one of the following values:
  • SEVERITY_SUCCESS: (Default) Success; no error (numerical value: 0)
  • SEVERITY_INFORMATIONAL: Informational; no error (numerical value: 1)
  • SEVERITY_WARNING: Warning; no error (numerical value: 2)
  • SEVERITY_ERROR: Error; simulation continues (numerical value: 3)
  • SEVERITY_TRANS_EXIT: Error; the active transaction is aborted (numerical value: 4)
  • SEVERITY_PROCESS_EXIT: Error; the simulation is aborted (numerical value: 5)
nCount | The specified error can occur nCount times before an error with the default severity is raised. If this parameter is omitted the specified severity is valid for all server responses

Example

dcltrans
transaction TWeb
begin
  WebIgnoreServerError(404);
  WebUrl("http://standardhost/", 0.0);
  WebIgnoreServerError(404, SEVERITY_SUCCESS, 3);
  WebIgnoreServerError(500, SEVERITY_WARNING);
  WebPageUrl("http://standardhost/");
end TWeb;
Parent topic: General Web Functions


WebPing Function

Action

Checks the availability of a specified host by sending an ICMP echo request (ping).

Include file

WebAPI.bdh

Syntax

WebPing( in sHost     : string,
         in nTimeout  : number optional,
         in nPings    : number optional,
         in nDataSize : number optional): boolean;

Return value

  • true if the host responds at least one time

  • false otherwise

Parameter | Description
sHost | Domain name or IP address, for example, hostname.com or 192.231.34.1
nTimeout | Time, in ms, in which the tested host has to respond, otherwise it is considered to be not responding (optional). The default timeout is 1 second.
nPings | Number of pings to be sent (optional). The default value is 3.
nDataSize | Size of the additional data that the ICMP echo request sends (optional). This must be a value between 0 and 65527, inclusive. The default value is 32.

Example

dcltrans
transaction TMain
var
  nResult: number;
begin
  if not WebPing("lab1") then
    Print("host lab1 is not responding")
  else
    Print("host lab1 is alive")
  end;
  if not WebPing("192.168.100.101", 500, 1)  then
    Print("host 192.168.100.101 is not responding")
  else
    Print("host 192.168.100.101 is alive")
  end;
end TMain;
Parent topic: General Web Functions


WebBase64Decode Function

Action

Converts ASCII-encoded data into unsigned binary data.

Note: This function is obsolete. It can still be used, although it's recommended to use the WebBase64DecodeEx function instead.

Include file

WebAPI.bdh

Syntax

WebBase64Decode( out   sTarget : string,
                 inout nTarget : number,
                 in    sSource : string ): boolean;

Return value

  • true if the decoding was successful

  • false otherwise

Parameter | Description
sTarget | String variable to receive the data.
nTarget | Maximum number of bytes to write into sTarget. This value must be less than or equal to the size of sTarget. nTarget will contain the length of the encoded binary data after a successful return.
sSource | Source string to decode.

For example, the string "dGVzdHVzZXI6dGVzdHBhc3M=" is converted to "testuser:testpass".

Example

dcltrans
  transaction TWebBase64Decode
  var
    sPlain    : string;
    sCoded    : string(100);
    nPlainLen : number;
    nCodedLen : number;
  begin
    sPlain := "testuser:testpass";
    write("plain: "); write(sPlain); writeln;

    WebBase64Encode(sCoded, sizeof(sCoded), nCodedLen, sPlain, Strlen(sPlain));
    write("encoded: "); write(sCoded); writeln;

    nPlainLen := sizeof(sPlain);
    WebBase64Decode(sPlain, nPlainLen, sCoded);
    write("decoded: "); write(sPlain); writeln;
  end TWebBase64Decode;

Output

plain: testuser:testpass
encoded: dGVzdHVzZXI6dGVzdHBhc3M=
decoded: testuser:testpass
Parent topic: General Web Functions
Related concepts
Handling Uniform Resource Locators (URLs)
Related reference
WebBase64Encode Function
WebBase64DecodeEx function


WebBase64DecodeEx function

Action

Converts ASCII-encoded data into unsigned binary data.

Include file

WebAPI.bdh

Syntax

WebBase64DecodeEx( out   sTarget : string,
                   in    sSource : string ): boolean;

Return value

  • true if the decoding was successful

  • false otherwise

Parameter | Description
sTarget | String variable to receive the decoded data.
sSource | Source string to decode.

Example

transaction TWeb
  var
    sEncoded : string;
    sDecoded : string;
  begin
    WebBase64EncodeEx(sEncoded, "Hallo");
    WebBase64DecodeEx(sDecoded, sEncoded);
    print(sEncoded);
    print(sDecoded);
  end TWeb;
Parent topic: General Web Functions
Related reference
WebBase64Decode Function
WebBase64EncodeEx Function


WebBase64Encode Function

Action

Converts unsigned binary input into ASCII-encoded, printable characters.

Note: This function is obsolete. It can still be used, although it's recommended to use the WebBase64EncodeEx function instead.

Include file

WebAPI.bdh

Syntax

WebBase64Encode( out sTarget    :string,
                 in  nMaxTarget : number,
                 out nLenTarget : number,
                 in  sSource    : string,
                 in  nSourceLen : number optional ): boolean;

Return value

  • true if the encoding was successful

  • false otherwise

Parameter | Description
sTarget | String variable to receive the encoded string.
nMaxTarget | Maximum number of characters to write into sTarget.
nLenTarget | Parameter receiving the number of characters in sTarget after successful encoding.
sSource | Source data to encode. This can also be binary data.
nSourceLen | Length in bytes of the source data (optional). Specifiy STRING_COMPLETE or omit this parameter to encode all available data.

For example, the string "testuser:testpass" is converted to "dGVzdHVzZXI6dGVzdHBhc3M=". Binary data can also be encoded in order to transport it safely over a 7-bit transport environment.

Note: The data size increases by 30% due to the encoding.

Example

dcltrans
  transaction TWebOwnAuthHeader
  var
    sUserPass : string;
    nUserPassLen : number;
  begin
    // Build your own authentication header
    WebBase64Encode(sUserPass, 200, nUserPassLen,
      "smith:paranoia{}[]~^");

    sUserPass := "Basic " + sUserPass;

    WebHeaderAdd("Authorization", sUserPass);
    WebUrl("http://standardhost/", 0.0);
  end TWebOwnAuthHeader;

Sample scripts

WebEncoding01.bdf, WebForms02.bdf

Parent topic: General Web Functions
Related concepts
Handling Uniform Resource Locators (URLs)
Related reference
WebBase64Decode Function
WebBase64EncodeEx Function


WebBase64EncodeEx Function

Action

Converts unsigned binary input into ASCII-encoded, printable characters.

Include file

WebAPI.bdh

Syntax

WebBase64EncodeEx( out sTarget    :string,
                   in  sSource    : string,
                   in  nSourceLen : number optional ): boolean;

Return value

  • true if the encoding was successful

  • false otherwise

Parameter | Description
sTarget | String variable to receive the encoded string.
sSource | Source data to encode. This can also be binary data.
nSourceLen | Length in bytes of the source data (optional). Specifiy STRING_COMPLETE or omit this parameter to encode all available data.

Example

transaction TWeb
  var
    sEncoded : string;
    sDecoded : string;
  begin
    WebBase64EncodeEx(sEncoded, "Hallo");
    WebBase64DecodeEx(sDecoded, sEncoded);
    print(sEncoded);
    print(sDecoded);
  end TWeb;
Parent topic: General Web Functions
Related reference
WebBase64DecodeEx function
WebBase64Encode Function


WebMD5Encode Function

Action

Encodes a string using the MD5 algorithm. The result is a string that comprises 32 hexadecimal digits.

Include file

WebAPI.bdh

Syntax

WebMD5Encode( out sResult    : string,
              in  nMaxResult : number,
              in  sToEncode  : string ): boolean;

Return value

  • true if the encoding was successful

  • false otherwise

Parameter | Description
sResult | String variable that receives the result. This string variable must be at least 33 characters long.
nMaxResult | Size of the specified string variable.
sToEncode | String that is to be encoded.

Example

dcltrans
  transaction TMain
  var
    sResult: string;
  begin
    WebMD5Encode(sResult, STRING_COMPLETE, "Password");
    Print(sResult);
  end TMain;
Parent topic: General Web Functions
Related reference
WebBase64Encode Function


WebFormUrlDecode Function

Action

Decodes encoded strings included in URLs. See WebFormUrlEncode for more details about the encoding format.

Include file

WebAPI.bdh

Syntax

WebFormUrlDecode( inout sString: string ): boolean;

Return value

  • true if the string could be decoded

  • false otherwise

Parameter | Description
sString | String variable to decode
Note: The input string is overwritten and replaced by the shorter or equal-sized decoded string.

Example

dcltrans
  transaction TWebFormUrlDecode
  var
    sPlain, sUrl : string;
    nUrlLen      : number;
  begin
    sPlain := "http://www.testurl.com/demo[1]()";
    write("plain: "); write(sPlain); writeln;
    nUrlLen := sizeof(sUrl);
    WebFormUrlEncode(sUrl, nUrlLen, sPlain);
    write("encoded: "); write(sUrl); writeln;
    WebFormUrlDecode(sUrl);
    write("decoded: "); write(sUrl); writeln;
  end TWebFormUrlDecode;

Output

plain: http://www.testurl.com/demo[1]()
encoded:
http%3A//www.testurl.com/demo%5B1%5D%28%29
decoded: http://www.testurl.com/demo[1]()
Parent topic: General Web Functions
Related reference
WebFormUrlEncode Function


WebFormUrlEncode Function

Action

Encodes any unsafe characters included in URLs in order to comply with the Uniform Resource Locators specification. This encoding is commonly applied to URL parameters or FORM post parameters.

Include file

WebAPI.bdh

Syntax

WebFormUrlEncode( out   sTarget    :string,
                  inout nMaxTarget : number,
                  in    sSource    : string ): boolean;

Return value

  • true if encoding was successful

  • false if an error occurred or the buffer size is too small

Parameter | Description
sTarget | String variable to receive the encoded string
nMaxTarget | Parameter containing the maximum number of characters to write into sTarget. This value must be <=<= the size of sTarget. If the buffer size is too small, WebFormUrlEncode returns false and sets nMaxTarget to the needed size.
sSource | Source string to encode

Printable ASCII characters being URL-encoded to its hexadecimal representation %hh by Silk Performer: % ? # [ ] { } | \ & = @ : ^ ~ ` " $ + ! * ' ( ) , < > ; /

Note: Octets must be encoded if they have no corresponding graphic character within the US ASCII coded character set, if the use of the corresponding character is unsafe, or if the corresponding character is reserved for some other interpretation within the particular URL scheme. No corresponding graphic US ASCII: URLs are written only with the printable graphic characters of the US ASCII coded character set. The octets 80-FF hexadecimal are not used in US ASCII, and the octets 00-1F and 7F hexadecimal represent control characters; these must be encoded.

Example

dcltrans
  transaction TWebFormUrlEncode
  var
    sUrl     : string;
    sPass    : string(100);
    nPassLen : number;
  begin
    // Encode all unsafe characters in a password
    nPassLen := sizeof(sPass);
    WebFormUrlEncode(sPass, nPassLen, "paranoia{}[]~^");
    sUrl := "http://smith:" + sPass + "@standardhost/";
    WebUrl(sUrl);
  end TWebFormUrlEncode;

Sample scripts

WebEncoding01.bdf

Parent topic: General Web Functions
Related reference
WebFormUrlDecode Function
WebBase64Encode Function


WebFormDefineEncodeCustom Function

Action

Defines how the encoding type ENCODE_CUSTOM encodes individual characters.

Include file

WebAPI.bdh

Syntax

WebFormDefineEncodeCustom( in sEncodingDefinition : string ): boolean;

Return value

  • true if successful

  • false otherwise (syntax error in sEncodingDefinition)

Parameter | Description
sEncodingDefinition | String that defines how the encoding type ENCODE_CUSTOM works.

Syntax of an encoding definition

EncodingDef = SingleDef { Separator SingleDef }
Separator   = ";" | ","
SingleDef   = BaseDef | BlankDef | RangeDef
BaseDef     = "base" "=" StandardEnc
StandardEnc = "ENCODE_FORM" | "ENCODE_ESCAPE" | "ENCODE_BLANKS" | "ENCODE_NONE"
BlankDef    = PosNegDef "Blank2Plus"
PosNegDef   = "+" | "-" | "*"
RangeDef    = PosNegDef CharSet
CharSet     = String | CharRange
String      = "'" { character } "'"
CharRange   = SingleChar [ ".." SingleChar ]
SingleChar  = ( number from 0 to 255 ) | ( "'" character "'" )

Example

// define ENCODE_CUSTOM identical to ENCODE_FORM (1st possibility)
WebFormDefineEncodeCustom("+0..255; -'a'..'z';"
                          " -'A'..'Z'; -'0'..'9';"
                          " -'*-@_. '; +Blank2Plus");

// define ENCODE_CUSTOM identical to ENCODE_FORM (2nd possibility)
WebFormDefineEncodeCustom("base=ENCODE_FORM");

// define ENCODE_CUSTOM identical to ENCODE_ESCAPE (1st possibility)
WebFormDefineEncodeCustom("+0..255; -'a'..'z';"
                          " -'A'..'Z'; -'0'..'9';"
                          " -'*-@_+./'; -Blank2Plus");

// define ENCODE_CUSTOM identical to ENCODE_ESCAPE (2nd possibility)
WebFormDefineEncodeCustom("base= ENCODE_ESCAPE");

// define ENCODE_CUSTOM identical to ENCODE_BLANKS (1st possibility)
WebFormDefineEncodeCustom("-0..255; +' '; +0; -Blank2Plus");

// define ENCODE_CUSTOM identical to ENCODE_BLANKS (2nd possibility)
WebFormDefineEncodeCustom("base= ENCODE_BLANKS");

// define ENCODE_CUSTOM identical to ENCODE_NONE (1st possibility)
WebFormDefineEncodeCustom("-0..255; -Blank2Plus");

// define ENCODE_CUSTOM identical to ENCODE_NONE (2nd possibility)
WebFormDefineEncodeCustom("base= ENCODE_NONE");

// URL encoding of Siebel 7 web client (1st possibility)
WebFormDefineEncodeCustom("+0..255; -'a'..'z';"
                          " -'A'..'Z'; -'0'..'9';"
                          " -' *-_.!()'; +Blank2Plus");

// URL encoding of Siebel 7 web client (2nd possibility)
WebFormDefineEncodeCustom("base=ENCODE_FORM; +'@'; -'!()'");
Parent topic: General Web Functions
Related concepts
Low-Level Web Function Replay Timing
Related reference
WebFormBuild Function
WebFormClear Function
WebFormValuePairInsert Function
WebFormValuePairRemove Function
WebFormValueSet Function
WebFormGet Function
Web Form Declarations


WebCancelAllRules Function

Action

Disables all existing verification and parsing rules that have been set by prior calls of verification or parsing functions with the WEB_FLAG_RULE flag set.

Include file

WebAPI.bdh

Syntax

WebCancelAllRules();

Return value

  • none

Parent topic: General Web Functions


FlashRemotingTransformation Function

Action

This function enables the transformation from binary AMF to a textual XML-based representation. This function is usually called in the TInit transaction of Flash Remoting scripts.

Include file

FlashRemoting.bdh

Syntax

FlashRemotingTransformation( in bRequest  : boolean,                             in bResponse :
boolean optional,                             in sOptions  :
string optional );
Parameter | Description
bRequest | If true, binary AMF in request bodies will be transformed.
bResponse | If true, binary AMF in response bodies will be transformed. If this parameter is omitted, the corresponding setting from the Web/Replay/Transformation tab in the profile settings dialog is used.
sOptions | Specifies additional options for the AMF transformation. If omitted, the corresponding setting from the Web/Replay/Transformation tab in the profile settings dialog is used.

Example

dcltrans
  transaction TInit
  begin
    FlashRemotingTransformation(true, true, "Verbose");
  end TInit;
Parent topic: General Web Functions


WebSetBrowserSim Function

Action

This functions allows to adjust the advanced options for the browser simulation.

Allows the limitation of connections on a per server basis (e.g. 2 connections to one server, 4 connections to two servers). Additionally distinguishes between HTTP 1.0 and HTTP 1.1 connections. (By default the Internet Explorer uses 2 connections to every server connected with HTTP 1.1 and 4 connections to all other servers).

Allows to tune the retry strategy of the emulated browser, too.

Include file

WebAPI.bdh

Syntax

WebSetBrowserSim(
   in nOption : number allownull,
   in nValue  : number ) : boolean;

Return value

  • true if successful
  • false otherwise
Parameter | Description
nOption

Specify any of the following values:

WEB_BROWSER_SIM_ConnHttp10
Specify the number of connection limit to every server using HTTP 1.0. Specify 0 to disable the connection emulation on the server basis.
WEB_BROWSER_SIM_ConnHttp11
Specify the number of connection limit to every server using HTTP 1.1. Specify 0 to disable the connection emulation on the server basi
WEB_BROWSER_SIM_ConnAll
Use this option to specify the unitary connection limit to every server, regardless if it uses HTTP 1.0 or HTTP 1.1.
WEB_BROWSER_SIM_MaxConn
Specify the absolute maximum number of connections, which the emulated browser opens. To perform an accurate connection simulation this value should be above the per server setting (above options).
WEB_BROWSER_SIM_RetryOnResetNoData
Specifies the number of request retries a browser performs, when the server does not respond at all, but resets the connection.
WEB_BROWSER_SIM_RetryOnResetInHeader
Specifies the number of request retries a browser performs, when the server resets the connections during receiving of the HTTP header.
WEB_BROWSER_SIM_RetryOnResetInBody
Specifies the number of request retries a browser performs, when the server resets the connections during receiving of the HTTP body.
WEB_BROWSER_SIM_RetryOnFinNoData
Specifies the number of request retries a browser performs, when the server does not respond at all, but closes the connection gracefully (Fin).
WEB_BROWSER_SIM_RetryOnFinInHeader
Specifies the number of request retries a browser performs, when the server closes the connections gracefully during receiving of the HTTP header.
WEB_BROWSER_SIM_RetryOnErrorNoData
Specifies the number of request retries a browser performs, when it encounters any error (besides connection closes) before the response of the server is received.
WEB_BROWSER_SIM_RetryOnErrorInHeader
Specifies the number of request retries a browser performs, when it encounters any error (besides connection closes) before the HTTP header has been received completely.
WEB_BROWSER_SIM_RetryOnErrorInBody
Specifies the number of request retries a browser performs, when it encounters any error (besides connection closes) before the HTTP body has been received completely.
nValue | Specify the appropriate value. See nOptions for a description.

Example

dcltrans
transaction TInit
begin
   WebSetBrowserSim(WEB_BROWSER_SIM_ConnHttp10, 4);
   WebSetBrowserSim(WEB_BROWSER_SIM_ConnHttp11, 2);
   WebSetBrowserSim(WEB_BROWSER_SIM_MaxConn, 16);
   WebSetBrowserSim(WEB_BROWSER_SIM_RetryOnResetNoData, 5);
   end TInit;
Parent topic: General Web Functions
Related reference
WebSetUserSim Function


WebSetHttpTag Function

Action

This functions allows to add an unique HTTP header tag to every web request of a load test. This can be used to correlate timing or accuracy problems during a load test with results of in-depth analysis tools.

Include file

WebAPI.bdh

Syntax

WebSetHttpTag( in sHeader : string,
               in nFlags  : number );
Parameter | Description
sHeader | Specify any valid HTTP header (name of the tag header).
nFlags Specify any combination of the following values:
WEB_TAG_FLAG_ProjectName
HTTP header contains the name of the load test: TE=<LoadTestName>
WEB_TAG_FLAG_TestName
HTTP header contains the name of the used Silk Performer project:TE=<ProjectName>
WEB_TAG_FLAG_ScriptName
HTTP header contains the name of the script: SN=<LoadTestName>
WEB_TAG_FLAG_ToolName
HTTP header identifies source as: SID=<SilkPerformerVersioned>
WEB_TAG_FLAG_UserGroup
HTTP header contains the name of the Silk Performer user-group to which the virtual user sending the request belongs: UG=<UserGroup>
WEB_TAG_FLAG_Profile
HTTP header contains the name of the Silk Performer profile which the virtual user sending the request uses: PF=<Profile>
WEB_TAG_FLAG_Workload
HTTP header contains the name of the Silk Performer workload which the virtual user sending the request uses: WL=<Workload>
WEB_TAG_FLAG_Transaction
HTTP header contains the name of the Silk Performer transaction which the virtual user sending the request is currently executing: TN=<Transaction>
WEB_TAG_FLAG_UserId
HTTP header contains a unique user id (cross loadtest): VU=<Id>
WEB_TAG_FLAG_BrowserSession
HTTP header contains a browser session id. This session id is incremented when the virtual user logically opens a browser: SI=<BrowserSessionId>
WEB_TAG_FLAG_PageContext
HTTP header contains a information about what document in the currently processed page is loaded. If it is a named frame then the value starts with the frame name. After a dot the page-unique document number is appended. Note that if embedded documents get cached this number need not be progresional: PC=<FrameName>.<DocId>
WEB_TAG_FLAG_RequestId
HTTP header contains a user-unique request id: ID=<RequestId>
WEB_TAG_FLAG_Timer
If the current request gets issued in a page context (page-level API) the HTTP header contains the specified timer name (if omitted the name is empty): NA=<TimerName>
WEB_TAG_FLAG_WorkloadType
HTTP header contains the Silk Performer workload type: WT=<WorkloadType>
Possible workload types:
  • 0: SteadyState
  • 1: Increasing
  • 2: Dynamic
  • 3: Queuing
  • 4: Monitoring
  • 5: AllDay
  • 6: Verify
  • 7: SingleUser
WEB_TAG_FLAG_Agent
HTTP header contains the name of the used Silk Performer agent: AN=<AgentName>
WEB_TAG_FLAG_LineNumber
HTTP header contains the line number of the currently executed Silk Performer function: LN=<LineNumber>
WEB_TAG_FLAG_Time
HTTP header contains the current controller time in the format of seconds since 1970: TI=<ElapsedSeconds>

Example

dcltrans
transaction TInit
begin
  WebSetHttpTag("MyTag",
  WEB_TAG_FLAG_RequestId |
  WEB_TAG_FLAG_UserId |
  WEB_TAG_FLAG_ProjectName |
  WEB_TAG_FLAG_UserGroup |
  WEB_TAG_FLAG_Profile |
  WEB_TAG_FLAG_LineNumber);
end TInit;
Parent topic: General Web Functions
Related reference
WebGetHttpTag Function


WebGetHttpTag Function

Action

This function retrieves the values which have been set by a call to the WebSetHttpTag function.

Include file

WebAPI.bdh

Syntax

WebGetHttpTag( out sHeader : string,
               out nFlags  : number );
Parameter | Description
sHeader | String that receives the HTTP header (name of the tag header).
nFlags Receives any combination of the following values:
WEB_TAG_FLAG_ProjectName
HTTP header contains the name of the used Silk Performer project:PN=<ProjectName>
WEB_TAG_FLAG_UserGroup
HTTP header contains the name of the Silk Performer user-group to which the virtual user sending the request belongs: UG=<UserGroup>
WEB_TAG_FLAG_Profile
HTTP header contains the name of the Silk Performer profile which the virtual user sending the request uses: PF=<Profile>
WEB_TAG_FLAG_Workload
HTTP header contains the name of the Silk Performer workload which the virtual user sending the request uses: WL=<Workload>
WEB_TAG_FLAG_Transaction
HTTP header contains the name of the Silk Performer transaction which the virtual user sending the request is currently executing: TN=<Transaction>
WEB_TAG_FLAG_UserId
HTTP header contains a unique user id (cross loadtest): VU=<Id>
WEB_TAG_FLAG_BrowserSession
HTTP header contains a browser session id. This session id is incremented when the virtual user logically opens a browser: SI=<BrowserSessionId>
WEB_TAG_FLAG_PageContext
HTTP header contains a information about what document in the currently processed page is loaded. If it is a named frame then the value starts with the frame name. After a dot the page-unique document number is appended. Note that if embedded documents get cached this number need not be progresional: PC=<FrameName>.<DocId>
WEB_TAG_FLAG_RequestId
HTTP header contains a user-unique request id: ID=<RequestId>
WEB_TAG_FLAG_Timer
If the current request gets issued in a page context (page-level API) the HTTP header contains the specified timer name (if omitted the name is empty): NA=<TimerName>
WEB_TAG_FLAG_WorkloadType
HTTP header contains the Silk Performer workload type: WT=<WorkloadType>
Possible workload types:
  • 0: SteadyState
  • 1: Increasing
  • 2: Dynamic
  • 3: Queuing
  • 4: Monitoring
  • 5: AllDay
  • 6: Verify
  • 7: SingleUser
WEB_TAG_FLAG_Agent
HTTP header contains the name of the used Silk Performer agent:AN=<AgentName>
WEB_TAG_FLAG_LineNumber
HTTP header contains the line number of the currently executed Silk Performer function: LN=<LineNumber>
WEB_TAG_FLAG_Time
HTTP header contains the current controller time in the format of seconds since 1970: TI=<ElapsedSeconds>

Example

dcltrans
transaction TInit
var
  sHeader : string;
  nFlags  : number;
begin
  WebSetHttpTag("MyTag",
  WEB_TAG_FLAG_RequestId |
  WEB_TAG_FLAG_UserId |
  WEB_TAG_FLAG_ProjectName |
  WEB_TAG_FLAG_UserGroup |
  WEB_TAG_FLAG_Profile |
  WEB_TAG_FLAG_LineNumber);
  WebGetHttpTag(sHeader, nFlags);
end TInit;
Parent topic: General Web Functions
Related reference
WebSetHttpTag Function


WebSetDiagnostics Function

Action

Sets appropriate HTTP headers for a diagnostics tool. A diagnostics tag is sent as an HTTP header along with each request, enabling linkage between client-side results and application diagnostics.

AppDynamics™ and dynaTrace Diagnostics™ each provide in-depth application performance diagnostics down to the code level. The WebSetDiagnostics function enables correlation of Web page and Web Service calls with both AppDynamics and dynaTrace PurePath™ results for root-cause analysis of performance bottlenecks.

Include file

WebAPI.bdh

Syntax

WebSetDiagnostics( in nOption : number );
Parameter Description
nOption Specify one of the following values:

  • WEB_DIAG_AppDynamics: Sends the appropriate HTTP headers for AppDynamics diagnostics

  • WEB_DIAG_dynaTraceDiagnostics: Sends the appropriate HTTP headers for dynaTrace AppMon

  • WEB_DIAG_dynaTraceSaasManaged: Sends the appropriate HTTP headers for dynaTrace Saas and Managed

  • 0: Disables HTTP header tagging

Example

dcltrans
transaction TInit
  begin
    WebSetDiagnostics(WEB_DIAG_AppDynamics);
  end TInit;
Parent topic: General Web Functions
Related reference
WebSetHttpTag Function


WebSetUserSim Function

Action

This functions allows to adjust the advanced options for the user tolerance simulation.

There are 3 different timeout values, which can be specified for different load states of the page:
  • No response from server (normally the shortest periode)
  • At least the first (root) document is loaded, but the HTML content (frames) is not complete
  • HTML content is complete, but at least one embedded object is missing

Additionally the pure image (embedded objects) load time can be specified, which starts, when the last HTML document is loaded.

In case of a timeout there are several options which the virtual user could take:
  • Retry the page (x times)
  • Do one of the following:
    • Abandon the page
    • Continue waiting - unlimited or unless another timeout occurs
    • Continue waiting for another defined timeout value

Not only the load time tolerance, but also the error accaptance of the virtual user can be controlled by this function. Therefore the number of retries can be specified wether the error happens in the HTML document portion of the page, or in the embedded objects.

Include file

WebAPI.bdh

Syntax

WebSetUserSim(
   in nOption : number,
   in nValue  : number ) : boolean;

Return value

  • true if successful
  • false otherwise
Parameter | Description
nOptions
Specify any of the following values:
WEB_USER_SIM_TimeoutNoData
Specifies the maximum time in ms an user is willing to wait when no response from the server arrives.
WEB_USER_SIM_ReloadNoData
Specifies if and how often the user presses the Refresh button in case of above timeout.
WEB_USER_SIM_ActionNoData
Specifies the action the user takes, after the above timeout occures and the page has already been retried the specified times:
Valid values:
WEB_USER_SIM_ACTION_Continue
The user continues waiting; unlimited or until another timeout occurs.
WEB_USER_SIM_ACTION_Abort
The user presses the Stop button - Abandons the page load.
Any positive value
Specifies the amount of ms the user waits additionally before he presses the Stop button.
WEB_USER_SIM_TimeoutDocNotComplete
Specify the maximum time in ms an user is willing to wait when the first (root) document is loaded, but the HTML content (frames) is not complete.
WEB_USER_SIM_ReloadDocNotComplete
Specifies if and how often the user presses the Refresh button in case of above timeout.
WEB_USER_SIM_ActionDocNotComplete
See WEB_USER_SIM_ActionNoData.
WEB_USER_SIM_TimeoutPageNotComplete
Specifies the maximum time in ms an user is willing to wait when the HTML content is complete, but at least one embedded object is missing.
WEB_USER_SIM_ReloadPageNotComplete
Specifies if and how often the user presses the Refresh button in case of above timeout.
WEB_USER_SIM_ActionPageNotComplete
See WEB_USER_SIM_ActionNoData
WEB_USER_SIM_ImgLoadTime
Specifies the maximum time in ms an user is willing to wait for the loading of all embedded objects. This time starts, when the last HTML document is loaded.
WEB_USER_SIM_ReloadImgLoadTimeExceeded
Specifies if and how often the user presses the Refresh button in case of above timeout.
WEB_USER_SIM_ActionImgLoadTimeExceeded
See WEB_USER_SIM_ActionNoData.
WEB_USER_SIM_ReloadPageOnError
Specifies if and how often the user presses the Refresh button in case of any error in the page. (e.g. missing image)
WEB_USER_SIM_ReloadOnlyIfErrorInDocs
Specifies if and how often the user presses the Refresh button in case of any error in the document portion of the page. (e.g. missing frame).
nValue | Specify the appropriate value. See nOptions for a description.

Example

dcltrans
  transaction TInit
  begin
   WebSetUserSim(WEB_USER_SIM_ImgLoadTime, 10000);
   WebSetUserSim(WEB_USER_SIM_ReloadImgLoadTimeExceeded, 1);
   WebSetUserSim(WEB_USER_SIM_ActionImgLoadTimeExceeded,
     WEB_USER_SIM_ACTION_Abort);
   WebSetUserSim(WEB_USER_SIM_ReloadOnlyIfErrorInDocs, 1);
  end TInit;
Parent topic: General Web Functions
Related reference
WebSetBrowserSim Function


Browser Settings

  • WebSetAcceptTypes Function
    Sets the HTTP/HTTPS accept types.
  • WebGetAcceptTypes Function
    Gets the current values of HTTP/HTTPS accept types.
  • WebSetAutoRedirect Function
    Specifies whether Silk Performer automatically parses redirection responses and redirects the request to the specified server.
  • WebSetBrowser Function
    Sets the browser type to be used for simulation.
  • WebSetCookies Function
    Sets the maximum number of cookies to be stored per domain.
  • WebGetCookies Function
    Gets the current value of the maximum number of cookies.
  • WebSetDocumentCache Function
    Specifies whether Silk Performer emulates a document cache.
  • WebSetHttpHeader Function
    Sets one or more user-defined headers for HTTP/HTTPS.
  • WebGetHttpHeader Function
    Gets all user-defined headers for HTTP/HTTPS that are currently set.
  • WebModifyHttpHeader Function
    Sets, modifies or removes one or more user-defined headers for HTTP/HTTPS.
  • WebSetHttpVersion Function (Deprecated)
    Sets the HTTP/HTTPS version string to be used by low-level Web API functions.
  • WebGetHttpVersion Function (Deprecated)
    Gets the currently used HTTP/HTTPS version string to be used.
  • WebSetKeepAlive Function
    Sets the Keep-Connection semantics for HTTP/HTTPS.
  • WebGetKeepAlive Function
    Checks whether the KeepConnection flag is set.
  • WebSetMaxThreads Function
    Sets the upper limit of possible concurrent threads.
  • WebGetMaxThreads Function
    Returns the current value of maximum concurrent threads as a number.
  • WebSetProxy Function
    Sets the proxy host name and port for a specific protocol.
  • WebGetProxy Function
    Gets the current proxy host name and port number either for all protocols or for a specific protocol.
  • WebSetProxyAutoConfigFile Function
    Specifies the location of a PAC (Proxy Auto-Configuration) file.
  • WebSetProxyAuth Function
    Sets the password for proxy authentication login.
  • WebSetProxyAuthBasic Function
    Sets the password for basic proxy authentication login.
  • WebSetProxyAuthNtlm Function
  • WebSetProxyBypass Function
    Sets the names of hosts not be accessed through a proxy.
  • WebGetProxyBypass Function
    Gets the names of hosts not to be accessed through a proxy.
  • WebSetUserAgent Function
    Sets the HTTP/HTTPS user agent and overrides those of the workbench.
  • WebGetUserAgent Function
    Gets the current value of the HTTP/HTTPS user agent.
Parent topic: Web Functions Reference


WebSetAcceptTypes Function

Action

Sets the HTTP/HTTPS accept types.

Include file

WebAPI.bdh

Syntax

WebSetAcceptTypes(in sAccept: string): boolean;

Return value

  • true if successful
  • false otherwise
Parameter | Description
sAccept | Contains the accept pattern string, for example, "*/*", "image/gif"

Example

dcltrans
transaction TWebInit
begin
  WebSetAcceptTypes("text/html, image/gif");
  WebDumpSettings();
end TWebInit;
Parent topic: Browser Settings
Related reference
WebGetAcceptTypes Function
Settings Functions Reference
Internet Functions


WebGetAcceptTypes Function

Action

Gets the current values of HTTP/HTTPS accept types.

Include file

WebAPI.bdh

Syntax

WebGetAcceptTypes( out sAccept : string,
                   in  nMaxLen : number optional ): boolean;

Return value

  • true if successful

  • false otherwise

Parameter | Description
sAccept | A string buffer that will receive the current list of AcceptTypes.
nMaxLen | The maximum length of the receive buffer sAccept (optional).

Example

dcltrans
  transaction TWebInit
  var
    sAccept: string;
  begin
    WebGetAcceptTypes(sAccept);
    write("HttpAccept: "); write(sAccept); writeln;
  end TWebInit;
Parent topic: Browser Settings
Related reference
WebSetAcceptTypes Function
Settings Functions Reference


WebSetAutoRedirect Function

Action

Specifies whether Silk Performer automatically parses redirection responses and redirects the request to the specified server.

Include file

WebAPI.bdh

Syntax

WebSetAutoRedirect( in bAuto     : boolean,
                    in nMaxRedir : number optional,
                    in nFlag     : number optional ) : boolean;

Return value

  • true if successful

  • false otherwise

Parameter | Description
bAuto | If this parameter is set to true, Silk Performer automatically parses redirection responses and redirects the request to the specified server
nMaxRedir | Specifies the maximum number of redirections that are automatically performed by Silk Performer (optional). The default value for this parameter is 5.
nFlag

Specifies whether to modify the standardhost variable (optional). This parameter can be one of the following:

WEB_AUTOREDIR_SETSTDHOST_FIRST
Sets the standardhost variable to the new location on the next redirection.
WEB_AUTOREDIR_SETSTDHOST_ALWAYS
Sets the standardhost variable to new location on all redirections.

The function’s default behavior is not to modify the standardhost variable.

The following error message is reported if too many redirections requests are received in a row:

HTTP: 1010 - too many redirections, possibly loop detected.

A possible reason for this error is that the script has not been customized properly. For example, a script must correctly handle session IDs that cause a Web application to send redirection messages.

Example

dcltrans
  transaction TMain
  var
    sUrl, sParam1, sSession: string(1000);
  begin
    // automatic redirect
    WebSetAutoRedirect(true);
    WebUrl("http://standardhost/SessionIdTest.asp");
    // manual redirect
    WebSetAutoRedirect(false);
    WebParseResponseRedirect(sUrl, sizeof(sUrl), NULL);
    WebParseResponseRedirect(sParam1, sizeof(sParam1), "Param1");
    WebParseResponseRedirect(sSession, sizeof(sSession),
                             "SessionID");
    WebUrl("http://standardhost/SessionIdTest.asp");
    writeln(sUrl); writeln(sParam1);
    writeln(sSession);
  end TMain;

Sample scripts

WebAuth01.bdf, WebHttpHeaders01.bdf, WebParseResponseHeader01.bdf, WebSecure02.bdf

Parent topic: Browser Settings


WebSetBrowser Function

Action

Sets the browser type to be used for simulation. Different browsers send different header information to the Web server. For example, setting the browser to WEB_BROWSER_MSIE11 lets the low-level web functions use the preset headers for Microsoft Internet Explorer 11 simulation. The setting WEB_BROWSER_CUSTOM lets the functions use the custom-defined header strings of the workbench settings.

Note: This setting overrides previous browser settings in your script.

Include file

WebAPI.bdh

Syntax

WebSetBrowser( in nBrowser: number ): boolean;

Return value

  • true if successful

  • false otherwise

Example

dcltrans
  transaction TWebInit
  begin
    WebSetBrowser(WEB_BROWSER_CUSTOM);
    WebDumpSettings();
  end TWebInit;
Parent topic: Browser Settings
Related reference
WebSetUserAgent Function
WebSetAcceptTypes Function
WebSetHttpHeader Function


WebSetCookies Function

Action

Sets the maximum number of cookies to be stored per domain. If the maximum is reached, older cookies are discarded. Setting nCookies to 0 disables cookie usage. The cookie database is created per user and kept in memory at run time only.

Include file

WebAPI.bdh

Syntax

WebSetCookies( in nCookies: number ): boolean;

Return value

  • true if successful

  • false otherwise

Parameter | Description
nCookies | Maximum number of cookies
Note: A call to WebSetCookies will reset the cookie database and delete all existing cookies.

Example

dcltrans  transaction TWebInit  begin    WebSetCookies(10);    WebDumpSettings();  end TWebInit;

Sample scripts

WebMulti01.bdf

Parent topic: Browser Settings
Related concepts
Cookie Database Functions Overview
Related reference
WebGetCookies Function


WebGetCookies Function

Action

Gets the current value of the maximum number of cookies.

Include file

WebAPI.bdh

Syntax

WebGetCookies( ): number;

Return value

Current value of the maximum number of cookies

Example

dcltrans
  transaction TWebInit
  begin
    write("MaxCookiesPerDomain: "); write(WebGetCookies());
    writeln;
  end TWebInit;
Parent topic: Browser Settings
Related concepts
Cookie Database Functions Overview
Related reference
WebSetCookies Function


WebSetDocumentCache Function

Action

Specifies whether Silk Performer emulates a document cache. A document cache is used to keep local copies of frequently accessed documents and thus reduce the hits at the server. You can specify to always, once per session, or never check whether a page has changed on the Web server since the virtual user last viewed it.

Note: This function overrides the corresponding setting in the Simulation tab of the Profile Settings - Web dialog.

Include file

WebAPI.bdh

Syntax

WebSetDocumentCache( in bEnable : boolean,
                     in nMode   : number optional ) : boolean;

Return value

  • true if successful

  • false otherwise

Parameter | Description
bEnable | Specifies whether to emulate a document cache.
nMode

Specifies when to check whether a page has changed on the Web server since the virtual user last viewed it (optional). This parameter must be one of the following values:

WEB_CACHE_CHECK_SESSION
Checks once per session whether a page has changed since the virtual user last viewed it. The term of a session is the sequence of starting a Web browser, surfing the Web, and closing the Web browser. The correlation of a session to Silk Performer transactions can be adjusted with the WebSetUserBehavior function.
WEB_CACHE_CHECK_ALWAYS
Always checks whether a page has changed since the virtual user last viewed it.
WEB_CACHE_CHECK_NEVER
Never checks whether a page has changed since the virtual user last viewed it.

If this parameter is omitted, Silk Performer simulation the behavior specified in the Browser tab of the Internet Settings dialog.

Example 1 (WEB_CACHE_CHECK_SESSION)

transaction TInit
begin
  WebSetUserBehavior(WEB_USERBEHAVIOR_REVISITING);
  WebSetDocumentCache(true, WEB_CACHE_CHECK_SESSION);
  WebCookieSet("Coffee=Bean; expires=Mon, 01-Jan-2001 05:00:00 GMT; path=/",
  "http://localhost"); // The cookie's scope is TInit!!!
end TInit;
transaction TWeb
begin
  WebPageUrl("http://localhost/ResponseCookie/Cookie.asp");
  WebPageLink("Corporate", "Corporate Link");
  WebPageUrl("http://localhost/ResponseCookie/Cookie.asp");
end TWeb;
transaction TMain
begin
  WebPageUrl("http://localhost/cache/cache_form.html", "Cache Test");
  WebPageSubmit("Submit with GET", SUBMIT_WITH_GET001, "Cache Handler");
  WebPageUrl("http://localhost/cache/cache_form.html", "Cache Test");
end TMain;
dclform
  SUBMIT_WITH_GET001:
    "Get-Button" := "Submit with GET";

We will have to execute each transaction at least twice to see how caching works. We used an additional function, WebsetUserBehavior, where we specified the script was to run a returning user (user behavior WEB_USERBEHAVIOR_REVISITING), for example, an online shopper that returns to his/her favorite shopping application.

Example 2 (WEB_CACHE_CHECK_ALWAYS)

transaction TInit
begin
  WebSetUserBehavior(WEB_USERBEHAVIOR_FIRST_TIME);
  WebSetDocumentCache(true, WEB_CACHE_CHECK_ALWAYS);
  WebCookieSet("Coffee=Bean; expires=Mon, 01-Jan-2001 05:00:00 GMT; path=/",
  "http://localhost"); // The cookie's scope is TInit!!!
end TInit;
transaction TMain
begin  WebPageUrl("http://localhost/ResponseCookie/Cookie.asp");
  WebPageLink("Corporate", "Corporate Link");
  WebPageUrl("http://localhost/ResponseCookie/Cookie.asp");
end TMain;
dclform
  SUBMIT_WITH_GET001:
    "Get-Button" := "Submit with GET";

In this example, we specify the user behavior WEB_USERBEHAVIOR_FIRST_TIME. This means that each execution cycle of a transaction will be interpreted as a new user that has never visited the Web site - which is what the document cache and cookies are checking for. To achieve this, each virtual user will reset their connections, clean up their cookie database (persistent or non-persistent) and eventually clear the document cache each time a transaction has completed. When setting first time user behavior, be sure that you do not have a persistent cookie set in the TInit transaction. This cookie will not be accessible to all other transactions. It will be invalidated as soon as the transaction is done.

Example 3 (WEB_CACHE_CHECK_NEVER)

transaction TInit
begin
  WebSetUserBehavior(WEB_USERBEHAVIOR_DISABLE);
  WebSetDocumentCache(true, WEB_CACHE_CHECK_NEVER);
  WebCookieSet("Coffee=Bean; expires=Mon, 01-Jan-2001 05:00:00 GMT; path=/",
  "http://localhost"); // The cookie's scope is TInit!!!
end TInit;

The user behavior WEB_USERBEHAVIOR_DISABLE simply means that the document cache and the cookie database will be the same throughout all cycles of a transaction. The cookie database will not be reset and the document cache will not be cleared.

Parent topic: Browser Settings
Related reference
WebBrowserReset Function
WebSetUserBehavior Function


WebSetHttpHeader Function

Action

Sets one or more user-defined headers for HTTP/HTTPS.

Include file

WebAPI.bdh

Syntax

WebSetHttpHeader( in sHeader : string ): boolean;

Return value

  • true if successful

  • false otherwise

Parameter | Description
sHeader | User defined header
Note: One header must not be terminated by a CRLF sequence. Multiple headers must be separated by a CRLF sequence.

Example

dcltrans
  transaction TWebInit
  begin
    WebSetHttpHeader("CustomHeader: CustomValue");
    WebDumpSettings();
  end TWebInit;

Sample scripts

WebHttpHeaders01.bdf

Parent topic: Browser Settings
Related reference
WebGetHttpHeader Function


WebGetHttpHeader Function

Action

Gets all user-defined headers for HTTP/HTTPS that are currently set. Note that this function retrieves values that are set with the WebSetHttpHeader function, but it does not retrieve values that are set with the WebHeaderAdd function.

Include file

WebAPI.bdh

Syntax

WebGetHttpHeader( out sHeader : string,
                  in  nMaxLen : number optional ): boolean;

Return value

  • true if successful

  • false otherwise

Parameter | Description
sHeader | A string buffer that will receive the current list of HTTP headers.
nMaxLen | The maximum length of the receive buffer sHeader (optional).

Example

dcltrans
  transaction TWebInit
  var
    sHeader : string;
  begin
    WebGetHttpHeader(sHeader);
    write("HttpHeader: "); write(sHeader); writeln;
  end TWebInit;
Parent topic: Browser Settings
Related reference
WebSetHttpHeader Function
WebHeaderAdd Function


WebModifyHttpHeader Function

Action

Sets, modifies or removes one or more user-defined headers for HTTP/HTTPS. Note that this function is only applicable to certain HTTP headers. It cannot be used to modify headers such as Accept, User-Agent and Accept-Encoding.

  • For Accept, use the function WebSetAcceptTypes.
  • For User-Agent, use the function WebSetUserAgent.
  • For Accept-Encoding, use the function WebSetOption(WEB_OPT_ENABLE_CONTENT_ENCODING, 0); It disables the default accept-encoding.

Include file

WebAPI.bdh

Syntax

WebModifyHttpHeader( in sHeader : string,
                     in sValue  : string allownull,
                     in nOption : number optional ): boolean;

Return value

  • true if successful

  • false otherwise

Parameter | Description
sHeader | User defined header.
sValue | Value of the specified header.
nOption

Can be one of the following values:

WEB_MODIFY_OPT_Add
Adds the specified header to the actual set of headers.
WEB_MODIFY_OPT_ReplaceFirst
Replaces the value of the first header with identical name. All following headers with the same name (if present) are not changed. To remove all those headers use the WEB_MODIFY_OPT_RemoveAdd option. If no header with the specified name can be found, a new header is added.
WEB_MODIFY_OPT_Remove
Removes all headers with the specified name. The value of sValue is ignored.
WEB_MODIFY_OPT_RemoveAdd (default)
Removes all headers with the specified name and adds the specified sHeader – sValue pair.

Example

dcltrans
  transaction TWeb
  begin
    WebModifyHttpHeader("Accept-Language", "en-us");
    WebPageUrl("http://server/");
    WebModifyHttpHeader("Accept-Language", "de", WEB_MODIFY_OPT_Add);
    WebPageUrl("http://server/");
  end TWeb;
Parent topic: Browser Settings
Related reference
WebSetHttpHeader Function


WebSetHttpVersion Function (Deprecated)

Action

This function has been deprecated. Use WebSetOption instead.

Sets the HTTP/HTTPS version string to be used by low-level Web API functions.

Note: A subsequent WebSetBrowser call will override this setting.

Include file

WebAPI.bdh

Syntax

WebSetHttpVersion(in sVersion : string): boolean;

Return value

  • true if successful

  • false otherwise

Parameter | Description
sVersion | HTTP version string.

Example

dcltrans
transaction TWebInit
begin
  WebSetHttpVersion("HTTP/1.0");
  WebDumpSettings();
end TWebInit;
Parent topic: Browser Settings
Related reference
WebGetHttpVersion Function (Deprecated)


WebGetHttpVersion Function (Deprecated)

Action

This function has been deprecated. Use WebGetOption instead.

Gets the currently used HTTP/HTTPS version string to be used.

Include file

WebAPI.bdh

Syntax

WebGetHttpVersion( out sVersion : string,
                   in  nMaxLen  : number optional ): boolean;

Return value

  • true if successful

  • false otherwise

Example

dcltrans
  transaction TWebInit
  var
    sVersion: string;
  begin
    WebGetHttpVersion(sVersion);
    write("HttpVersion: "); write(sVersion); writeln;
  end TWebInit;
Parent topic: Browser Settings
Related reference
WebSetHttpVersion Function (Deprecated)


WebSetKeepAlive Function

Action

Sets the Keep-Connection semantics for HTTP/HTTPS.

Note: A subsequent WebSetBrowser call will override this setting.

Include file

WebAPI.bdh

Syntax

WebSetKeepAlive( in bAlive : boolean ) : boolean;

Return value

  • true if successful

  • false otherwise

Parameter | Description
bAlive | If this parameter is set to true, a Keep-Alive header is added to the request
Note: Silk Performer automatically tries to reuse an open connection on subsequent requests.

Example

dcltrans
  transaction TWebInit
  begin
    WebSetKeepAlive(true);
  end TWebInit;

Sample scripts

WebMultiClientIpAddresses01.bdf

Parent topic: Browser Settings
Related reference
WebGetKeepAlive Function


WebGetKeepAlive Function

Action

Checks whether the KeepConnection flag is set.

Include file

WebAPI.bdh

Syntax

WebGetKeepAlive(): boolean;

Return value

  • true if flag is set

  • false otherwise

Example

dcltrans
transaction TWebInit
begin
  write("HttpKeepConnection: ");
  if WebGetKeepAlive() then
    write("true"); writeln;
  else
    write("false"); writeln;
  end;
end TWebInit;
Parent topic: Browser Settings
Related reference
WebSetKeepAlive Function


WebSetMaxThreads Function

Action

Sets the upper limit of possible concurrent threads. Setting this limit to 1 lets the functions execute synchronously.

Include file

WebAPI.bdh

Syntax

WebSetMaxThreads(in nMaxThreads: number): boolean;

Return value

  • true if successful

  • false otherwise

Parameter | Description
nMaxThreads | Maximum number of possible concurrent threads; this number is limited to 32.

Example

dcltrans
transaction TWebInit
begin
  WebSetMaxThreads(4);
  WebDumpSettings();
end TWebInit;

Sample scripts

WebMulti01.bdf

Parent topic: Browser Settings
Related reference
WebGetMaxThreads Function


WebGetMaxThreads Function

Action

Returns the current value of maximum concurrent threads as a number.

Include file

WebAPI.bdh

Syntax

WebGetMaxThreads(): number;

Return value

Number of maximum concurrent threads

Example

dcltrans
transaction TWebInit
begin
  write("MaxThreads: "); write(WebGetMaxThreads()); writeln;
end TWebInit;
Parent topic: Browser Settings
Related reference
WebSetMaxThreads Function


WebSetProxy Function

Action

Sets the proxy host name and port for a specific protocol.

By using the domain parameter, a “proxy stack” can be specified with multiple WebSetProxy calls. The last call has the highest priority. Using this functionality a PAC file like behaviour can be implemented.

Include file

WebAPI.bdh

Syntax

WebSetProxy(
  in nProxy  : number,
  in sHost   : string,
  in nPort   : number,
  in sDomain: string optional ): boolean;

Return value

  • true if successful

  • false otherwise

Parameter | Description
nProxy

Proxy type. Can be one of the following types:

  • WEB_PROXY_FTP

  • WEB_PROXY_HTTP

  • WEB_PROXY_HTTPS

  • WEB_PROXY_SOCKS
sHost | Host name of the proxy server
nPort | Port the proxy server listens to
sDomain | If specified the proxy is only used by sending requests to the specified domain. The domain parameter may contain a wildcard (*) character either at the beginning or at the end. Multiple calls to WebSetProxy can be made, where the latest one has the top priority (proxy stack). Specifying an empty string ("") for the sHost parameter means no proxy for the specified domain or domain pattern.

Example

dcltrans
  transaction TWebInit
  begin    // Set up proxy connection using the WebSetting commands
    WebSetProxy(WEB_PROXY_HTTP, "proxy.mydomain.com", 80);
    WebSetProxyBypass(FALSE, NULL);     // Set password used for authentication
    WebSetProxyAuth("proxyuser", "proxypass");
  end TWebInit;
  transaction TWebInit1
  begin
    WebSetProxy(WEB_PROXY_HTTP, "proxy", 8080, "www*");
    //use this proxy for all hosts starting with "www"              (priority 4)
    WebSetProxy(WEB_PROXY_HTTP, "", 0, "www.microsoft.com");
    //but go directly to www.microsoft.com                          (priority 3)
    WebSetProxy(WEB_PROXY_HTTP, "proxy", 8081, "*yahoo.com");
    //use proxy on a different port for all "yahoo.com" domains     (priority 2)
    WebSetProxy(WEB_PROXY_HTTP, "proxy", 8082, "www.yahoo.com");
    //use proxy on a different port for all "www.yahoo.com" domains (priority 1)
  end TWebInit1;
Parent topic: Browser Settings
Related reference
WebGetProxy Function


WebGetProxy Function

Action

Gets the current proxy host name and port number either for all protocols or for a specific protocol. If this function is called to retrieve all proxies set up, it returns a list like

http=http://www-proxy.austria.eu.net:8080
ftp=ftp://ftp-proxy.austria.eu.net:2121
Note: Only default proxies are returned. Proxies that have been set with a domain specification are not returned.

Include file

WebAPI.bdh

Syntax

WebGetProxy( out sProxy     :string,
             in  nMaxLen    : number optional,
             in  nProxyType : number optional ): boolean;

Return value

  • true if successful

  • false otherwise

Parameter | Description
sProxy | A string buffer that will receive the list of default proxies.
nMaxLen | The maximum length of the receive buffer sProxy (optional).
nProxyType

Type of proxy settings to retrieve (optional). Can be one of the following protocols:

  • WEB_PROXY_FTP

  • WEB_PROXY_HTTP

  • WEB_PROXY_HTTPS

  • WEB_PROXY_SOCKS

If this parameter is omitted, this function returns a list containing all proxies currently set up.

Example

dcltrans
  transaction TInit
  var
    sProxy: string;
  begin
    WebGetProxy(sProxy);
    write("Proxies: "); write(sProxy); writeln;
  end TInit;
Parent topic: Browser Settings
Related reference
WebSetProxy Function


WebSetProxyAutoConfigFile Function

Action

Specifies the location of a PAC (Proxy Auto-Configuration) file.

Include file

WebAPI.bdh

Syntax

WebSetProxyAutoConfigFile( in sProxyAutoConfig : string,
                           in bCachedLookups   : boolean optional );
Parameter | Description
sProxyAutoConfig | Specifies the location of the PAC file. This may be a Web URL like http://localhost:81/proxy.pac or it may be a file location like K:\temp\proxy.pac. Specify null to reset this setting.
bCachedLookups | "True" uses the cached proxy for reoccurring sites. "False" (default) always executes the proxy auto-config lookup.
Parent topic: Browser Settings


WebSetProxyAuth Function

Action

Sets the password for proxy authentication login. Use empty strings or NULL values to disable proxy authentication.

Note: This function overrides the corresponding setting in the Simulation tab of the Profile Settings - Web dialog.

Include file

WebAPI.bdh

Syntax

WebSetProxyAuth( in sUsername     : string allownull,
                 in sPassword     : string optional,
                 in sProxy        : string optional,
                 in bReactiveOnly : boolean optional): boolean;

Return value

  • true if successful

  • false otherwise

Parameter | Description
sUsername | User name for proxy authentication. This parameter may be NULL.
sPassword | Password for proxy authentication. This parameter may be NULL (optional).
sProxy | Proxy for which the username and password should be set (optional). If this parameter is omitted the username and password will be used for authentication after the next 407 response from the server.
bReactiveOnly | If this parameter is set to true (default is false; optional), the user and password pair can only be used in a reaction to a 407 response from the server.

Calling this function inserts the username/password pair into the authentication database used when a server requests proxy authentication (code 407). On subsequent requests, the authentication header line will be added to the request headers automatically.

  • To set the default username password, call WebSetUserAuth("user1", "pass1");

  • To delete the default username/password, call WebSetUserAuth("", ""); This does not remove the entry from the authentication database.

  • To remove all cached authentication entries from the cookie database, call WebSetUserAuth(NULL, NULL);

  • In addition, you can add authentication entries directly to the authentication database by providing a protection space and the realm. For example, WebSetUserAuth("BasicAuthUser", "BasicAuthPass", "proxy", false);

Example

dcltrans
  transaction TWebInit
  begin
    // Set up proxy connection using the WebSetting commands
    WebSetProxy(WEB_PROXY_HTTP, "proxy.mydomain.com", 80);
    WebSetProxyBypass(FALSE, NULL);     // Set password used for authentication
    WebSetProxyAuth("proxyuser", "proxypass", "proxy:80");
    WebSetProxyAuth("proxyusersecure", "proxypasssecure", "proxy:443");
  end TWebInit;

Sample scripts

WebAuth01.bdf

Parent topic: Browser Settings
Related reference
WebSetProxy Function
WebSetProxyAuthBasic Function
WebSetProxyAuthNtlm Function
WebSetUserAuth Function
WebSetUserAuthBasic Function
WebSetUserAuthNtlm Function
WebSetUserAuthDigest Function


WebSetProxyAuthBasic Function

Action

Sets the password for basic proxy authentication login. Use empty strings or NULL values to disable proxy authentication.

Note: This function overrides the corresponding setting in the Simulation tab of the Profile Settings - Web dialog. In contrary to the WebSetProxyAuth function it does not change the credentials for a NTLM/Kerberos user authentication.

Include file

WebAPI.bdh

Syntax

WebSetProxyAuthBasic( in sUsername     : string allownull,
                      in sPassword     : string optional,
                      in sProxy        : string optional,
                      in bReactiveOnly : boolean optional): boolean;

Return value

  • true if successful

  • false otherwise

Parameter | Description
sUsername | User name for proxy authentication. This parameter may be NULL.
sPassword | Password for proxy authentication (optional).
sProxy | Proxy for which the username and password should be set (optional). If this parameter is omitted the username and password will be used for authentication after the next 407 response from the server.
bReactiveOnly | If this parameter is set to true (optional; default is false), the user and password pair can only be used in a reaction to a 407 response from the server.

Calling this function inserts the username/password pair into the authentication database used when a server requests proxy authentication (code 407). On subsequent requests, the authentication header line will be added to the request headers automatically.

  • To set the default username password, call WebSetProxyAuthBasic("user1", "pass1");

  • To delete the default username/password, call WebSetProxyAuthBasic("", ""); This does not remove the entry from the authentication database.

  • To remove all cached authentication entries from the cookie database, call WebSetUse WebSetProxyAuthBasic rAuth(NULL);

  • In addition, you can add authentication entries directly to the authentication database by providing a protection space and the realm. For example, WebSetProxyAuthBasic ("BasicAuthUser", "BasicAuthPass", "proxy", false);

Example

dcltrans
  transaction TWebInit
  begin
    // Set up proxy connection using the WebSetting commands
    WebSetProxy(WEB_PROXY_HTTP, "proxy.mydomain.com", 80);
    WebSetProxyBypass(FALSE, NULL);

    // Set password used for authentication
    WebSetProxyAuthBasic("proxyuser", "proxypass", "proxy:80");
    WebSetProxyAuthBasic("proxyusersecure", "proxypasssecure",
  "proxy:443");
  end TWebInit;
Parent topic: Browser Settings
Related reference
WebSetProxyAuth Function
WebSetProxyAuthNtlm Function
WebSetUserAuth Function
WebSetUserAuthBasic Function
WebSetUserAuthNtlm Function
WebSetUserAuthDigest Function


WebSetProxyAuthNtlm Function

Action

Sets the password for NTLM/Kerberos proxy authentication. In contrary to the WebSetProxyAuth function it does not change the credentials for basic proxy authentication.

Include file

WebAPI.bdh

Syntax

WebSetProxyAuthNtlm( in sUsername : string,
                     in sPassword : string ): boolean;

Return value

  • true if successful

  • false otherwise

Parameter | Description
sUsername | User name for proxy authentication. If you have to specify a domain use the notation: "domain\\user".
sPassword | Password for proxy authentication.

To reset the username and password to the default (logged on user), call WebSetProxyAuthNTLM("","");

Example

dcltrans
  transaction TWebInit
  begin
    // Set up proxy connection using the WebSetting commands
    WebSetProxy(WEB_PROXY_HTTP, "lab1", 80);
    WebSetProxyBypass(FALSE, NULL);

    // Set password used for authentication
    WebSetProxyAuthNtlm("testlab\\admin", "pass");
    WebSetProxyAuthNtlm("", "");
  end TWebInit;
Parent topic: Browser Settings
Related reference
WebSetProxyAuth Function
WebSetProxyAuthBasic Function
WebSetUserAuth Function
WebSetUserAuthBasic Function
WebSetUserAuthNtlm Function
WebSetUserAuthDigest Function


WebSetProxyBypass Function

Action

Sets the names of hosts not be accessed through a proxy.

Include file

WebAPI.bdh

Syntax

WebSetProxyBypass( in bBypassLocal : boolean,
                   in sBypass      : string optional ): boolean;

Return value

  • true if successful

  • false otherwise

Parameter | Description
bBypassLocal | If this parameter is set to true, the low-level web functions bypass proxies to hosts that do not contain a period in their names
sBypass | Optional list of host names or IP addresses, or both, that should not be routed through the proxy (optional). The host names are separated by blanks. The list can contain wildcards. This parameter may be NULL if not needed.

Example

dcltrans
  transaction TWebInit
  begin
    // Set up proxy connection using the WebSetting commands
    WebSetProxy(WEB_PROXY_HTTP, "proxy.mydomain.com", 80);
    WebSetProxyBypass(FALSE);

    // Set password used for authentication
    WebSetProxyAuth("proxyuser", "proxypass");
  end TWebInit;
Parent topic: Browser Settings
Related reference
WebGetProxyBypass Function


WebGetProxyBypass Function

Action

Gets the names of hosts not to be accessed through a proxy.

Include file

WebAPI.bdh

Syntax

WebGetProxyBypass( out sProxyBypass    : string,
                   in  nMaxProxyBypass : number optional ): boolean;

Return value

  • true if successful

  • false otherwise

Parameter | Description
sProxyBypass | String variable that receives the list of proxy bypasses set.
nMaxProxyBypass | Maximum number of characters to put into the string variable sProxyBypass (optional). This number must be smaller than or equal to the string buffer size of sProxyBypass.

Example

dcltrans
  transaction TWebInit
  var
    sProxyBypassList: string;
  begin
    WebGetProxyBypass(sProxyBypassList);
    write("ProxyBypassList: "); write(sProxyBypassList);writeln;
  end TWebInit;
Parent topic: Browser Settings
Related reference
WebSetProxyBypass Function


WebSetUserAgent Function

Action

Sets the HTTP/HTTPS user agent and overrides those of the workbench.

Include file

WebAPI.bdh

Syntax

WebSetUserAgent(in sUserAgent: string): boolean;

Return value

  • true if successful

  • false otherwise

Parameter | Description
sUserAgent | Contains the string to be used with the User-Agent header

Example

dcltrans
  transaction TWebInit
  begin
    WebSetUserAgent("CustomClient 1.0");
    WebDumpSettings();
  end TWebInit;
Parent topic: Browser Settings
Related reference
WebGetUserAgent Function


WebGetUserAgent Function

Action

Gets the current value of the HTTP/HTTPS user agent.

Include file

WebAPI.bdh

Syntax

WebGetUserAgent( out sUserAgent : string,
                 in  nMaxLen    : number optional ): boolean;

Return value

  • true if successful

  • false otherwise

Parameter | Description
sUserAgent | A string buffer that will receive the current name of user agent.
nMaxLen | The maximum length of the receive buffer sUserAgent (optional).

Example

dcltrans
  transaction TWebInit
  var
    sUserAgent: string;
  begin
    WebGetUserAgent(sUserAgent);
    write("HttpUserAgent: "); write(sUserAgent); writeln;
  end TWebInit;
Parent topic: Browser Settings
Related reference
WebSetUserAgent Function


Low-Level Web Functions

  • Low-Level Web Functions Overview
    Silk Performer’s low-level web functions provide an easy, high-level method for communicating with a Web server.
  • Low-Level Web Function Replay Timing
    When low-level web traffic is recorded using the recorder, a wait time is included at the end of recorded functions to tell the replay engine how long to wait before executing the next function in the script.
  • WebUrl Function
    Requests and reads a complete document specified by a URL using FTP or HTTP.
  • WebUrlDelete Function
    Sends a DELETE request to the HTTP/1.1 server.
  • WebUrlHead Function
    Sends a HEAD request to the server.
  • WebUrlOptions Function
    Sends an OPTIONS request to the HTTP/1.1 server.
  • WebUrlPostBin Function
    Posts binary data to the Web server by means of the HTTP POST method.
  • WebUrlPutBin Function
    Sends binary data to the Web server by means of the HTTP PUT method.
  • WebUrlPostFile Function
    Posts binary data, stored in a file, to the Web server by means of the HTTP POST method.
  • WebUrlTrace Function
    Sends a TRACE request to the HTTP/1.1 server.
  • WebFileUpload Function
    Posts the content of a Web form, including specified files, to the Web server by means of the HTTP POST method.
  • WebFileUploadEx Function
    Uploads a file to the web server.
  • WebHeaderAdd Function
    Adds a custom HTTP header to the next WebUrl* or WebForm* function
  • WebAddImageCoordinates Function
    When a URL is submitted due to a server side image map request (ISMAP), this function adds the necessary pair of coordinates to the URL.
  • WebUrlBeginPage Function
    Marks the beginning of a page that is loaded by low-level web functions.
  • WebUrlEndPage Function
    Marks the end of a page that is loaded by low-level web functions.
  • WebFormBuild Function
    This function composes URL-encoded form strings similar to those specified in the dclform section.
  • WebFormClear Function
    Removes all entries from a Web form declared in the dclform section.
  • WebFormReset Function
    Resets a Web form as declared in the dclform section.
  • WebFormExpand Function
    This function converts forms specified in the dclform section to URL-encoded form strings.
  • WebFormGet Function
    Evaluates new values for the random variables (if specified in dclrand below) and sends the form content to the Web server.
  • WebFormHead Function
    Evaluates new values for the random variables and sends the form content to the Web server.
  • WebFormPost Function
    Posts the content of a Web form to the Web server by means of the HTTP POST method.
  • WebFormPostBin Function
    Posts binary data to the Web server by means of the HTTP POST method.
  • WebFormPostFile Function
    Posts binary data to the Web server by means of the HTTP POST method.
  • WebFormPostEx Function
    Posts the contents of two forms to the Web server by means of the HTTP POST method.
  • WebFormValuePairInsert Function
    Inserts a new pair of values into a Web form declared in the dclform section.
  • WebFormValuePairRemove Function
    Removes a number of pairs of values from a Web form declared in the dclform section.
  • WebFormValueSet Function
    Sets the left-side and/or the right-side value of a Web form entry.
  • WebFormValueGet Function
    Retrieves the left-side and/or the right-side value of a Web form entry.
  • WebCustomRequest Function
  • WebCustomRequestBin Function
  • WebCustomRequestFile Function
    Requests and reads a complete document specified by a URL using the specified HTTP method.
  • WebSetEncoding Function
    Compresses the data of the next WebUrl* or WebPage* function with the gzip or zlib (deflate) algorithm.
  • WebAddMultiPart Function
    When WebAddMultiPart or WebAddMultiPartFromeFile is called, the passed data is stored in lists. When WebPostMultiPart is called, these lists are then merged with a unique boundary and transferred to the server using WebUrlPostBin.
  • WebAddMultiPartFromFile Function
    When WebAddMultiPart or WebAddMultiPartFromeFile is called, the passed data is stored in lists. When WebPostMultiPart is called, these lists are then merged with a unique boundary and transferred to the server using WebUrlPostBin.
  • WebPostMultiPart Function
    When WebAddMultiPart or WebAddMultiPartFromeFile is called, the passed data is stored in lists. When WebPostMultiPart is called, these lists are then merged with a unique boundary and transferred to the server using WebUrlPostBin.
Parent topic: Web Functions Reference
Related reference
Web Form Declarations


Low-Level Web Functions Overview

Silk Performer’s low-level web functions provide an easy, high-level method for communicating with a Web server. Each low-level web call results in sending a request and waiting for a response.

Low-level web functions can be used synchronously or asynchronously. Set the thread limitation value (see WebSetMaxThreads function) to 1 for synchronous operation.

Formatting URLs

Silk Performer’s low-level web functions rely heavily on the use of URLs. The format of all URLs must follow accepted syntax and semantics in order to access resources via the Web. Canonicalization is the process of formatting a URL to follow this accepted syntax and semantics. Characters that must be encoded include any characters that have no corresponding graphic character in the US ASCII coded character set (i.e., hexadecimal 80-FF, which are not used in the US-ASCII coded character set, and hexadecimal 00-1F and 7F, which are control characters), blank spaces, "%" (which is used to encode other characters) and unsafe characters (<, >, ", #, {, }, |, \, ^, ~, [, ], and ').

Printable ASCII characters being URL encoded % ? # [ ] { } | \ & = @ : ^ ~ ' ` " $ + ! * ' ( ) , < >

Form submissions

Forms declared in the dclform section are combined and URL encoded prior to submission.

Example

dclform
  SAMPLE1:
    "leftval1" := "rightval1",
    "leftval2" := "",
    ""         := "rightval3",
    "encoded"  := "unsafe @ characters";

will be sent as part of URLs

WebUrl("http://www.host.com/cgi/sample?leftval1=rightval1&"
"leftval2=&rightval3&encoded=unsafe+%40+characters");

or as POST body:

"leftval1=rightval1&leftval2=&rightval3&encoded=unsafe+%40+characters"
Parent topic: Low-Level Web Functions
Related concepts
Handling Uniform Resource Locators (URLs)
Low-Level Web Function Replay Timing
Parsing Functions
Cookie Database Functions Overview
Related reference
SSL (Secure Socket Layer) Extensions
WebSetMaxThreads Function
WebHeaderAdd Function
WebThreadWait Function


Low-Level Web Function Replay Timing

When low-level web traffic is recorded using the recorder, a wait time is included at the end of recorded functions to tell the replay engine how long to wait before executing the next function in the script. The use of wait times simulates slow connections and user wait times in order to help provide more realistic tests.

The wait time appended to a recorded function is the time elapsed between the execution of the current function and the execution of the next function. The implication of this behaviour is that low-level web functions with the wait parameter set to zero are executed in parallel up to the configured maximum number of concurrent threads (WebSetMaxThreads). A low-level web function with the wait parameter set to >0 makes the virtual user pause for the specified wait time. When the specified time has elapsed, the virtual user continues executing the script.

Note: The wait time is always zero in Stress Test mode, regardless of the values specified in the low-level web functions.
Parent topic: Low-Level Web Functions
Related reference
WebFormPost Function


WebUrl Function

Action

Requests and reads a complete document specified by a URL using FTP or HTTP. Use localhost if you want to connect to the local server.

Include file

WebAPI.bdh

Syntax

WebUrl( in sUrl  : string,
        in fWait : float optional ): boolean;

Return value

  • true if the worker thread communicating with the server could be started successfully

  • false otherwise. The return value will not inform about any Web traffic-related problems due to independent threaded operation.

Parameter | Description
sUrl | Complete URL to the file on the server
fWait | Minimum time or minimum mean time that this function call has to last (optional). Default value is 0.0

Example

dcltrans
  transaction TMain
  var
   fMyWait : float init 5.0;
  begin
    WebUrl("http://www.myserver.com/index.html", 0.0);
    WebUrl("http://user:pass@www.myserver.com/index.html", 50.0);
    WebUrl("http://www.myserver.com:80/", 0.5);
    WebUrl("ftp://user:pass@ftp.myserver.com:21", fMyWait);
  end TMain;

Sample scripts

WebAuth01.bdf, WebCookie01.bdf, WebEncoding01.bdf, WebForms01.bdf, WebForms03.bdf, WebHello.bdf, WebHttp11.bdf, WebHttpHeaders01.bdf, WebIncreasingWorkload.bdf, WebMeasure01.bdf, WebMulti01.bdf, WebMultiClientIpAddresses01.bdf, WebParseResponseHeader01.bdf, WebRegularExpressions01.bdf, WebSecure02.bdf, WebStatusCodes01.bdf, WebStone01.bdf, WebTimer01.bdf, WebUrl01.bdf

SilkEssential sample

Ftp.sep

Parent topic: Low-Level Web Functions
Related concepts
Handling Uniform Resource Locators (URLs)


WebUrlDelete Function

Action

Sends a DELETE request to the HTTP/1.1 server. The DELETE method requests that the origin server delete the resource identified by the Request-URI. A successful response SHOULD be 200 (OK) if the response includes an entity describing the status, 202 (Accepted) if the action has not yet been enacted, or 204 (No Content) if the response is OK but does not include an entity.

Include file

WebAPI.bdh

Syntax

WebUrlDelete( in sUrl  : string,
              in fWait : float optional): boolean;

Return value

  • true if the worker thread communicating with the server could be started successfully

  • false otherwise

Parameter | Description
sUrl | Complete URL to the file on the server
fWait | Minimum time or minimum mean time that this function call has to last (optional). Default value is 0.0

Example

dcltrans
transaction TWebHttp11
  begin
    // To have a resource we can delete, we first have to
    // upload a test file to the server.
    // Note that you will need write permissions
    WebUrlPutBin("http://standardhost/test.html","1234567890", 10, "text/txt", 0.0);
    // And now let’s delete it again:
    WebUrlDelete("http://standardhost/test.html", 0.0);
  end TWebHttp11;

Sample scripts

WebHttp11.bdf

Parent topic: Low-Level Web Functions
Related concepts
Handling Uniform Resource Locators (URLs)


WebUrlHead Function

Action

Sends a HEAD request to the server. The server will send no data but a response message.

Include file

WebAPI.bdh

Syntax

WebUrlHead( in sUrl  : string,
            in fWait : float optional): boolean;

Return value

  • true if the worker thread communicating with the server could be started successfully

  • false otherwise. The return value will not inform about any Web traffic-related problems due to independent threaded operation.

Parameter | Description
sUrl | Complete URL to the file on the server
fWait | Minimum time or minimum mean time that this function call has to last (optional). Default value is 0.0

Example

dcltrans
  transaction TMain
  begin
    WebUrlHead("http://www.myserver.com/index.html", 0.0);
  end TMain;
Parent topic: Low-Level Web Functions
Related concepts
Handling Uniform Resource Locators (URLs)


WebUrlOptions Function

Action

Sends an OPTIONS request to the HTTP/1.1 server. The OPTIONS method represents a request for information about the communication options available on the request/response chain identified by the Request-URI. This method allows the client to determine the options and/or requirements associated with a resource or the capabilities of a server without implying a resource action or initiating a resource retrieval. If the Request-URI is an asterisk ("*"), the OPTIONS request is intended to apply to the server as a whole. An "OPTIONS *" request can be applied through a proxy by specifying the destination server in the Request-URI without any path information.

Include file

WebAPI.bdh

Syntax

WebUrlOptions( in sUrl  : string,
               in fWait : float optional): boolean;

Return value

  • true if the worker thread communicating with the server could be started successfully

  • false otherwise

Parameter | Description
sUrl | Complete URL to the file on the server
fWait | Minimum time or minimum mean time that this function call has to last (optional). Default value is 0.0

Example

dcltrans
  transaction TWebGetOptions
  begin
    WebUrlOptions("http://standardhost/*", 0.0);
  end TWebGetOptions;

Sample scripts

WebHttp11.bdf

Parent topic: Low-Level Web Functions
Related concepts
Handling Uniform Resource Locators (URLs)


WebUrlPostBin Function

Action

Posts binary data to the Web server by means of the HTTP POST method. Instead of ASCII-encoded content, binary data may be sent using this post function. The Content-Length header will automatically be added to the request. The appropriate Content-Type has to be specified. In order to send binary data (octets) more safely over the Internet, use the WebBase64Encode to convert the data to 6-bit ASCII characters.

Include file

WebAPI.bdh

Syntax

WebUrlPostBin( in sUrl         : string,
               in sData        : string,
               in nDataLen     : number,
               in sContentType : string,
               in fWait        : float optional ): boolean;

Return value

  • true if the worker thread posting the form content to the server could be started successfully

  • false otherwise

Parameter | Description
sUrl | Complete URL to the file on the server
sData | Data to post to the server. This may be binary data. For posting all available binary data specify STRING_COMPLETE for nDataLength and use the bin() operator for sData (see example).
nDataLen | Length in bytes of data contained in the buffer sData. Specify STRING_COMPLETE or omit this parameter to post all available data
sContentType | Content type string used in the request, for example, "image/gif"
fWait | Minimum time or minimum mean time that this function call has to last (optional). Default value is 0.0

Example

dcltrans
  transaction TWebFormPostBin
  var
    sBase64Encoded : string;
    nLen           : number;
    sData          : string;
  begin
    WebBase64Encode(sBase64Encoded, sizeof(sBase64Encoded), nLen,
      "name=Harry Smith&address=Elkenney Str. 26"
      "&phone=+43223344", 57);
    WebUrlPostBin("http://standardhost/data2html.asp", sBase64Encoded,
      STRING_COMPLETE, "text/html");
    WebUrlPostBin("http://standardhost/data2html.asp",
      bin(sData), STRING_COMPLETE, "application/octet-stream");
  end TWebFormPostBin;

Sample scripts

WebFileUpload01.bdf, WebForms02.bdf, WebPost01.bdf

Parent topic: Low-Level Web Functions
Related concepts
Handling Uniform Resource Locators (URLs)
Related reference
WebBase64Encode Function
WebUrlPostFile Function


WebUrlPutBin Function

Action

Sends binary data to the Web server by means of the HTTP PUT method. Instead of ASCII-encoded content, binary data may be sent using this function. The Content-Length header will automatically be added to the request. The appropriate Content-Type has to be specified. In order to send binary data (octets) more safely over the Internet, use the WebBase64Encode to convert the data to 6-bit ASCII characters.

Include file

WebAPI.bdh

Syntax

WebUrlPutBin( in sUrl     : string,
              in sData    : string,
              in nDataLen : number,
              in sContent : string,
              in fWait    : float optional): boolean;

Return value

  • true if the worker thread posting the form content to the server could be started successfully

  • false otherwise

Parameter | Description
sUrl | Complete URL to the file on the server
sData | Data to post to the server. This may be also binary data. For posting all available binary data specify STRING_COMPLETE for nDataLength and use the bin() operator for sData (see example).
nDataLen | Length in bytes of data contained in the buffer sData. Specify STRING_COMPLETE or omit this parameter to post all available data.
sContent | Content type string used in the request, for example "image/gif"
fWait | Minimum time or minimum mean time that this function call has to last (optional). Default value is 0.0

Example

dcltrans
  transaction TWebHttp11
   var
    sData : string;
  begin
    WebUrlTrace("http://standardhost/index.html", 0.0);
    // To have a resource we can delete, we first have to
    // upload a test file to the server.
    // Note that you will need write permissions
    WebUrlPutBin("http://standardhost/test.html",
      "1234567890", STRING_COMPLETE, "text/txt", 0.0);
    sData := "\h00010203040506070809101112131415";
    WebUrlPutBin("http://standardhost/test.html",
                 bin(sData), STRING_COMPLETE, "application/octet-stream", 0.0);
    // And now let’s delete it again.
    WebUrlDelete("http://standardhost/test.html", 0.0);
    WebUrlOptions("http://standardhost/*", 0.0);
  end TWebHttp11;

Sample scripts

WebHttp11.bdf

Parent topic: Low-Level Web Functions
Related concepts
Handling Uniform Resource Locators (URLs)
Related reference
WebBase64Encode Function


WebUrlPostFile Function

Action

Posts binary data, stored in a file, to the Web server by means of the HTTP POST method. Instead of ASCII-encoded content, binary data may be sent using this post function. The Content-Length header will automatically be added to the request. The appropriate Content-Type has to be specified.

Include file

WebAPI.bdh

Syntax

WebUrlPostFile( in sUrl         : string,
                in sFile        : string,
                in sContentType : string,
                in fWait        : float optional ): boolean;

Return value

  • true if successful

  • false otherwise

Parameter | Description
sUrl | Complete URL to the file on the server.
sFile | File containing the data, which should be posted to the server.
sContentType | Content type string used in the request, for example, "image/gif".
fWait | Minimum time or minimum mean time that this function call has to last (optional). Default value is 0.0.

Example

dcltrans
  transaction TWeb
  var
    sFile : string;
  begin
    sFile := "c:\\temp\\dummyfile.txt";
    WebUrlPostFile("http://standardhost/data2html.asp", sFile, "text/plain");
  end TWeb;
Parent topic: Low-Level Web Functions


WebUrlTrace Function

Action

Sends a TRACE request to the HTTP/1.1 server. The TRACE method is used to invoke a remote, application-layer loopback of the request message. The final recipient of the request SHOULD reflect the message received back to the client as the entity-body of a 200 (OK) response. Use of the Max-Forwards header field allows the client to limit the length of the request chain; this is useful for testing a chain of proxies forwarding messages in an infinite loop. If successful, the response SHOULD contain the entire request message in the entity body, with a Content-Type of "message/http".

Include file

WebAPI.bdh

Syntax

WebUrlTrace(
  in sUrl : string,
  in fWait : float optional): boolean;

Return value

  • true if the worker thread communicating with the server could be started successfully

  • false otherwise

Parameter | Description
sUrl | Complete URL to the file on the server
fWait | Minimum time or minimum mean time that this function call has to last (optional). Default value is 0.0

Example

dcltrans
  transaction TWebHttp11
  begin
    WebUrlTrace("http://standardhost/index.html", 0.0);
  end TWebHttp11;
Parent topic: Low-Level Web Functions
Related concepts
Handling Uniform Resource Locators (URLs)


WebFileUpload Function

Action

Posts the content of a Web form, including specified files, to the Web server by means of the HTTP POST method. This function implements a RFC1867-compliant file upload function for form-based file upload in HTML.

This is a mapping to WebUrlPostBin, and uses a form specified in the dclform section to construct the data to post to the server.

The form consists of name-value pairs as usual, only the files to upload need a minor modification: a file to upload needs to be specified by a name-value pair in the following way:

"filename" := "<name of the input tag>;<file name>;<content type>";

Example: upload of file c:\test.txt

HTML code:

<form enctype="multipart/form-data" action="data2html.asp" method=post>
  <input type="text" name="anyname" value="anyvalue">
  <input size="32" name="my_file" type="file">
  <input type="submit" value="Upload">
</form>

BDL form:

"anyname"  := "anyvalue",
"filename" := "my_file;C:\\test.txt;plain/text";

Include file

WebAPI.bdh

Syntax

WebFileUpload( in sUrl     : string,
               in formBody : form,
               in fWait    : float optional ): boolean;

Return value

  • true if successful

  • false otherwise

Parameter | Description
sUrl | Complete URL to the file on the server
formBody | Form identifier used in the dclform section (see example below). The expanded form is added to the body of the request. The Content-Length is added automatically. The Content-Type is multipart/form-data.
fWait | Minimum time or minimum mean time that this function call has to last (optional). Default value is 0.0

Example

dcltrans
  transaction TWebFileUpload
  begin
    WebFileUpload("http://standardhost/data2html.asp", FILE_UPLOAD_FORM);
  end TWebFileUpload;

dclform
FILE_UPLOAD_FORM:
  "anyname"  := "anyvalue",
  "filename" := "my_file;C:\\temp\\test.doc;application/msword";
Parent topic: Low-Level Web Functions
Related reference
WebUrlPostBin Function


WebFileUploadEx Function

Action

Uploads a file to the web server. This function implements a RFC1867-compliant file upload function for form-based file upload in HTML.

WebFileUploadEx automatically recognizes a multipart form and a file upload. When uploading a file during recording, the Silk Performer Recorder automatically scripts the respective function and the uploaded file is added to the data files.

A file that is to be uploaded must be specified by a name-value pair in the following way:
"filename" := "<name of the input tag>;<file name>;<content type>";

Include file

WebAPI.bdh

Syntax

WebFileUploadEx( in sUrl  : string,
                 formUrl  : form,
                 formBody : form,
                 in fWait : double optional ): boolean;

Return value

  • true if the file is found and submitted successfully

  • false otherwise

Parameter | Description
sUrl | Complete URL to the file on the server
formUrl | Form identifier used in the dclform section (see example below). The expanded form is added to the URL after the "?".
formBody | Form identifier used in the dclform section (see example below). The expanded form is added to the body of the request. The Content-Length and Content-Type header are added automatically.
fWait | Minimum time or minimum mean time that this function call has to last (optional). Default value is 0.0

Example

The form content in the dclform section is represented in an unencoded format to enhance readability and customizability. The data gets URL encoded on file upload. There are two possibilities to send data unencoded:

  • Add the query string as it should be sent to the server directly to the URL, for example, "http://www.comp.com/cgi/special?<don't>;[encode]/this". Note that blanks are encoded when this method is used.
  • Use WebUrlPostBin or WebFormPostBin to post data as provided to the Web server.
dcltrans
  transaction TWebFileUpload
  begin
    WebFileUploadEx("http://standardhost/data2html.asp", URL_FORM, FILE_UPLOAD_FORM);
  end TWebFileUpload;

dclform
URL_FORM:
  "ID" := "1234";
FILE_UPLOAD_FORM:
  "anyname"  := "anyvalue",
  "filename" := "my_file;C:\\temp\\test.doc;application/msword";
Parent topic: Low-Level Web Functions


WebHeaderAdd Function

Action

Adds a custom HTTP header to the next WebUrl* or WebForm* function. This also enables replacing standard headers, like the default POST encoding type "Content-Type: application/x-www-form-urlencoded", with a custom encoding type. You can add up to 128 headers per request by calling this function repeatedly.

Include file

WebAPI.bdh

Syntax

WebHeaderAdd( in sName  : string,
              in sValue : string ): boolean;

Return value

  • true if the header information was accepted

  • false otherwise

Parameter | Description
sName | Name of the HTTP header
sValue | Value string of this header

Example

dcltrans
  transaction TWebOwnAuthHeader
  var
    sUserPass    : string(200);
    nUserPassLen : number;
  begin
    // Build your own authentication header
    WebBase64Encode(sUserPass, 200, nUserPassLen,
                    "smith:paranoia{}[]~^",
    Strlen("smith:paranoia{}[]~^"));
    sUserPass := "Basic " + sUserPass;
    WebHeaderAdd("Authorization", sUserPass);
    WebUrl("http://standardhost/", 0.0);
  end TWebOwnAuthHeader;

Sample scripts

WebEncoding01.bdf, WebHttpHeaders01.bdf

Parent topic: Low-Level Web Functions


WebAddImageCoordinates Function

Action

When a URL is submitted due to a server side image map request (ISMAP), this function adds the necessary pair of coordinates to the URL. After all query parameters are added, those coordinates are then added to the subsequent Web function call.

Include file

WebAPI.bdh

Syntax

WebAddImageCoordinates(in sCoordinates: string);
Parameter | Description
sCoordinates | Coordinates that you want to add to the URL.

Example

dcltrans
  transaction TMain
  begin
    WebPageUrl("http://standardhost");
    WebAddImageCoordinates("?172,79");
    WebPageLink("Click here");
  end TMain;
Parent topic: Low-Level Web Functions


WebUrlBeginPage Function

Action

Marks the beginning of a page that is loaded by low-level web functions. It waits for all running threads (WebThreadWait) and starts a page timer. The next WebUrlBeginPage or WebUrlEndPage function call with a different timer name or without a timer name stops the timer.

This function is generated by the Recorder if the automatic page detection option is selected in the Recording tab of the Web category in the Profile Settings dialog.

Include file

WebAPI.bdh

Syntax

WebUrlBeginPage(in sTimer: string optional): boolean;

Return value

  • true if successful

  • false otherwise

Parameter | Description
sTimer | Name of the timer for page measurements (optional). If this parameter is omitted, no measurements are performed.

Example

dcltrans
  transaction TMain
  begin
    WebUrlBeginPage("ShopIt");
    WebUrl("http://lab3/shopit/banner.gif");
    WebFormPost("http://lab3/shopit/product.asp", SHOPIT_PRODUCT_ASP002);
    WebUrl("http://lab3/shopit/pic.gif");
    WebUrlEndPage();
  end TMain;
dclform
  SHOPIT_PRODUCT_ASP002:
    "code" := "2";
Parent topic: Low-Level Web Functions
Related reference
WebUrlEndPage Function


WebUrlEndPage Function

Action

Marks the end of a page that is loaded by low-level web functions. It waits for all running threads (WebThreadWait) and stops the page timer.

This function is generated by the Recorder if the automatic page detection option is selected in the Recording tab of the Web category in the Profile Settings dialog.

Include file

WebAPI.bdh

Syntax

WebUrlEndPage(): boolean;

Return value

  • true if successful

  • false otherwise

Example

dcltrans
  transaction TMain
  begin
    WebUrlBeginPage("ShopIt");
    WebUrl("http://lab3/shopit/banner.gif");
    WebFormPost("http://lab3/shopit/product.asp", SHOPIT_PRODUCT_ASP002);
    WebUrl("http://lab3/shopit/pic.gif");
    WebUrlEndPage();
  end TMain;
dclform
SHOPIT_PRODUCT_ASP002:"code" := "2";
Parent topic: Low-Level Web Functions
Related reference
WebUrlBeginPage Function


WebFormBuild Function

Action

This function composes URL-encoded form strings similar to those specified in the dclform section. The resulting string is commonly used to add parameters to URLs or to build up messages to be sent with WebUrlPostBin.

WebFormBuild appends a pair of sLeftVal "=" sRightVal at the end of sForm. If sForm is NULL when calling WebFormBuild, "&" is added before adding the pair of sLeftVal "=" sRightVal to the result of the previous call.

Include file

WebAPI.bdh

Syntax

WebFormBuild( out   sForm       : string allownull,
              inout nMaxFormLen : number,
              in    sLeftVal    : string allownull,
              in    sRightVal   : string allownull ): boolean;

Return value

  • true if the form is generated successfully

  • false otherwise

Parameter | Description
sForm | Target string to be filled; NULL value allowed
nMaxFormLen | Variable containing the maximum length of target string. On return it will contain the current length of the string written to sTarget.
sLeftVal | Left value of form parameter, which may be NULL
sRightVal | Right value of form parameter, which may be NULL
Note: For the first call of WebFormBuild, sForm must be initialized with the string to be added and nMaxFormLen must be initialized with the maximum length of the buffer of sForm. For subsequent calls, sForm must be NULL.

  • If sLeftVal/sRightVal is not NULL and not empty, it is encoded using the function StrFormEscape.

  • If sLeftVal is NULL or empty, only sRightVal is added to sForm.

  • Is sRightVal is NULL or empty, sLeftVal and "=" is added to sForm.

Example

dcltrans
  transaction TWebFormBuild
  var
    sForm     : string(1000);
    nFormSize : number;
    bOk       : boolean;
  begin
    sForm     := "http://www.MyCompany.com?";
    nFormSize := sizeof(sForm);

    bOk := WebFormBuild(sForm, nFormSize, "country", "USA");
    bOk := WebFormBuild(NULL, nFormSize, "jack@datz.com", NULL);
    bOk := WebFormBuild(NULL, nFormSize, NULL, "46&kj%= jd");

    WebUrl(sForm);
    write("form = "); write(sForm); writeln;
    sForm := ""; nFormSize := sizeof(sForm);

    bOk := WebFormBuild(sForm, nFormSize, "TestLeftVal", "TestRightVal");

    WebUrlPostBin("http://www.company.com", sForm,
                  nFormSize, "text/html");
    write("form = "); write(sForm); writeln;
  end TWebFormBuild;

Output

form = http://www%2EMyCompany%2Ecom?country=USA&
jack%40datz%2Ecom=&46%26kj%25%3D+jd
form = TestLeftVal=TestRightVal

Sample scripts

WebForms03.bdf

Parent topic: Low-Level Web Functions


WebFormClear Function

Action

Removes all entries from a Web form declared in the dclform section. This function can be used to dynamically modify the content of a Web form.

Include file

WebAPI.bdh

Syntax

WebFormClear( inout fForm: form ): boolean;

Return value

  • true if successful

  • false otherwise

Parameter | Description
fForm | Web form whose entries will be removed

Example

dcltrans
  transaction TMain
  var
    sFirstName, sLastName, sPhone: string;
  begin
    WebFormValuePairInsert(fForm, "street", "Beach Road");
    WebFormValuePairInsert(fForm, "phone", "1212-555-8532");
    WebFormValueGet(fForm, sFirstName, sizeof(sFirstName),
      "first name");
    WebFormValueGet(fForm, sLastName, sizeof(sLastName), "last name");
    WebFormValueGet(fForm, sPhone, sizeof(sPhone), "phone");
    write("first name = "); write(sFirstName); writeln;
    write("last name = "); write(sLastName); writeln;
    write("phone = "); write(sPhone); writeln;
    WebFormValueSet(fForm, "phone", "1411-555-0969");
    WebFormValueGet(fForm, sPhone, sizeof(sPhone), "phone");
    write("phone = "); write(sPhone); writeln;
    WebFormValuePairRemove(fForm, "street");
    WebFormClear(fForm);
  end TMain;

  dclform
    fForm:
    "first name" := "Peter",
    "last name" := "Heart";

Sample scripts

WebForms04.bdf

Parent topic: Low-Level Web Functions
Related reference
WebFormValuePairInsert Function


WebFormReset Function

Action

Resets a Web form as declared in the dclform section. This function can be used to undo all dynamically made modifications.

Include file

WebAPI.bdh

Syntax

WebFormReset( inout fForm: form ): boolean;

Return value

  • true if successful

  • false otherwise

Parameter | Description
fForm | Web form whose content will be reset

Example

dcltrans
  transaction TMain
  var
    sFirstName, sLastName, sPhone: string;
  begin
    WebFormValuePairInsert(fForm, "street", "Beach Road");
    WebFormValuePairInsert(fForm, "phone", "1212-555-8532");
    WebFormValueSet(fForm, "last name", "Smith");
    WebFormValueGet(fForm, sFirstName, sizeof(sFirstName), "first name");
    WebFormValueGet(fForm, sLastName, sizeof(sLastName), "last name");
    WebFormValueGet(fForm, sPhone, sizeof(sPhone), "phone");
    write("first name = "); write(sFirstName); writeln;
    write("last name = "); write(sLastName); writeln;
    write("phone = "); write(sPhone); writeln;

    WebFormReset(fForm);

    WebFormValueGet(fForm, sFirstName, sizeof(sFirstName), "first name");
    WebFormValueGet(fForm, sLastName, sizeof(sLastName), "last name");
    WebFormValueGet(fForm, sPhone, sizeof(sPhone), "phone");
    write("first name = "); write(sFirstName); writeln;
    write("last name = "); write(sLastName); writeln;
    write("phone = "); write(sPhone); writeln;
  end TMain;

dclform
  fForm:
    "first name" := "Peter",
    "last name"  := "Heart";
Parent topic: Low-Level Web Functions
Related reference
WebFormClear Function
WebFormValuePairInsert Function
WebFormValuePairRemove Function
WebFormValueSet Function


WebFormExpand Function

Action

This function converts forms specified in the dclform section to URL-encoded form strings. The resulting string is commonly used to add parameters to URLs or to build up messages to be sent with WebUrlPostBin.

Include file

WebAPI.bdh

Syntax

WebFormExpand( in  fForm       : form,
               out sExpForm    : string,
               in  nMaxExpForm : number,
               in  bCalcRandom : boolean): boolean;

Return value

  • true if successful

  • false otherwise

Parameter | Description
fForm | Form declared in the dclform section.
sExpForm | String variable receiving the URL encoded form string.
nMaxExpForm | Length of the string receiving the URL encoded form string. If it is set to STRING_COMPLETE all available data is stored in sExpForm.
bCalcRandom | Specifies whether to calculate the random variables part of the form.

Example

dclrand
  nrPhone: RndUniN(5550000..5559999);

dcltrans
  transaction TMain
  var
    sForm : string(100);
    i : number;
  begin
    for i := 1 to 5 do
      // calculate new random values each time
      WebFormExpand(FORM_01, sForm, STRING_COMPLETE, true);
      write(sForm); writeln;
    end;

    // do not calculate new random values
    WebFormExpand(FORM_01, sForm, STRING_COMPLETE, false);
    write(sForm); writeln;
  end TMain;

dclform
  FORM_01:
    "name" := "John",
    "phone" := nrPhone;

Output

name=John&phone=5556872
name=John&phone=5558055
name=John&phone=5559284
name=John&phone=5558252
name=John&phone=5551969
name=John&phone=5551969

Sample scripts

WebForms04.bdf

Parent topic: Low-Level Web Functions


WebFormGet Function

Action

Sends the form content to the Web server. The form content is transformed into a single string that is appended to the URL. The URL defines the file to be retrieved from the Web server using the HTTP GET method. If the form includes a random variable, this function selects a new random value each time the form is posted.

Include file

WebAPI.bdh

Syntax

WebFormGet(
  in sUrl : string,
  in formUrl : form,
  in fWait : float optional): boolean;

Return value

  • true if the worker thread communicating with the server could be started successfully

  • false otherwise. The return value will not inform about any Web traffic-related problems due to independent threaded operation.

Parameter | Description
sUrl | Complete URL to the file on the server
formUrl | Form identifier used in the dclform section (see example below). The expanded form string is appended to the URL after the "?".
fWait | Minimum time or minimum mean time that this function call has to last (optional). Default value is 0.0

The form content in the dclform section is represented in an unencoded format to enhance readability and customizability. The data gets URL encoded on form submission. There are two possibilities to send data unencoded:

  • Add the query string as it should be sent to the server directly to the URL, for example, http://www.comp.com/cgi/special?dont encode blanks

  • Use WebUrlPostBin or WebFormPostBin to post data as provided to the Web server.

Example

var
  nWait : float;
  sName : string(100);
dclrand
  rnWait : RndExpF(5.0);
  rnPhone : RndStr("0123456789"; 16..16);
  rsAddress : RndFile("Address.rnd", 100);
  rsFName : RndFile("gfname.rnd", 20);
  rsLName : RndFile("glname.rnd", 20);
dcltrans
transaction TWebFormGet
begin
  // Get a random full name
  sName := rsFName + " " + rsLName;
  // and a random think time
  nWait := rnWait;
  WebFormGet("http://standardhost:2080/data2html.asp", FORM_01, nWait);
end TWebFormGet;
dclform
  FORM_01:
    "name" := sName,
    "address" := rsAddress,
    "phone" := rnPhone;

Sample scripts

WebForms01.bdf, WebForms03.bdf, WebForms04.bdf, WebMeasure01.bdf, WebMulti01.bdf, WebParseResponse01.bdf

Parent topic: Low-Level Web Functions
Related reference
WebFormUrlDecode Function
WebFormUrlEncode Function
WebUrlPostBin Function
WebFormPostBin Function


WebFormHead Function

Action

Sends the form content to the Web server. The form content is transformed into a single string that is appended to the URL. The URL defines the file to be retrieved from the Web server by means of the HTTP HEAD method. If the form includes a random variable, this function selects a new random value each time the form is posted.

Include file

WebAPI.bdh

Syntax

WebFormHead( in sUrl   : string,
             in idForm : form,
             in fWait  : float optional ) : boolean;

Return value

  • true if the worker thread communicating with the server could be started successfully

  • false otherwise. The return value will not inform about any Web traffic-related problems due to independent threaded operation.

Parameter | Description
sUrl | Complete URL to the file on the server
idForm | Form identifier used in the dclform section (see example below)
fWait | Minimum time or minimum mean time that this function call has to last (optional). Default value is 0.0

The form content in the dclform section is represented in an unencoded format to enhance readability and customizability. The data gets URL encoded on form submission. There are two possibilities to send data unencoded:

  • Add the query string as it should be sent to the server directly to the URL, for example, http://www.comp.com/cgi/special?dont encode blanks

  • Use WebUrlPostBin or WebFormPostBin to post data as provided to the Web server.

Example

var
  rsRandomRequestString : string;
dcltrans
  transaction TWebFormHead
  begin
    ...
    WebFormHead("http://www.myserver.com/mail2form.cgi",
    FORM_CUST_REQUEST, 0.0);
    ...
    end TWebFormHead;

dclform
  FORM_CUST_REQUEST:
  "email"   := "joe@somewhere.com",
  "request" := rsRandomRequestString;
Parent topic: Low-Level Web Functions
Related reference
WebFormUrlDecode Function
WebFormUrlEncode Function
WebUrlPostBin Function
WebFormPostBin Function


WebFormPost Function

Action

Posts the content of a Web form to the Web server by means of the HTTP POST method. If the form includes a random variable, this function selects a new random value each time the form is posted. Use the WebFormPostEx function to post two forms in the same request.

Include file

WebAPI.bdh

Syntax

WebFormPost( in sUrl     : string,
             in formBody : form,
             in fWait    : float optional ): boolean;

Return value

  • true if the worker thread posting the form content to the server could be started successfully

  • false otherwise. The return value will not inform about any Web traffic-related problems due to independent threaded operation.

Parameter | Description
sUrl | Complete URL to the file on the server
formBody | Form identifier used in the dclform section (see example below). The expanded form is added to the body of the request. The Content-Length and Content-Type header is added automatically. The default Content-Type is application/x-www-form-urlencoded and can be overwritten by a call to WebHeaderAdd("Content-Type", "myEncoding") prior to WebFormPost.
fWait | Minimum time or minimum mean time that this function call has to last (optional). Default value is 0.0

The form content in the dclform section is represented in an unencoded format to enhance readability and customizability. The data gets URL encoded on form submission. There are two possibilities to send data unencoded:

  • Add the query string as it should be sent to the server directly to the URL, for example, "http://www.comp.com/cgi/special?<don't>;[encode]/this". Note that blanks are encoded when this method is used.

  • Use WebUrlPostBin or WebFormPostBin to post data as provided to the Web server.

Example

var
  nWait : float;
  sName : string(100);

dclrand
  rnWait    : RndExpF(5.0);
  rnPhone   : RndStr("0123456789"; 16..16);
  rsAddress : RndFile("Address.rnd", 100);
  rsFName   : RndFile("gfname.rnd", 20);
  rsLName   : RndFile("glname.rnd", 20);

dcltrans
  transaction TWebFormPost
  begin
    // Get a random full name
    sName := rsFName + " " + rsLName;

    // and a random think time
    nWait := rnWait;
    WebFormPost("http://standardhost:2080/data2html.asp",
    FORM_01, nWait);
  end TWebFormPost;

dclform
  FORM_01:
    "name"    := sName,
    "address" := rsAddress,
    "phone"   := rnPhone;

Sample scripts

WebForms01.bdf, WebMeasure01.bdf, WebMulti01.bdf, WebParseResponse01.bdf, WebPost01.bdf, WebVerification01.bdf

Parent topic: Low-Level Web Functions
Related reference
WebFormUrlDecode Function
WebFormUrlEncode Function
WebUrlPostBin Function
WebFormPostBin Function
WebFormPostEx Function


WebFormPostBin Function

Action

Posts binary data to the Web server by means of the HTTP POST method. If the form includes a random variable, this function selects a new random value each time the form is posted.

Instead of ASCII-encoded form content, binary data may be sent using this post function. The Content-Length header will automatically be added to the request. The appropriate Content-Type has to be specified. In order to send binary data (octets) more safely over the Internet, use the WebBase64Encode to convert the data to 6-bit ASCII characters.

Include file

WebAPI.bdh

Syntax

WebFormPostBin( in sUrl         : string,
                in formUrl      : form,
                in sData        : string,
                in nDataLen     : number,
                in sContentType : string,
                in fWait        : float optional): boolean;

Return value

  • true successful.

  • false otherwise.

Parameter | Description
sUrl | Complete URL to the file on the server
formUrl | Form identifier used in the dclform section (see example below). The expanded form is added to the URL after the "?".
sData | Data to post to the server. This may be also binary data. For posting all available binary data specify STRING_COMPLETE for nDataLength and use the bin() operator for sData (see example).
nDataLen | Length in bytes of data contained in the buffer sData. Specify STRING_COMPLETE or omit this parameter to post all available data.
sContentType | Content type string used in the request, for example, "image/gif"
fWait | Minimum time or minimum mean time that this function call has to last (optional). The default value is 0.0

The form content in the dclform section is represented in an unencoded format to enhance readability and customizability. The data gets URL encoded on form submission. There are two possibilities to send data unencoded:

  • Add the query string as it should be sent to the server directly to the URL, for example, "http://www.comp.com/cgi/special?<don't>;[encode]/this". Note that blanks are encoded when this method is used.

  • Use WebUrlPostBin to post data as provided to the Web server.

Example

dcltrans
  transaction TWebFormPostBin
  var
    sData : string;
  begin
    // Post hard coded binary data in hexadecimal form
    // (first 16 ASCII sequences) along with an additional sub query
    sData := "\h00010203040506070809101112131415";
    WebFormPostBin("http://standardhost/data2html.asp", FORM_01,
      bin(sData),
      STRING_COMPLETE, "binary/costum", 0.0);
  end TWebFormPostBin;

dclform
  FORM_01:
    "SessionID" := "SID12345";

Sample scripts

WebForms02.bdf, WebPost01.bdf

Parent topic: Low-Level Web Functions
Related reference
WebFormPost Function
WebFormPostEx Function
WebFormUrlDecode Function
WebFormUrlEncode Function
WebBase64Encode Function
WebUrlPostBin Function


WebFormPostFile Function

Action

Posts binary data to the Web server by means of the HTTP POST method. If the form includes a random variable, this function selects a new random value each time the form is posted.

Instead of ASCII-encoded form content, binary data may be sent using this post function. The Content-Length header will automatically be added to the request. The appropriate Content-Type has to be specified. In order to send binary data (octets) more safely over the Internet, use the WebBase64Encode to convert the data to 6-bit ASCII characters.

Include file

WebAPI.bdh

Syntax

WebFormPostFile( in sUrl         : string,
                 in formUrl      : form,
                 in sFile        : string,
                 in sContentType : string,
                 in fWait        : float optional): boolean;

Return value

  • true successful.

  • false otherwise.

Parameter | Description
sUrl | Complete URL to the file on the server
formUrl | Form identifier used in the dclform section (see example below). The expanded form is added to the URL after the "?".
sFile | File to post to the server.
sContentType | Content type string used in the request, for example, "image/gif"
fWait | Minimum time or minimum mean time that this function call has to last (optional). The default value is 0.0

The form content in the dclform section is represented in an unencoded format to enhance readability and customizability. The data gets URL encoded on form submission. There are two possibilities to send data unencoded:

  • Add the query string as it should be sent to the server directly to the URL, for example, "http://www.comp.com/cgi/special?<don't>;[encode]/this". Note that blanks are encoded when this method is used.

  • Use WebUrlPostBin to post data as provided to the Web server.

Example

dcltrans
  transaction TWebFormPostFile
  var
    sFile: string;
  begin
    sFile := "c:\\temp\\dummyfile.txt";
    WebFormPostFile("http://standardhost/data2html.asp", FORM_01,
    sFile, "text/plain", 0.0);
  end TWebFormPostFile;

dclform
  FORM_01:
    "SessionID" := "SID12345";
Parent topic: Low-Level Web Functions
Related reference
WebFormUrlDecode Function
WebFormUrlEncode Function
WebFormPost Function
WebFormPostEx Function
WebBase64Encode Function
WebUrlPostBin Function


WebFormPostEx Function

Action

Posts the contents of two forms to the Web server by means of the HTTP POST method. If the form includes a random variable, this function selects a new random value each time the form is posted.

The difference between this function and the WebFormPost is that a form may be posted in the body of the request in addition to the URL.

Include file

WebAPI.bdh

Syntax

WebFormPostEx( inout sUrl     : string,
               in    formUrl  : form,
               in    formBody : form,
               in    fWait    : float optional ) : boolean;

Return value

  • true if the worker thread posting the form content to the server could be started successfully

  • false otherwise

Parameter | Description
sUrl | Complete URL to the file on the server
formUrl | Form identifier used in the dclform section (see example below). The expanded form is added to the URL after the "?".
formBody | Form identifier used in the dclform section (see example below). The expanded form is added to the body of the request. The Content-Length and Content-Type header are added automatically. The default Content-Type is application/x-www-form-urlencoded and can be overwritten by a call to WebHeaderAdd("Content-Type", "myEncoding") prior to invoking WebFormPostEx.
fWait | Minimum time or minimum mean time that this function call has to last (optional). Default value is 0.0

The form content in the dclform section is represented in an unencoded format to enhance readability and customizability. The data gets URL encoded on form submission. There are two possibilities to send data unencoded:

  • Add the query string as it should be sent to the server directly to the URL, for example, "http://www.comp.com/cgi/special?<don't>;[encode]/this". Note that blanks are encoded when this method is used.

  • Use WebUrlPostBin or WebFormPostBin to post data as provided to the Web server.

Example

var
  nWait : float;
  sName : string(100);

dclrand
  rnWait    : RndExpF(5.0);
  rnPhone   : RndStr("0123456789"; 16..16);
  rsAddress : RndFile("Address.rnd", 100);
  rsFName   : RndFile("gfname.rnd", 20);
  rsLName   : RndFile("glname.rnd", 20);

dcltrans
  transaction TWebFormPostEx
  begin
    // Get a random full name
    sName := rsFName + " " + rsLName;
    // and a random think time
    nWait := rnWait;
    WebFormPostEx("http://standardhost:2080/data2html.asp",
    FORM_01, FORM_01, nWait);
  end TWebFormPostEx;

dclform
  FORM_01:
  "name"    := sName,
  "address" := rsAddress,
  "p hone"  := rnPhone;

Sample scripts

WebForms01.bdf, WebPost01.bdf, WebTimer01.bdf

Parent topic: Low-Level Web Functions
Related reference
WebFormPost Function
WebFormPostBin Function
WebFormUrlDecode Function
WebFormUrlEncode Function
WebUrlPostBin Function


WebFormValuePairInsert Function

Action

Inserts a new pair of values into a Web form declared in the dclform section. This function can be used to dynamically modify the content of a Web form.

Include file

WebAPI.bdh

Syntax

WebFormValuePairInsert( in fForm       : form,
                        in sLeftValue  : string,
                        in sRightValue : string,
                        in nPosition   : number optional,
                        in nAttribute  : number optional ): boolean;

Return value

  • true if successful

  • false otherwise

Parameter | Description
fForm | Web form whose content will be extended by the given pair of values.
sLeftValue | String representing the left-side value of the pair of values inserted into the Web form.
sRightValue | String representing the right-side value of the pair of values inserted into the Web form.
nPosition | Position where the new pair of values is inserted (optional). If this parameter is omitted, the new pair is appended at the end of the Web form.
nAttribute | Attribute of the pair of values (optional). If this value is omitted no special attribute is assigned.

Example

dcltrans
  transaction TMain
  var
    sFirstName, sLastName, sPhone: string;
  begin
    WebFormValuePairInsert(fForm, "street", "Beach Road");
    WebFormValuePairInsert(fForm, "phone",
      "1212-555-8532", 4, USE_HTML_VAL);
    WebFormValueGet(fForm, sFirstName, STRING_COMPLETE, "first name");
    WebFormValueGet(fForm, sLastName, STRING_COMPLETE, "last name");
    WebFormValueGet(fForm, sPhone, STRING_COMPLETE, "phone");
    write("first name = "); write(sFirstName); writeln;
    write("last name = "); write(sLastName); writeln;
    write("phone = "); write(sPhone); writeln;
    WebFormValueSet(fForm, "phone", "1411-555-0969");
    WebFormValueGet(fForm, sPhone, STRING_COMPLETE, "phone");
    write("phone = "); write(sPhone); writeln;
    WebFormValuePairRemove(fForm, "street");
    WebFormClear(fForm);
  end TMain;

dclform
  fForm:
    "first name" := "Peter",
    "last name"  := "Heart";

Sample scripts

WebForms04.bdf

Parent topic: Low-Level Web Functions
Related reference
WebFormValuePairRemove Function


WebFormValuePairRemove Function

Action

Removes a number of pairs of values from a Web form declared in the dclform section. This function can be used to dynamically modify the content of a Web form.

Include file

WebAPI.bdh

Syntax

WebFormValuePairRemove( in fForm      : form,
                        in sLeftValue : string,
                        in nPosition  : number optional ): boolean;

Return value

  • true if successful

  • false otherwise

Parameter | Description
fForm | Web form whose content will be reduced by all matching pairs of values
sLeftValue | String representing the left-side value of all pairs of values removed from the Web form
nPosition | Position of the pair of values which is removed (optional). If this parameter is passed to the function, the sLeftValue parameter is ignored. Otherwise, if this parameter is omitted, Silk Performer searches the Web form for all occurrences of sLeftValue and removes all matching entries

Example

dcltrans
  transaction TMain
  var
    sFirstName, sLastName, sPhone: string;
  begin
    WebFormValuePairInsert(fForm, "street", "Beach Road");
    WebFormValuePairInsert(fForm, "phone", "1212-555-8532");
    WebFormValueGet(fForm, sFirstName, STRING_COMPLETE, "first name");
    WebFormValueGet(fForm, sLastName, STRING_COMPLETE, "last name");
    WebFormValueGet(fForm, sPhone, STRING_COMPLETE, "phone");
    write("first name = "); write(sFirstName); writeln;
    write("last name = "); write(sLastName); writeln;
    write("phone = "); write(sPhone); writeln;
    WebFormValueSet(fForm, "phone", "1411-555-0969");
    WebFormValueGet(fForm, sPhone, STRING_COMPLETE, "phone");
    write("phone = "); write(sPhone); writeln;
    WebFormValuePairRemove(fForm, "street");
    WebFormClear(fForm);
  end TMain;

dclform
  fForm:
    "first name" := "Peter",
    "last name"  := "Heart";

Sample scripts

WebForms04.bdf

Parent topic: Low-Level Web Functions
Related reference
WebFormValuePairInsert Function


WebFormValueSet Function

Action

Sets the left-side and/or the right-side value of a Web form entry. This function can be used to dynamically modify the content of a Web form.

Include file

WebAPI.bdh

Syntax

WebFormValueSet( in fForm       : form,
                 in sLeftValue  : string allownull,
                 in sRightValue : string allownull,
                 in nPosition   : number optional
                 in nAttribute  : number optional ): boolean;

Return value

  • true if successful

  • false otherwise

Parameter | Description
fForm | Web form whose content will be modified
sLeftValue | String representing the left-side value to set or to search for, depending on the nPosition parameter
sRightValue | String representing the right-side value to set or to search for, depending on the nPosition parameter
nPosition

Position of the Web form entry whose values will be set (optional).

If this parameter is passed to the function, the function behaves as follows:

  • If sRightValue is not NULL, both values are set, the left-side value to sLeftValue, and the right-side value to sRightValue

  • If sRightValue is NULL, the specified left-side value is set to sLeftValue

  • If sLeftValue is NULL, the specified right-side value is set to sRightValue

Otherwise, if this parameter is omitted, Silk Performer searches the Web form for a matching left-side value and sets the corresponding right-side value.
nAttribute | Attribute of the pair of values (optional). If this value is omitted no special attribute is assigned. See the form attributes section in the Web form declarations section for all possible values.

Example

dcltrans
  transaction TMain
  var
    sFirstName, sLastName, sPhone: string;
  begin
    WebFormValuePairInsert(fForm, "street", "Beach Road");
    WebFormValuePairInsert(fForm, "phone", "1212-555-8532");
    WebFormValueGet(fForm, sFirstName, STRING_COMPLETE, "first name");
    WebFormValueGet(fForm, sLastName, STRING_COMPLETE, "last name");
    WebFormValueGet(fForm, sPhone, STRING_COMPLETE, "phone");
    write("first name = "); write(sFirstName); writeln;
    write("last name = "); write(sLastName); writeln;
    write("phone = "); write(sPhone); writeln;
    WebFormValueSet(fForm, "phone", "1411-555-0969",
0, USE_HTML_VAL);
    WebFormValueGet(fForm, sPhone, STRING_COMPLETE, "phone");
    write("phone = "); write(sPhone); writeln;
    WebFormValuePairRemove(fForm, "street");
    WebFormClear(fForm);
  end TMain;

dclform
  fForm:
    "first name" := "Peter",
    "last name" := "Heart";

Sample scripts

WebForms04.bdf

Parent topic: Low-Level Web Functions
Related reference
WebFormValueGet Function
Web Form Declarations


WebFormValueGet Function

Action

Retrieves the left-side and/or the right-side value of a Web form entry. This function can be used to dynamically modify the content of a Web form.

Include file

WebAPI.bdh

Syntax

WebFormValueGet( in  fForm      : form,
                 out sValue     : string,
                 in  nValueSize : number,
                 in  sLeftValue : string,
                 in  nPosition  : number optional,
                 in  bGetLeft   : boolean optional,
                 out nAttribute : number optional): boolean;

Return value

  • true if successful

  • false otherwise

Parameter | Description
fForm | Web form whose content will be retrieved.
sValue | String receiving the specified value of a Web form entry.
nValueSize | Length of the string receiving the value.
sLeftValue | String representing a left-side value to search for.
nPosition

Position of the Web form entry (optional).

If this parameter is passed to the function, the function returns either the right-side or the left-side value of the specified entry, depending on the bGetLeft parameter

Otherwise, if this parameter is omitted, this function searches the specified Web form for a left-side value equal to sLeftValue and returns the corresponding right-side value.
bGetLeft | Specifies whether to return the left-side or the right-side value of a given Web form entry (optional). If this parameter is passed to the function, the function retrieves the left-side value instead of the right-side value.
nAttribute | If this parameter is not omitted it receives the attribute of the specified pair of values.

Example

dcltrans
  transaction TMain
  var
    sString, sFirstName, sLastName, sPhone : string;
    nAttrFirst, nAttrLast                  : number;
  begin
    WebFormValuePairInsert(fForm, "street", "Beach Road");
    WebFormValuePairInsert(fForm, "phone", "1212-555-8532");
    WebFormValueGet(fForm, sFirstName, sizeof(sFirstName),
"first name", 0, false, nAttrFirst);
    WebFormValueGet(fForm, sLastName, sizeof(sLastName),
"last name", 0, false, nAttrLast);
    WebFormValueGet(fForm, sPhone, sizeof(sPhone), "phone");
    write("first name = "); write(sFirstName);
    write(", attribute = "); write(nAttrFirst); writeln;
    write("last name = "); write(sLastName);
    write(", attribute = "); write(nAttrLast); writeln;
    write("phone = "); write(sPhone); writeln;

    // retrieve the left-hand value of the first pair
    WebFormValueGet(fForm, sString, sizeof(sString), "", 1, true);
    WebFormValueSet(fForm, "phone", "1411-555-0969");
    WebFormValueGet(fForm, sPhone, sizeof(sPhone), "phone");
    write("phone = "); write(sPhone); writeln;
    WebFormValuePairRemove(fForm, "street");
    WebFormClear(fForm);
  end TMain;

dclform
  fForm:
    "first name" := "Peter" <ENCODE_CUSTOM>,
    "last name"  := "Heart";

Sample scripts

WebForms04.bdf

Parent topic: Low-Level Web Functions
Related reference
WebFormValueSet Function


WebCustomRequest Function

Action

Requests and reads a complete document specified by a URL using the specified HTTP method.

Include file

WebAPI.bdh

Syntax

WebCustomRequest( in sMethod  : string,
                  in sUrl     : string,
                  in formBody : form optional,
                  in formUrl  : form optional,
                  in fWait    : float optional ): boolean;

Return value

  • true if successful

  • false otherwise

Parameter | Description
sMethod | HTTP method used for the request (like GET, POST or M-GET).
sUrl | Absolute URL to the file on the server. The entire character content of the query string will not be URL-encoded.
formBody

Form identifier used in the dclform section (optional). The expanded form is added to the body of the request. The Content-Length and Content-Type headers are added automatically. The default Content-Type is "application/x-www-form-urlencoded" and can be overwritten by a WebHeaderAdd("Content-Type", "myEncoding") function call prior to the WebCustomRequest function call.

Set this parameter to FORM_NULL if you do not want to specify a form. You would do this when you want to specify the following parameters but want to omit this parameter.
formUrl

Form identifier used in the dclform section (optional). The expanded form string is appended to the URL after the "?". All unsafe characters are URL-encoded.

Set this parameter to FORM_NULL if you do not want to specify a form. You would do this when you want to specify the following parameters but want to omit this parameter.
fWait | Minimum time or minimum mean time that this function call has to last (optional). The default value is 0.0.

Example

dcltrans
  transaction TMain
  begin
    WebCustomRequest("GET", "http://standardhost/product.asp?code=2");
    WebCustomRequest("M-POST", "http://standardhost/product.asp",
SHOPIT_PRODUCT_ASP003, SHOPIT_PRODUCT_ASP002);
  end TMain;

dclform
  SHOPIT_PRODUCT_ASP002:
    "code" := "2";
  SHOPIT_PRODUCT_ASP003:
    "tent" := "1";
Parent topic: Low-Level Web Functions
Related reference
WebCustomRequestBin Function


WebCustomRequestBin Function

Action

Requests and reads a complete document specified by a URL using the specified HTTP method. The optional request body consists of binary data.

Include file

WebAPI.bdh

Syntax

WebCustomRequestBin( in sMethod     : string,
                     in sUrl        : string,
                     in sData       : string,
                     in nDataLength : number optional,
                     in sContent    : string optional,
                     in formUrl     : form optional,
                     in fWait       : float optional): boolean;

Return value

  • true if successful

  • false otherwise

Parameter | Description
sMethod | HTTP method used for the request (like GET, POST, or M-GET).
sUrl | Absolute URL to the file on the server. The entire character content of the query string will not be URL-encoded.
sData | Data to post to the server. This may also be binary data. For posting all available binary data specify STRING_COMPLETE for nDataLength and use the bin() operator for sData (see example).
nDataLength | Amount of the data that is posted to the server (in bytes). Specify STRING_COMPLETE or omit this parameter to post all available data.
sContent | Content type string used in the request, for example, "image/gif" (optional). If this parameter is omitted, an "application/x-www-form-urlencoded" header is sent.
formUrl

Form identifier used in the dclform section (optional). The expanded form string is appended to the URL after the "?". All unsafe characters are URL-encoded.

Set this parameter to FORM_NULL if you do not want to specify a form. You would do this when you want to specify the following parameters but want to omit this parameter.
fWait | Minimum time or minimum mean time that this function call has to last (optional). The default value is 0.0.

Example

dcltrans
  transaction TMain
  var
    sData: string(4);
  begin
    SetLong(sData, 1, 15708);
    WebCustomRequest("GET", "http://standardhost/product.asp?code=2");
    WebCustomRequestBin("M-POST", "http://standardhost/main.asp",
      bin(sData), STRING_COMPLETE, "application/octet-stream", SHOPIT_PRODUCT_ASP002);
  end TMain;

dclform
  SHOPIT_PRODUCT_ASP002:
    "code" := "2";
Parent topic: Low-Level Web Functions
Related reference
WebCustomRequest Function
WebCustomRequestFile Function


WebCustomRequestFile Function

Action

Requests and reads a complete document specified by a URL using the specified HTTP method. The optional request body consists of binary data.

Include file

WebAPI.bdh

Syntax

WebCustomRequestFile( in sMethod  : string,
                      in sUrl     : string,
                      in sFile    : string,
                      in sContent : string optional,
                      in formUrl  : form optional,
                      in fWait    : float optional ): boolean;

Return value

  • true if successful

  • false otherwise

Parameter | Description
sMethod | HTTP method used for the request (like GET, POST, or M-GET).
sUrl | Absolute URL to the file on the server. The entire character content of the query string will not be URL-encoded.
sFile | File to post to the server.
sContent | Content type string used in the request, for example, "image/gif" (optional). If this parameter is omitted, an "application/x-www-form-urlencoded" header is sent.
formUrl

Form identifier used in the dclform section (optional). The expanded form string is appended to the URL after the "?". All unsafe characters are URL-encoded.

Set this parameter to FORM_NULL if you do not want to specify a form. You would do this when you want to specify the following parameters but want to omit this parameter.
fWait | Minimum time or minimum mean time that this function call has to last (optional). The default value is 0.0.

Example

dcltrans
  transaction TMain
  var
    sFile: string;
  begin
    sFile := "c:\\temp\\dummyfile.txt";
    WebCustomRequest("GET", "http://standardhost/product.asp?code=2");
    WebCustomRequestFile("M-POST", "http://standardhost/main.asp",
    sFile, "application/octet-stream", SHOPIT_PRODUCT_ASP002);
  end TMain;

dclform
  SHOPIT_PRODUCT_ASP002:
    "code" := "2";
Parent topic: Low-Level Web Functions
Related reference
WebCustomRequest Function


WebSetEncoding Function

Action

Compresses the data of the next WebUrl* or WebPage* function with the gzip or zlib (deflate) algorithm.

Include file

WebAPI.bdh

Syntax

WebSetEncoding( in nEncodingKind : number );
Parameter Description
nEncodingKind

Can be one of following values:

  • WEB_ENCODING_NONE
  • WEB_ENCODING_GZIP
  • WEB_ENCODING_ZLIB

Example

dcltrans
  transaction TmyTrans1
  var sData : string;
  begin
    WebHeaderAdd("Content-Encoding", "gzip");
    WebSetEncoding(WEB_ENCODING_GZIP);
    WebPagePost("http://demo.borland.com/TestSite/rawData2Html.asp",
                "Zip This Text With GZIP Before Sending To Server");

    WebHeaderAdd("Content-Encoding", "deflate");
    WebSetEncoding(WEB_ENCODING_ZLIB);
    WebPagePost("http://demo.borland.com/TestSite/rawData2Html.asp",
                "Zip This Text With ZLIB Before Sending To Server");

    sData := "Zip This Text With GZIP Before Sending To Server";
    WebHeaderAdd("Content-Encoding", "gzip");
    WebSetEncoding(WEB_ENCODING_GZIP);
    WebUrlPostBin("http://demo.borland.com/TestSite/rawData2Html.asp",
                  sData, binlen(sData), "text", 0.0);

    sData := "Zip This Text With ZLIB Before Sending To Server";
    WebHeaderAdd("Content-Encoding", "deflate");
    WebSetEncoding(WEB_ENCODING_ZLIB);
Parent topic: Low-Level Web Functions
Parent topic: Page-Level Web Functions Overview


WebAddMultiPart Function

Action

When WebAddMultiPart or WebAddMultiPartFromeFile is called, the passed data is stored in lists. When WebPostMultiPart is called, these lists are then merged with a unique boundary and transferred to the server using WebUrlPostBin.

Include file

WebAPI.bdh

Syntax

WebAddMultiPart ( in sBodyHeader : string,
                  in sBodyData   : string );

Return value

none

Parameter | Description
sBodyHeader | Auxiliary information that may be required when unpacking or processing the object, for example Content-Type, Content-Transfer-Encoding, Content-ID. Each line must end with \r\n.
sBodyData | The data of the multipart object.

Example

dcltrans
  transaction TMultiPartRelated
  var
    sMultiPartHeader: string;
    sMultiPartData: string;
  begin
// usage:
//
//   WebAddMultiPart(bodyheader, bodydata)
//   WebAddMultiPartFromFile(bodyheader, filename)
//   WebPostMultiPart("https://...", "multipart/related; type=\"text/xml\"");
//
// where bodyheader is e.g.:
//
//   Content-Type: text/xml; charset=UTF-8
//   Content-Transfer-Encoding: 8bit
//   Content-ID: <rootpart@soapui.org>
//
// and bodydata is
//   o) in case of WebAddMultiPart, e.g.:
//
//     <soapenv:Envelope xmlns:soapenv="http://schemas.xmlsoap.org/soap/envelope/" xmlns:kun="http://services.dst.baintern.de/wsdl/basis/dokumentenmgmt/KundenBescheideAblageServiceMessages_V_1" xmlns:bes="http://services.dst.baintern.de/types/basis/dokumentenmgmt/BescheidDokumenteEinstellen_StatusPerDateitransferDTOType_v_1" xmlns:all="http://services.dst.baintern.de/types/basis/dokumentenmgmt/AllgemeinDTOType_v_1">
//     ...
//     </soapenv:Envelope>
//
//   o) in case of WebAddMultiPartFromFile the filename of the document to upload, e.g. "1_Bescheid.zip"

    //sample 1, doing a 4 part request:
    sMultiPartHeader := "Content-Type: text/plain\r\n";
    sMultiPartData   := "This is my first text\r\n";
    WebAddMultiPart(sMultiPartHeader, sMultiPartData);
    sMultiPartHeader := "Content-Type: application/octet-stream\r\n";
    sMultiPartData   := "\h0102030405060708090A0B0C0D0E0F0D0A";
    WebAddMultiPart(sMultiPartHeader, sMultiPartData);
    sMultiPartHeader := "Content-Type: text/plain\r\n";
    sMultiPartData   := "This is my second text\r\n";
    WebAddMultiPart(sMultiPartHeader, sMultiPartData);
    sMultiPartHeader := "Content-Type: text/xml\r\n";
    sMultiPartData   := "<xml>This is xml</xml>\r\n";
    WebAddMultiPart(sMultiPartHeader, sMultiPartData);
    sMultiPartHeader := "Content-Type: text/plain\r\nContent-Disposition: attachment; name=\"simpletext.txt\"\r\n";
    sMultiPartData   := "simpletext.txt";
    WebAddMultiPartFromFile(sMultiPartHeader, sMultiPartData);
    WebPostMultiPart("http://demo.borland.com/testsite/rawdata2html.asp", "multipart/related");

    //sample 2:
    //throws an error as no WebAddMultiPart was specified
    WebPostMultiPart("https://demo.borland.com/testsite/svars.asp", "x");

    //sample 3:
    // throws an error as the file is not existent (in Silk Performer's search scope)
    sMultiPartHeader:=
      "Content-Type: application/zip\r\n"
      "Content-Disposition: attachment; name=\"test.zip\"\r\n";
    WebAddMultiPartFromFile(sMultiPartHeader, "test.zip");
    WebPostMultiPart("http://demo.borland.com/testsite/rawdata2html.asp", "multipart/related");

  end TMultiPartRelated;
Parent topic: Low-Level Web Functions


WebAddMultiPartFromFile Function

Action

When WebAddMultiPart or WebAddMultiPartFromeFile is called, the passed data is stored in lists. When WebPostMultiPart is called, these lists are then merged with a unique boundary and transferred to the server using WebUrlPostBin.

Include file

WebAPI.bdh

Syntax

WebAddMultiPartFromFile ( in sBodyHeader : string,
                          in sFileName   : string );

Return value

none

Parameter | Description
sBodyHeader | Auxiliary information that may be required when unpacking or processing the object, for example Content-Type, Content-Transfer-Encoding, Content-ID. Each line must end with \r\n.
sFileName | The file name of the document.

Example

dcltrans
  transaction TMultiPartRelated
  var
    sMultiPartHeader: string;
    sMultiPartData: string;
  begin
// usage:
//
//   WebAddMultiPart(bodyheader, bodydata)
//   WebAddMultiPartFromFile(bodyheader, filename)
//   WebPostMultiPart("https://...", "multipart/related; type=\"text/xml\"");
//
// where bodyheader is e.g.:
//
//   Content-Type: text/xml; charset=UTF-8
//   Content-Transfer-Encoding: 8bit
//   Content-ID: <rootpart@soapui.org>
//
// and bodydata is
//   o) in case of WebAddMultiPart, e.g.:
//
//     <soapenv:Envelope xmlns:soapenv="http://schemas.xmlsoap.org/soap/envelope/" xmlns:kun="http://services.dst.baintern.de/wsdl/basis/dokumentenmgmt/KundenBescheideAblageServiceMessages_V_1" xmlns:bes="http://services.dst.baintern.de/types/basis/dokumentenmgmt/BescheidDokumenteEinstellen_StatusPerDateitransferDTOType_v_1" xmlns:all="http://services.dst.baintern.de/types/basis/dokumentenmgmt/AllgemeinDTOType_v_1">
//     ...
//     </soapenv:Envelope>
//
//   o) in case of WebAddMultiPartFromFile the filename of the document to upload, e.g. "1_Bescheid.zip"

    //sample 1, doing a 4 part request:
    sMultiPartHeader := "Content-Type: text/plain\r\n";
    sMultiPartData   := "This is my first text\r\n";
    WebAddMultiPart(sMultiPartHeader, sMultiPartData);
    sMultiPartHeader := "Content-Type: application/octet-stream\r\n";
    sMultiPartData   := "\h0102030405060708090A0B0C0D0E0F0D0A";
    WebAddMultiPart(sMultiPartHeader, sMultiPartData);
    sMultiPartHeader := "Content-Type: text/plain\r\n";
    sMultiPartData   := "This is my second text\r\n";
    WebAddMultiPart(sMultiPartHeader, sMultiPartData);
    sMultiPartHeader := "Content-Type: text/xml\r\n";
    sMultiPartData   := "<xml>This is xml</xml>\r\n";
    WebAddMultiPart(sMultiPartHeader, sMultiPartData);
    sMultiPartHeader := "Content-Type: text/plain\r\nContent-Disposition: attachment; name=\"simpletext.txt\"\r\n";
    sMultiPartData   := "simpletext.txt";
    WebAddMultiPartFromFile(sMultiPartHeader, sMultiPartData);
    WebPostMultiPart("http://demo.borland.com/testsite/rawdata2html.asp", "multipart/related");

    //sample 2:
    //throws an error as no WebAddMultiPart was specified
    WebPostMultiPart("https://demo.borland.com/testsite/svars.asp", "x");

    //sample 3:
    // throws an error as the file is not existent (in Silk Performer's search scope)
    sMultiPartHeader:=
      "Content-Type: application/zip\r\n"
      "Content-Disposition: attachment; name=\"test.zip\"\r\n";
    WebAddMultiPartFromFile(sMultiPartHeader, "test.zip");
    WebPostMultiPart("http://demo.borland.com/testsite/rawdata2html.asp", "multipart/related");

  end TMultiPartRelated;
Parent topic: Low-Level Web Functions


WebPostMultiPart Function

Action

When WebAddMultiPart or WebAddMultiPartFromeFile is called, the passed data is stored in lists. When WebPostMultiPart is called, these lists are then merged with a unique boundary and transferred to the server using WebUrlPostBin.

Include file

WebAPI.bdh

Syntax

WebPostMultiPart ( in sUrl         : string,
                   in sContentType : string );

Return value

none

Parameter | Description
sUrl | Complete URL to the file on the server.
sContentType | The multipart/related Content-Type request header, optional parameters are type, start and start-info. The boundary delimiter is created automatically.

Example

dcltrans
  transaction TMultiPartRelated
  var
    sMultiPartHeader: string;
    sMultiPartData: string;
  begin
// usage:
//
//   WebAddMultiPart(bodyheader, bodydata)
//   WebAddMultiPartFromFile(bodyheader, filename)
//   WebPostMultiPart("https://...", "multipart/related; type=\"text/xml\"");
//
// where bodyheader is e.g.:
//
//   Content-Type: text/xml; charset=UTF-8
//   Content-Transfer-Encoding: 8bit
//   Content-ID: <rootpart@soapui.org>
//
// and bodydata is
//   o) in case of WebAddMultiPart, e.g.:
//
//     <soapenv:Envelope xmlns:soapenv="http://schemas.xmlsoap.org/soap/envelope/" xmlns:kun="http://services.dst.baintern.de/wsdl/basis/dokumentenmgmt/KundenBescheideAblageServiceMessages_V_1" xmlns:bes="http://services.dst.baintern.de/types/basis/dokumentenmgmt/BescheidDokumenteEinstellen_StatusPerDateitransferDTOType_v_1" xmlns:all="http://services.dst.baintern.de/types/basis/dokumentenmgmt/AllgemeinDTOType_v_1">
//     ...
//     </soapenv:Envelope>
//
//   o) in case of WebAddMultiPartFromFile the filename of the document to upload, e.g. "1_Bescheid.zip"

    //sample 1, doing a 4 part request:
    sMultiPartHeader := "Content-Type: text/plain\r\n";
    sMultiPartData   := "This is my first text\r\n";
    WebAddMultiPart(sMultiPartHeader, sMultiPartData);
    sMultiPartHeader := "Content-Type: application/octet-stream\r\n";
    sMultiPartData   := "\h0102030405060708090A0B0C0D0E0F0D0A";
    WebAddMultiPart(sMultiPartHeader, sMultiPartData);
    sMultiPartHeader := "Content-Type: text/plain\r\n";
    sMultiPartData   := "This is my second text\r\n";
    WebAddMultiPart(sMultiPartHeader, sMultiPartData);
    sMultiPartHeader := "Content-Type: text/xml\r\n";
    sMultiPartData   := "<xml>This is xml</xml>\r\n";
    WebAddMultiPart(sMultiPartHeader, sMultiPartData);
    sMultiPartHeader := "Content-Type: text/plain\r\nContent-Disposition: attachment; name=\"simpletext.txt\"\r\n";
    sMultiPartData   := "simpletext.txt";
    WebAddMultiPartFromFile(sMultiPartHeader, sMultiPartData);
    WebPostMultiPart("http://demo.borland.com/testsite/rawdata2html.asp", "multipart/related");

    //sample 2:
    //throws an error as no WebAddMultiPart was specified
    WebPostMultiPart("https://demo.borland.com/testsite/svars.asp", "x");

    //sample 3:
    // throws an error as the file is not existent (in Silk Performer's search scope)
    sMultiPartHeader:=
      "Content-Type: application/zip\r\n"
      "Content-Disposition: attachment; name=\"test.zip\"\r\n";
    WebAddMultiPartFromFile(sMultiPartHeader, "test.zip");
    WebPostMultiPart("http://demo.borland.com/testsite/rawdata2html.asp", "multipart/related");

  end TMultiPartRelated;
Parent topic: Low-Level Web Functions


Page-Level Web Functions Overview

The page-level web functions focus on Web pages rather than on single documents. A high-speed HTML parser enables the Web replay engine to access hyperlinks, forms and other load-relevant elements while downloading HTML documents. The functions also download embedded documents like images, applets and frames automatically.

One of the most important benefits of parsing HTML is direct access to session IDs that may reside in query strings of URLs or in hidden fields of forms. However, for sake of speed and memory overhead, HTML elements that are not relevant for navigation or data entry are ignored by the parser. This means that you can query the HTML document for hyperlinks, but in order to access HTML tables you still need to use the WebParseResponseData function.

When to use the page-level web functions :

  • When your Web pages contain dynamically embedded documents, for example, ad banner rotators.

  • When you do not want to care about session handling or when pages contain lots of session information that would require many WebParseResponseData function calls to maintain the session during replay.

  • When your server requires the “referrer” header to be set dynamically.

  • When your load balancer redirects the client to different servers dynamically.

  • When you want to use automatic verification for a page that checks whether the context between pages can be maintained.

  • For shorter, easy-to-read scripts.

When to use the low-level web functions instead:

  • When you need to generate the highest possible load on your server (number of virtual users, throughput)

  • When your Web pages use lots of client-side scripting, for example, JavaScript, VBScript, in order to download further documents or cause page transitions.

  • When your application is not Web-browser-based, for example, multimedia clients that use HTTP for communication but do not use HTML.

  • When maintaining context between pages is not relevant.

Page context

The Web page context is the link used to navigate from one page to another. The context can be maintained if there is enough HTML hyperlink information in page A to navigate to page B. Thus the context-less page-level web functions use an absolute URL to request a Web document, whereas the contextual functions try to retrieve the URL from the prior Web page. If a contextual function fails to find the necessary hyperlink information, the context is lost and all subsequent page download requests may also fail.

Context-less functions

WebPageUrl
Requests a document.
WebPageForm
Submits the form data.
WebPagePost
Posts the content of a Web form in binary format to the Web server by means of the HTTP POST method.
WebPagePostFile
Posts the content of a Web form in binary format to the Web server by means of the HTTP POST method.
WebPageCustomRequest
Requests and reads a complete Web page specified by a URL using HTTP. If the retrieved document is of content type HTML, it is parsed, and embedded documents are requested.
WebPageCustomRequestBin
Requests and reads a complete Web page specified by a URL using HTTP. If the retrieved document is of content type HTML, it is parsed, and embedded documents are requested.
WebPageCustomRequestFile
Requests and reads a complete document specified by a URL using the specified HTTP method.

Context-full functions

WebPageLink
Queries the link information and requests a document
WebPageBack
Goes back one page.
WebPageSubmit
Queries form information and submits a form.
WebPageSubmitBin
Queries form information and submits binary data.

Context query functions

WebPageQueryLink
Queries context information for available hyperlinks.
  • Context Management Overview
    The HTTP protocol, by its very nature, is a stateless protocol.
  • WebPageUrl Function
    Requests and reads a complete document specified by a URL using the specified HTTP method.
  • WebPageForm Function
    Posts the content of a Web form to the Web server by means of the HTTP POST method.
  • WebPagePost Function
    Posts binary data to the Web server by means of the HTTP POST method.
  • WebPagePostFile Function
    Posts binary data to the Web server by means of the HTTP POST method.
  • WebPageLink Function
    Queries the currently active page for the specified HTML hyperlink.
  • WebPageBack Function
    Moves the page context back for one or more pages.
  • WebPageSubmit Function
    Queries the currently active page for the specified HTML form.
  • WebPageSubmitBin Function
    Queries the currently active page for the specified HTML form.
  • WebPageSubmitFile Function
    Queries the currently active page for the specified HTML form.
  • WebPageSubmitFileUpload Function
    Queries the currently active page for the specified HTML form.
  • WebPageFileUpload Function
    Posts the content of a Web form, including specified files, to the Web server by means of the HTTP POST method.
  • WebPageAddUrl Function
  • WebPageQueryLink Function
    This function queries the currently active page context for hyperlinks.
  • WebPageCustomRequest Function
  • WebPageCustomRequestBin Function
    Requests and reads a complete document specified by a URL using the specified HTTP method.
  • WebPageCustomRequestFile Function
  • WebPageStoreContext Function
    Stores the context of the last page in the history, so that it will be available to all subsequent WebPageLink and WebPageSubmit calls.
  • WebPageDeleteContext Function
    Deletes a context stored by a call of the WebPageStore function.
  • WebPageSuppress function
    Specifies a file that must not be loaded by future Web function calls.
  • WebPageLoadAll Function
  • WebPageSetActionUrlAbs Function
    Modifies the action URL of a subsequent WebPageSubmit or WebPageSubmitBin function using an absolute URL specified by the sUrl parameter.
  • WebPageSetActionUrl Function
    Modifies the action URL of a subsequent WebPageSubmit or WebPageSubmitBin function using a URL parsed by a call to the WebPageParseUrl function.
  • WebPageParseUrl Function
    Modifies the html-parser to find additional hyperlinks (for subsequent WebPageLink functions) and URLs, which can be used in subsequent WebPageSetActionUrl or WebPageQueryParsedUrl commands.
  • WebPageQueryParsedUrl Function
    This function is used to retrieve the URL parsed because of a WebPageParseUrl function call with the WEB_FLAG_PARSE_URL flag set.
  • WebSetEncoding Function
    Compresses the data of the next WebUrl* or WebPage* function with the gzip or zlib (deflate) algorithm.
Parent topic: Web Functions Reference
Related reference
WebParseResponseData Function


Context Management Overview

The HTTP protocol, by its very nature, is a stateless protocol. HTTP follows a simple request/response paradigm. The client (that is the browser or any other application /applet, which uses HTTP for communication with a server) opens a TCP/IP connection to the server, sends a request, and receives the response from the server. Different requests from the same client to the same server - be it on the same TCP/IP connection or on another one - do not bear any relationship to each other.

Web applications, on the other hand, are becoming more and more complex and need to embed single requests within a larger entity, for example, a complete HTML page, a user session which has been initiated on the Web server, a shopping cart, a registered customer, etc.

To do so, there must be some means to transfer state information from the server to the client, which in turn is returned back to the server within subsequent HTTP requests so that the server can associate the request with the user session (shopping cart, customer, etc.) and respond properly.

By their very nature, any Web browser properly handles the techniquesused by Web applications to transfer state information.

A load testing project that should deliver useful results must simulate real users using real browsers for accessing a Web server. Otherwise the results would be inaccurate at best, or mere meaningless. To accomplish this, a load testing tool must be able to cope with all techniques used for maintaining state information, just like any browser does.

  • Context Less
    A context-less function does not refer to previous events or results during the script execution.
  • Context Full
    In contrast to context-less functions, context-full functions are designed to use results from previous function calls.
Parent topic: Page-Level Web Functions Overview


Context Less

A context-less function does not refer to previous events or results during the script execution. Thus it works without using information from previous steps. This means that for a context-less function call, all information that is necessary to perform this function must be specified in the script. Scripting or recording a context-less function is therefore the reason of session or other dynamic information in scripts.

A typical feature of context-less functions is that they have a parameter that specifies the URL to download.

Context-less functions in Silk Performer's page-level API are:

WebPageUrl
Requests a document.
WebPageForm
Submits the form data.
WebPagePost
Posts the content of a Web form in binary format to the Web server by means of the HTTP POST method.
WebPagePostFile
Posts binary data to the Web server by means of the HTTP POST method.
WebPageCustomRequest
Requests and reads a complete Web page specified by a URL using HTTP. If the retrieved document is of content type HTML, it is parsed, and embedded documents are requested.
WebPageCustomRequestBin
Requests and reads a complete Web page specified by a URL using HTTP. The optional request body consists of binary data. If the retrieved document is of content type HTML, it is parsed, and embedded documents are requested.
WebPageCustomRequestFile
Requests and reads a complete document specified by a URL using the specified HTTP method.

If any of these functions uses a form from the "dclform" - section in the script, we say that this form is used context-less. This is because there is no corresponding HTML form where unchanged (e.g. hidden) values can be taken from. All form values must be specified in the script.

Parent topic: Context Management Overview


Context Full

In contrast to context-less functions, context-full functions are designed to use results from previous function calls. How to use the results can be specified in a way that, with a high probability, does not incorporate dynamic data.

Context-full functions in Silk Performer's page-level API are:

WebPageLink
Queries the link information and requests a document.
WebPageBack
Goes back one page.
WebPageSubmit
Queries form information and submits a form.
WebPageSubmitBin
Queries form information and submits binary data.
Parent topic: Context Management Overview


WebPageUrl Function

Action

Requests and reads a complete document specified by a URL using the specified HTTP method. Use localhost if you want to connect to the local server. If the retrieved document is of content type HTML, it is parsed and embedded documents are requested.

Include file

WebAPI.bdh

Syntax

WebPageUrl(
  in sUrl : string,
  in sTimer : string optional,
in formUrl : form optional): boolean;

Return value

  • true if the page is downloaded successfully

  • false otherwise

Parameter | Description
sUrl | Absolute URL to the file on the server. All characters that are part of the query string are not URL-encoded.
sTimer | Name of the timer used for page measurements (optional). If this parameter is omitted, no measurements are performed.
formUrl | Form identifier used in the dclform section (optional). The expanded form string is appended to the URL after the "?". All unsafe characters are URL-encoded.

Example

dcltrans
  transaction TMain
  begin
    WebPageUrl("http://lab3/shopit/product.asp?code=2");
    WebPageUrl("http://lab3/shopit/product.asp",
"ShopIt - Product", SHOPIT_PRODUCT_ASP002);
  end TMain;
dclform
  SHOPIT_PRODUCT_ASP002:
    "code" := "2";
Parent topic: Page-Level Web Functions Overview


WebPageForm Function

Action

Posts the content of a Web form to the Web server by means of the HTTP POST method. If the form includes a random variable, this function selects a new random value each time the form is posted. If the retrieved document is of content type HTML, it is parsed and embedded documents are retrieved.

Include file

WebAPI.bdh

Syntax

WebPageForm(
  in sUrl : string,
  in formBody : form,
  in sTimer : string optional,
  in formUrl : form optional): boolean;

Return value

  • true if the page is downloaded successfully

  • false otherwise

Parameter | Description
sUrl | Absolute URL to the document on the server. All characters that are part of the query string are not URL-encoded.
formBody | Form identifier used in the dclform section. The expanded form is added to the body of the request. The Content-Length and Content-Type header are added automatically. The default Content-Type is application/x-www-form-urlencoded and can be overwritten by a WebHeaderAdd("Content-Type", "myEncoding") function call prior to the WebPageForm function call.
sTimer | Name of the timer used for page measurements (optional). If this parameter is omitted, no measurements are performed.
formUrl | Form identifier used in the dclform section (optional). The expanded form string is appended to the URL after the "?". All unsafe characters are URL-encoded.

Example

dcltrans
  transaction TMain
  begin
    WebPageForm("http://lab3/shopit/kindofpayment.asp", SUBMIT001,
"ShopIt - Pay with credit card");
  end TMain;
dclform
  SUBMIT001:
    "choice" := "Credit card",
    "paymentButton" := "Submit";
Parent topic: Page-Level Web Functions Overview


WebPagePost Function

Action

Posts binary data to the Web server by means of the HTTP POST method. If the optional form for the query string includes a random variable, this function selects a new random value each time the form is posted. If the retrieved document is of content-type HTML, it is parsed and embedded documents are retrieved.

Instead of ASCII-encoded form content, binary data may be sent using this post function. The Content-Length header is automatically added to the request. The appropriate Content-Type has to be specified. In order to send binary data (octets) more safely over the Internet, use the WebBase64Encode function to convert the data to 6-bit ASCII characters.

Include file

WebAPI.bdh

Syntax

WebPagePost( in sUrl        : string,
             in sData       : string,
             in nDataLength : number optional,
             in sContent    : string optional,
             in sTimer      : string optional,
             in formUrl     : form optional ): boolean;

Return value

  • true if the page is downloaded successfully

  • false otherwise

Parameter | Description
sUrl | Absolute URL to the document on the server. All characters that are part of the query string are not URL-encoded.
sData | Data to post to the server. This may also be binary data. For posting all available binary data specify STRING_COMPLETE for nDataLength and use the bin() operator for sData (see example).
nDataLength | Amount of the data that is posted to the server (in bytes). Specify STRING_COMPLETE or omit this parameter to post all available data.
sContent | Content type string used in the request, for example, "image/gif".
sTimer | Name of the timer used for page measurements (optional). If this parameter is omitted, no measurements are performed.
formUrl | Form identifier used in the dclform section (optional). The expanded form is added to the URL after the "?".

Example

dcltrans
  transaction TWebPagePost
  begin
    // Post hard coded binary data in hexadecimal form
    // (first 20 ASCII sequences) along with an additional sub query
    WebPagePost("http://standardhost/data2html.asp",
        "\h0001020304050607080910111213141516171819",
        STRING_COMPLETE, "binary/custom", "Dummy Timer", FORM_01);
  end TWebPagePost;

dclform
  FORM_01:
    "SessionID" := "SID12345";
Parent topic: Page-Level Web Functions Overview
Related reference
WebBase64Encode Function
WebPageForm Function
WebPagePostFile Function


WebPagePostFile Function

Action

Posts binary data to the Web server by means of the HTTP POST method. If the optional form for the query string includes a random variable, this function selects a new random value each time the form is posted. If the retrieved document is of content-type HTML, it is parsed and embedded documents are retrieved.

Instead of ASCII-encoded form content, binary data may be sent using this post function. The Content-Length header is automatically added to the request. The appropriate Content-Type has to be specified. In order to send binary data (octets) more safely over the Internet, use the WebBase64Encode function to convert the data to 6-bit ASCII characters.

Include file

WebAPI.bdh

Syntax

WebPagePostFile( in sUrl     : string,
                 in sFile    : string,
                 in sContent : string optional,
                 in sTimer   : string optional,
                 in formUrl  : form optional ): boolean;

Return value

  • true if the page is downloaded successfully

  • false otherwise

Parameter | Description
sUrl | Absolute URL to the document on the server. All characters that are part of the query string are not URL-encoded.
sFile | File to post to the server.
sContent | Content type string used in the request, for example, "image/gif" (optional).
sTimer | Name of the timer used for page measurements (optional). If this parameter is omitted, no measurements are performed.
formUrl | Form identifier used in the dclform section (optional). The expanded form is added to the URL after the "?".

Example

dcltrans
  transaction TWebPagePostFile
  var
    sFile: string;
  begin
    sFile := "c:\\temp\\dummyfile.txt";
    WebPagePostFile("http://standardhost/data2html.asp",
    sFile, "text/plain", "Dummy Timer", FORM_01);
  end TWebPagePostFile;

dclform
  FORM_01:
    "SessionID" := "SID12345";
Parent topic: Page-Level Web Functions Overview
Related reference
WebBase64Encode Function


WebPageLink Function

Action

Queries the currently active page for the specified HTML hyperlink. If this link is found, the function requests and reads the complete Web page that the link refers to. If the retrieved document is of content type HTML, it is parsed and embedded documents are requested.

There are different possibilities how hyperlinks can be named. These hyperlink identification rules are listed herein, ordered by priority:

  • Content text between the anchor begin and anchor end tag.

    <a href="data2html.asp">Content</a>

  • If the hyperlink is image-based, the “alt” attribute is used and added to the content text between the anchor begin and anchor end tag.

    <a href="data2html.asp"><img alt="BBK" src="p.gif"></a>

In the case of changing hyperlink descriptions, you can refer to the hyperlink by number instead of the description text. All hyperlinks are numbered sequentially throughout the Web page.

Include file

WebAPI.bdh

Syntax

WebPageLink( in sHyperlink : string allownull,
             in sTimer     : string optional,
             in nLinkNo    : number optional,
             in sFrame     : string optional,
             in hContext   : number optional): boolean;

Return value

  • true if the hyperlink is found and the page is downloaded successfully

  • false otherwise

Parameter | Description
sHyperlink | The name of the hyperlink to search for in the currently active Web page, or if the hContext parameter is not omitted to search for in the specified context. Set this parameter to NULL if a name is not available or if you want to identify the hyperlink only by number.
sTimer | Name of the timer used for page measurements (optional). If this parameter is omitted, no measurements are performed.
nLinkNo | Number of the hyperlink in the Web page (optional). If sHyperlink is NULL, the function requests the document that the n-th hyperlink in the page refers to. If sHyperlink specifies a name, the function follows the n-th hyperlink with the given name.
sFrame | The name of the frame the document is assigned to (optional). If this parameter is provided, the hyperlink is searched only within this frame document.
hContext | Context, stored by a prior call of the WebPageStoreContext function, where to search for the link (optional). If this parameter is omitted the link is searched in the actual page and all stored contexts.

Example

dcltrans
  transaction TMain
  var
    hContext: number;
  begin
    WebPageUrl("http://lab3/shopit/", "ShopIt - Greetings");
    WebPageStoreContext(hContext);
    WebPageLink("Join the experience!", "ShopIt - New Visitor");
    WebPageSubmit("Continue", CONTINUE001, "ShopIt - Main menu");
    WebPageLink("Products", "ShopIt - Products");
    WebPageLink(NULL, "ShopIt - Product", 3);
    WebPageLink("Help", "ShopIt - Help", 0, NULL, hContext);
  end TMain;

dclform
  CONTINUE001:
    "name"            := "jack",
    "New-Name-Button" := "Continue";
Parent topic: Page-Level Web Functions Overview
Related reference
WebPageQueryLink Function


WebPageBack Function

Action

Moves the page context back for one or more pages.

Include file

WebAPI.bdh

Syntax

WebPageBack( in nPages: number optional ) : boolean;

Return value

  • true if successful

  • false otherwise

Parameter | Description
nPages | Number of pages to move the page context back (optional). If this parameter is omitted, the functions moves the page context back for one page.

Example

dcltrans
  transaction TMain
  begin
    WebPageUrl("http://www.mytestmall.com/", "Testmall - Menu");
    WebPageLink("Products", "Testmall - Products");
    WebPageBack();
    WebPageLink("Search", "Testmall - Search");
  end TMain;
Parent topic: Page-Level Web Functions Overview


WebPageSubmit Function

Action

Queries the currently active page for the specified HTML form. If the form is found, the function submits the form to the Web server by means of the HTTP POST method and reads the response page. If the retrieved document is of content type HTML, it is parsed and embedded documents are requested. This function also supports multi-part file upload (RFC1867-compliant file upload).

The form value pairs of the parsed HTML base are used to provide data for the subsequent submission. This way hidden fields, for example, session ids, are automatically taken from the HTML form and submitted to the server. These default values may be overwritten by using a form identifier declared in the dclform section. The submission method, GET or POST, is defined by the HTML form. If it is missing, the GET method will be used.

WebPageSubmit() recognizes automatically form and form entry.

A file that is to be uploaded must be specified by a name-value pair in the following way:
"filename" := "<name of the input tag>;<file name>;<content type>";

Form identification rules are listed herein, ordered by priority:

  • HTML forms to be queried are identified by a name:

    <form name="form1" action="data2html.asp">
  <input type=hidden name="cantfind" value="#b21334a45">
  <input type=text name=ShoeSize value=44>
</form>

  • The “value” attribute of the submit button:

    <form name="form1" action="data2html.asp">
  <input type="submit" value=Insert>
</form>

  • The image used for submission may provide an “alt” attribute:

    <form name="form1" action="data2html.asp">
  <input type="image" src=box5.gif alt="PostBox">
</form>

In the case of a changing HTML form name, you can refer to the HTML form by number. All forms are numbered sequentially throughout the Web page.

Include file

WebAPI.bdh

Syntax

WebPageSubmit( in sHtmlForm   : string allownull,
               in formSubmit  : form,
               in sTimer      : string optional,
               in nHtmlFormNo : number optional,
               in sFrame      : string optional,
               in hContext    : number optional): boolean;

Return value

  • true if the form is found and submitted successfully

  • false otherwise

Parameter | Description
sHtmlForm | The name of the HTML form to search for in the currently active Web page, or if the hContext parameter is not omitted to search for in the specified context. Set this parameter to NULL if a name is not available or if you want to identify the HTML form only by its number.
formSubmit | Form identifier used in the dclform section. The expanded form is added to the body of the request. The Content-Length and Content-Type header are added automatically.
sTimer | Name of the timer used for page measurements (optional). If this parameter is omitted, no measurements are performed.
nHtmlFormNo | Number of the Web form in the Web page (optional). If sHtmlForm is NULL, the number specifies the n-th form in the page. If sHtmlForm specifies a name, the number specifies the n-th form with the given name.
sFrame | The name of the frame the document is assigned to (optional). If this parameter is provided, the form is searched only within this frame document.
hContext | Context, stored by a prior call of the WebPageStoreContext function, where to search for the form (optional). If this parameter is omitted the form is searched in the actual page and all stored contexts.

Example

dcltrans
  transaction TMain
  var
    hContext: number;
  begin
    WebPageUrl("http://lab3/shopit/", "ShopIt - Greetings");
    WebPageStoreContext(hContext);
    WebPageLink("Join the experience!", "ShopIt - New Visitor");
    WebPageSubmit("Continue", CONTINUE001, "ShopIt - Main menu");
    WebPageLink("Products", "ShopIt - Products");
    WebPageLink(NULL, "ShopIt - Product", 3);
    WebPageSubmit("Search", SEARCH001, "ShopIt - Search", 0, NULL, hContext);
  end TMain;

dclform
  CONTINUE001:
    "name"            := "jack",
    "New-Name-Button" := "Continue";
  SEARCH001:
    "search"          := "boot";

Example (for file upload)

 transaction TMain
  var
  begin
    WebPageUrl("http://demowebsite/conn_main.asp", "SilkPerformer Internet Compliancy Tests - Connectivity - Main");

    ThinkTime(37.7);
    WebPageSubmit("Submit", SUBMIT001, "Upload"); // Form 8

    ThinkTime(12.7);
    WebPageLink("Back", "SilkPerformer Internet Compliancy Tests - Connectivity - Main (#1)"); // Link 1
  end TMain;

dclform
  SUBMIT001:
    "filename" := "my_file;Math.jar;application/x-zip-compressed" <ENCODE_NONE> , // changed
    "submit"   := "" <USE_HTML_VAL> ; // unchanged, value: "Submit"
Parent topic: Page-Level Web Functions Overview


WebPageSubmitBin Function

Action

Queries the currently active page for the specified HTML form. If this form is found, the function submits the form to the Web server by means of the HTTP POST method and reads the response page. If the retrieved document is of content type HTML, it is parsed and embedded documents are requested.

This function is used when the form submission uses an encoding format different to ‘application/x-www-form-urlencoded’. Most common cases are file uploads which use content-type ‘multipart/form-data’. Note that the default value pairs of the HTML form are not automatically used for submission. The body message has to be supplied as a whole.

Form identification rules are listed herein, ordered by priority:

  • HTML forms to be queried are identified by a name:

    <form name="form1" action="data2html.asp">
    <input type=hidden name="cantfind" value="#b21334a45">
    <input type=text name=ShoeSize value=44>
</form>

  • The “value” attribute of the submit button:

    <form name="form1" action="data2html.asp">
    <input type="submit" value=Insert>
</form>

  • The image used for submission may provide an “alt” attribute:

    <form name="form1" action="data2html.asp">
    <input type="image" src=box5.gif alt="PostBox">
</form>

In the case of changing HTML form name, you can refer to the HTML form by number. All forms are numbered sequentially throughout the Web page.

Include file

WebAPI.bdh

Syntax

WebPageSubmitBin( in sHtmlForm   : string allownull,
                  in sData       : string,
                  in nDataLength : number optional,
                  in sContent    : string optional,
                  in sTimer      : string optional,
                  in nFormNo     : number optional
                  in sFrame      : string optional,
                  in hContext    : number optional ): boolean;

Return value

  • true if the form is found and submitted successfully

  • false otherwise

Parameter | Description
sHtmlForm | The name of the HTML form to search for in the currently active Web page, or if the hContext parameter is not omitted in the specified context. Set this parameter to NULL if a name is not available or if you want to identify the HTML form only by its number.
sData | Data to post to the server. This may also be binary data. For posting all available binary data specify STRING_COMPLETE for nDataLength and use the bin() operator for sData (see example).
nDataLength | Amount of data that is posted to the server (in bytes). Specify STRING_COMPLETE or omit this parameter to post all available data.
sContent | Content type string used in the request, for example, "image/gif" (optional).
sTimer | Name of the timer used for page measurements (optional). If this parameter is omitted, no measurements are performed.
nFormNo | Number of the Web form in the Web page (optional). If sHtmlForm is NULL, the number specifies the n-th form in the page. If sHtmlForm specifies a name, the number specifies the n-th form with the given name.
sFrame | The name of the frame the document is assigned to (optional). If this parameter is provided, the form is searched only within this frame document.
hContext | Context, stored by a prior call of the WebPageStoreContext function, where to search the form (optional). If this parameter is omitted the form is searched for in the actual page and all stored contexts.

Example

transaction TMain
begin
  WebPageUrl("http://lab1/", "Silk Performer Test Site");
  WebPageLink("File Upload Samples",
              "SA-FileUp Samples - Main Page");
  WebPageLink("Simple", "Simple Upload Example");
  WebPageSubmitBin("Upload File",
    "-----------------------------210021814825312\r\n"
    "Content-Disposition: form-data; name=\"FILE1\";"
    " filename=\"C:\\log.txt\"\r\n"
    "Content-Type: text/plain\r\n"
    "\r\n"
    "18:03:37.037 try to enter\r\n"
    "19:00:50.726 try to enter\r\n"
    "16:35:41.361 try to enter\r\n"
    "18:10:54.004 try to enter\r\n"
    "\r\n"
    "-----------------------------210021814825312\r\n"
    "Content-Disposition: form-data; name=\"SUB1\"\r\n"
    "\r\n"
    "Upload File\r\n"
    "-----------------------------210021814825312--\r\n", STRING_COMPLETE,
    "multipart/form-data",
    "Simple File Upload Results");
end TMain;

transaction TMain1
  var
    sData : string;
  begin
    sData := "\h0000656600760403000000003400";
    WebPageUrl("http://lab1/", "Silk Performer Test Site");
    WebPageSubmitBin("Upload Data", bin(sData), STRING_COMPLETE, "application/octet-stream")
  end TMain1;
Parent topic: Page-Level Web Functions Overview


WebPageSubmitFile Function

Action

Queries the currently active page for the specified HTML form. If this form is found, the function submits the form to the Web server by means of the HTTP POST method and reads the response page. If the retrieved document is of content type HTML, it is parsed and embedded documents are requested.

This function is used when the form submission uses an encoding format different to ‘application/x-www-form-urlencoded’. Most common cases are file uploads which use content-type ‘multipart/form-data’. Note that the default value pairs of the HTML form are not automatically used for submission. The body message has to be supplied as a whole.

Form identification rules are listed herein, ordered by priority:

  • HTML forms to be queried are identified by a name:

    <form name="form1" action="data2html.asp">
  <input type=hidden name="cantfind" value="#b21334a45">
  <input type=text name=ShoeSize value=44>
</form>

  • The “value” attribute of the submit button:

    <form name="form1" action="data2html.asp">
  <input type="submit" value=Insert>
</form>

  • The image used for submission may provide an “alt” attribute:

    <form name="form1" action="data2html.asp">
  <input type="image" src=box5.gif alt="PostBox">
</form>

In the case of changing HTML form name, you can refer to the HTML form by number. All forms are numbered sequentially throughout the Web page.

Include file

WebAPI.bdh

Syntax

WebPageSubmitFile( in sHtmlForm : string allownull,
                   in sFile     : string,
                   in sContent  : string optional,
                   in sTimer    : string optional,
                   in nFormNo   : number optional,
                   in sFrame    : string optional,
                   in hContext  : number optional): boolean;

Return value

  • true if the form is found and submitted successfully

  • false otherwise

Parameter | Description
sHtmlForm | The name of the HTML form to search for in the currently active Web page, or if the hContext parameter is not omitted in the specified context. Set this parameter to NULL if a name is not available or if you want to identify the HTML form only by its number.
sFile | File to post to the server.
sContent | Content type string used in the request, for example, "image/gif" (optional).
sTimer | Name of the timer used for page measurements (optional). If this parameter is omitted, no measurements are performed.
nFormNo | Number of the Web form in the Web page (optional). If sHtmlForm is NULL, the number specifies the n-th form in the page. If sHtmlForm specifies a name, the number specifies the n-th form with the given name.
sFrame | The name of the frame the document is assigned to (optional). If this parameter is provided, the form is searched only within this frame document.
hContext | Context, stored by a prior call of the WebPageStoreContext function, where to search the form (optional). If this parameter is omitted the form is searched for in the actual page and all stored contexts.

Example

dcltrans
  transaction TMain
  var
    sFile: string;
  begin
    sFile := "c:\\temp\\dummyfile.txt";
    WebPageUrl("http://lab1/", "Silk Performer Test Site");
    WebPageLink("File Upload Samples",
                "SA-FileUp Samples - Main Page");
    WebPageLink("Simple", "Simple Upload Example");
    WebPageSubmitFile("Upload File", sFile);
  end TMain;
Parent topic: Page-Level Web Functions Overview


WebPageSubmitFileUpload Function

Action

Queries the currently active page for the specified HTML form. If this form is found, the function submits the form, including specified files, to the Web server by means of the HTTP POST method and reads the response page. If the retrieved document is of content type HTML, it is parsed and embedded documents are requested. This function implements a RFC1867-compliant file upload function for form-based file upload in HTML.

This is a mapping to WebPageSubmitBin function, and uses a form specified in the dclform section to construct the data to post to the server.

The form consists of name-value pairs as usual, only the files to upload need a minor modification: a file to upload needs to be specified by a name-value pair in the following way:

"filename" := "<name of the input tag>;<file name>;<content type>";

Example

Upload of file c:\test.txt

HTML code:

<form enctype="multipart/form-data" action="data2html.asp" method=post>
  <input type="text" name="anyname" value="anyvalue">
  <input size="32" name="my_file" type="file">
  <input type="submit" value="Upload">
</form>

BDL form:

"anyname"  := "anyvalue",
"filename" := "my_file;C:\\test.txt;plain/text";

Include file

WebAPI.bdh

Syntax

WebPageSubmitFileUpload( in sHtmlForm  : string allownull,
                         in formSubmit : form,
                         in sTimer     : string optional,
                         in nFormNo    : number optional,
                         in sFrame     : string optional,
                         in hContext   : number optional) : boolean;

Return value

  • true if successful

  • false otherwise

Parameter | Description
sHtmlForm | The name of the HTML form to search for in the currently active Web page, or if the hContext parameter is not omitted in the specified context. Set this parameter to NULL if a name is not available or if you want to identify the HTML form only by its number.
formSubmit | Form identifier used in the dclform section. The expanded form is added to the body of the request. The Content-Length is added automatically. The Content-Type is multipart/form-data.
sTimer | Name of the timer used for page measurements (optional). If this parameter is omitted, no measurements are performed.
nHtmlFormNo | Number of the Web form in the Web page (optional). If sHtmlForm is NULL, the number specifies the n-th form in the page. If sHtmlForm specifies a name, the number specifies the n-th form with the given name.
sFrame | The name of the frame the document is assigned to (optional). If this parameter is provided, the form is searched only within this frame document.
hContext | Context, stored by a prior call of the WebPageStoreContext function, where to search for the form (optional). If this parameter is omitted the form is searched in the actual page and all stored contexts.

Example

dcltrans
  transaction TWebPageSubmitFileUpload
  begin
    WebPageUrl("http://lab1/", "Test Site");
    WebPageLink("File Upload Samples", "Form-based File Upload ");
    WebPageSubmitFileUpload("uploadform", FILE_UPLOAD_FORM,
"File Upload Results");
  end TWebPageSubmitFileUpload;

dclform
  FILE_UPLOAD_FORM:
    "anyname"  := "anyvalue",
    "filename" := "my_file;C:\\temp\\test.doc;application/msword";
Parent topic: Page-Level Web Functions Overview
Related reference
WebPageSubmitBin Function


WebPageFileUpload Function

Action

Posts the content of a Web form, including specified files, to the Web server by means of the HTTP POST method. This function implements a RFC1867-compliant file upload function for form-based file upload in HTML.

This is a mapping to WebPagePost, and uses a form specified in the dclform section to construct the data to post to the server.

The form consists of name-value pairs as usual, only the files to upload need a minor modification: a file to upload needs to be specified by a name-value pair in the following way:

"filename" := "<name of the input tag>;<file name>;<content type>";

Example

Upload of file c:\test.txt

HTML code:

<form enctype="multipart/form-data"
action="data2html.asp" method=post>
  <input type="text" name="anyname" value="anyvalue">
  <input size="32" name="my_file" type="file">
  <input type="submit" value="Upload">
</form>

BDL form:

"anyname"  := "anyvalue", "filename" := "my_file;C:\\test.txt;plain/text";

Include file

WebAPI.bdh

Syntax

WebPageFileUpload( in sUrl     : string,
                   in formBody : form,
                   in sTimer   : string optional,
                   in formUrl  : form optional ) : boolean;

Return value

  • true if successful

  • false otherwise

Parameter | Description
sUrl | Complete URL to the file on the server.
formBody | Form identifier used in the dclform section (see example below). The expanded form is added to the body of the request. The Content-Length is added automatically. The Content-Type is multipart/form-data.
sTimer | Name of the timer used for page measurements (optional). If this parameter is omitted, no measurements are performed.
formUrl | Form identifier used in the dclform section (optional). The expanded form is added to the URL after the "?".

Example

dcltrans
  transaction TWebPageFileUpload
  begin
    WebPageFileUpload("http://standardhost/data2html.asp",
                      FILE_UPLOAD_FORM);
  end TWebPageFileUpload;

dclform
  FILE_UPLOAD_FORM:
    "anyname"  := "anyvalue",
    "filename" := "my_file;"
                  "C:\\temp\\test.doc;application/msword";
Parent topic: Page-Level Web Functions Overview
Related reference
WebPagePost Function


WebPageAddUrl Function

Action

This function specifies an additional URL to be downloaded by the next page-level web function call (e.g.: WebPageUrl, WebPageLink).

This function specifies an additional URL to be downloaded by the next page-level web function call (e.g.: WebPageUrl, WebPageLink). This can be used to simulate the loading of documents done by JavaScript or applets.

Note: This function does not perform any network requests. The subsequent WebPage function call will include this URL in the Web page download. Thus, the page download timer will correctly include the download of these documents.

Include file

WebAPI.bdh

Syntax

WebPageAddUrl(in sUrl : string,
              in formUrl : form optional,
              in nCount : number optional) : boolean;

Return value

  • true if the URL was added successfully

  • false otherwise

Parameter | Description
sUrl | Absolute or relative URL to the file on the server. All characters that are part of the query string are not URL-encoded. A relative URL is resolved to an absolute URL base on the URL that is downloaded by the next page-level Web API function call.
formUrl | Form identifier used in the dclform section (optional). The expanded form string is appended to the URL after the "?". All unsafe characters are URL-encoded.
nCount | The specified URL is added nCount times.

Example

dcltrans
transaction TMain
begin
  // absolute URL
  WebPageAddUrl("http://adimages.lab3/advertisement.gif");
  // relative URL, absolute path - downloads: "http://lab3/images/banner.gif"
  WebPageAddUrl("banner.gif");
  // relative URL, query string, 3 times
  // downloads: "http://lab3/images/product.asp?code=2"
  WebPageAddUrl("product.asp", SHOPIT_PRODUCT_ASP002, 3);
  WebPageUrl("http://lab3/shopit/", "ShopIt - Product");
end TMain;
dclform
  SHOPIT_PRODUCT_ASP002:
    "code" := "2";
Parent topic: Page-Level Web Functions Overview


WebPageQueryLink Function

Action

This function queries the currently active page context for hyperlinks. The query can be specified by defining a substring which has to occur in the hyperlinks URL (tag “href”) or by providing the number of the link. The results are the hyperlink’s name, the URL and the sequential number if the hyperlink is found.

Include file

WebAPI.bdh

Syntax

WebPageQueryLink( in  sUrlFilter   : string allownull,
                  in  nLinkNo      : number optional,
                  out sLinkName    : string optional,
                  in  nLinkNameLen : number optional,
                  out sUrl         : string optional,
                  in  nMaxUrlLen   : number optional,
                  in  sFrame       : string optional,
                  in  nMode        : number optional ): number;

Return value

  • the sequential number of the hyperlink found.

  • zero otherwise.

Parameter | Description
sUrlFilter | String which has to occur in the hyperlink's URL (tag “href”). Specify NULL to query for all hyperlinks.
nLinkNo | Hyperlink number to query for. If sUrlFilter is NULL, the function queries the n-th hyperlink in the page. Otherwise, the function queries the n-th hyperlink that matches the filter. Specify zero to use only the filter.
sLinkName | String variable that receives the name of the hyperlink (optional). See the WebPageLink function for naming rules.
nLinkNameLen | Maximum length of the hyperlink name to return (optional). This value must be less than or equal to the size of the string variable sLinkName.
sUrl | String receiving the URL the hyperlink refers to (optional). See the WebPageLink function for naming rules.
nMaxUrlLen | Maximum length of the URL string to return. This value must be less than or equal to the size of the string variable sUrl.
sFrame | The name of the frame the document is assigned to (optional). If this parameter is provided, the hyperlink is searched only within this frame document.
nMode

This can be any combination of the following values (optional):

  • WEB_QUERY_FLAG_LAST_PAGE (default)

  • WEB_QUERY_FLAG_HISTORY

  • WEB_QUERY_FLAG_STORED_CONTEXTS

Example

dcltrans
  transaction TMain
  var
    nLinkNo : number;
    sLink   : string(100);
    sUrl    : string(200);
  begin
    WebPageUrl("http://www.mytestmall.com/welcome_new.asp",
               "New Shopper");
    WebPageLink("Store Directory", "Product Listing Page");

    // search for the first hyperlink
    // with the string "pfid" in the URL
    nLinkNo := WebPageQueryLink("pfid", 0, sLink, STRING_COMPLETE, sUrl);

    // write test output
    write("link = "); writeln(sLink);
    write("URL = "); writeln(sUrl);

    // now request the page of the selected product
    WebPageLink(sLink, "SelectProductFromListing");
  end TMain;

Example

dcltrans
  transaction TQueryAllLinks
  var
    sName : string;
    i     : number;
  begin
    WebPageUrl("http://www.mycompany.com/");

    i := 1;
    while (WebPageQueryLink(NULL, i, sName, STRING_COMPLETE) > 0) do
      Print(string(i) + ". link: " + sName);
      i := i+1;
    end;

    Print(string(i-1) + " hyperlinks found");
  end TQueryAllLinks;
Parent topic: Page-Level Web Functions Overview
Related reference
WebPageLink Function


WebPageCustomRequest Function

Action

Requests and reads a complete document specified by a URL using the specified HTTP method. If the retrieved document is of content type HTML, it is parsed, and embedded documents are requested.

Include file

WebAPI.bdh

Syntax

WebPageCustomRequest( in sMethod  : string,
                      in sUrl     : string,
                      in formBody : form optional,
                      in sTimer   : string optional,
                      in formUrl  : form optional ): boolean;

Return value

  • true if successful

  • false otherwise

Parameter | Description
sMethod | HTTP method used for the request (like GET, POST, or M-GET).
sUrl | Absolute URL to the file on the server. The entire character content of the query string will not be URL-encoded.
formBody

Form identifier used in the dclform section (optional). The expanded form is added to the body of the request. The Content-Length and Content-Type headers are added automatically. The default Content-Type is "application/x-www-form-urlencoded" and can be overwritten by a WebHeaderAdd("Content-Type", "myEncoding") function call prior to the WebPageCustomRequest function call.

Set this parameter to FORM_NULL if you do not want to specify a form. You would do this when you want to specify the following parameters but want to omit this parameter.
sTimer | Name of the timer used for page measurements (optional). If this parameter is omitted, no measurements are performed.
formUrl | Form identifier used in the dclform section (optional). The expanded form string is appended to the URL after the "?". All unsafe characters are URL-encoded.

Example

dcltrans
  transaction TMain
  begin
    WebPageCustomRequest("GET", "http://standardhost/product.asp?code=2");
    WebPageCustomRequest("M-POST", "http://standardhost/product.asp",
      SHOPIT_PRODUCT_ASP003, "ShopIt - Product", SHOPIT_PRODUCT_ASP002);
  end TMain;

dclform
  SHOPIT_PRODUCT_ASP002:
    "code" := "2";
  SHOPIT_PRODUCT_ASP003:
    "tent" := "1";
Parent topic: Page-Level Web Functions Overview
Related reference
WebPageCustomRequestBin Function


WebPageCustomRequestBin Function

Action

Requests and reads a complete document specified by a URL using the specified HTTP method. The optional request body consists of binary data. If the retrieved document is of content type HTML, it is parsed, and embedded documents are requested.

Include file

WebAPI.bdh

Syntax

WebPageCustomRequestBin( in sMethod     : string,
                         in sUrl        : string,
                         in sData       : string,
                         in nDataLength : number optional,
                         in sContent    : string optional,
                         in sTimer      : string optional,
                         in formUrl     : form optional): boolean;

Return value

  • true if successful

  • false otherwise

Parameter | Description
sMethod | HTTP method used for the request (like GET, POST, or M-GET).
sUrl | Absolute URL to the file on the server. The entire character content of the query string will not be URL-encoded.
sData | Data to post to the server. This may also be binary data. For posting all available binary data specify STRING_COMPLETE for nDataLength and use the bin() operator for sData (see example).
nDataLength | Amount of the data that is posted to the server (in bytes). Specify STRING_COMPLETE or omit this parameter to post all available data.
sContent | Content type string used in the request, for example, "image/gif" (optional). If this parameter is omitted, an "application/x-www-form-urlencoded" header is sent.
sTimer | Name of the timer used for page measurements (optional). If this parameter is omitted, no measurements are performed.
formUrl | Form identifier used in the dclform section (optional). The expanded form string is appended to the URL after the "?". All unsafe characters are URL-encoded.

Example

dcltrans
  transaction TMain
  var
    sData: string(4);
  begin
    SetLong(sData, 1, 15708);
    WebPageCustomRequest("GET", "http://standardhost/product.asp?code=2");
    WebPageCustomRequestBin("M-POST", "http://standardhost/product.asp", bin(sData),
        STRING_COMPLETE, "application/octet-stream",
        "M-Post", SHOPIT_PRODUCT_ASP002);
  end TMain;

dclform
  SHOPIT_PRODUCT_ASP002:
    "code" := "2";
Parent topic: Page-Level Web Functions Overview
Related reference
WebPageCustomRequest Function
WebPageCustomRequestFile Function
WebCustomRequest Function


WebPageCustomRequestFile Function

Action

Requests and reads a complete document specified by a URL using the specified HTTP method. The optional request body consists of binary data. If the retrieved document is of content type HTML, it is parsed, and embedded documents are requested.

Include file

WebAPI.bdh

Syntax

WebPageCustomRequestFile( in sMethod  : string,
                          in sUrl     : string,
                          in sFile    : string,
                          in sContent : string optional,
                          in sTimer   : string optional,
                          in formUrl  : form optional): boolean;

Return value

  • true if successful

  • false otherwise

Parameter | Description
sMethod | HTTP method used for the request (like GET, POST, or M-GET).
sUrl | Absolute URL to the file on the server. The entire character content of the query string will not be URL-encoded.
sFile | File to post to the server.
sContent | Content type string used in the request, for example, "image/gif" (optional). If this parameter is omitted, an "application/x-www-form-urlencoded" header is sent.
sTimer | Name of the timer used for page measurements (optional). If this parameter is omitted, no measurements are performed.
formUrl | Form identifier used in the dclform section (optional). The expanded form string is appended to the URL after the "?". All unsafe characters are URL-encoded.

Example

dcltrans
  transaction TMain
  var
    sFile: string;
  begin
    sFile := "c:\\temp\\dummyfile.txt";
    WebPageCustomRequest("GET", "http://standardhost/product.asp?code=2");
    WebPageCustomRequestFile("M-POST", "http://standardhost/product.asp", sFile,
                             "application/octet-stream", "M-Post", SHOPIT_PRODUCT_ASP002);
  end TMain;

dclform
  SHOPIT_PRODUCT_ASP002:
    "code" := "2";
Parent topic: Page-Level Web Functions Overview
Related reference
WebPageCustomRequest Function


WebPageStoreContext Function

Action

Stores the context of the last page in the history, so that it will be available to all subsequent WebPageLink and WebPageSubmit calls. The available memory places are limited to 10 stored contexts. Call the WebPageDeleteContext function if the stored context is not needed any more.

The function call WebBrowserReset(WEB_RESET_ALL) deletes all stored contexts!

Include file

WebAPI.bdh

Syntax

WebPageStoreContext( inout hContext: number ): boolean;

Return value

  • true if the context is stored successfully

  • false otherwise

Parameter | Description
hContext | Variable that receives a handle to the stored context (used for a call to the WebPageDeleteContext function only.

Example

dcltrans
  transaction TInit
  begin
    //WebSetBrowser(WEB_BROWSER_MSIE5);
    WebSetUserBehavior(WEB_USERBEHAVIOR_FIRST_TIME);
    WebSetDocumentCache(true, WEB_CACHE_CHECK_SESSION);
  end TInit;

  transaction TMain
  var
    hContext: number;
  begin
    WebPageUrl("http://mycompany.com/");
    WebPageStoreContext(hContext);
    WebPageLink("Internet Compliancy Tests");
    WebPageLink("Frame Tests");
    WebPageLink("sample", "Main Frame");
    WebPageUrl("http://quote.broker.com/");
    WebPageLink("quotes", "Document Moved");
    // this is a link of the page: "http://mycompany.com/"
    WebPageLink("VCRocket", "VCRocket", 0, NULL, hContext);
    WebPageDeleteContext(hContext);
  end TMain;
Parent topic: Page-Level Web Functions Overview
Related reference
WebPageDeleteContext Function


WebPageDeleteContext Function

Action

Deletes a context stored by a call of the WebPageStore function.

Include file

WebAPI.bdh

Syntax

WebPageDeleteContext(in hContext: number): boolean;

Return value

  • true if the context is deleted successfully

  • false otherwise

Parameter | Description
hContext | Handle to a stored context.

Example

dcltrans
  transaction TInit
  begin
    //WebSetBrowser(WEB_BROWSER_MSIE5);
    WebSetUserBehavior(WEB_USERBEHAVIOR_FIRST_TIME);
    WebSetDocumentCache(true, WEB_CACHE_CHECK_SESSION);
  end TInit;

  transaction TMain
  var
    hContext: number;
  begin
    WebPageUrl("http://mycompany.com/");
    WebPageStoreContext(hContext);
    WebPageLink("Internet Compliancy Tests");
    WebPageLink("Frame Tests");
    WebPageLink("sample", "Main Frame");
    WebPageUrl("http://quote.broker.com/");
    WebPageLink("quotes", "Document Moved");
    // this is a link of the page: "http://mycompany.com/"
    WebPageLink("VCRocket", "VCRocket", 0, NULL, hContext);
    WebPageDeleteContext(hContext);
  end TMain;
Parent topic: Page-Level Web Functions Overview
Related reference
WebPageStoreContext Function


WebPageSuppress function

Action

Specifies a file that must not be loaded by future Web function calls.

Include file

WebAPI.bdh

Syntax

WebPageSuppress(in sUrl: string): boolean;

Return value

  • true if the file is successfully added to the suppress list

  • false otherwise

Parameter | Description
sUrl | Absolute URL to the file on the server.

Example

dcltrans
transaction TMain
begin
WebPageSuppress("http://mycompany.com/t?s=all");
WebPageUrl("http://mycompany.com/");
WebPageLoadAll();
WebPageUrl("http://mycompany.com/");
end TMain;
Parent topic: Page-Level Web Functions Overview
Related reference
WebPageLoadAll Function
WebSetDomainSuppress Function


WebPageLoadAll Function

Action

Clears all suppress-file entries added by prior calls to the WebPageSuppress function. No files are suppressed any more.

Include file

WebAPI.bdh

Syntax

WebPageLoadAll(): boolean;

Return value

  • true if the suppress-file list is cleared successfully

  • false otherwise

Example

dcltrans
transaction TMain
begin
WebPageSuppress("http://mycompany.com/t?s=all");
WebPageUrl("http://mycompany.com/");
WebPageLoadAll();
WebPageUrl("http://mycompany.com/");
end TMain;
Parent topic: Page-Level Web Functions Overview
Related reference
WebPageSuppress function
WebSetDomainSuppress Function


WebPageSetActionUrlAbs Function

Action

Modifies the action URL of a subsequent WebPageSubmit or WebPageSubmitBin function using an absolute URL specified by the sUrl parameter.

If only the action URL of an HTML form is changed with client side scripting, all fields of the parsed form can be used and the action URL can be changed to any valid URL using this function.

Include file

WebAPI.bdh

Syntax

WebPageSetActionUrlAbs(  in sUrl    : string,
                         in formUrl : form optional ): boolean;

Return value

  • true if the operation completed successfully

  • false otherwise

Parameter | Description
sUrl | Absolute URL to the file on the server. All characters that are part of the query string are not URL-encoded.
formUrl | Form identifier used in the dclform section (optional). The expanded form string is appended to the URL after the "?". All unsafe characters are URL-encoded.

Example

dcltrans
  transaction TMain
  begin
    WebPageUrl("http://lab3/shopit/", "ShopIt - Greetings");
    WebPageLink("Join the experience!", "ShopIt - New Visitor");
    WebPageSetActionUrlAbs("http://lab3/welcome.asp");
    WebPageSubmit("Continue", FORM_NULL, "ShopIt - Main menu")
  end TMain;
Parent topic: Page-Level Web Functions Overview


WebPageSetActionUrl Function

Action

Modifies the action URL of a subsequent WebPageSubmit or WebPageSubmitBin function using a URL parsed by a call to the WebPageParseUrl function.

If only the action URL of an HTML form is changed with client side scripting, all fields of the parsed form can be used and the action URL can be changed to any parsed URL.

Include file

WebAPI.bdh

Syntax

WebPageSetActionUrl( in sUrl     : string,
                     in nUrlNo   : number optional,
                     in sFrame   : string optional,
                     in hContext : number optional): boolean;

Return value

  • true if the operation completed successfully

  • false otherwise

Parameter | Description
sUrl | Specifies the URL (parsed by a call to WebPageParseUrl) of which the URL should be used as action URL in the subsequent form submission. This URL is searched in the currently active Web page, or if the hContext parameter is not omitted it is searched in the specified context.
nUrlNo | Number of the URL in the specified frame (optional). The first appearance is taken if this parameter is omitted.
sFrame | Specifies the frame where to search the URL.
hContext | Context, stored by a prior call of the WebPageStoreContext function, where to search the URL (optional). If this parameter is omitted the URL is searched in the actual page and all stored contexts.

Example

dcltrans
  transaction TMain
  begin
    WebPageParseUrl("Continue", "load=\"", "\"");
    WebPageUrl("http://lab3/shopit/", "ShopIt - Greetings");
    WebPageLink("Join the experience!", "ShopIt - New Visitor");
    WebPageSetActionUrl("Continue");
    WebPageSubmit("buy", FORM_BUY, "ShopIt - Main menu");
  end TMain;

dclform
  FORM_BUY;
Parent topic: Page-Level Web Functions Overview


WebPageParseUrl Function

Action

Modifies the html-parser to find additional hyperlinks (for subsequent WebPageLink functions) and URLs, which can be used in subsequent WebPageSetActionUrl or WebPageQueryParsedUrl commands. A name must be specified, which is assigned to the links and URLs. A CR or LF between the beginning of the left boundary and the end of the right boundary is not allowed.

More than one WebPageParseUrl statements can be placed before a page-level API call, resulting in multiple parsing rules applied concurrently during downloading of the page.

Note: A sub-sequent WebPageParseUrl call with the same sName parameter removes any parsed results from the first WebPageParseUrl call.

Include file

WebAPI.bdh

Syntax

WebPageParseUrl( in sName          : string,
                 in sLeftBoundary  : string optional,
                 in sRightBoundary : string optional,
                 in nOptions       : number optional ) : boolean;

Return value

  • none

Parameter | Description
sName | Name that is assigned to all links and URLs found.
sLeftBoundary | Left boundary string of the link or URL to search for (optional). If this parameter is omitted the parsing starts at the beginning of the document.
sRightBoundary | Right boundary string of the link or URL to search for (optional). If this parameter is omitted the parsing stops at the end of the document.
nOptions

Set to any combination of the following flags:

WEB_FLAG_CASE_SENSITIVE
If this flag is set the string compare operation is case sensitive.
WEB_FLAG_IGNORE_WHITE_SPACE
If this flag is set all white spaces are ignored.
WEB_FLAG_DONT_FORCE_LOAD
Specify this option to enable caching for subsequent request. Note that only documents are parsed which are downloaded (no cache hit).
WEB_FLAG_PARSE_URL
Specify this flag to enable the usage of the found URLs in subsequent calls to WebPageSetActionUrl and WebPageQueryParsedUrl.
WEB_FLAG_PARSE_LINK
Specify this flag to enable the usage of the found URLs in subsequent calls to WebPageLink.

If neither, WEB_FLAG_PARSE_URL nor WEB_FLAG_PARSE_LINK are specified a combination of the two flags is used.

Example

dcltrans
  transaction TMain
  begin
    WebPageParseUrl("Continue", "load=\"", "\"");
    WebPageUrl("http://lab3/shopit/", "ShopIt - Greetings");
    WebPageLink("Join the experience!", "ShopIt - New Visitor");
    WebPageSetActionUrl("Continue");
    WebPageSubmit("unnamed", FORM_NULL, "ShopIt - Main menu");
  end TMain;
Parent topic: Page-Level Web Functions Overview
Related reference
WebPageSetActionUrl Function
WebPageQueryParsedUrl Function


WebPageQueryParsedUrl Function

Action

This function is used to retrieve the URL parsed because of a WebPageParseUrl function call with the WEB_FLAG_PARSE_URL flag set.

Include file

WebAPI.bdh

Syntax

WebPageQueryParsedUrl( out sResult    : string,
                       in  nResultLen : number,
                       in  sUrl       : string,
                       in  nUrlNumber : number optional,
                       in  sFrame     : string optional,
                       in  hContext   : number optional): boolean;

Return value

  • true if successful

  • false otherwise

Parameter | Description
sResult | String variable that receives the parsed URL.
nResultLen | Maximum length of the URL to return. This value must be less than or equal to the size of the string variable sUrl.
sUrl | Name that has been specified by the WebPageParseUrl command
nUrlNumber | The nUrlNumber appearance of the URL is retrieved (optional). If this parameter is omitted the first appearance is taken.
sFrame | The name of the frame the where the URL should be searched (optional). If this parameter is provided, the URL is searched only within this frame document.
hContext | Context, stored by a prior call of the WebPageStoreContext function, where to search the URL (optional). If this parameter is omitted the URL is searched in the actual page and all stored contexts.

Example

dcltrans
  transaction TMain
  var
    sResult : string;
  begin
    WebPageParseUrl("Continue", "load=\"", "\"");
    WebPageUrl("http://lab3/shopit/", "ShopIt - Greetings");
    WebPageLink("Join the experience!", "ShopIt - New Visitor");
    WebPageQueryParsedUrl(sResult, STRING_COMPLETE, "Continue", 2);
    WebPageUrl(sResult, "Continue");
  end TMain;
Parent topic: Page-Level Web Functions Overview


Asynchronous Communication Functions

  • WebAsyncPreparePush Function
    Prepares an asynchronous communication channel for the push model.
  • WebAsyncPreparePoll Function
    Prepares an asynchronous communication channel for the poll model.
  • WebAsyncPrepareLongPoll Function
    Prepares an asynchronous communication channel for the long poll model.
  • WebAsyncGetResponseHeaders Function
    Retrieves the HTTP headers of the response.
  • WebAsyncStop Function
    Stops an asynchronous communication channel and aborts outstanding requests of this channel.
  • WebSocketConnect Function
    Connects to a WebSocket server and establishes an asynchronous bidirectional communication channel.
  • WebSocketConnectSync Function
    Connects to a WebSocket server and establishes a synchronous bidirectional communication channel.
  • WebSocketClose Function
    Closes the WebSocket communication channel.
  • WebSocketSendTextMessage Function
    Sends a text message to the WebSocket server. The function does not wait for a response.
  • WebSocketSendBinaryMessage Function
    Sends a binary message to the WebSocket server. The function does not wait for a response.
  • WebSocketReceiveMessage Function
    Receives a WebSocket message from the server.
Parent topic: Web Functions Reference
Related concepts
Testing WebSocket Connections


WebAsyncPreparePush Function

Action

Prepares an asynchronous communication channel for the push model. The next BDL API call must be a low-level web API call, which will initiate an asynchronous communication channel. Asynchronous page-level API calls are not supported. The asynchronous request(s) happen in the background and will be executed in parallel to subsequent BDL API calls in the script.

An asynchronous communication channel is closed either by calling the BDL function WebAsyncStop() or when the browser session ends or at the end of the transaction if first time user behaviour is configured.

The callback will be called for each message part sent from the server and once with an empty sResponseBody argument when the communication channel is closed (end of response).

Include file

webapi.bdh

Syntax

WebAsyncPreparePush( in cbResponseCallback : callback optional ): number;
Parameter | Description
cbResponseCallback | The asynchronous response callback function. It has to be passed with the callback keyword (for example: callback(FCallback). The function has to be declared as follows: function FWebAsyncResponseCallback(sResponseBody : string) <ASYNC_CALLBACK_FUNCTION>. The function has to be of type ASYNC_CALLBACK_FUNCTION. sResponseBody of the callback contains the content of the current response message part.

Return value

Returns a handle to the prepared asynchronous communication channel. This value has to be passed to WebAsyncStop() to stop the asynchronous communication and close the channel.

Example

dclfunc
  function FAsyncCallback(sResponseBody : string) <ASYNC_CALLBACK_FUNCTION>
  begin
    RepMessage("MESSAGE: '" + sResponseBody + "'", SEVERITY_INFORMATIONAL);
    if (StrSearch(sResponseBody, "last message", STR_SEARCH_FIRST) <> 0) then
      UserSignal("LastMessage");
    end;
  end FAsyncCallback;

dcltrans
  transaction TMainListen
  var
    nAsyncChannel : number;
  begin
    WebPageUrl("http://demo.borland.com:8080/atmosphere-meteor-pubsub-2.1.3/", "/atmosphere-meteor-pubsub-2.0.3/");
    nAsyncChannel := WebAsyncPreparePush(callback(FAsyncCallback));
    WebFormGet("http://demo.borland.com:8080/atmosphere-meteor-pubsub-2.1.3/pubsub/mychannel_1234",
      METEOR_PUB_SUB_FORM);

    UserWaitFor("LastMessage", 60);

    WebAsyncStop(nAsyncChannel);

  end TMainListen;
Parent topic: Asynchronous Communication Functions
Related concepts
Testing Asynchronous Communication on the Protocol Level
Related reference
WebAsyncPreparePoll Function
WebAsyncPrepareLongPoll Function


WebAsyncPreparePoll Function

Action

Prepares an asynchronous communication channel for the poll model. The next BDL API call must be a low-level web API call, which will initiate an asynchronous communication channel. Asynchronous page-level API calls are not supported. The asynchronous request(s) happen in the background and will be executed in parallel to subsequent BDL API calls in the script.

An asynchronous communication channel is closed either by calling the BDL function WebAsyncStop() or when the browser session ends or at the end of the transaction if first time user behaviour is configured.

The poll requests will be performed automatically at the specified interval until the asynchronous communication channel is closed. The callback will be called exactly once for each poll request.

Include file

webapi.bdh

Syntax

WebAsyncPreparePoll( in fInterval          : double,
                     in cbResponseCallback : callback optional ): number;
Parameter | Description
fInterval | The interval of the poll requests in seconds. If a poll request takes longer than the interval time, the following request will be performed immediately afterwards.
cbResponseCallback | The asynchronous response callback function. It has to be passed with the callback keyword (for example: callback(FCallback). The function has to be declared as follows: function FWebAsyncResponseCallback(sResponseBody : string) <ASYNC_CALLBACK_FUNCTION>. The function has to be of type ASYNC_CALLBACK_FUNCTION. sResponseBody of the callback contains the content of the current response message part.

Return value

  • true if successful

  • false otherwise

Example

dclfunc
  function FAsyncCallback(sResponseBody : string) <ASYNC_CALLBACK_FUNCTION>
  var
  begin
     RepMessage("RESPONSE: " + sResponseBody, SEVERITY_INFORMATIONAL);
  end FAsyncCallback;

dcltrans
  transaction TMain
  var
    nAsyncChannel : number;
  begin
    WebPageUrl("http://ajaxify.com/run/wiki/", "Ajax Wiki Demo");

    nAsyncChannel := WebAsyncPreparePoll(5.0, callback(FAsyncCallback));
    WebFormGet("http://ajaxify.com/run/wiki/content.php", WIKI_MESSAGES);

    Wait(23.0);

    WebAsyncStop(nAsyncChannel); // can be ommitted at the end of the transaction/script

  end TMain;
Parent topic: Asynchronous Communication Functions
Related concepts
Testing Asynchronous Communication on the Protocol Level
Related reference
WebAsyncPreparePush Function
WebAsyncPrepareLongPoll Function


WebAsyncPrepareLongPoll Function

Action

Prepares an asynchronous communication channel for the long poll model. The next BDL API call must be a low-level web API call, which will initiate an asynchronous communication channel. Asynchronous page-level API calls are not supported. The asynchronous request(s) happen in the background and will be executed in parallel to subsequent BDL API calls in the script.

An asynchronous communication channel is closed either by calling the BDL function WebAsyncStop() or when the browser session ends or at the end of the transaction if first time user behaviour is configured.

Long poll requests are performed automatically until the asynchronous communication channel is closed. One long poll request follows immediately after the other. The callback will be called for each response message part received from the server and with an empty sResponseBody argument once the communication channel is closed.

Include file

webapi.bdh

Syntax

WebAsyncPrepareLongPoll( in cbResponseCallback : callback optional ): number;
Parameter | Description
cbResponseCallback | The asynchronous response callback function. It has to be passed with the callback keyword (for example: callback(FCallback). The function has to be declared as follows: function FWebAsyncResponseCallback(sResponseBody : string) <ASYNC_CALLBACK_FUNCTION>. The function has to be of type ASYNC_CALLBACK_FUNCTION. sResponseBody of the callback contains the content of the current response message part.

Return value

  • true if successful

  • false otherwise

Example

var
  nTrackingId : number;
dclfunc
  function FAsyncCallback(sResponseBody : string) <ASYNC_CALLBACK_FUNCTION>
  begin
    if Strlen(sResponseBody) = 0 then return end;

    RepMessage("MESSAGE: '" + sResponseBody + "'", SEVERITY_INFORMATIONAL);

    if (nTrackingId >= 5) then
      UserSignal("LastMessage");
    else
      nTrackingId := nTrackingId+1;
    end;
  end FAsyncCallback;

dcltrans
  transaction TMain
  var
    nAsyncChannel : number;
  begin
    nTrackingId := 0;

    nAsyncChannel := WebAsyncPrepareLongPoll(callback(FAsyncCallback));
    WebFormGet("http://lnz-testsite/showImage.php", FORM_PARAMS);

    UserWaitFor("LastMessage", 60);

    WebAsyncStop(nAsyncChannel);
  end TMain;

dclform

  FORM_PARAMS:
    "timewait"   := 1,
    "id="        := nTrackingId;
Parent topic: Asynchronous Communication Functions
Related concepts
Testing Asynchronous Communication on the Protocol Level
Related reference
WebAsyncPreparePush Function
WebAsyncPreparePoll Function


WebAsyncGetResponseHeaders Function

Action

Retrieves the HTTP headers of the response sent by the server through an asynchronous communication channel. This function can only be called in an asynchronous callback function.

Include file

webapi.bdh

Syntax

WebAsyncGetResponseHeaders( out sHeaders : string ): boolean;
Parameter | Description
sHeaders | Out variable, which receives the HTTP headers string.

Return value

  • true if successful

  • false otherwise

Example

dclfunc
  function FAsyncCallback(sResponseBody : string) <ASYNC_CALLBACK_FUNCTION>
  var
    sHeader : string;
  begin
    WebAsyncGetResponseHeaders(sHeader);
    RepMessage("HEADER: '" + sHeader + "'", SEVERITY_INFORMATIONAL);
    RepMessage("MESSAGE: '" + sResponseBody + "'", SEVERITY_INFORMATIONAL);

   if (StrSearch(sResponseBody, "last message", STR_SEARCH_FIRST) <> 0) then
      UserSignal("LastMessage");
    end;
  end FAsyncCallback;

dcltrans
  transaction TMainListen
  var
    nAsyncChannel : number;
    sParsedTrackingId : string;
  begin
    WebPageUrl("http://demo.borland.com:8080/atmosphere-meteor-pubsub-2.1.3/", "/atmosphere-meteor-pubsub-2.0.3/");

    Print("sTrackingId: '" + sTrackingId + "'");

    WebParseDataBoundEx(sParsedTrackingId, STRING_COMPLETE, "\n", 0, "|", WEB_FLAG_ALL_RESPONSES | WEB_FLAG_CASE_SENSITIVE, 1);
    WebFormGet("http://demo.borland.com:8080/atmosphere-meteor-pubsub-2.1.3/pubsub/mychannel_1234",
      METEOR_PUB_SUB_FORM, 5.0);

    sTrackingId := sParsedTrackingId;
    Print("sTrackingId: '" + sParsedTrackingId + "'");

    nAsyncChannel := WebAsyncPrepareLongPoll(callback(FAsyncCallback));
    WebFormGet("http://demo.borland.com:8080/atmosphere-meteor-pubsub-2.1.3/pubsub/mychannel_1234",
      METEOR_PUB_SUB_FORM);

    UserWaitFor("LastMessage", 60);

    WebAsyncStop(nAsyncChannel);

  end TMainListen;
Parent topic: Asynchronous Communication Functions


WebAsyncStop Function

Action

Stops an asynchronous communication channel and aborts outstanding requests of this channel.

Include file

webapi.bdh

Syntax

WebAsyncStop( nAsyncHandle : number ): boolean;
Parameter | Description
nAsyncHandle | The handle value of the asynchronous communication channel, which was returned by a preceding WebAsyncPrepare...() function.

Return value

  • true if successful

  • false otherwise

Example

dclfunc
  function FAsyncCallback(sResponseBody : string) <ASYNC_CALLBACK_FUNCTION>
  begin
    RepMessage("MESSAGE: '" + sResponseBody + "'", SEVERITY_INFORMATIONAL);
    if (StrSearch(sResponseBody, "last message", STR_SEARCH_FIRST) <> 0) then
      UserSignal("LastMessage");
    end;
  end FAsyncCallback;

dcltrans
  transaction TMainListen
  var
    nAsyncChannel : number;
  begin
    WebPageUrl("http://demo.borland.com:8080/atmosphere-meteor-pubsub-2.1.3/", "/atmosphere-meteor-pubsub-2.0.3/");
    nAsyncChannel := WebAsyncPreparePush(callback(FAsyncCallback));
    WebFormGet("http://demo.borland.com:8080/atmosphere-meteor-pubsub-2.1.3/pubsub/mychannel_1234",
      METEOR_PUB_SUB_FORM);

    UserWaitFor("LastMessage", 60);

    WebAsyncStop(nAsyncChannel);

  end TMainListen;
Parent topic: Asynchronous Communication Functions


WebSocketConnect Function

Action

Connects to a WebSocket server and establishes an asynchronous bidirectional communication channel.

Include file

webapi.bdh

Syntax

WebSocketConnect( in sUrl               : string,
                  in csResponseCallback : callback <ASYNC_CALLBACK_FUNCTION> optional ): number

Parameter | Description
sUrl | The URL of the WebSocket server. A WebSocket URL in JavaScript usually looks like this: ws://echo.websocket.org In Silk Performer, you have to specify http instead of ws, for example: http://echo.websocket.org
csResponseCallback | The asynchronous response callback function. It has to be passed with the callback keyword (for example: callback(FCallback). The function has to be declared as follows: function WebSocketConnect(csResponseCallback : string) <ASYNC_CALLBACK_FUNCTION>. The function has to be of type ASYNC_CALLBACK_FUNCTION. csResponseCallback of the callback contains the content of the current response message part.

Return value

  • a handle, which identifies the WebSocket, if the connection was established successfully
  • false otherwise

Example

 transaction TMain
  var
    hWebSocket : number;
  begin
    hWebSocket := WebSocketConnect("http://echo.websocket.org", callback(FWebSocketMessageReceived));

    WebSocketSendTextMessage(hWebSocket, "Rock it with HTML5 WebSocket");

    Print("Waiting...");
    Wait(4.1);

    WebSocketSendTextMessage(hWebSocket, "Hello World!");

    Print("Waiting...");
    Wait(3.6);

    WebSocketSendTextMessage(hWebSocket, "Bye");
    WebSocketClose(hWebSocket);
  end TMain;
Parent topic: Asynchronous Communication Functions


WebSocketConnectSync Function

Action

Connects to a WebSocket server and establishes a synchronous bidirectional communication channel.

Include file

webapi.bdh

Syntax

WebSocketConnectSync( in sUrl : string ): number

Parameter | Description
sUrl | The URL of the WebSocket server. A WebSocket URL in JavaScript usually looks like this: ws://echo.websocket.org In Silk Performer, you have to specify http instead of ws, for example: http://echo.websocket.org

Return value

  • a handle, which identifies the WebSocket, if the connection was established successfully
  • false otherwise

Example

transaction TMain
  var
    hWebSocket0 : number;
    sMessage : string;
    nMessageKind : number;
  begin

    // SYNCHRONOUS: Messages from server via WebSocketReceiveMessage

    hWebSocket0 := WebSocketConnectSync("http://lnz-testsite:90/websocketechoexample/websocketecho");

    ThinkTime(2.1);
    WebSocketSendTextMessage(hWebSocket0, "Rock it with HTML5 WebSocket");

    WebSocketReceiveMessage(hWebSocket0, sMessage, nMessageKind);

    Print("Received message: '" + sMessage + "'");
    if (nMessageKind = WEBSOCKET_MESSAGEKIND_TEXT) then
      Print("Message Kind: TEXT");
    elseif (nMessageKind = WEBSOCKET_MESSAGEKIND_BINARY) then
      Print("Message Kind: BINARY");
    end;

    ThinkTime(3.8);
    WebSocketSendTextMessage(hWebSocket0, "Hello World!");

    WebSocketReceiveMessage(hWebSocket0, sMessage, nMessageKind);

    Print("Received message: '" + sMessage + "'");
    if (nMessageKind = WEBSOCKET_MESSAGEKIND_TEXT) then
      Print("Message Kind: TEXT");
    elseif (nMessageKind = WEBSOCKET_MESSAGEKIND_BINARY) then
      Print("Message Kind: BINARY");
    end;

    ThinkTime(2.8);
    WebSocketSendTextMessage(hWebSocket0, "Bye");

    WebSocketReceiveMessage(hWebSocket0, sMessage, nMessageKind);

    Print("Received message: '" + sMessage + "'");
    if (nMessageKind = WEBSOCKET_MESSAGEKIND_TEXT) then
      Print("Message Kind: TEXT");
    elseif (nMessageKind = WEBSOCKET_MESSAGEKIND_BINARY) then
      Print("Message Kind: BINARY");
    end;

    // NO MESSAGE FROM SERVER => Timeout, expect error to be raised for the following WebSocketReceiveMessage() (after 4.0 seconds of waiting)
    WebSocketReceiveMessage(hWebSocket0, sMessage, nMessageKind, 4.0); // specify 4.0 seconds timeout, default is infinite

    ThinkTime(1.0);
    WebSocketClose(hWebSocket0);
  end TMain;
Parent topic: Asynchronous Communication Functions


WebSocketClose Function

Action

Closes a WebSocket communication channel. The client sends a close message to the server and waits until the server actually closes the connection. After WebSocketClose has been called, the associated WebSocket handle is not valid any longer.

Include file

webapi.bdh

Syntax

WebSocketClose( in hWebSocket    : number,
                in nStatusCode   : number optional,
                in sCloseMessage : dstring optional ): boolean;
Parameter | Description
hWebSocket | A handle, which identifies the WebSocket. To retrieve this handle, use the WebSocketConnect() function.
nStatusCode Optional: Reason for closing the WebSocket connection. For valid values, refer to http://tools.ietf.org/html/rfc6455#section-7.4. Some well known values are defined as BDL constants:
  • WEBSOCKET_CLOSESTATUS_NORMAL_CLOSURE := 1000;
  • WEBSOCKET_CLOSESTATUS_GOING_AWAY := 1001;
  • WEBSOCKET_CLOSESTATUS_PROTOCOL_ERROR := 1002;
  • WEBSOCKET_CLOSESTATUS_DATATYPE_NOT_ACCEPTED := 1003;
  • WEBSOCKET_CLOSESTATUS_NO_STATUSCODE := 1005;
  • WEBSOCKET_CLOSESTATUS_CLOSED_ABNORMALLY := 1006;
  • WEBSOCKET_CLOSESTATUS_DATA_INCONSISTENT := 1007;
  • WEBSOCKET_CLOSESTATUS_POLICY_VIOLATION := 1008;
  • WEBSOCKET_CLOSESTATUS_MESSAGE_TOO_BIG := 1009;
  • WEBSOCKET_CLOSESTATUS_EXTENSION_NOT_SUPPORTED := 1010;
  • WEBSOCKET_CLOSESTATUS_UNEXPECTED_CONDITION := 1011;
  • WEBSOCKET_CLOSESTATUS_TLS_HANDSHAKE_FAILURE := 1015;
sCloseMessage | Optional: Additional message for diagnostic purposes

Return value

  • true if successful

  • false otherwise

Example

 transaction TMain
  var
    hWebSocket : number;
  begin
    hWebSocket := WebSocketConnect("http://echo.websocket.org", callback(FWebSocketMessageReceived));

    WebSocketSendTextMessage(hWebSocket, "Rock it with HTML5 WebSocket");

    Print("Waiting...");
    Wait(4.1);

    WebSocketSendTextMessage(hWebSocket, "Hello World!");

    Print("Waiting...");
    Wait(3.6);

    WebSocketSendTextMessage(hWebSocket, "Bye");
    WebSocketClose(hWebSocket);
  end TMain;
Parent topic: Asynchronous Communication Functions


WebSocketSendTextMessage Function

Action

Sends a text message to the WebSocket server. The function does not wait for a response. Note: A WebSocket is an asynchronous communication channel, which is not bound to the conventional request-response pattern. Both the client and the server can send messages at any time.

Include file

webapi.bdh

Syntax

WebSocketSendTextMessage( in hWebSocket       : number,
                          in sData            : dstring,
                          in nMaxFragmentSize : number optional ): boolean

Parameter | Description
hWebSocket | A handle, which identifies the WebSocket. To retrieve this handle, use the WebSocketConnect() function.
sData | The content of the message to be sent to the server.
nMaxFragmentSize | Large messages can be split up into smaller parts or fragments by the client. This parameter specifies the maximum size of one fragment.

Return value

  • true if successful

  • false otherwise

Example

 transaction TMain
  var
    hWebSocket : number;
  begin
    hWebSocket := WebSocketConnect("http://echo.websocket.org", callback(FWebSocketMessageReceived));

    WebSocketSendTextMessage(hWebSocket, "Rock it with HTML5 WebSocket");

    Print("Waiting...");
    Wait(4.1);

    WebSocketSendTextMessage(hWebSocket, "Hello World!");

    Print("Waiting...");
    Wait(3.6);

    WebSocketSendTextMessage(hWebSocket, "Bye");
    WebSocketClose(hWebSocket);
  end TMain;
Parent topic: Asynchronous Communication Functions


WebSocketSendBinaryMessage Function

Action

Sends a binary message to the WebSocket server. The function does not wait for a response. Note: A WebSocket is an asynchronous communication channel, which is not bound to the conventional request-response pattern. Both the client and the server can send messages at any time.

Include file

webapi.bdh

Syntax

WebSocketSendBinaryMessage( in hWebSocket       : number,
                            in sData            : dstring,
                            in nMaxFragmentSize : number optional ): boolean

Parameter | Description
hWebSocket | A handle, which identifies the WebSocket. To retrieve this handle, use the WebSocketConnect() function.
sData | The content of the message to be sent to the server.
nMaxFragmentSize | Large messages can be split up into smaller parts or fragments by the client. This parameter specifies the maximum size of one fragment.

Return value

  • true if successful

  • false otherwise

Example

transaction TMain
  var
    hWebSocket : number;
  begin
    hWebSocket := WebSocketConnect("http://echo.websocket.org", callback(FWebSocketMessageReceived));

    WebSocketSendTextMessage(hWebSocket, "Rock it with HTML5 WebSocket");

    Print("Waiting...");
    Wait(4.1);

    WebSocketSendBinaryMessage(hWebSocket, "\h48656c6c6f20576f726c6421");

    Print("Waiting...");
    Wait(3.6);

    WebSocketSendTextMessage(hWebSocket, "Bye");
    WebSocketClose(hWebSocket);
  end TMain;
Parent topic: Asynchronous Communication Functions


WebSocketReceiveMessage Function

Action

Receives a WebSocket message from the server. You must establish a synchronous WebSocket connection (with the function WebSocketConnectSync) beforehand. Do not use the function WebSocketConnect in this case, as this will establish an asynchronous WebSocket connection.

Include file

webapi.bdh

Syntax

WebSocketReceiveMessage( in hWebSocket    : number,
                         out sData        : dstring optional,
                         out nMessageKind : number optional,
                         in fTimeout      : double optional ): boolean
Parameter | Description
hWebSocket | A handle, which identifies the WebSocket. To retrieve this handle, use the WebSocketConnectSync() function.
sData Will contain the WebSocket message received from the server.

If nMessageKind is of type text, sData will contain the text converted in the current codepage.

If nMessageKind is of type binary, sData will contain the bytes received from the server.

nMessageKind Will contain the kind of WebSocket message received from the server. Can be one of the following:
  • WEBSOCKET_MESSAGEKIND_TEXT := 1; // text message
  • WEBSOCKET_MESSAGEKIND_BINARY := 2; // binary message
fTimeout | Defines the timeout (in seconds) for waiting for a WebSocket message from the server. If no message is received within this timespan, the function returns false. The default value is 0 (infinite).

Return value

  • true if successful

  • false otherwise

Example

 transaction TMain
  var
    hWebSocket0 : number;
    sMessage : string;
    nMessageKind : number;
  begin

    // SYNCHRONOUS: Messages from server via WebSocketReceiveMessage

    hWebSocket0 := WebSocketConnectSync("http://lnz-testsite:90/websocketechoexample/websocketecho");

    ThinkTime(2.1);
    WebSocketSendTextMessage(hWebSocket0, "Rock it with HTML5 WebSocket");

    WebSocketReceiveMessage(hWebSocket0, sMessage, nMessageKind);

    Print("Received message: '" + sMessage + "'");
    if (nMessageKind = WEBSOCKET_MESSAGEKIND_TEXT) then
      Print("Message Kind: TEXT");
    elseif (nMessageKind = WEBSOCKET_MESSAGEKIND_BINARY) then
      Print("Message Kind: BINARY");
    end;

    ThinkTime(3.8);
    WebSocketSendTextMessage(hWebSocket0, "Hello World!");

    WebSocketReceiveMessage(hWebSocket0, sMessage, nMessageKind);

    Print("Received message: '" + sMessage + "'");
    if (nMessageKind = WEBSOCKET_MESSAGEKIND_TEXT) then
      Print("Message Kind: TEXT");
    elseif (nMessageKind = WEBSOCKET_MESSAGEKIND_BINARY) then
      Print("Message Kind: BINARY");
    end;

    ThinkTime(2.8);
    WebSocketSendTextMessage(hWebSocket0, "Bye");

    WebSocketReceiveMessage(hWebSocket0, sMessage, nMessageKind);

    Print("Received message: '" + sMessage + "'");
    if (nMessageKind = WEBSOCKET_MESSAGEKIND_TEXT) then
      Print("Message Kind: TEXT");
    elseif (nMessageKind = WEBSOCKET_MESSAGEKIND_BINARY) then
      Print("Message Kind: BINARY");
    end;

    // NO MESSAGE FROM SERVER => Timeout, expect error to be raised for the following WebSocketReceiveMessage() (after 4.0 seconds of waiting)
    WebSocketReceiveMessage(hWebSocket0, sMessage, nMessageKind, 4.0); // specify 4.0 seconds timeout, default is infinite

    ThinkTime(1.0);
    WebSocketClose(hWebSocket0);
  end TMain;
Parent topic: Asynchronous Communication Functions


Page Statistic Functions

  • WebPageStatistics Function
    Provides measurements for the last page-level function call.
  • WebPageStatCalcSummaryNode Function
    Calculates a node summary of all nodes that match the specified search criteria.
  • WebPageStatCountNodes Function
    Counts all nodes that match the specified search criteria.
  • WebPageStatFindFirstNode Function
    Returns the first node that matches the specified search criteria.
  • WebPageStatFindNextNode Function
    Returns the next node that matches the specified search criteria.
  • WebPageStatGetFirstEmbedded Function
    Returns the first embedded object of a node (specified by node ID).
  • WebPageStatGetNextEmbedded Function
  • WebPageStatGetFirstFrame Function
    Returns the first frame of a node (specified by node ID).
  • WebPageStatGetNextFrame Function
  • WebPageStatGetNextReload Function
    Returns the subsequent node in a redirection chain.
  • WebPageStatGetNodeData Function
    Returns information about a node (specified by the node ID) that is returned by a previous WebPageStatXXX function call.
  • WebPageStatGetNodeInfo Function
    Returns information about a node (specified by the node ID) that is returned by a previous WebPageStatXXX function call.
  • WebPageStatGetRootNode Function
    Returns the root node of the most recently loaded page.
  • WebPageStatToTsd Function
    Adds detailed timers for the last page to the time series data.
Parent topic: Web Functions Reference


WebPageStatistics Function

Action

Provides measurements for the last page-level function call.

Include file

WebAPI.bdh

Syntax

WebPageStatistics(
   in  nSource : number,
   in  nOption : number,
   out nResult : number): boolean;

Return value

  • true if the specified value was set

  • false otherwise

Parameter | Description
nSource

Specifies for which documents to provide measurements. This parameter must be one of the following values:

STATFLAG_HTMLDOC
Provides measurements for all HTML documents.
STATFLAG_OTHERDOC
Provides measurements all types of documents except HTML documents.
STATFLAG_ALL
Provides measurements for all types of documents.
nOption

Can be set to one of the following values:

STATFLAG_HTTPREQUESTS
Number of requests without an "if-modified-since" header.
STATFLAG_CONDHTTPREQUESTS
Number of conditional requests; these are requests with an "if-modified-since" header.
STATFLAG_CACHEHITS
Number of cache hits; that is, when the requested document was found in the document cache and no request was sent to the server.
STATFLAG_HITSFAILED
Number of failed requests.
STATFLAG_1XX
Number of 1xx responses.
STATFLAG_2XX
Number of 2xx responses.
STATFLAG_3XX
Number of 3xx responses.
STATFLAG_4XX
Number of 4xx responses.
STATFLAG_5XX
Number of 5xx responses.
STATFLAG_TIMERCONNECT
Sum of the duration, in ms, of all TCP/IP connects.
STATFLAG_TIMERSSLCONNECT
Sum of the duration, in ms, of all SSL connects.
STATFLAG_TIMERSEND
Sum of the duration, in ms, of all send operations.
STATFLAG_TIMERSERVERBUSY
Sum of all server-busy times, in ms. The time measurement starts after the last packet was sent and stops when the first packet is received.
STATFLAG_TIMERRECV
Sum of the duration, in ms, of all receive operations.
STATFLAG_TIMERDNS
Sum of the duration, in ms, of all domain name resolutions.
STATFLAG_CONNECTCOUNT
Number of TCP/IP connects.
STATFLAG_SSLCONNECTCOUNT
Number of SSL connection handshakes; this is a subset of the STATFLAG_CONNECTCOUNT measurement.
STATFLAG_SENDCOUNT
Number of requests sent to the server.
STATFLAG_LINKS
Number of HTTP(S) links in the most recently downloaded Web page. The Link checking option must be enabled for this result to be available.
STATFLAG_LINKSWORKING
Number of working HTTP(S) links in the most recently downloaded Web page. The Link checking option must be enabled for this result to be available.
STATFLAG_BYTESSENT
Number of bytes sent to the server.
STATFLAG_BYTESRECEIVED
Number of bytes received from the server.
STATFLAG_TimeToFirstByte
Time from request start until the first response from the server arrives.
nResult | Variable that receives the result.

Example

dcltrans
  transaction TMain
  var
    nResult: number;
  begin
    WebPageUrl("http://standardhost/");
    WebPageStatistics(STATFLAG_ALL, STATFLAG_TIMERSERVERBUSY, nResult);
    Print(string(nResult));
    WebPageStatistics(STATFLAG_HTMLDOC, STATFLAG_TIMERDNS, nResult);
    Print(string(nResult));
  end TMain;
Parent topic: Page Statistic Functions


WebPageStatCalcSummaryNode Function

Action

Calculates a node summary of all nodes that match the specified search criteria. Possible search parameters include: URL, content-type of the response, document load-type (load, cache-hit, suppressed), document kind (html or embedded), and the location within a redirection chain (a redirection chain is created when a request is retried or reissued because of a redirection or an authentication request by the server).

The return value is the number of nodes that have been used for the calculation of the summary node.

To generally enable extended page statistics functionality, call WebSetOption with an option of WEB_OPT_DETAILED_PAGE_STAT (for a detailed description of the various values see WebSetOption).

Include file

WebAPI.bdh

Syntax

WebPageStatCalcSummaryNode(
   in sUrlFilter         : string optional,
   in sContentTypeFilter : string optional,
   in nMatch             : number optional,
   in nFlags             : number optional ): number;

Return value

The number of nodes that have been used for the calculation of the summary node.

Parameter | Description
sUrlFilter | String to which the actual URL is to be compared. The nMatch parameter specifies the comparison method. When this parameter is omitted (null or “”), no URL comparison is performed.
sContentTypeFilter | String to which the actual content-type (server response) is to be compared. The nMatch parameter specifies the comparison method. When this parameter is omitted (null or “”) no content-type comparison is performed.
nMatch

Specify one of the following values (optional):

PAGE_STAT_MATCH_Exact (default)
Case-sensitive comparison.
PAGE_STAT_MATCH_ExactNoCase
Case-insensitive comparison.
PAGE_STAT_MATCH_Wildcard
The search string must either begin or end with a ‘*’ character, which matches everything. The remainder of the string is compared case-sensitively.
PAGE_STAT_MATCH_WildcardNoCase
The search string must either begin or end with a ‘*’ character, which matches everything. The rest of the string is compared case-insensitively.
PAGE_STAT_MATCH_RegExp
The search string is a regular expression. See the regular expression chapter for a description of Silk Performer regular expression capability.
nFlags

Specifies the various options used by the search for the nodes. When this parameter is omitted the default options specified by the call to WebSetOption(WEB_OPT_DETAILED_PAGE_STAT) are used. Otherwise specify one of the following values:

PAGE_STAT_FLAG_UseHtml
The search includes nodes of the document section of the page (commonly html documents).
PAGE_STAT_FLAG_UseEmbedded
The search includes nodes of the embedded section of the page (commonly images or scripts).
PAGE_STAT_FLAG_NodeTypeLoad
The search includes nodes that caused a request to be sent to the server (no cache hits and no suppressed documents).
PAGE_STAT_FLAG_NodeTypeCacheHit
The search includes nodes that have been found in the cache (full cache hit), so that no request to the server has been sent.
PAGE_STAT_FLAG_NodeTypeSuppress
The search includes nodes for which no request has been sent to the server, because they have been suppressed by the user (WebPageSuppress or WebSetDomainSuppress).
PAGE_STAT_FLAG_RedirChainOnlyFirst
The search only returns the first nodes of a potential redirection chain (a redirection chain is created when a request is retried or reissued because of a redirection or an authentication request by the server). Any subsequent nodes of a redirection chain are not returned.
PAGE_STAT_FLAG_RedirChainOnlyLast
The search only returns the last nodes of a potential redirection chain. Any proceeding nodes of a redirection chain are not returned. This option can be used to only find documents that the browser can actually show to the user.

Example

dcltrans
  transaction TInit
  begin
    WebSetOption(WEB_OPT_DETAILED_PAGE_STAT,
                 PAGE_STAT_FLAG_AllLoadedDocs);
  end TInit;

  transaction TWeb
  var
    nNodes  : number;
    fValue  : float;
  begin

    WebPageURL("http://lab3/");
    nNodes := WebPageStatCalcSummaryNode(null, "image/*",
              PAGE_STAT_MATCH_WildcardNoCase);
    if nNodes > 0 then
      WebPageStatGetNodeData(STATFLAG_BytesSent, fValue,
                             PAGE_STAT_Calculated);
      print("Bytes sent for images: " + string(fValue));
    end;
  end TWeb;
Parent topic: Page Statistic Functions


WebPageStatCountNodes Function

Action

Counts all nodes that match the specified search criteria. Possible search parameters are: URL, content-type of the response, document load-type (load, cache-hit, suppressed), document kind (html or embedded), and location within a redirection chain (a redirection chain is created when a request is retried or reissued because of a redirection or an authentication request by the server).

The return value is the number of nodes that match the specified search criteria.

To generally enable extended page statistics functionality, call WebSetOption with an option of WEB_OPT_DETAILED_PAGE_STAT (for a detailed description of the various values see WebSetOption).

Include file

WebAPI.bdh

Syntax

WebPageStatCountNodes(
   in sUrlFilter         : string optional,
   in sContentTypeFilter : string optional,
   in nMatch             : number optional,
   in nFlags             : number optional ): number;

Return value

The number of nodes that match the specified search criteria.

Parameter | Description
sUrlFilter | String to which the actual URL is to be compared. The nMatch parameter specifies the comparison method. When this parameter is omitted (null or “”), no URL comparison is performed.
sContentTypeFilter | String to which the actual content-type (server response) is to be compared. The nMatch parameter specifies the comparison method. When this parameter is omitted (null or “”) no content-type comparison is performed.
nMatch

Specify one of the following values (optional):

PAGE_STAT_MATCH_Exact (default)
Case-sensitive comparison
PAGE_STAT_MATCH_ExactNoCase
Case-insensitive comparison
PAGE_STAT_MATCH_Wildcard
The search string must either begin or end with a ‘*’ character, which matches everything. The remainder of the string is compared case-sensitively.
PAGE_STAT_MATCH_WildcardNoCase
The search string must either begin or end with a ‘*’ character, which matches everything. The rest of the string is compared case-insensitively.
PAGE_STAT_MATCH_RegExp
The search string is a regular expression. See the regular expression chapter for a description of Silk Performer regular expression capability.
nFlags

Specifies the various options used by the search for the nodes. When this parameter is omitted the default options specified by the call to WebSetOption(WEB_OPT_DETAILED_PAGE_STAT) are used. Otherwise specify one of the following values:

PAGE_STAT_FLAG_UseHtml
The search includes nodes of the document section of the page (commonly html documents).
PAGE_STAT_FLAG_UseEmbedded
The search includes nodes of the embedded section of the page (commonly images or scripts).
PAGE_STAT_FLAG_NodeTypeLoad
The search includes nodes that caused a request to be sent to the server (no cache hits and no suppressed documents).
PAGE_STAT_FLAG_NodeTypeCacheHit
The search includes nodes that have been found in the cache (full cache hit), so that no request to the server has been sent.
PAGE_STAT_FLAG_NodeTypeSuppress
The search includes nodes for which no request has been sent to the server, because they have been suppressed by the user (WebPageSuppress or WebSetDomainSuppress).
PAGE_STAT_FLAG_RedirChainOnlyFirst
The search only returns the first nodes of a potential redirection chain (a redirection chain is created when a request is retried or reissued because of a redirection or an authentication request by the server). Any subsequent nodes of a redirection chain are not returned.
PAGE_STAT_FLAG_RedirChainOnlyLast
The search only returns the last nodes of a potential redirection chain. Any proceeding nodes of a redirection chain are not returned. This option can be used to only find documents that the browser can actually show to the user.

Example

dcltrans
  transaction TInit
  begin
    WebSetOption(WEB_OPT_DETAILED_PAGE_STAT,
                PAGE_STAT_FLAG_AllLoadedDocs);
  end TInit;

  transaction TWeb
  var
    nNodes  : number;
    fValue  : float;
  begin

    WebPageURL("http://lab3/");
    nNodes := WebPageStatCountNodes(null, "image/*",
              PAGE_STAT_MATCH_WildcardNoCase);
    if nNodes > 0 then
      WebPageStatGetNodeData(STATFLAG_BytesSent, fValue,
                             PAGE_STAT_Calculated);
      print("number of images: " + string(fValue));
    end;
  end TWeb;
Parent topic: Page Statistic Functions


WebPageStatFindFirstNode Function

Action

Returns the first node that matches the specified search criteria. Possible search parameters are: URL, content-type of the response, document load-type (load, cache-hit, suppressed), document kind (html or embedded), and location within a redirection chain (a redirection chain is created when a request is retried or reissued because of a redirection or an authentication request by the server).

The return value is a node ID that can be used in other WebPageStatXXX calls.

To generally enable extended page statistics functionality, call WebSetOption with an option of WEB_OPT_DETAILED_PAGE_STAT (for a detailed description of the various values see WebSetOption).

Include file

WebAPI.bdh

Syntax

WebPageStatFindFirstNode(
   in sUrlFilter         : string optional,
   in sContentTypeFilter : string optional,
   in nMatch             : number optional,
   in nFlags             : number optional ): number;

Return value

  • 0 if the node can not be found

  • >0 otherwise

Parameter | Description
sUrlFilter | String to which the actual URL is to be compared. The nMatch parameter specifies the comparison method. When this parameter is omitted (null or “”), no URL comparison is performed.
sContentTypeFilter | String to which the actual content-type (server response) is to be compared. The nMatch parameter specifies the comparison method. When this parameter is omitted (null or “”) no content-type comparison is performed.
nMatch

Specify one of the following values (optional):

PAGE_STAT_MATCH_Exact (default)
Case-sensitive comparison.
PAGE_STAT_MATCH_ExactNoCase
Case-insensitive comparison.
PAGE_STAT_MATCH_Wildcard
The search string must either begin or end with a ‘*’ character, which matches everything. The remainder of the string is compared case-sensitively.
PAGE_STAT_MATCH_WildcardNoCase
The search string must either begin or end with a ‘*’ character, which matches everything. The rest of the string is compared case-insensitively.
PAGE_STAT_MATCH_RegExp
The search string is a regular expression. See the regular expression chapter for a description of Silk Performer regular expression capability.
nFlags

Specifies the various options used by the search for the nodes. When this parameter is omitted the default options specified by the call to WebSetOption(WEB_OPT_DETAILED_PAGE_STAT) are used. Otherwise specify one of the following values:

PAGE_STAT_FLAG_UseHtml
The search includes nodes of the document section of the page (commonly html documents).
PAGE_STAT_FLAG_UseEmbedded
The search includes nodes of the embedded section of the page (commonly images or scripts).
PAGE_STAT_FLAG_NodeTypeLoad
The search includes nodes that caused a request to be sent to the server (no cache hits and no suppressed documents).
PAGE_STAT_FLAG_NodeTypeCacheHit
The search includes nodes that have been found in the cache (full cache hit), so that no request to the server has been sent.
PAGE_STAT_FLAG_NodeTypeSuppress
The search includes nodes for which no request has been sent to the server, because they have been suppressed by the user (WebPageSuppress or WebSetDomainSuppress).
PAGE_STAT_FLAG_RedirChainOnlyFirst
The search only returns the first nodes of a potential redirection chain (a redirection chain is created when a request is retried or reissued because of a redirection or an authentication request by the server). Any subsequent nodes of a redirection chain are not returned.
PAGE_STAT_FLAG_RedirChainOnlyLast
The search only returns the last nodes of a potential redirection chain. Any proceeding nodes of a redirection chain are not returned. This option can be used to only find documents that the browser can actually show to the user.

Example

dcltrans
  transaction TInit
  begin
    WebSetOption(WEB_OPT_DETAILED_PAGE_STAT,
                 PAGE_STAT_FLAG_AllLoadedDocs);
  end TInit;

  transaction TWeb
  var
    nNodes  : number;
    sUrl    : string;
  begin

    WebPageURL("http://lab3/");
    nNodes := WebPageStatFindFirstNode(null, "image/*",
             PAGE_STAT_MATCH_WildcardNoCase);
    while nNodes > 0 do
      WebPageStatGetNodeInfo(null, sURL);
      print("URL: " + sURL);
      nNodes := WebPageStatFindNextNode(null, "image/*",
               PAGE_STAT_MATCH_WildcardNoCase);
    end;
  end TWeb;
Parent topic: Page Statistic Functions


WebPageStatFindNextNode Function

Action

Returns the next node that matches the specified search criteria. Use in combination with WebPageStatFindFirstNode. Possible search parameters are: URL, content-type of the response, document load-type (load, cache-hit, suppressed), document type (html or embedded), and the location within a redirection chain (a redirection chain is created when a request is retried or reissued because of a redirection or an authentication request by the server).

The return value is a node ID that can be used in other WebPageStatXXX calls.

To generally enable extended page statistics functionality, call WebSetOption with an option of WEB_OPT_DETAILED_PAGE_STAT (for a detailed description of the various values see WebSetOption).

Include file

WebAPI.bdh

Syntax

WebPageStatFindNextNode(
   in sUrlFilter         : string optional,
   in sContentTypeFilter : string optional,
   in nMatch             : number optional,
   in nFlags             : number optional ): number;

Return value

  • 0 if the node can not be found

  • >0 otherwise

Parameter | Description
sUrlFilter | String to which the actual URL is to be compared. The nMatch parameter specifies the comparison method. When this parameter is omitted (null or “”), no URL comparison is performed.
sContentTypeFilter | String to which the actual content-type (server response) is to be compared. The nMatch parameter specifies the comparison method. When this parameter is omitted (null or “”) no content-type comparison is performed.
nMatch

Specify one of the following values (optional):

PAGE_STAT_MATCH_Exact (default)
Case-sensitive comparison.
PAGE_STAT_MATCH_ExactNoCase
Case-insensitive comparison.
PAGE_STAT_MATCH_Wildcard
The search string must either begin or end with a ‘*’ character, which matches everything. The remainder of the string is compared case-sensitively.
PAGE_STAT_MATCH_WildcardNoCase
The search string must either begin or end with a ‘*’ character, which matches everything. The rest of the string is compared case-insensitively.
PAGE_STAT_MATCH_RegExp
The search string is a regular expression. See the regular expression chapter for a description of Silk Performer regular expression capability.
nFlags

Specifies the various options used by the search for the nodes. When this parameter is omitted the default options specified by the call to WebSetOption(WEB_OPT_DETAILED_PAGE_STAT) are used. Otherwise specify one of the following values:

PAGE_STAT_FLAG_UseHtml
The search includes nodes of the document section of the page (commonly html documents).
PAGE_STAT_FLAG_UseEmbedded
The search includes nodes of the embedded section of the page (commonly images or scripts).
PAGE_STAT_FLAG_NodeTypeLoad
The search includes nodes that caused a request to be sent to the server (no cache hits and no suppressed documents).
PAGE_STAT_FLAG_NodeTypeCacheHit
The search includes nodes that have been found in the cache (full cache hit), so that no request to the server has been sent.
PAGE_STAT_FLAG_NodeTypeSuppress
The search includes nodes for which no request has been sent to the server, because they have been suppressed by the user (WebPageSuppress or WebSetDomainSuppress).
PAGE_STAT_FLAG_RedirChainOnlyFirst
The search only returns the first nodes of a potential redirection chain (a redirection chain is created when a request is retried or reissued because of a redirection or an authentication request by the server). Any subsequent nodes of a redirection chain are not returned.
PAGE_STAT_FLAG_RedirChainOnlyLast
The search only returns the last nodes of a potential redirection chain. Any proceeding nodes of a redirection chain are not returned. This option can be used to only find documents that the browser can actually show to the user.

Example

dcltrans
  transaction TInit
  begin
    WebSetOption(WEB_OPT_DETAILED_PAGE_STAT,
                 PAGE_STAT_FLAG_AllLoadedDocs);
  end TInit;

  transaction TWeb
  var
    nNodes  : number;
    sUrl    : string;
  begin

    WebPageURL("http://lab3/");
    nNodes := WebPageStatFindFirstNode(null, "image/*",
             PAGE_STAT_MATCH_WildcardNoCase);
    while nNodes > 0 do
      WebPageStatGetNodeInfo(null, sURL);
      print("URL: " + sURL);
      nNodes := WebPageStatFindNextNode(null, "image/*",
               PAGE_STAT_MATCH_WildcardNoCase);
    end;
  end TWeb;
Parent topic: Page Statistic Functions


WebPageStatGetFirstEmbedded Function

Action

Returns the first embedded object of a node (specified by node ID). The node ID is returned by a previous WebPageStatXXX function call. Use this function in combination with WebPageStatGetNextEmbedded().

The return value is a node ID that can be used in other WebPageStatXXX calls.

To generally enable extended page statistics functionality, call WebSetOption with an option of WEB_OPT_DETAILED_PAGE_STAT (for a detailed description of the various values see WebSetOption).

Include file

WebAPI.bdh

Syntax

WebPageStatGetFirstEmbedded(
   in nNode  : number,
   in nFlags : number optional ): number;

Return value

  • 0 if there is no embedded object

  • >0 otherwise

Parameter | Description
nNode | Node ID returned by a previous WebPageStatXXX function.
nFlags

Specifies the various options used by the search. If this parameter is omitted, the default options specified by the call to WebSetOption(WEB_OPT_DETAILED_PAGE_STAT) are used. Otherwise specify one of the following values:

PAGE_STAT_FLAG_NodeTypeLoad
Returns nodes that caused a request to be sent to the server (no cache hits and no suppressed documents).
PAGE_STAT_FLAG_NodeTypeCacheHit
Returns nodes that have been found in the cache (full cache hit), so that no request to the server has been sent.
PAGE_STAT_FLAG_NodeTypeSuppress
Returns nodes for which no request has been sent to the server, because they have been suppressed by the user (WebPageSuppress or WebSetDomainSuppress).
PAGE_STAT_FLAG_RedirChainOnlyLast:
Returns the last node of a potential redirection chain (a redirection chain is created when a request is retried or reissued because of a redirection or an authentication request by the server).

Example

dcltrans
  transaction TInit
  begin
    WebSetOption(WEB_OPT_DETAILED_PAGE_STAT,
                 PAGE_STAT_FLAG_AllLoadedDocs);
  end TInit;

  transaction TWeb
  var
    nNodeRoot : number;
    nNode     : number;
    fValue    : float;
    sUrl      : string;
  begin

    WebPageURL("http://lab3/");
    nNodeRoot := WebPageStatGetRootNode();
    if nNodeRoot > 0 then
      nNode := WebPageStatGetFirstEmbedded(nNodeRoot);
      while nNode > 0 do
        WebPageStatGetNodeInfo(null, sUrl);
        WebPageStatGetNodeData(STATFLAG_BytesSent, fValue);
        print("Url: " + sUrl);
        print("BytesSent: " + string(fValue));
        nNode := WebPageStatGetNextEmbedded(nNodeRoot);
      end;
    end;
  end TWeb;
Parent topic: Page Statistic Functions


WebPageStatGetNextEmbedded Function

Action

Returns the next embedded object of a node (specified by its node ID). Use this function in combination with WebPageStatGetFirstEmbedded().

The return value is a node ID, which can be used in various other WebPageStatXXX calls.

To generally enable extended page statistics functionality, call WebSetOption with an option of WEB_OPT_DETAILED_PAGE_STAT (for a detailed description of the various values see WebSetOption).

Include file

WebAPI.bdh

Syntax

WebPageStatGetNextEmbedded(
   in nNode  : number,
   in nFlags : number optional ): number;

Return value

  • 0 if there are no more embedded objects

  • >0 otherwise

Parameter | Description
nNode | Node ID returned by a previous WebPageStatXXX function.
nFlags

Specifies the various options used by the search for the node. If this parameter is omitted the default options specified by the call to WebSetOption(WEB_OPT_DETAILED_PAGE_STAT) are used. Otherwise specify one of the following values:

PAGE_STAT_FLAG_UseEmbedded
Returns nodes of the embedded section of the page (commonly images or scripts).
PAGE_STAT_FLAG_NodeTypeLoad
Returns nodes that caused a request to be sent to the server (no cache hits and no suppressed documents).
PAGE_STAT_FLAG_NodeTypeCacheHit
Returns nodes found in the cache (full cache hit), so that no request to the server is sent.
PAGE_STAT_FLAG_NodeTypeSuppress
Returns nodes for which no request has been sent to the server, because they have been suppressed by the user (WebPageSuppress or WebSetDomainSuppress).
PAGE_STAT_FLAG_RedirChainOnlyLast
Returns the last node of a potential redirection chain (a redirection chain is created when a request is retried or reissued because of a redirection or an authentication request by the server).

Example

dcltrans
  transaction TInit
  begin
    WebSetOption(WEB_OPT_DETAILED_PAGE_STAT,
                 PAGE_STAT_FLAG_AllLoadedDocs);
  end TInit;

  transaction TWeb
  var
    nNodeRoot : number;
    nNode     : number;
    fValue    : float;
    sUrl      : string;
  begin

    WebPageURL("http://lab3/");
    nNodeRoot := WebPageStatGetRootNode();
    if nNodeRoot > 0 then
      nNode := WebPageStatGetFirstEmbedded(nNodeRoot);
      while nNode > 0 do
        WebPageStatGetNodeInfo(null, sUrl);
        WebPageStatGetNodeData(STATFLAG_BytesSent, fValue);
        print("Url: " + sUrl);
        print("BytesSent: " + string(fValue));
        nNode := WebPageStatGetNextEmbedded(nNodeRoot);
      end;
    end;
  end TWeb;
Parent topic: Page Statistic Functions


WebPageStatGetFirstFrame Function

Action

Returns the first frame of a node (specified by node ID). The node ID is returned by a previous WebPageStatXXX function call. Use this function in combination with WebPageStatGetNextFrame().

The return value is a node ID that can be used in other WebPageStatXXX calls.

To generally enable extended page statistics functionality, call WebSetOption with an option of WEB_OPT_DETAILED_PAGE_STAT (for a detailed description of the various values see WebSetOption).

Include file

WebAPI.bdh

Syntax

WebPageStatGetFirstFrame(
   in nNode  : number,
   in nFlags : number optional ): number;

Return value

  • 0 if no frame is present

  • >0 otherwise

Parameter | Description
nNode | Node ID returned by a previous WebPageStatXXX function.
nFlags

Specifies the various options used by the search. If this parameter is omitted, the default options specified by the call to WebSetOption(WEB_OPT_DETAILED_PAGE_STAT) are used. Otherwise specify one of the following values:

PAGE_STAT_FLAG_NodeTypeLoad
Returns nodes that caused a request to be sent to the server (no cache hits and no suppressed documents).
PAGE_STAT_FLAG_NodeTypeCacheHit
Returns nodes that have been found in the cache (full cache hit), so that no request to the server has been sent.
PAGE_STAT_FLAG_NodeTypeSuppress
Returns nodes for which no request has been sent to the server, because they have been suppressed by the user (WebPageSuppress or WebSetDomainSuppress).
PAGE_STAT_FLAG_RedirChainOnlyLast
Returns the last node of a potential redirection chain (a redirection chain is created when a request is retried or reissued because of a redirection or an authentication request by the server.)

Example

dcltrans
  transaction TInit
  begin
    WebSetOption(WEB_OPT_DETAILED_PAGE_STAT,
                 PAGE_STAT_FLAG_AllLoadedDocs);
  end TInit;

  transaction TWeb
  var
    nNodeRoot : number;
    nNode     : number;
    fValue    : float;
    sUrl      : string;
  begin

    WebPageURL("http://lab3/");
    nNodeRoot := WebPageStatGetRootNode();
    if nNodeRoot > 0 then
      nNode := WebPageStatGetFirstFrame(nNodeRoot);
      while nNode > 0 do
        WebPageStatGetNodeInfo(null, sUrl);
        WebPageStatGetNodeData(STATFLAG_BytesSent, fValue);
        print("Url: " + sUrl);
        print("BytesSent: " + string(fValue));
        nNode := WebPageStatGetNextFrame(nNodeRoot);
      end;
    end;
  end TWeb;
Parent topic: Page Statistic Functions


WebPageStatGetNextFrame Function

Action

Returns the next frame of a node (specified by its node ID). Use this function in combination with WebPageStatGetFirstFrame().

The return value is a node ID, which can be used in other WebPageStatXXX calls.

To generally enable extended page statistics functionality, call WebSetOption with an option of WEB_OPT_DETAILED_PAGE_STAT (for a detailed description of the various values see WebSetOption).

Include file

WebAPI.bdh

Syntax

WebPageStatGetNextFrame(
   in nNode  : number,
   in nFlags : number optional ): number;

Return value

  • 0 if there are no more frames

  • >0 otherwise

Parameter | Description
nNode | Node ID returned by a previous WebPageStatXXX function.
nFlags

Specifies the various options used by the search for the node. If this parameter is omitted the default options specified by the call to WebSetOption(WEB_OPT_DETAILED_PAGE_STAT) are used. Otherwise specify one of the following values:

PAGE_STAT_FLAG_NodeTypeLoad
Returns nodes that caused a request to be sent to the server (no cache hits and no suppressed documents).
PAGE_STAT_FLAG_NodeTypeCacheHit
Returns nodes that have been found in the cache (full cache hit), so that no request to the server is sent.
PAGE_STAT_FLAG_NodeTypeSuppress
Returns nodes for which no request has been sent to the server because they have been suppressed by the user (WebPageSuppress or WebSetDomainSuppress).
PAGE_STAT_FLAG_RedirChainOnlyLast
Returns the last node of a potential redirection chain (a redirection chain is created when a request is retried or reissued because of a redirection or an authentication request by the server).

Example

dcltrans
  transaction TInit
  begin
    WebSetOption(WEB_OPT_DETAILED_PAGE_STAT,
                 PAGE_STAT_FLAG_AllLoadedDocs);
  end TInit;

  transaction TWeb
  var
    nNodeRoot : number;
    nNode     : number;
    fValue    : float;
    sUrl      : string;
  begin

    WebPageURL("http://lab3/");
    nNodeRoot := WebPageStatGetRootNode();
    if nNodeRoot > 0 then
      nNode := WebPageStatGetFirstFrame(nNodeRoot);
      while nNode > 0 do
        WebPageStatGetNodeInfo(null, sUrl);
        WebPageStatGetNodeData(STATFLAG_BytesSent, fValue);
        print("Url: " + sUrl);
        print("BytesSent: " + string(fValue));
        nNode := WebPageStatGetNextFrame(nNodeRoot);
      end;
    end;
  end TWeb;
Parent topic: Page Statistic Functions


WebPageStatGetNextReload Function

Action

Returns the subsequent node in a redirection chain. A redirection chain is created when a request is retried or reissued because of a redirection or an authentication request by the server.

The return value is a node ID, which can be used in various other WebPageStatXXX calls.

To generally enable extended page statistics functionality, call WebSetOption with an option of WEB_OPT_DETAILED_PAGE_STAT (for a detailed description of the various values see WebSetOption).

Include file

WebAPI.bdh

Syntax

WebPageStatGetNextReload( in nNode: number optional ): number;

Return value

  • 0 if there is no redirection chain or the provided node is the last node in the chain.

  • >0 otherwise

Parameter | Description
nNode | Node ID returned by a previous WebPageStatXXX function. When this parameter is omitted, the most recently returned node ID is used.

Example

dcltrans
  transaction TInit
  begin
    WebSetOption(WEB_OPT_DETAILED_PAGE_STAT,
                 PAGE_STAT_FLAG_AllLoadedNodes);
  end TInit;

  transaction TWeb
  var
    nNode       : number;
    nNodeReload : number;
    fValue      : float;
    sUrl        : string;
  begin
    WebPageUrl("http://lab3/");
    nNode := WebPageStatGetRootNode();
    if nNode > 0 then
      nNodeReload := WebPageStatGetNextReload();
      if nNodeReload > 0 then
        WebPageStatGetNodeInfo(null, sUrl);
        print("Reload Url: " + sUrl);
        nNode := nNodeReload;
      end;

      if WebPageStatGetFirstFrame(nNode) > 0 then
        WebPageStatGetNodeData(STATFLAG_BytesSent, fValue);
        print("BytesSent: " + string(fValue));
      end;
    end;
  end TWeb;
Parent topic: Page Statistic Functions


WebPageStatGetNodeData Function

Action

Returns information about a node (specified by the node ID) that is returned by a previous WebPageStatXXX function call.

To generally enable extended page statistics functionality, call WebSetOption with an option of WEB_OPT_DETAILED_PAGE_STAT (for a detailed description of the various values see WebSetOption).

Include file

WebAPI.bdh

Syntax

WebPageStatGetNodeData(
   in  nOption : number,
   out fResult : float,
   in  nNode   : number optional ): boolean;

Return value

  • true if the information is retrieved successfully

  • false otherwise

Parameter | Description
nOption

Specify one of the following values:

STATFLAG_TimerConnect
Sum of the duration, in seconds, of all TCP/IP connects.
STATFLAG_TimerSSLConnect
Sum of the duration, in seconds, of all SSL connects.
STATFLAG_TimerSend
Sum of the duration, in seconds, of all send operations.
STATFLAG_TimerServerBusy
Sum of all server-busy times, in seconds. Time measurement begins after the last packet is sent and ends when the first packet is received.
STATFLAG_TimerRecv
Sum of the duration, in seconds, of all receive operations.
STATFLAG_TimerDns
Sum of the duration, in seconds, of all domain name resolutions.
STATFLAG_TimerDoc
The duration of the whole server round-trip (starting with DNS time and stopping when with the last byte is received). If used on a calculated summary node this will be a summary of the individual node times.
STATFLAG_ConnectCount
Number of TCP/IP connects.
STATFLAG_ConnectCountFailed
Number of failed TCP/IP connects.
STATFLAG_ConnectCountRetries
Number of retried TCP/IP connects.
STATFLAG_BYTESSENT
Number of bytes sent to the server.
STATFLAG_BYTESRECEIVED
Number of bytes received from the server.
STATFLAG_CookiesSent
Number of sent cookies.
STATFLAG_CookiesReceived
Number of received cookies.
fResult | Retrieves the result of the specified value.
nNode | Specify the node ID of the node for which information is to be returned (possibly returned by a previous WebPageStatXXX function). Provide a value of PAGE_STAT_Calculated if data of the most recent calculated node should be returned (WebPageStatCalcSummaryNode). When this parameter is omitted, the most recently returned or calculated node is used.

Example

dcltrans
  transaction TInit
  begin
    WebSetOption(WEB_OPT_DETAILED_PAGE_STAT,
                 PAGE_STAT_FLAG_AllLoadedDocs);
  end TInit;

  transaction TWeb
  var
    nNode  : number;
    nNodes : number;
    fValue : float;
  begin
    WebPageUrl("http://lab3/");
    nNode := WebPageStatGetRootNode();
    if nNode > 0 then
      WebPageStatGetNodeData(STATFLAG_TimerServerBusy, fValue);
      print("ServerBusyTime [s]: " + string(fValue));
      nNodes := WebPageStatCalcSummaryNode(null, "image/*",
              PAGE_STAT_MATCH_WildcardNoCase);
      if nNodes > 0 then
        WebPageStatGetNodeData(STATFLAG_BytesSent, fValue,
                             PAGE_STAT_Calculated);
        print("Bytes sent for images: " + string(fValue));
      end;
    end;
  end TWeb;
Parent topic: Page Statistic Functions


WebPageStatGetNodeInfo Function

Action

Returns information about a node (specified by the node ID) that is returned by a previous WebPageStatXXX function call. Possible return values are the URL, the content-type of the response, the document load-type (load, cache-hit, or suppressed), the document kind (html or embedded) and the location within a redirection chain (a redirection chain is created when a request is retried or reissued because of a redirection or an authentication request by the server).

To generally enable extended page statistics functionality, call WebSetOption with an option of WEB_OPT_DETAILED_PAGE_STAT (for a detailed description of the various values see WebSetOption).

Include file

WebAPI.bdh

Syntax

WebPageStatGetNodeInfo(
   out nNodeType    : number allownull,
   out sUrl         : string optional,
   out sContentType : string optional,
   out bHtml        : boolean optional,
   out bReload      : boolean optional,
   in  nNode        : number optional ): boolean;

Return value

  • true if the information is retrieved successfully

  • false otherwise

Parameter | Description
nNodeType

Will be one of the following values:

PAGE_STAT_FLAG_NodeTypeLoad
Node caused a request to the server (no cache hits and no suppressed documents).
PAGE_STAT_FLAG_NodeTypeCacheHit
Node found in the cache (full cache hit), so that no request to the server has been sent.
PAGE_STAT_FLAG_NodeTypeSuppress
No request has been sent to the server for this node because it has been suppressed by the user (WebPageSuppress or WebSetDomainSuppress).

If this value is not of interest, null can be specified.

sUrl

Returns the URL of the node.

If this value is not of interest, it can be omitted. Or null can be specified.

sContentType

Returns the content-type (server response) of the node.

If this value is not of interest, it can be omitted. Or null can be specified.

bHtml

Returns whether the node belongs to the document section of the page (normally html) or to the embedded section (normally an image or a script).

If this value is not of interest, it can be omitted. Or null can be specified.

bReload | Returns if the node is not the first document of a potential redirection chain (a redirection chain is created when a request is retried or reissued because of a redirection or an authentication request by the server).
nNode | Specify the node ID of the node for which information is to be returned (possibly returned by a previous WebPageStatXXX function). Provide a value of PAGE_STAT_Calculated if data of the most recent calculated node should be returned (WebPageStatCalcSummaryNode). When this parameter is omitted, the most recently returned or calculated node is used.

Example

dcltrans
  transaction TInit
  begin
    WebSetOption(WEB_OPT_DETAILED_PAGE_STAT,
                PAGE_STAT_FLAG_AllLoadedDocs);
  end TInit;

  transaction TWeb
  var
    nNode  : number;
    nType  : number;
    sUrl   : string;
    sCT    : string;
    bReload: boolean;
    fValue : float;
  begin
    WebPageUrl("http://lab3/");
    nNode := WebPageStatGetRootNode();
    if nNode > 0 then
      WebPageStatGetNodeInfo(nType, sUrl, sCT, null, bReload, nNode);
      WebPageStatGetNodeData(STATFLAG_TimerServerBusy, fValue);
      print("Type: " + string(nType));
      print("Url: " + sUrl);
      print("Content type: " + sCT);
      if bReload then
        print("root doc needed more than one request");
      end;
      print("ServerBusyTime [s]: " + string(fValue));
    end;
  end TWeb;
Parent topic: Page Statistic Functions


WebPageStatGetRootNode Function

Action

Returns the root node of the most recently loaded page. A node is a request/response pair which is illustrated as one element of the page-tree in TrueLog Explorer. Dependent of the setting specified by the call to WebSetOption, the returned node is either the first issued request (PAGE_STAT_FLAG_RedirChainOnlyFirst) or, if this request is redirected or retried, the last one when called with a value of PAGE_STAT_FLAG_RedirChainOnlyLast. The optional flag parameter can be used to overwrite the default flag value specified by the call to WebSetOption.

The return value is a node ID, which can be used in various other WebPageStatXXX calls.

To generally enable the extended page statistics functionality, call WebSetOption with an option of WEB_OPT_DETAILED_PAGE_STAT. For a detailed description of the various values see WebSetOption().

Include file

WebAPI.bdh

Syntax

WebPageStatGetRootNode( in nFlags: number optional ): number;

Return value

  • 0 if the node could not be found

  • >0 otherwise

Parameter Description
nFlags

Specifies the various options used by the search for the root node. If this parameter is omitted, the default options specified by the call to WebSetOption(WEB_OPT_DETAILED_PAGE_STAT) are used. Otherwise, specify one of the following values:

PAGE_STAT_FLAG_UseHtml
Returns nodes of the document section of the page (commonly html documents).
PAGE_STAT_FLAG_NodeTypeLoad
Returns nodes that caused a request to be sent to the server (no cache hits and no suppressed documents).
PAGE_STAT_FLAG_NodeTypeCacheHit
Returns nodes that have been found in the cache (full cache hit), so that no request to the server has been sent.
PAGE_STAT_FLAG_NodeTypeSuppress
Returns nodes for which no request has been sent to the server, because they have been suppressed by the user (WebPageSuppress or WebSetDomainSuppress).
PAGE_STAT_FLAG_RedirChainOnlyLast
Returns the last node of a potential redirection chain. (A redirection chain evolves when a request is retried or reissued because of a redirection or an authentication request by the server).

Example

dcltrans
  transaction TInit
  begin
    WebSetOption(WEB_OPT_DETAILED_PAGE_STAT,
                 PAGE_STAT_FLAG_AllLoadedDocs);
  end TInit;

  transaction TWeb
  var
    nNode  : number;
    fValue : float;
    sUrl   : string;
  begin
    WebPageUrl("http://lab3/");
    nNode := WebPageStatGetRootNode();
    if nNode > 0 then
      WebPageStatGetNodeInfo(null, sUrl);
      print("Root Url: " + sUrl);

      if WebPageStatGetFirstFrame(nNode) > 0 then
        WebPageStatGetNodeData(STATFLAG_BytesSent, fValue);
        print("BytesSent: " + string(fValue));
      end;
    end;
  end TWeb;
Parent topic: Page Statistic Functions


WebPageStatToTsd Function

Action

Adds detailed timers for the last page to the time series data.

Adds following timers to the “Timer” section:

  • <timername> - Connect

  • <timername> - DNS

  • <timername> - Recv

  • <timername> - Send

  • <timername> - ServerBusy

  • <timername> - SSL Handshake

The nOption parameter specifies which portion of the page should be measured. To execute this function for every page level call with a provided timername use the WebSetOption function.

Include file

WebAPI.bdh

Syntax

WebPageStatToTsd( in sTimer  : string,
                  in nSource : number ): boolean;

Return value

  • true if successful

  • false otherwise

Parameter | Description
sTimer | Specifies the prefix, used to compose the complete timer names.
nSource

Specifies for which part of the page should be measured. This parameter must be one of the following values:

STATFLAG_HtmlDoc
Measures all HTML documents.
STATFLAG_OtherDoc
Measures all types of documents except HTML documents.
STATFLAG_RootDoc
Measures only the first document.
STATFLAG_All
Measures all documents.

Example

dcltrans
  transaction TMain
  begin
    WebPageUrl("http://standardhost/");
    WebPageStatToTsd("Homepage", STATFLAG_All);
    WebPageLink("click here");
    WebPageLink("again");
    WebPageStatToTsd("Project view", STATFLAG_HtmlDoc );
  end TMain;
Parent topic: Page Statistic Functions
Related reference
WebSetOption Function
WebPageStatistics Function


Cookie Database Functions Overview

Under HTTP (HyperText Transfer Protocol), cookies are the means by which a server or a script can maintain state information on the client workstation. Silk Performer has implemented a non-persistent cookie database per virtual user for this purpose. WebCookie functions are provided so users can set cookies into, and access them from, the cookie database.

See WebSetCookies to set the size of the cookie database or to disable the use of cookies.

Note: The URL provided with the cookie function contains information about three cookie options: domain, secure and path.
  • WebCookieGet Function
    Returns the cookie header for the specified URL once all threads have finished their tasks.
  • WebCookieList Function
    Lists all cookies out of the cookie database and writes them to the output file.
  • WebCookieListFirst Function
    Lists the first cookie found in the cookie database.
  • WebCookieListNext Function
    Lists the next cookie found in the cookie database.
  • WebCookieResetDb Function
    Deletes all cookies in the cookie database.
  • WebCookieSet Function
    Sets a cookie in the cookie database.
Parent topic: Web Functions Reference
Related concepts
Cookies
Related reference
WebSetCookies Function
WebGetCookies Function


WebCookieGet Function

Action

Returns the cookie header for the specified URL once all threads have finished their tasks.

Include file

WebAPI.bdh

Syntax

WebCookieGet( out sCookie    : string,
              in  nMaxCookie : number,
              in  sUrl       : string): boolean;

Return value

  • true if a cookie is found

  • false otherwise

Parameter | Description
sCookie | Buffer that receives the cookie header if WebCookieGet succeeds
nMaxCookie | Specifies the size of the sCookie buffer. Specify STRING_COMPLETE to get all received data.
sUrl | URL for which to get cookies

Example

dclfunc
  function CookieGet(sUrl: string)
  var
    sCookieBuffer: string;
  begin
    if WebCookieGet(sCookieBuffer, STRING_COMPLETE, sUrl) then
      write("["); write(sCookieBuffer); write("] to URL: ");
      write(sUrl); writeln;
    else
      write("no appropriate cookie found! - URL: ");
      write(sUrl); writeln;
    end;
  end CookieGet;

SilkEssential sample

Cookies.sep

Parent topic: Cookie Database Functions Overview
Related reference
WebCookieSet Function


WebCookieList Function

Action

Lists all cookies out of the cookie database and writes them to the output file. This BDL function is implemented in WebAPI.bdh.

Include file

WebAPI.bdh

Syntax

WebCookieList(in nOptions : number optional);
Parameter Description
nOptions

(optional)

WEB_COOKIE_FLAG_DONT_FORCE_DOMAIN
Specifies that the domain of the cookie should only be included if it was originally specified when the cookie was entered into the cookie database.

Example

// This function shows how to list cookies stored
// in the cookie database
dclfunc
  function WebCookieList(nOptions : number optional)
  const MAX_COOKIE_BUF := 4096;
  var
    bCookie : boolean;
    sCookieBuffer : string(MAX_COOKIE_BUF);
  begin
    write("------ cookie database ------"); writeln;
    bCookie := WebCookieListFirst(sCookieBuffer, MAX_COOKIE_BUF, nOptions);
    while bCookie do
      write(sCookieBuffer); writeln;
      bCookie := WebCookieListNext(sCookieBuffer, MAX_COOKIE_BUF, nOptions);
    end;
  end WebCookieList;
Parent topic: Cookie Database Functions Overview
Related reference
WebCookieListFirst Function
WebCookieListNext Function


WebCookieListFirst Function

Action

Lists the first cookie found in the cookie database. This function waits for all threads to finish before listing the data.

Include file

WebAPI.bdh

Syntax

WebCookieListFirst( out sCookie    : string,
                    in  nMaxCookie : number optional,
                    in  nOptions   : number optional): boolean;

Return value

  • true if a cookie is found

  • false otherwise

Parameter | Description
sCookie | Buffer that receives the cookie header.
nMaxCookie | Specifies the size of the sCookie buffer (optional). Specify STRING_COMPLETE to get all received data.
nOptions

(optional)

WEB_COOKIE_FLAG_DONT_FORCE_DOMAIN
Specifies that the domain of the cookie should only be included if it was originally specified when the cookie was entered into the cookie database.

Example

// This function shows how to list cookies stored
// in the cookie database
dclfunc
  function WebCookieList(nOptions : number optional)
  var
    bCookie       : boolean;
    sCookieBuffer : string;
  begin
    write("------ cookie database ------"); writeln;
    bCookie := WebCookieListFirst(sCookieBuffer, STRING_COMPLETE, nOptions);
    while bCookie do
      write(sCookieBuffer); writeln;
      bCookie := WebCookieListNext(sCookieBuffer, STRING_COMPLETE, nOptions);
    end;
  end WebCookieList;

SilkEssential sample

Cookies.sep

Parent topic: Cookie Database Functions Overview
Related reference
WebCookieList Function
WebCookieListNext Function


WebCookieListNext Function

Action

Lists the next cookie found in the cookie database. Use this function after a successful WebCookieListFirst function call.

Note: This function waits for all threads to finish before listing the data.

Include file

WebAPI.bdh

Syntax

WebCookieListNext( out sCookie    : string,
                   in  nMaxCookie : number optional,
                   in  nOptions   : number optional): boolean;

Return value

  • true if a cookie is found

  • false if the end of the cookie database is reached

Parameter | Description
sCookie | Buffer that receives the cookie header.
nMaxCookie | Specifies the size of the sCookie buffer (optional). Specify STRING_COMPLETE to get all received data.
nOptions

(optional)

WEB_COOKIE_FLAG_DONT_FORCE_DOMAIN
Specifies that the domain of the cookie should only be included if it was originally specified when the cookie was entered into the cookie database.

Example

// This function shows how to list cookies stored
// in the cookie database
dclfunc
  function WebCookieList(nOptions : number optional)
  var
    bCookie : boolean;
    sCookieBuffer : string;
  begin
    write("------ cookie database ------"); writeln;
    bCookie := WebCookieListFirst(sCookieBuffer, STRING_COMPLETE, nOptions);

    while bCookie do
      write(sCookieBuffer); writeln;
      bCookie := WebCookieListNext(sCookieBuffer, STRING_COMPLETE, nOptions);
    end;
  end WebCookieList;

SilkEssential sample

Cookies.sep

Parent topic: Cookie Database Functions Overview
Related reference
WebCookieList Function
WebCookieListFirst Function


WebCookieResetDb Function

Action

Deletes all cookies in the cookie database.

Include file

WebAPI.bdh

Syntax

WebCookieResetDb(): boolean;

Return value

  • true if successful

  • false otherwise

Example

dcltrans
  transaction TWebCookieResetDb
  begin
    WebCookieResetDb();
  end TWebCookieResetDb;
Parent topic: Cookie Database Functions Overview


WebCookieSet Function

Action

Sets a cookie in the cookie database. The optional arguments domain, path and secure not specified in the sCookie string are set to their appropriate default values by examining sUrl.

Include file

WebAPI.bdh

Syntax

WebCookieSet( in sCookie : string,
              in sUrl    : string,
              in nDocNum : number optional ): boolean;

Return value

  • true if successful

  • false otherwise

Parameter | Description
sCookie | Data of a Set-Cookie: response header.
sUrl | String that specified the URL for which the cookie should be set.
nDocNum | If this parameter is not specified, the cookie is added to the cookie database immediatly. By specifying this parameter the cookie becomes a delayed cookie. This means, it will not be added to the cookie database immediately, but only before the document (frame) with the given number of the following page is downloaded.

Example

const
  MAX_COOKIE_BUFFER := 4096;

dclrand
  rsCustNo     : RndStr("0123456789", 10..10);
  rsCookieName : RndStr("COOKIE", 6..12);

dcltrans
  transaction TWebCookie
  var
    sCookie: string(MAX_COOKIE_BUFFER);
  begin
    // Put randomized cookies into the cookie database
    sCookie := "CUSTOMER_NO=" + rsCustNo +
               "; path=/; expires=Wednesday, 09-Nov-99 23:12:40";
    WebCookieSet(sCookie, "http://standardhost/");

    // Put a cookie into the cookie database
    sCookie := rsCookieName + "=; path=/; secure";
    WebCookieSet(sCookie, "http://standardhost/");
    // Put a cookie with a random name into the cookie database
    sCookie := rsCookieName + "=; path=/; secure";
    WebCookieSet(sCookie, "http://standardhost/");

    // Put a cookie into the cookie database
    // after the frameset and the first frame has been downloaded
    WebCookieSet(sCookie, "http://standardhost/", 3);
    WebPageUrl("http://standardhost/"); // frameset with 5 frames
  end TWebCookie;

Sample scripts

WebMulti01.bdf

SilkEssential sample

Cookies.sep

Parent topic: Cookie Database Functions Overview
Related reference
WebCookieGet Function
WebSetCookies Function
WebGetCookies Function


Parsing Functions

  • WebParseHtmlBound Function
    Parses the HTML content for sLeftBoundary and sRightBoundary and stores the string between these boundaries in sResult.
  • WebParseHtmlBoundEx function
    Parses the HTML content for sLeftBoundary and sRightBoundary and stores the string between these boundaries in sResult.
  • WebParseHtmlBoundArray Function
    Parses the HTML content for sLeftBoundary and sRightBoundary and stores all strings between these boundaries in saResult.
  • WebParseDataBound Function
    Parses the response data for sLeftBoundary and sRightBoundary and stores the string between these boundaries in sResult.
  • WebParseDataBoundEx Function
    Parses the response data for sLeftBoundary and sRightBoundary and stores the string between these boundaries in sResult.
  • WebParseDataBoundArray Function
    Parses the response data for sLeftBoundary and sRightBoundary and stores all strings between these boundaries in saResult.
  • WebParseHtmlTitle Function
    Parses the <TITLE> tag of the HTML response and stores the content it in the provided string.
  • WebParseTable Function
    Parses HTML tables and stores the content of the specified cell in the provided string.
  • WebParseTableVLookup Function
    Parses HTML tables and stores the content of the specified cell in the provided string. In contrast to the function WebParseTable, the row number is determined dynamically through the content of a search column.
  • WebParseResponseData Function
    Parses the response data (commonly HTML) for sLeftBoundary and sRightBoundary and stores the string between these boundaries in sResult.
  • WebParseResponseHeader Function
    Parses the HTTP headers of a server response and stores the header value in sResult.
  • WebParseResponseRedirect Function
    Parses the URL of a redirection response for URL encoded parameters.
  • WebParseResponseStatus Function
    Parses the response header status line if a variable is specified as an out parameter.
  • WebParseResponseTag Function
    Parses the HTML response and stores the value of a specified attribute in a string variable.
  • WebParseResponseTagContent Function
    Parses the HTML response and stores the HTML content or the raw HTML code in a string variable.
Parent topic: Web Functions Reference


WebParseHtmlBound Function

Action

Parses the HTML content for sLeftBoundary and sRightBoundary and stores the string between these boundaries in sResult. If the right delimiter (sRightBoundary) is not specified (set to NULL), the string after sLeftBoundary with length nMaxResultLen is returned. If the left delimiter (sLeftBoundary) is not specified (set to NULL), the string from beginning to the right delimiter with a maximum length of nMaxResultLen is returned. If both boundary search strings are omitted (sLeftBoundary and sRightBoundary are set to NULL), all data with maximum length is stored into sResult. If the nMaxResultLen is set to STRING_COMPLETE an unlimited amount of data is stored in the sResult parameter.

It is important to know that all parsing and verification functions must be specified before the Web API call for which the response data should be parsed/verified. You can specify multiple parse/verification functions before a Web API call. The order of the parse/verification functions is not relevant (Exception: WebParseDataBound and WebVerifyDataBound using the flag WEB_FLAG_SYNCHRON).

When verifying/parsing an HTML page that consists of multiple frames, you can specify which frame document to verify/parse by specifying the sFrame parameter. By default, all HTML documents of the HTML page are scanned. This applies to HTML pages that are retrieved through a page-level command like WebPageUrl or WebPageLink.

Include file

WebAPI.bdh

Syntax

WebParseHtmlBound( out sResult        : string,
                   in  nMaxResultLen  : number optional,
                   in  sLeftBoundary  : string optional,
                   in  sRightBoundary : string optional,
                   in  nOptions       : number optional,
                   in  sFrame         : string optional,
                   out nBytesParsed   : number optional );

Return value

  • none

Parameter | Description
sResult | String variable that receives the string between the specified boundary strings.
nMaxResultLen | Maximum length of the string to return (optional). If this parameter is omitted or set to STRING_COMPLETE all available data is stored in sResult.
sLeftBoundary | Left boundary of the HTML content to compare.
sRightBoundary | Right boundary of the HTML content to compare.
nOptions

Parsing options (optional). If this flag is omitted, none of the listed options are applied, meaning that the string comparison is case-insensitive, white spaces are not ignored, etc.

WEB_FLAG_CASE_SENSITIVE
If this flag is set the string compare operation is case sensitive.
WEB_FLAG_IGNORE_WHITE_SPACE
If this flag is set all white spaces are ignored.
WEB_FLAG_DONT_FORCE_LOAD
Specify this option to enable caching for subsequent request. Note that nothing is parsed if the specified table is not loaded (cache hit).
WEB_FLAG_RULE
Specify this flag to perform the parsing operation in every subsequent web function. After every web function the specified output variables are set to the new value. If you want to use the variables in other transactions or in event handler functions use global variables! Call WebCancelAllRules() do disable all verification and parsing rules.
Note: The option WEB_FLAG_RULE should only be used in the INIT transaction or in combination with the WebCancelAllRules function!
sFrame | Frame that gets searched for the content string (optional). If this parameter is omitted the whole page is scanned.
nBytesParsed | Variable receiving the number of the bytes that are actually parsed (optional).

Example

dcltrans
  transaction TMain
  var
    nResult : number;
    sResult : string;
  begin
    WebParseHtmlBound(sResult, STRING_COMPLETE, "Begin", "X.X");
    WebPageUrl("http://mycompany.com/");
    Print(sResult);

    WebParseHtmlBound(sResult,
STRING_COMPLETE, "Begin", "X.X",  WEB_FLAG_IGNORE_WHITE_SPACE, "FrameA", nResult);
    WebUrl("http://mycompany.com/Shop/default.htm");
    Print(sResult);
    Print(string(nResult) + "Bytes parsed");
  end TMain;
Parent topic: Parsing Functions


WebParseHtmlBoundEx function

Action

Parses the HTML content for sLeftBoundary and sRightBoundary and stores the string between these boundaries in sResult. If the right delimiter (sRightBoundary) is not specified (set to NULL), the string after sLeftBoundary with length nMaxResultLen is returned. If the left delimiter (sLeftBoundary) is not specified (set to NULL), the string from beginning to the right delimiter with a maximum length of nMaxResultLen is returned. If both boundary search strings are omitted (sLeftBoundary and sRightBoundary are set to NULL), all data with maximum length is stored into sResult. If the nMaxResultLen is set to STRING_COMPLETE an unlimited amount of data is stored in the sResult parameter.

When verifying/parsing an HTML page that consists of multiple frames, you can specify which frame document to verify/parse by specifying the sFrame parameter. By default, all HTML documents of the HTML page are scanned. This applies to HTML pages that are retrieved through a page-level command like WebPageUrl or WebPageLink.

It is important to know that all parsing and verification functions must be specified before the Web API call for which the response data should be parsed/verified. You can specify multiple parse/verification functions before a Web API call. The order of the parse/verification functions is not relevant (Exception: WebParseDataBound and WebVerifyDataBound using the flag WEB_FLAG_SYNCHRON).

Include file

WebAPI.bdh

Syntax

WebParseHtmlBoundEx(out sResult         : string,
                    in  nMaxResultLen   : number optional,
                    in  sLeftBoundary   : string optional,
                    in  nLeftOccurrence : number optional,
                    in  sRightBoundary  : string optional,
                    in  nOptions        : number optional,
                    in  sFrame          : string optional,
                    out nBytesParsed    : number optional);

Return value

  • none

Parameter | Description

sResult

String variable that receives the string between the specified boundary strings.
nMaxResultLen | Maximum length of the string to return (optional). If this parameter is omitted or set to STRING_COMPLETE all available data is stored in sResult.
sLeftBoundary | Left boundary of the HTML content to compare.
nLeftOccurrence | The sLeftBoundary has to be found nLeftOccurrence times, before the copy process starts and the right boundary is searched (optional). The default value is one. Provide WEB_OCCURENCE_LAST to specify the last Occurrence.
sRightBoundary | Right boundary of the HTML content to compare.

nOptions

Parsing options (optional). If this flag is omitted, none of the listed options are applied, meaning that the string comparison is case-insensitive, white spaces are not ignored, etc.

WEB_FLAG_CASE_SENSITIVE
If this flag is set the string compare operation is case sensitive.
WEB_FLAG_IGNORE_WHITE_SPACE
If this flag is set all white spaces are ignored.
WEB_FLAG_DONT_FORCE_LOAD
Specify this option to enable caching for the subsequent request. Note that nothing is parsed if the specified table is not loaded (cache hit).
WEB_FLAG_RULE
Specify this flag to perform the parsing operation in every subsequent Web function. After every Web function the specified output variables are set to the new value. If you want to use the variables in other transactions or in event handler functions, you must use global variables. Call WebCancelAllRules() to disable all verification and parsing rules.
Important: The option WEB_FLAG_RULE should only be used in the INIT transaction or in combination with the WebCancelAllRules function.
sFrame | Frame that gets searched for the content string (optional). If this parameter is omitted the whole page is scanned.
nBytesParsed | Variable receiving the number of the bytes that are actually parsed (optional).

Example

dcltrans
  transaction TMain
  var
    nResult : number;
    sResult : string;
  begin
    WebParseHtmlBoundEx(sResult, STRING_COMPLETE, "Begin", 2, "X.X");
    WebPageUrl("http://mycompany.com/");
    Print(sResult);

    WebParseHtmlBoundEx(sResult, STRING_COMPLETE, "Begin", 2, "X.X", WEB_FLAG_IGNORE_WHITE_SPACE, "FrameA", nResult);
    WebUrl("http://mycompany.com/Shop/default.htm");
    Print(sResult);
    Print(string(nResult) + "Bytes parsed");
  end TMain;
Parent topic: Parsing Functions


WebParseHtmlBoundArray Function

Action

Parses the HTML content for sLeftBoundary and sRightBoundary and stores all strings between these boundaries in saResult. If the right delimiter (sRightBoundary) is not specified (set to NULL), every nMaxLen (must be specified) bytes after the occurrences of sLeftBoundary are returned. In contrary the WebParseHtmlBoundEx function the second left boundary is only searched after the right boundary has been found or, if the right boundary parameter is omitted, nMaxLen bytes after the occurrence of the first left boundary.

When verifying/parsing an HTML page that consists of multiple frames, you can specify which frame document to verify/parse by specifying the sFrame parameter. By default, all HTML documents of the HTML page are scanned. This applies to HTML pages that are retrieved through a page-level command like WebPageUrl or WebPageLink.

It is important to know that all parsing and verification functions must be specified before the Web API call for which the response data should be parsed/verified. You can specify multiple parse/verification functions before a Web API call. The order of the parse/verification functions is not relevant (Exception: WebParseDataBound and WebVerifyDataBound using the flag WEB_FLAG_SYNCHRON).

Include file

WebAPI.bdh

Syntax

WebParseHtmlBoundArray( inout saResult       : array of string,
                        in    nMaxCount      : number,
                        in    sLeftBoundary  : string,
                        in    sRightBoundary : string allownull,
                        out   nFound         : number optional,
                        in    nOptions       : number optional,
                        in    nSkip          : number optional,
                        in    sFrame         : string optional,
                        in    nMaxLen        : number optional);
Parameter | Description
saResult | Array of string variable that receives all the strings between the specified boundary strings.
nMaxCount | Maximum number of strings copied into the provided array. This value must be less than or equal to the size of the array.
sLeftBoundary | Left boundary to compare.
sRightBoundary | Right boundary. After the sLeftBoundary has to been found, all data is copied into the actual string parameter until the right boundary is found (optional). If this parameter is omitted the nMaxLen parameter must be specified.
nFound | Variable that receives the number of the found strings (optional).
nOptions

Parsing options (optional). If this flag is omitted, none of the listed options are applied, meaning that the string comparison is case-insensitive, white spaces are not ignored, etc.

WEB_FLAG_CASE_SENSITIVE
If this flag is set the string compare operation is case sensitive.
WEB_FLAG_IGNORE_WHITE_SPACE
If this flag is set all white spaces are ignored.
WEB_FLAG_DONT_FORCE_LOAD
Specify this option to enable caching for subsequent request. Note that nothing is parsed if the specified table is not loaded (cache hit).
WEB_FLAG_RULE
Specify this flag to perform the parsing operation in every subsequent web function. After every web function the specified output variables are set to the new value. If you want to use the variables in other transactions or in event handler functions use global variables! Call WebCancelAllRules() do disable all verification and parsing rules.
Note: The option WEB_FLAG_RULE should only be used in the INIT transaction or in combination with the WebCancelAllRules function!
nSkip | Specifies the number of parse results, which should not be stored in the array (optional). The first element of the array will be the (nSkip+1) th parse result.
sFrame | Frame that gets searched for the content string (optional). If this parameter is omitted the whole page is scanned.
nMaxLen | Specifies the maximum number of bytes copied to each string (optional). If the sRightBoundary parameter is omitted this parameter must be specified and determines the end of every parsing operation.

Example

transaction TWeb
  var
    sa, sa1         : array[10] of string;
    nFound, nFound1 : number;
    i               : number;
  begin
    WebParseHtmlBoundArray(sa, 10, "Price:", "Euro", nFound);
    WebParseHtmlBoundArray(sa1,
10, "Begin", null, nFound1, 0, 0, null, 5);
    WebPageUrl("http://lab3");

    print("found " + string(nFound) + " prices");
    print("found " + string(nFound1) + " Begin... statements");
    for i:= 1 to  nFound do
      print(sa[i]);
    end;
    for i:= 1 to nFound1 do
      print(sa1[i]);
    end;
  end TWeb;
Parent topic: Parsing Functions
Related reference
WebParseDataBoundArray Function


WebParseDataBound Function

Action

Parses the response data for sLeftBoundary and sRightBoundary and stores the string between these boundaries in sResult. If the right delimiter (sRightBoundary) is not specified (set to NULL), the string after sLeftBoundary with length nMaxResultLen is returned. If the left delimiter (sLeftBoundary) is not specified (set to NULL), the string from beginning (or after the last position of a previous search with) with maximum length nMaxResultLen is returned. If both boundary search strings are omitted (sLeftBoundary and sRightBoundary are set to NULL), all data with maximum length is stored into sResult. If the nMaxResultLen is set to STRING_COMPLETE an unlimited amount of data is stored in the sResult parameter.

When verifying/parsing an HTML page that consists of multiple frames (HTML documents), you can specify which frame document to verify/parse by specifying the nDocNum parameter. By default (1) the top document (e.g. a frameset) is scanned. This applies to HTML pages that are retrieved through a page-level command like WebPageUrl or WebPageLink.

It is important to know that all parsing and verification functions must be specified before the Web API call for which the response data should be parsed/verified. You can specify multiple parse/verification functions before a Web API call. The order of the parse/verification functions is not relevant (Exception: WebParseDataBound and WebVerifyDataBound using the flag WEB_FLAG_SYNCHRON).

Note: This function can be added automatically to your script using the visual parsing functionality of TrueLog Explorer.

Include file

WebAPI.bdh

Syntax

WebParseDataBound( out sResult        : string,
                   in  nMaxResultLen  : number optional,
                   in  sLeftBoundary  : string optional,
                   in  sRightBoundary : string optional,
                   in  nOptions       : number optional,
                   in  nDocNum        : number optional,
                   out nBytesParsed   : number optional );

Return value

  • none

Parameter | Description
sResult | String variable that receives the string between the specified boundary strings.
nMaxResultLen | Maximum length of the string to return (optional). If this parameter is omitted or set to STRING_COMPLETE all available data is stored in sResult.
sLeftBoundary | Left boundary of the HTML content to compare.
sRightBoundary | Right boundary of the HTML content to compare.
nOptions

Parsing options (optional). If this flag is omitted, none of the listed options are applied, meaning that the string comparison is case-insensitive, white spaces are not ignored, etc.

WEB_FLAG_CASE_SENSITIVE
If this flag is set the string compare operation is case sensitive.
WEB_FLAG_IGNORE_WHITE_SPACE
If this flag is set all white spaces are ignored .
WEB_FLAG_DONT_FORCE_LOAD
Specify this option to enable caching for subsequent request. Note that nothing is parsed if the specified table is not loaded (cache hit).
WEB_FLAG_SYNCHRON
Parsing operations with this flag set, are done in a sequential way. The second parsing operation is not executed before the first has been completed.
WEB_FLAG_ALL_RESPONSES
If this flag is specified all server responses are scanned (even redirection responses, which are normally not displayed by a browser).
WEB_FLAG_INCLUDE_EMBEDDED.
If this flag is specified, even embedded documents can be specified by the nDocNum parameter. Normally the number of a document is defined by the occurrence of the source definition in an HTML document (src=...). If this flag is specified, every embedded object increases this counter, which assigns higher numbers to subsequent frames.
WEB_FLAG_INCLUDE_HEADER
If this flag is specified the response header can also be verified.
WEB_FLAG_HEADER_ONLY
If this flag is specified only the response header is verified.
WEB_FLAG_RULE
Specify this flag to perform the parsing operation in every subsequent web function. After every web function the specified output variables are set to the new value. If you want to use the variables in other transactions or in event handler functions use global variables! Call WebCancelAllRules() do disable all verification and parsing rules.
Note: The option WEB_FLAG_RULE should only be used in the INIT transaction or in combination with the WebCancelAllRules function!
nDocNum | Specifies the document to parse (optional). Specify WEB_DOC_ALL if you want to parse all documents. If this parameter is omitted, the first document gets parsed. (see above definition FLAG_INCLUDE_EMBEDDED)
nBytesParsed | Variable receiving the number of bytes actually parsed (optional).

Example

dcltrans
  transaction TMain
  var
    nResult : number;
    sHead   : string;
    sResult : string;
  begin
    WebParseDataBound(sResult, STRING_COMPLETE, "<Title>", "</Title>");
    WebPageUrl("http://mycompany.com/");
    WebParseDataBound(sHead, STRING_COMPLETE, "<head>", "</head>",
      WEB_FLAG_CASE_SENSITIVE | WEB_FLAG_IGNORE_WHITE_SPACE);
    WebParseDataBound(sResult, 200, "<b>Shop",
"&amp;", WEB_FLAG_CASE_SENSITIVE, 2, nResult);
    WebUrl("http://mycompany.com/Shop/default.htm");
    Print(sHead);
    Print(sResult);
    Print(string(nResult) + "Bytes parsed");
  end TMain;
Parent topic: Parsing Functions


WebParseDataBoundEx Function

Action

Parses the response data for sLeftBoundary and sRightBoundary and stores the string between these boundaries in sResult. If the right delimiter (sRightBoundary) is not specified (set to NULL), the string after sLeftBoundary with length nMaxResultLen is returned. If the left delimiter (sLeftBoundary) is not specified (set to NULL), the string from beginning (or after the last position of a previous search with) with maximum length nMaxResultLen is returned. If both boundary search strings are omitted (sLeftBoundary and sRightBoundary are set to NULL), all data with maximum length is stored into sResult. If the nMaxResultLen is set to STRING_COMPLETE an unlimited amount of data is stored in the sResult parameter. If nLeftOccurrence is greater than 1 (default is one) the sLeftBoundary has to be found nLeftOccurrence times, before the copy process starts and the right boundary is searched.

When verifying/parsing an HTML page that consists of multiple frames (HTML documents), you can specify which frame document to verify/parse by specifying the nDocNum parameter. By default (1) the top document (e.g. a frameset) is scanned. This applies to HTML pages that are retrieved through a page-level command like WebPageUrl or WebPageLink.

It is important to know that all parsing and verification functions must be specified before the Web API call for which the response data should be parsed/verified. You can specify multiple parse/verification functions before a Web API call. The order of the parse/verification functions is not relevant (Exception: WebParseDataBound and WebVerifyDataBound using the flag WEB_FLAG_SYNCHRON).

Note: This function can be added automatically to your script using the visual parsing functionality of TrueLog Explorer.

Include file

WebAPI.bdh

Syntax

WebParseDataBoundEx(out sResult        : string,
                    in  nMaxResultLen  : number optional,
                    in  sLeftBoundary  : string optional,
                    in  nLeftOccurrence : number optional,
                    in  sRightBoundary : string optional,
                    in  nOptions       : number optional,
                    in  nDocNum        : number optional,
                    out nBytesParsed   : number optional);

Return value

  • none

Parameter | Description
sResult | String variable that receives the string between the specified boundary strings.
nMaxResultLen | Maximum length of the string to return (optional). If this parameter is omitted or set to STRING_COMPLETE all available data is stored in sResult.
sLeftBoundary | Left boundary of the HTML content to compare.
nLeftOccurrence | The sLeftBoundary has to be found nLeftOccurrence times, before the copy process starts and the right boundary is searched (optional). The default value is one. Provide WEB_OCCURENCE_LAST to specify the last occurrence.
sRightBoundary | Right boundary of the HTML content to compare.
nOptions

Parsing options (optional). If this flag is omitted, none of the listed options are applied, meaning that the string comparison is case-insensitive, white spaces are not ignored, etc.

WEB_FLAG_CASE_SENSITIVE
If this flag is set the string compare operation is case sensitive.
WEB_FLAG_IGNORE_WHITE_SPACE
If this flag is set all white spaces are ignored.
WEB_FLAG_DONT_FORCE_LOAD
Specify this option to enable caching for subsequent request. Note that nothing is parsed if the specified table is not loaded (cache hit).
WEB_FLAG_SYNCHRON
Parsing operations with this flag set, are done in a sequential way. The second parsing operation is not executed before the first has been completed.
WEB_FLAG_ALL_RESPONSES
If this flag is specified all server responses are scanned (even redirection responses, which are normally not displayed by a browser).
WEB_FLAG_INCLUDE_EMBEDDED
If this flag is specified, even embedded documents can be specified by the nDocNum parameter. Normally the number of a document is defined by the occurrence of the source definition in an HTML document (src=...). If this flag is specified, every embedded object increases this counter, which assigns higher numbers to subsequent frames.
WEB_FLAG_INCLUDE_HEADER
If this flag is specified the response header can also be verified.
WEB_FLAG_HEADER_ONLY
If this flag is specified only the response header is verified.
WEB_FLAG_RULE
Specify this flag to perform the parsing operation in every subsequent web function. After every web function the specified output variables are set to the new value. If you want to use the variables in other transactions or in event handler functions use global variables! Call WebCancelAllRules() do disable all verification and parsing rules.
Note: The option WEB_FLAG_RULE should only be used in the INIT transaction or in combination with the WebCancelAllRules function!
nDocNum | Specifies the document to parse (optional). Specify WEB_DOC_ALL if you want to parse all documents. If this parameter is omitted, the first document gets parsed. (see above definition FLAG_INCLUDE_EMBEDDED)
nBytesParsed | Variable receiving the number of bytes actually parsed (optional).

Example

dcltrans
  transaction TMain
  var
    nResult: number;
    sFont: string;
    sResult: string;
  begin
    WebParseDataBoundEx(sResult, STRING_COMPLETE, "<table>", 2, "</table>");
    WebPageUrl("http://mycompany.com/");
    WebParseDataBoundEx(sFont,
STRING_COMPLETE, "<font>", 6, "</font>", WEB_FLAG_CASE_SENSITIVE |
WEB_FLAG_IGNORE_WHITE_SPACE);
    WebParseDataBoundEx(sResult, 200, "<b>Shop", 2,
"&amp;", WEB_FLAG_CASE_SENSITIVE, 2, nResult);
    WebUrl("http://mycompany.com/Shop/default.htm");
    Print(sFont);
    Print(sResult);
    Print(string(nResult) + "Bytes parsed");
  end TMain;
Parent topic: Parsing Functions


WebParseDataBoundArray Function

Action

Parses the response data for sLeftBoundary and sRightBoundary and stores all strings between these boundaries in saResult. If the right delimiter (sRightBoundary) is not specified (set to NULL), every nMaxLen (must be specified) bytes after the occurrences of sLeftBoundary are returned. In contrary the WebParseDataBoundEx function the second left boundary is only searched after the right boundary has been found or, if the right boundary parameter is omitted, nMaxLen bytes after the occurrence of the first left boundary.

When verifying/parsing an HTML page that consists of multiple frames (HTML documents), you can specify which frame document to verify/parse by specifying the nDocNum parameter. By default (1) the top document (for example a frameset) is scanned. This applies to HTML pages that are retrieved through a page-level command like WebPageUrl or WebPageLink.

It is important to know that all parsing and verification functions must be specified before the Web API call for which the response data should be parsed/verified. You can specify multiple parse/verification functions before a Web API call. The order of the parse/verification functions is not relevant (Exception: WebParseDataBound and WebVerifyDataBound using the flag WEB_FLAG_SYNCHRON).

Include file

WebAPI.bdh

Syntax

WebParseDataBoundArray( inout saResult       : array of string,
                        in    nMaxCount      : number,
                        in    sLeftBoundary  : string,
                        in    sRightBoundary : string allownull,
                        out   nFound         : number optional,
                        in    nOptions       : number optional,
                        in    nSkip          : number optional,
                        in    nDocNum        : number optional,
                        in    nMaxLen        : number optional);
Parameter Description

saResult

Array of string variable that receives all the strings between the specified boundary strings.

nMaxCount

Maximum number of strings copied into the provided array. This value must be less than or equal to the size of the array.

sLeftBoundary

Left boundary to compare.

sRightBoundary

Right boundary. After the sLeftBoundary has been found, all data is copied into the actual string parameter until the right boundary is found (optional). If this parameter is omitted the nMaxLen parameter must be specified.

nFound

Variable that receives the number of the found strings (optional).

nOptions

Parsing options (optional). If this flag is omitted, none of the listed options are applied, meaning that the string comparison is case-insensitive, white spaces are not ignored, etc.

WEB_FLAG_CASE_SENSITIVE
If this flag is set the string compare operation is case sensitive.
WEB_FLAG_IGNORE_WHITE_SPACE
If this flag is set all white spaces are ignored.
WEB_FLAG_DONT_FORCE_LOAD
Specify this option to enable caching for the subsequent request. Note that nothing is parsed if the specified table is not loaded (cache hit).
WEB_FLAG_SYNCHRON
Parsing operations with this flag set are done in a sequential way. The second parsing operation is not executed before the first has been completed.
WEB_FLAG_ALL_RESPONSES
If this flag is specified all server responses are scanned, even redirection responses, which are normally not displayed by a browser.
WEB_FLAG_INCLUDE_EMBEDDED
If this flag is specified, even embedded documents can be specified by the nDocNum parameter. Normally the number of a document is defined by the occurrence of the source definition in an HTML document (src=...). If this flag is specified, every embedded object increases this counter, which assigns higher numbers to subsequent frames.
WEB_FLAG_INCLUDE_HEADER
If this flag is specified the response header can also be verified.
WEB_FLAG_HEADER_ONLY
If this flag is specified only the response header is verified.
WEB_FLAG_RULE
Specify this flag to perform the parsing operation in every subsequent Web function. After every Web function the specified output variables are set to the new value. If you want to use the variables in other transactions or in event handler functions, you must use global variables. Call WebCancelAllRules() to disable all verification and parsing rules.
Important: The option WEB_FLAG_RULE should only be used in the INIT transaction or in combination with the WebCancelAllRules function.

nSkip

Specifies the number of parse results that should not be stored in the array (optional). The first element of the array will be the parse-result number nSkip+1.

nDocNum

Specifies the document to parse (optional). Specify WEB_DOC_ALL if you want to parse all documents. If this parameter is omitted, the first document gets parsed (see also FLAG_INCLUDE_EMBEDDED).

nMaxLen

Specifies the maximum number of bytes copied to each string (optional). If the sRightBoundary parameter is omitted, this parameter must be specified and determines the end of every parsing operation.

Example

transaction TWeb
  var
    sa, sa1         : array[10] of string;
    nFound, nFound1 : number;
    i               : number;
  begin
    WebParseDataBoundArray(sa, 10, "<!--", "-->", nFound);
    WebParseDataBoundArray(sa1,
10, "Begin", null, nFound1, 0, 0, 0, 5); //5 bytes
    WebPageUrl("http://lab3");

    print("found " + string(nFound) + " comments");
    print("found " + string(nFound1) + " Begin... statements");
    for i:= 1 to nFound do
      print(sa[i]);
    end;
    for i:= 1 to nFound1 do
      print(sa1[i]);
    end;
  end TWeb;
Parent topic: Parsing Functions
Related reference
WebParseHtmlBoundArray Function


WebParseHtmlTitle Function

Action

Parses the <TITLE> tag of the HTML response and stores the content it in the provided string. A subsequent low-level web function will not return a value until the request has finished. If a page consists of more than one HTML document, the sub frame that gets parsed for the HTML title can be specified with the nDoc parameter.

When verifying/parsing an HTML page that consists of multiple frames (HTML documents), you can specify which frame document to verify/parse by specifying the nDocNum parameter. By default (1) the top document (e.g. a frameset) is scanned. This applies to HTML pages that are retrieved through a page-level command like WebPageUrl or WebPageLink.

It is important to know that all parsing and verification functions must be specified before the Web API call for which the response data should be parsed/verified. You can specify multiple parse/verification functions before a Web API call. The order of the parse/verification functions is not relevant (Exception: WebParseDataBound and WebVerifyDataBound using the flag WEB_FLAG_SYNCHRON).

Include file

WebAPI.bdh

Syntax

WebParseHtmlTitle( out sResult       : string,
                   in  nMaxResultLen : number optional,
                   in  nDocNum       : number optional );

Return value

  • none

Parameter | Description
sResult | String variable that receives the string between the specified boundary strings.
nMaxResultLen | Maximum length of the string to return (optional). If this parameter is omitted or set to STRING_COMPLETE all available data is stored in sResult.
nDocNum | Specifies the document where to parse the HTML title (optional). The default (1) specifies the top document (e.g. a frameset).

Example

dcltrans
  transaction TMain
  var
    sResult  : string;
    sResult1 : string;
  begin
    WebParseHtmlTitle(sResult, STRING_COMPLETE);
    WebPageUrl("http://mycompany.com/");
    WebParseHtmlTitle(sResult, STRING_COMPLETE);
    WebUrl("http://mycompany.com/Shop/default.htm");
    WebVerifyHtmlTitle(sResult);
    WebVerifyHtmlTitle(sResult1, 200, 2); // second frame
    WebPageUrl("http://mycompany.com/frame/framea.html");
  end TMain;
Parent topic: Parsing Functions


WebParseTable Function

Action

Parses HTML tables and stores the content of the specified cell in the provided string. A subsequent low-level web function will not return a value until the request has finished.

When verifying/parsing an HTML page that consists of multiple frames, you can specify which frame document to verify/parse by specifying the sFrame parameter. By default, all HTML documents of the HTML page are scanned. This applies to HTML pages that are retrieved through a page-level command like WebPageUrl or WebPageLink.

It is important to know that all parsing and verification functions must be specified before the Web API call for which the response data should be parsed/verified. You can specify multiple parse/verification functions before a Web API call. The order of the parse/verification functions is not relevant (Exception: WebParseDataBound and WebVerifyDataBound using the flag WEB_FLAG_SYNCHRON).

Include file

WebAPI.bdh

Syntax

WebParseTable( out sResult       : string,
               in  nMaxResultLen : number,
               in  nTablenNum    : number,
               in  nRow          : number,
               in  nColumn       : number,
               in  nOptions      : number optional,
               in  sFrame        : string optional,
               out nBytesParsed  : number optional);

Return value

  • none

Parameter | Description
sResult | String variable that receives the content of the specified cell.
nMaxResultLen | Maximum length of the string to return. Set this parameter to STRING_COMPLETE all available data is stored in sResult.
nTableNum | The nTableNum th table is parsed.
nRow | Specifies the row of the cell to parse.
nColumn | Specifies the column of the cell to parse.
nOptions

Parsing options (optional). If this flag is omitted, none of the listed options are applied, meaning that the string comparison is case-insensitive, white spaces are not ignored, etc.

WEB_FLAG_DONT_FORCE_LOAD
Specify this option to enable caching for subsequent request. Note that nothing is parsed if the specified table is not loaded (cache hit).
sFrame | Frame that gets searched for the specified table (optional). If this parameter is omitted the whole page is scanned.
nBytesParsed | Variable receiving the number of the bytes that actually parsed (optional).

Example

dcltrans
  transaction TMain
  var
    sResult  : string;
    sResult1 : string;
    nResult  : number;
  begin
    WebParseTable(sResult, STRING_COMPLETE, 2, 3, 4);
    WebPageUrl("http://mycompany.com/");
    Print(sResult);

    WebParseTable(sResult,
STRING_COMPLETE, 2, 1, 2, WEB_FLAG_DONT_FORCE_LOAD); // sResult can be ""
    WebUrl("http://mycompany.com/Shop/default.htm");
    Print(sResult);

    WebParseTable(sResult, STRING_COMPLETE, 2, 2, 2);
    WebParseTable(sResult,
STRING_COMPLETE, 3, 2, 3, 0, "FrameB", nResult);
    WebPageUrl("http://mycompany.com/frame/framea.html");
    Print(sResult);
    Print(sResult1);
    Print(string(nResult) + "Bytes parsed");
  end TMain;
Parent topic: Parsing Functions


WebParseTableVLookup Function

Action

Parses HTML tables and stores the content of the specified cell in the provided string. In contrast to the function WebParseTable, the row number is determined dynamically through the content of a search column. A subsequent low-level web function will not return a value until the request has finished.

When verifying/parsing an HTML page that consists of multiple frames, you can specify which frame document to verify/parse by specifying the sFrame parameter. By default, all HTML documents of the HTML page are scanned. This applies to HTML pages that are retrieved through a page-level command like WebPageUrl or WebPageLink.

It is important to know that all parsing and verification functions must be specified before the Web API call for which the response data should be parsed/verified. You can specify multiple parse/verification functions before a Web API call. The order of the parse/verification functions is not relevant (Exception: WebParseDataBound and WebVerifyDataBound using the flag WEB_FLAG_SYNCHRON).

Include file

WebAPI.bdh

Syntax

WebParseTableVLookup( out sResult        : string,
                      in  nMaxResultLen  : number,
                      in  nTableNum      : number,
                      in  nSearchColumn  : number,
                      in  sSearchText    : string,
                      in  nSearchOptions : number,
                      in  nResultColumn  : number,
                      in  sFrame         : string optional,
                      out nBytesParsed   : number optional);

Return value

  • none

Parameter | Description
sResult | String variable that receives the content of the specified cell.
nMaxResultLen | Maximum length of the string to return. Set this parameter to STRING_COMPLETE all available data is stored in sResult.
nTableNum | The nTableNum th table is parsed.
nSearchColumn | Specifies in which column to look for sSearchText.
nSearchText | The search text identifies the correct row. If multiple rows match the search text, the first matching row is parsed.
nSearchOptions
WEB_FLAG_CONTAINS
The actual parsed table cell must contain the specified string. Otherwise the verification fails.
WEB_FLAG_CONTAINS_NOT
The actual parsed table cell must not contain the specified string. Otherwise the verification fails.
WEB_FLAG_IS_DIFFERENT
The actual parsed table cell must not be equal to the specified string. Otherwise the verification fails.
WEB_FLAG_EQUAL
The actual parsed table cell must be equal to the specified string. Otherwise the verification fails. If none of the above 3 flags are specified, the WEB_FLAG_EQUAL flag is used.
WEB_FLAG_CASE_SENSITIVE
If this flag is set the string compare operation is case sensitive.
WEB_FLAG_IGNORE_WHITE_SPACE
If this flag is set all white spaces are ignored.
WEB_FLAG_DONT_FORCE_LOAD
Specify this option to enable caching for subsequent request. Note that this may lead to unpredictable behaviour, because the verification may only cover certain parts (that are loaded) of a page.
nResultColumn | Specifies the column of the cell to parse.
sFrame | Frame that gets searched for the specified table (optional). If this parameter is omitted the whole page is scanned.
nBytesParsed | Variable receiving the number of the bytes that actually parsed (optional).

Example

/* Table #3 on the page:
Number  Name                         Price
  1000  3 Person Dome Tent        $ 299.99
  1001  External Frame Backpack   $ 179.95
  1002  Glacier Sun Glasses        $ 67.99
  1003  Padded Socks               $ 19.99
  1004  Hiking Boots              $ 109.90
  1005  Back Country Shorts        $ 24.95
*/
  transaction TMain
  var
    sResult : string;
  begin

    WebParseTableVLookup(sResult, STRING_COMPLETE, 3, 1, "1003", WEB_FLAG_EQUAL, 2);
    WebPageUrl("http://demo.borland.com/gmopost/online-catalog.htm", "OnLine Catalog");
    Print("sResult: " + sResult); // "Padded Socks"

    WebParseTableVLookup(sResult, STRING_COMPLETE, 3, 1, "1003", WEB_FLAG_EQUAL | WEB_FLAG_DONT_FORCE_LOAD, 2);
    WebPageUrl("http://demo.borland.com/gmopost/online-catalog.htm", "OnLine Catalog");
    Print("sResult: " + sResult); // sResult can be ""

  end TMain;
Parent topic: Parsing Functions


WebParseResponseData Function

Action

Parses the response data (commonly HTML) for sLeftBoundary and sRightBoundary and stores the string between these boundaries in sResult. This modifier can be used in many situations. One of the most common is retrieving state information out of hidden form field values. When the right delimiter (sRightBoundary) is not specified (set to NULL), the string after sLeftBoundary with length nMaxResultLen is returned. When the left delimiter (sLeftBoundary) is not specified (set to NULL), the string from beginning or after the last position of a previous search with maximum length nMaxResultLen is returned. When both boundary search strings are omitted (sLeftBoundary and sRightBoundary are set to NULL), all data with maximum length is stored into sResult.

It is important to know that all parsing and verification functions must be specified before the Web API call for which the response data should be parsed/verified. You can specify multiple parse/verification functions before a Web API call. The order of the parse/verification functions is not relevant (Exception: WebParseDataBound and WebVerifyDataBound using the flag WEB_FLAG_SYNCHRON).

Note: The order of multiple calls to WebParseResponseData affects finding the parameters. The subsequent low-level web function will NOT return until the request has finished. Other requests started before may run in parallel. This parsing is optimized for speed. For more complex parsing you can use this function to retrieve the whole document and parse it yourself using the string functions.
Note: If you want to parse a Web document, you must first call the WebParseResponseData function. Then you call the function which retrieves the document.
Note: This function is obsolete. It can still be used, although it's recommended to use the WebParseDataBound function instead.

Include file

WebAPI.bdh

Syntax

WebParseResponseData( out sResult        : string,
                      in  nMaxResultLen  : number,
                      in  sLeftBoundary  : string optional,
                      in  sRightBoundary : string optional,
                      out nBytesParsed   : number optional ): boolean;

Return value

  • true if the parsing modifier could be created successfully

  • false otherwise

Parameter | Description
sResult | String variable that receives the string between the specified boundary strings.
nMaxResultLen | Maximum length of the string to return. This value must be less than or equal to the size of the string variable sResult.
sLeftBoundary | Left boundary string of the value to search for (optional). Passing a NULL value will store all the document data (like HTML) into sResult.
sRightBoundary | Right boundary string of the value to search for (optional). Passing a NULL value will store all the document data (like HTML) after the occurrence of sLeftBoundary into sResult.
nBytesParsed | Variable receiving the number of bytes actually parsed (optional).

Example

dcltrans
  transaction TWeb
  var
    sTitle           : string(100);
    sHiddenSessionID : string(100);
begin
    // Check for an error message set in the HTML title.
    // (Note: the HTTP response error should be set to a
    // value > 200!! See HTTP specifications)
    WebParseResponseData(sTitle, sizeof(sTitle),
                         "<title>", "</title>");

    // our session info has a fixed size of 11 characters
    WebParseResponseData(sHiddenSessionID, 11, "name=\"SessionID\""
                         "value=\"");
    WebUrl("http://standardhost/", 0.0);
    write(sTitle); writeln;
    write(sHiddenSessionID); writeln;
  end TWeb;

Sample scripts

WebFileUpload01.bdf, WebMultiIpAddresses01.bdf, WebRegularExpressions01.bdf, WebSecure02.bdf

Parent topic: Parsing Functions
Related reference
WebParseDataBound Function


WebParseResponseHeader Function

Action

Parses the HTTP headers of a server response and stores the header value in sResult. When the search parameter is not specified (set to NULL), all HTTP headers are retrieved at once. The nResponseNo parameter specifies which response header is subject of interest. If this parameter is omitted, all response headers are checked (If a header is not found in the first response, Silk Performer looks for it in the next response). If the nResponseNo, the sHeaderName, and the nResponseNo parameters are omitted, the first call retrieves the first complete response header. All subsequent calls (with the last 3 parameters omitted) retrieve the subsequent response-headers. The subsequent low-level web function will not return until the request has finished. Other requests started before may run in parallel.

It is important to know that all parsing and verification functions must be specified before the Web API call for which the response data should be parsed/verified. You can specify multiple parse/verification functions before a Web API call. The order of the parse/verification functions is not relevant (Exception: WebParseDataBound and WebVerifyDataBound using the flag WEB_FLAG_SYNCHRON).

Note: If you want to parse a Web server response, you must first call the WebParseResponseHeader function. Then you send the request to the Web server.

Include file

WebAPI.bdh

Syntax

WebParseResponseHeader( out sResult       : string,
                        in  nMaxResultLen : number optional,
                        in  sHeaderName   : string optional,
                        in  nHeaderNo     : number optional,
                        in  nResponseNo   : number optional): boolean;

Return value

  • true if the parsing modifier could be created successfully

  • false otherwise

Parameter | Description
sResult | String variable that receives the value of the HTTP header or all HTTP headers (CRLF separated)
nMaxResultLen | Maximum length of the string to return (optional). If this parameter is omitted or set to STRING_COMPLETE all available data is stored in sResult.
sHeaderName | Name of the header for which to retrieve the associated value (optional). Passing a NULL value will store all HTTP headers CRLF separated into sResult.
nHeaderNo | Index of the header value to be retrieved (optional). If this parameter is omitted, all values are concatenated (with commas as separators between the values).
nResponseNo | Index of the response header value that is to be retrieved or searched (optional). If this parameter is omitted, all response headers are searched; if the sHeaderName parameter is omitted as well, the order of the function calls specifies which response header to get. If this parameter is set to WEB_RESPONSE_LAST, the last response header is searched.

Example

dcltrans
  transaction TWeb
  var
    sHeader1 : string;
    sHeader2 : string;
    sServer1 : string;
    sServer2 : string;
  begin
    WebParseResponseHeader(sHeader1);
    WebParseResponseHeader(sHeader2, STRING_COMPLETE);
    WebParseResponseHeader(sServer1, STRING_COMPLETE, "server", 1, 2);
    WebUrl("http://standardhost/", 0.0);

    write(sHeader1); writeln;
    write(sHeader2); writeln;
    write(sServer1); writeln;
    write(sServer2); writeln;
  end TWeb;

Sample scripts

WebParseResponse01.bdf, WebParseResponseHeader01.bdf

Parent topic: Parsing Functions


WebParseResponseRedirect Function

Action

Parses the URL of a redirection response for URL encoded parameters. This modifier is commonly used to get state information generated at server side at run time, like session IDs. When the search parameter is not specified (set to NULL), the complete redirect URL is retrieved.

It is important to know that all parsing and verification functions must be specified before the Web API call for which the response data should be parsed/verified. You can specify multiple parse/verification functions before a Web API call. The order of the parse/verification functions is not relevant (Exception: WebParseDataBound and WebVerifyDataBound using the flag WEB_FLAG_SYNCHRON).

Note: The order of multiple calls to WebParseResponseRedirect function affects finding the parameters. The subsequent low-level web function will NOT return until the request has finished. Other requests started before may run in parallel. If only NULL parameter values are specified, no parsing is performed. Instead, the server’s redirection status message will not generate an error message.
Note: If you want to parse a Web server response, you must first call the WebParseResponseHeader function. Then you send the request to the Web server.

Include file

WebAPI.bdh

Syntax

WebParseResponseRedirect( out sResult       : string optional,
                          in  nMaxResultLen : number optional,
                          in  sSearchParam  : string optional ): boolean;

Return value

  • true if the parsing modifier could be created successfully

  • false otherwise

Parameter | Description
sResult | String variable that receives the value of the named parameter or the redirect URL (optional). May be NULL if no return value is needed.
nMaxResultLen | Maximum length of the string to return (optional). This value must be less than or equal to the size of the string variable sResult.
sSearchParam | Name of the parameter for which to retrieve the associated value (optional). Passing a NULL value causes the complete URL to be stored in sResult.

Example

dcltrans
  transaction TWeb
  var
    sParam1 : string(1000);
    sSession : string(200);
  begin
    WebParseResponseRedirect(sParam1, STRING_COMPLETE, "Param1");
    WebParseResponseRedirect(sSession, STRING_COMPLETE,"SessionID");
    WebUrl("http://localhost/SessionIdTest.asp", 0.0);
    write(sParam1); writeln;
    write(sSession); writeln;
  end TWeb;

Sample scripts

WebRegularExpressions01.bdf

Parent topic: Parsing Functions


WebParseResponseStatus Function

Action

Parses the response header status line if a variable is specified as an out parameter. The subsequent low-level web function will NOT return until the request has finished. Other requests started before may run in parallel. This function might be used, for example, to avoid errors during an authentication handshake.

It is important to know that all parsing and verification functions must be specified before the Web API call for which the response data should be parsed/verified. You can specify multiple parse/verification functions before a Web API call. The order of the parse/verification functions is not relevant (Exception: WebParseDataBound and WebVerifyDataBound using the flag WEB_FLAG_SYNCHRON).

Note: This function avoids an error only once. After the specified error occurred, another WebParseResponseStatus function call is necessary.
Note: If you want to parse a Web document, you must first call the WebParseResponseStatus function. Then you call the function which retrieves the document.
Note: This function is obsolete. It can still be used, although it's recommended to use the WebIgnoreServerError function instead.

Include file

WebAPI.bdh

Syntax

WebParseResponseStatus(
in nIgnoreStatus : number,
out nStatusCode : number optional,
out sStatusMsg : string optional,
in nMaxStatusMsg : number optional): boolean;

Return value

  • true if the parsing modifier could be created successfully

  • false otherwise

Parameter | Description
nIgnoreStatus | Forces the subsequent request not to report an error for HTTP status code = nIgnoreStatus. Set this value to 0 to disable HTTP status code error reporting for all error codes.
nStatusCode | Parameter that receives the value of the HTTP header status code (optional). Omit this parameter if the status code is not needed for further processing.
sStatusMsg | String variable that receives the status message of the HTTP response header (optional).
nMaxStatusMsg | Maximum length of the string to write into sStatusMsg (optional). This value must be less than or equal to the size of the string variable sStatusMsg.

Example

dcltrans
  transaction TMyTransaction
  begin
    // ignore HTTP error code: 401 Authorization Required
    WebParseResponseStatus(401);
    WebUrl("http://www.mydomain.com/", 0.0);
    // now send the request, including user name and password
    WebUrl("http://username:userpass@www.mydomain.com/", 0.0);
  end TMyTransaction;

Sample scripts

WebAuth01.bdf, WebStatusCodes01.bdf

Parent topic: Parsing Functions
Related reference
WebIgnoreServerError Function


WebParseResponseTag Function

Action

Parses the HTML response and stores the value of a specified attribute in a string variable. The attribute in question can be specified by a tag, an attribute-value pair (which must be part of the tag), the name of the frame, and the nth appearance of these conditions.

Finding the data is not affected by the order of multiple calls to WebParseResponseTag or by calls to other parsing functions (like WebParseResponseTagContent, WebParseResponseData, and so on). The subsequent low-level web function will not return until the request has finished. Other requests started before may run in parallel.

When verifying/parsing an HTML page that consists of multiple frames, you can specify which frame document to verify/parse by specifying the sFrame parameter. By default, all HTML documents of the HTML page are scanned. This applies to HTML pages that are retrieved through a page-level command like WebPageUrl or WebPageLink.

It is important to know that all parsing and verification functions must be specified before the Web API call for which the response data should be parsed/verified. You can specify multiple parse/verification functions before a Web API call. The order of the parse/verification functions is not relevant (Exception: WebParseDataBound and WebVerifyDataBound using the flag WEB_FLAG_SYNCHRON).

Note: If you want to parse a Web server response, you must first call the WebParseResponseHeader function. Then you send the request to the Web server.

Include file

WebAPI.bdh

Syntax

WebParseResponseTag( out sResult        : string,
                     in  nMaxResultLen  : number,
                     in  sTag           : string,
                     in  sAttribute     : string,
                     in  sCondAttribute : string optional,
                     in  sCondValue     : string optional,
                     in  nAppearance    : number optional,
                     in  sFrame         : string optional,
                     out nResultLen     : number optional ): boolean;

Return value

  • true if the parsing modifier could be created successfully

  • false otherwise

Parameter | Description
sResult | String variable that receives the value of the specified attribute.
nMaxResultLen | Maximum length of the string to return. This value must be less than or equal to the size of the string variable sResult.
sTag | Tag in which the attribute has to be found.
sAttribute | Attribute to search for.
sCondAttribute | Attribute of the conditional attribute-value pair that must be present in the tag (optional). If this parameter is omitted, no conditional attribute-value pair is checked.
sCondValue | Value of the conditional attribute-value pair that must be present in the result tag (optional).
nAppearance | This parameter specifies which instance of the appearance when all conditions are met is the one for which the result is set (optional). If this parameter is omitted the first appearance is taken.
sFrame | Frame name where to search (optional). If this parameter is omitted, the whole page is searched. An empty string specifies the top frame.
bBaseDocOnly | If this parameter is set to true, only the base document is searched. If sFrame specifies a frame set, the sub frames are not scanned (optional). If this parameter is omitted, all sub frames are searched also.
nResultLen | Variable that receives the number of bytes actually copied to sResult (optional).

Example

dcltrans
  transaction TMain
  var
    sResult, sLink, sFrame1, sFrame2: string;
  begin
    WebParseResponseTag(sResult, STRING_COMPLETE, "table", "height");
    WebPageUrl("http://mycompany.com/");
    Print(sResult);
    WebParseResponseTag(sLink, STRING_COMPLETE, "A", "href");
    WebParseResponseTag(sResult,
STRING_COMPLETE, "font", "face", "size", "5", 2);
    WebUrl("http://mycompany.com/Shop/default.htm");
    Print(sLink);
    Print(sResult);

    // "", true ... search only in the base frame set
    WebParseResponseTag(sFrame1,
STRING_COMPLETE, "Frame", "Src", 0,
0, 1, "", true);
    WebParseResponseTag(sFrame2,
STRING_COMPLETE, "Frame", "Src", 0, 0, 2, "", true);
    WebPageUrl("http://mycompany.com/frame/frame.html");
    Print(sFrame1);
    Print(sFrame2);
  end TMain;
Parent topic: Parsing Functions


WebParseResponseTagContent Function

Action

Parses the HTML response and stores the HTML content or the raw HTML code in a string variable. The data in question can be specified by a tag, an attribute-value pair (which must be part of the tag), the name of the frame, and the nth appearance of these conditions.

Finding the data is not affected by the order of multiple calls to WebParseResponseTagContent or by calls to other parsing functions (like WebParseResponseTag, WebParseResponseData, and so on). The subsequent low-level web function will not return until the request has finished. Other requests started before may run in parallel.

When verifying/parsing an HTML page that consists of multiple frames, you can specify which frame document to verify/parse by specifying the sFrame parameter. By default, all HTML documents of the HTML page are scanned. This applies to HTML pages that are retrieved through a page-level command like WebPageUrl or WebPageLink.

It is important to know that all parsing and verification functions must be specified before the Web API call for which the response data should be parsed/verified. You can specify multiple parse/verification functions before a Web API call. The order of the parse/verification functions is not relevant (Exception: WebParseDataBound and WebVerifyDataBound using the flag WEB_FLAG_SYNCHRON).

Note: If you want to parse a Web server response, you must first call the WebParseResponseHeader function. Then you send the request to the Web server.

Include file

WebAPI.bdh

Syntax

WebParseResponseTagContent( out sResult       : string,
                            in  nMaxResultLen  : number,
                            in  sTag           : string,
                            in  sCondAttribute : string optional,
                            in  sCondValue     : string optional,
                            in  nAppearance    : number optional,
                            in  sFrame         : string optional,
                            in  bBaseDocOnly   : boolean optional,
                            in  bGetCode       : boolean optional,
                            out nResultLen     : number optional ): boolean;

Return value

  • true if the parsing modifier could be created successfully

  • false otherwise

Parameter | Description
sResult | String variable that receives the value of the specified attribute.
nMaxResultLen | Maximum length of the string to return. This value must be less than or equal to the size of the string variable sResult.
sTag | Tag whose content (or code) has to be returned.
sCondAttribute | Attribute of the conditional attribute-value pair that must be present in the tag (optional). If this parameter is omitted, no conditional attribute-value pair is checked.
sCondValue | Value of the conditional attribute-value pair that must be present in the result tag (optional).
nAppearance | This parameter specifies which instance of the appearance when all conditions are met is the one for which the result is set (optional). If this parameter is omitted the first appearance is taken.
sFrame | Frame name where to search (optional). If this parameter is omitted, the whole page is searched. An empty string specifies the top frame.
bBaseDocOnly | If this parameter is set to TRUE, only the base document is searched. If sFrame specifies a frame set, the sub frames are not scanned (optional). If this parameter is omitted, all sub frames are searched also.
bGetCode | If this parameter is TRUE the raw data between begin and end tags is returned. If this parameter is omitted only the content (what you see at the browser) of the specified tag is returned.
nResultLen | Variable that receives the number of bytes actually copied to sResult (optional).

Example

dcltrans
  transaction TMain
  var
    sBody             : string(5000);
    sRawHead, sResult : string;
  begin
    WebParseResponseTagContent(sBody, STRING_COMPLETE, "body");
    WebPageUrl("http://mycompany.com/");
    WebParseResponseTagContent(sRawHead, STRING_COMPLETE, "head",
0, 0, 1, "", false, true);
    WebParseResponseTagContent(sResult,
STRING_COMPLETE, "font", "size", "5");
    WebUrl("http://mycompany.com/Shop/default.htm");
    Print(sBody);
    Print(sRawHead);
    Print(sResult);
  end TMain;
Parent topic: Parsing Functions


Response Verification Functions

  • WebVerifyHtml Function
    Parses the HTML response data and counts the appearance of the specified content with the provided string.
  • WebVerifyHtmlBound Function
    Parses the HTML response data and verifies the specified string within the boundaries.
  • WebVerifyHtmlBoundEx Function
    Parses the HTML response data and verifies the specified string within the boundaries.
  • WebVerifyHtmlDigest Function
  • WebVerifyHtmlTitle Function
    Parses the <TITLE> tag of the HTML response and compares its content with the provided string.
  • WebVerifyTable Function
    Parses HTML tables and compares its cell content with the provided string.
  • WebVerifyTableVLookup Function
    Parses HTML tables and compares its cell content with the provided string. If it does not match, an error is raised. In contrast to the function WebVerifyTable, the row number is determined dynamically through the content of a search column.
  • WebVerifyData Function
    Parses the server response data and counts the appearance of the specified content with the provided string.
  • WebVerifyDataBound Function
    Parses the server response data and verifies the specified string within the boundaries.
  • WebVerifyDataBoundEx function
    Parses the server response data and verifies the specified string within the boundaries.
  • WebVerifyDataDigest Function
    Checks whether the Internet traffic that Silk Performer receives differs from the traffic that the Recorder captured during an earlier recording session.
  • WebVerifyResponseData Function
    Checks whether the Internet traffic Silk Performer receives differs from the traffic the Recorder captured during a former recording session.
  • WebVerifyTitle Function
    Parses the <TITLE> tag of the HTML response and compares its content with the provided string.
  • WebVerifyContent Function
    Parses the HTML response and counts the appearance of the specified content with the provided string.
Parent topic: Web Functions Reference


WebVerifyHtml Function

Action

Parses the HTML response data and counts the appearance of the specified content with the provided string. If the verification condition is not met, an error is raised. The severity of this error can be specified. The appearance count of the specified content can be retrieved by an optional out-parameter. A subsequent low-level web function will not return a value until the request has finished. A cache hit is not performed unless the WEB_FLAG_DONT_FORCE_LOAD option is set. The verification is done even if this option is set and the verified request or a certain part of a page is a cache hit.

When verifying/parsing an HTML page that consists of multiple frames, you can specify which frame document to verify/parse by specifying the sFrame parameter. By default, all HTML documents of the HTML page are scanned. This applies to HTML pages that are retrieved through a page-level command like WebPageUrl or WebPageLink.

It is important to know that all parsing and verification functions must be specified before the Web API call for which the response data should be parsed/verified. You can specify multiple parse/verification functions before a Web API call. The order of the parse/verification functions is not relevant (Exception: WebParseDataBound and WebVerifyDataBound using the flag WEB_FLAG_SYNCHRON).

This verification feature can be enabled/disabled globally (Profile Settings / Web / Verification / HTML / HTML verification).

Note: This function can be added automatically to your script using the visual verification functionality of TrueLog Explorer.

Include file

WebAPI.bdh

Syntax

WebVerifyHtml( in  sVerify     : string,
               in  nAppearance : number optional,
               in  nOptions    : number optional,
               in  sFrame      : string optional,
               in  nSeverity   : number optional := SEVERITY_ERROR,
               out nResult     : number optional );
Parameter | Description
sVerify | String to compare with the parsed HTML content.
nAppearance | Optional: Value to which the actual appearance of the specified content string is compared (see nOptions). If this parameter is omitted, the specified string must appear at least once to meet the verification rules.
nOptions Optional:
WEB_FLAG_EQUAL
The verification succeeds if the actual appearance is equal to nAppearance.
WEB_FLAG_GREATER (default)
The verification succeeds if the actual appearance is greater than nAppearance.
WEB_FLAG_SMALLER
The verification succeeds if the actual appearance is smaller than nAppearance.
WEB_FLAG_CASE_SENSITIVE
If this flag is set the string compare operation is case sensitive.
WEB_FLAG_IGNORE_WHITE_SPACE
If this flag is set all white spaces are ignored.
WEB_FLAG_DONT_FORCE_LOAD
Specify this option to enable caching for a subsequent request. Note that this may lead to unpredictable behaviour, because the verification may only cover certain parts (which are loaded) of a page.
WEB_FLAG_RULE
Specify this flag to perform the verification on every subsequent web function. Verification functions with this flag are usually located in the TInit transaction. Call WebCancelAllRules() to disable all verification rules.
Note: The option WEB_FLAG_RULE should only be used in the INIT transaction or in combination with the WebCancelAllRules function!
sFrame | Frame that gets searched for the content (optional). If this parameter is omitted the whole page is scanned.
nSeverity Optional: Severity of the error that is raised if the verification fails. Can be one of the following values:
  • SEVERITY_SUCCESS: Success; no error (numerical value: 0)
  • SEVERITY_INFORMATIONAL: Informational; no error (numerical value: 1)
  • SEVERITY_WARNING: Warning; no error (numerical value: 2)
  • SEVERITY_ERROR: (Default) Error; simulation continues (numerical value: 3)
  • SEVERITY_TRANS_EXIT: Error; the active transaction is aborted (numerical value: 4)
  • SEVERITY_PROCESS_EXIT: Error; the simulation is aborted (numerical value: 5)
nResult | Optional: If a variable is provided, it will receive the number of appearances of the specified content string.

Example

dcltrans
  transaction TMain
  var    nResult: number;
  begin
    WebVerifyHtml("Begin");
    WebPageUrl("http://mycompany.com/");
    WebVerifyHtml("Begin", 0, 0, NULL, SEVERITY_WARNING);
    WebVerifyHtml("Shop", 2, WEB_FLAG_EQUAL | WEB_FLAG_GREATER);
    WebUrl("http://mycompany.com/Shop/default.htm");
    WebVerifyHtml("Html", 3, WEB_FLAG_CASE_SENSITIVE |
WEB_FLAG_SMALLER, "Right", SEVERITY_ERROR, nResult);
    WebPageUrl("http://mycompany.com/frame/framea.html");
    Print(string(nResult));
  end TMain;
Parent topic: Response Verification Functions


WebVerifyHtmlBound Function

Action

Parses the HTML response data and verifies the specified string within the boundaries. If the verification condition is not met, an error is raised. The severity of this error can be specified. The result of the verification can be retrieved by an optional out-parameter. A subsequent low-level web function will not return a value until the request has finished. A cache hit is not performed unless the WEB_FLAG_DONT_FORCE_LOAD option is set. The verification is done even if this option is set and the verified request or a certain part of a page is a cache hit.

When verifying/parsing an HTML page that consists of multiple frames, you can specify which frame document to verify/parse by specifying the sFrame parameter. By default, all HTML documents of the HTML page are scanned. This applies to HTML pages that are retrieved through a page-level command like WebPageUrl or WebPageLink.

It is important to know that all parsing and verification functions must be specified before the Web API call for which the response data should be parsed/verified. You can specify multiple parse/verification functions before a Web API call. The order of the parse/verification functions is not relevant (Exception: WebParseDataBound and WebVerifyDataBound using the flag WEB_FLAG_SYNCHRON).

This verification feature can be enabled/disabled globally (Profile Settings / Web / Verification / HTML / HTML verification).

Note: This function can be added automatically to your script using the visual verification functionality of TrueLog Explorer.

Include file

WebAPI.bdh

Syntax

WebVerifyHtmlBound( in  sLeftBoundary  : string,
                    in  sRightBoundary : string,
                    in  sVerify        : string,
                    in  nOptions       : number optional,
                    in  sFrame         : string optional,
                    in  nSeverity      : number optional := SEVERITY_ERROR,
                    out bSuccess       : boolean optional );
Parameter | Description
sLeftBoundary | Left boundary of the HTML content to compare.
sRightBoundary | Right boundary of the HTML content to compare.
sVerify | String to compare with the parsed HTML content.
nOptions

(optional)

WEB_FLAG_CASE_SENSITIVE
If this flag is set the string compare operation is case sensitive.
WEB_FLAG_IGNORE_WHITE_SPACE
If this flag is set all white spaces are ignored.
WEB_FLAG_DONT_FORCE_LOAD
Specify this option to enable caching for subsequent request. Note that this may lead to unpredictable behaviour, because the verification may only cover certain parts (which are loaded) of a page.
WEB_FLAG_RULE
Specify this flag to perform the verification on every subsequent web function. Verification functions with this flag are usually located in the TInit transaction. Call WebCancelAllRules() to disable all verification rules.
Note: The option WEB_FLAG_RULE should only be used in the INIT transaction or in combination with the WebCancelAllRules function!
sFrame | Frame that gets searched for the content (optional). If this parameter is omitted the whole page is scanned.
nSeverity Optional: Severity of the error that is raised if the verification fails. Can be one of the following values:
  • SEVERITY_SUCCESS: Success; no error (numerical value: 0)
  • SEVERITY_INFORMATIONAL: Informational; no error (numerical value: 1)
  • SEVERITY_WARNING: Warning; no error (numerical value: 2)
  • SEVERITY_ERROR: (Default) Error; simulation continues (numerical value: 3)
  • SEVERITY_TRANS_EXIT: Error; the active transaction is aborted (numerical value: 4)
  • SEVERITY_PROCESS_EXIT: Error; the simulation is aborted (numerical value: 5)
bSuccess | If a variable is provided, it will receive the result of the verification (optional).

Example

dcltrans
  transaction TMain
  var
    bResult: boolean;
  begin
    WebVerifyHtmlBound("Begin", "X.X", "End ");
    WebPageUrl("http://mycompany.com/");
    WebVerifyHtmlBound("Begin", "X.X", "End ", 0, NULL,
SEVERITY_WARNING);
    WebVerifyHtmlBound("Shop", "City", "ing", WEB_FLAG_CASE_SENSITIVE);
    WebUrl("http://mycompany.com/Shop/default.htm");
    WebVerifyHtmlBound("Name:", "Age", "Smith",
WEB_FLAG_IGNORE_WHITE_SPACE, "Name", SEVERITY_ERROR, bResult);
    WebPageUrl("http://mycompany.com/frame/framea.html");
    if not bResult then
      Print("Verification failed");
    end;
  end TMain;
Parent topic: Response Verification Functions


WebVerifyHtmlBoundEx Function

Action

Parses the HTML response data and verifies the specified string within the boundaries. If the verification condition is not met, an error is raised. The severity of this error can be specified. The result of the verification can be retrieved by an optional out-parameter. A subsequent low-level web function will not return a value until the request has finished. A cache hit is not performed unless the WEB_FLAG_DONT_FORCE_LOAD option is set. The verification is done even if this option is set and the verified request or a certain part of a page is a cache hit.

When verifying/parsing an HTML page that consists of multiple frames, you can specify which frame document to verify/parse by specifying the sFrame parameter. By default, all HTML documents of the HTML page are scanned. This applies to HTML pages that are retrieved through a page-level command like WebPageUrl or WebPageLink.

It is important to know that all parsing and verification functions must be specified before the Web API call for which the response data should be parsed/verified. You can specify multiple parse/verification functions before a Web API call. The order of the parse/verification functions is not relevant (Exception: WebParseDataBound and WebVerifyDataBound using the flag WEB_FLAG_SYNCHRON).

This verification feature can be enabled/disabled globally (Profile Settings > Web > Verification > HTML > HTML verification).

Note: This function can be added automatically to your script using the visual verification functionality of TrueLog Explorer.

Include file

WebAPI.bdh

Syntax

WebVerifyHtmlBoundEx( in  sLeftBoundary   : string,
                      in  nLeftOccurrence : number,
                      in  sRightBoundary  : string,
                      in  sVerify         : string,
                      in  nOptions        : number optional,
                      in  sFrame          : string optional,
                      in  nSeverity       : number optional := SEVERITY_ERROR,
                      out bSuccess        : boolean optional );

Return value

  • none

Parameter | Description
sLeftBoundary | Left boundary of the HTML content to compare.
nLeftOccurrence | The sLeftBoundary has to be found nLeftOccurrence times, before the verification process starts and the right boundary is searched (optional). The default value is one. Provide WEB_OCCURENCE_LAST to specify the last occurrence.
sRightBoundary | Right boundary of the HTML content to compare.
sVerify | String to compare with the parsed HTML content.
nOptions

(optional)

WEB_FLAG_CASE_SENSITIVE
If this flag is set the string compare operation is case sensitive.
WEB_FLAG_IGNORE_WHITE_SPACE
If this flag is set all white spaces are ignored.
WEB_FLAG_DONT_FORCE_LOAD
Specify this option to enable caching for subsequent request. Note that this may lead to unpredictable behaviour, because the verification may only cover certain parts (which are loaded) of a page.
WEB_FLAG_RULE
Specify this flag to perform the verification on every subsequent web function. Verification functions with this flag are usually located in the TInit transaction. Call WebCancelAllRules() to disable all verification rules.
Important: The option WEB_FLAG_RULE should only be used in the INIT transaction or in combination with the WebCancelAllRules function.
sFrame | Frame that gets searched for the content (optional). If this parameter is omitted the whole page is scanned.
nSeverity Optional: Severity of the error that is raised if the verification fails. Can be one of the following values:
  • SEVERITY_SUCCESS: Success; no error (numerical value: 0)
  • SEVERITY_INFORMATIONAL: Informational; no error (numerical value: 1)
  • SEVERITY_WARNING: Warning; no error (numerical value: 2)
  • SEVERITY_ERROR: (Default) Error; simulation continues (numerical value: 3)
  • SEVERITY_TRANS_EXIT: Error; the active transaction is aborted (numerical value: 4)
  • SEVERITY_PROCESS_EXIT: Error; the simulation is aborted (numerical value: 5)
bSuccess | If a variable is provided, it will receive the result of the verification (optional).

Example

dcltrans
  transaction TMain
  var
    bResult: boolean;
  begin
    WebVerifyHtmlBoundEx("Begin", 2, "X.X", "End ");
    WebPageUrl("http://mycompany.com/");
    WebVerifyHtmlBoundEx("Begin", 2, "X.X", "End ", 0, NULL,
SEVERITY_WARNING);
    WebVerifyHtmlBound("Shop", "City", "ing", WEB_FLAG_CASE_SENSITIVE);
    WebUrl("http://mycompany.com/Shop/default.htm");
    WebVerifyHtmlBound("Name:", "Age", "Smith",
WEB_FLAG_IGNORE_WHITE_SPACE, "Name", SEVERITY_ERROR, bResult);
    WebPageUrl("http://mycompany.com/frame/framea.html");
    if not bResult then      Print("Verification failed");    end;  end TMain;
Parent topic: Response Verification Functions


WebVerifyHtmlDigest Function

Action

Checks whether the HTML content that Silk Performer receives differs from a prior test. As TrueLog Explorer does, Silk Performer generates a digest, containing information about the occurrence of each character of the HTML content, and compares the results with the digest generated by TrueLog Explorer. When verifying HTML page that consists of multiple frames (HTML documents), you can specify which frame document to verify by specifying the sFrame parameter. By default the whole page is scanned. For a detailed explanation of the digest calculations see WebVerifyDataDigest.

Include file

WebAPI.bdh

Syntax

WebVerifyHtmlDigest( in  sDigest     : string,
                     in  nDigestLen  : number,
                     in  nDifference : number optional,
                     in  nOptions    : number optional,
                     in  sFrame      : string optional,
                     in  nSeverity   : number optional := SEVERITY_ERROR,
                     out nActDiff    : number optional ) : boolean;

Return value

  • true if the parsing modifier was created successfully.

  • false otherwise.

Parameter | Description
sDigest | Digest generated by TrueLog Explorer.
nDigestLen | Size of the digest generated by TrueLog Explorer. Specify STRING_COMPLETE for the complete digest.
nDifference | Upper tolerance level for the response verification (optional). For each digest entry, this function calculates the difference between the TrueLog Explorer and the Silk Performer digests. Finally, this function calculates the sum total of the differences of the TrueLog Explorer and the Silk Performer digests. If this sum total is greater than the tolerance level you specified, Silk Performer reports it as an error. If you want to ensure that both the TrueLog Explorer and the Silk Performer digests are compatible, you must specify a negative value (e.g.: -1). If you do not specify a value, or if you set it to zero, the default setting will be used instead.
nOptions

(optional)

WEB_FLAG_DONT_FORCE_LOAD
Specify this option to enable caching for the subsequent request. Note that this may lead to unpredictable behaviour, because the verification may only cover certain parts (which are loaded) of a page.
sFrame | Frame that gets scanned (optional). If this parameter is omitted the whole page is scanned.
nSeverity Optional: Severity of the error that is raised if the verification fails. Can be one of the following values:
  • SEVERITY_SUCCESS: Success; no error (numerical value: 0)
  • SEVERITY_INFORMATIONAL: Informational; no error (numerical value: 1)
  • SEVERITY_WARNING: Warning; no error (numerical value: 2)
  • SEVERITY_ERROR: (Default) Error; simulation continues (numerical value: 3)
  • SEVERITY_TRANS_EXIT: Error; the active transaction is aborted (numerical value: 4)
  • SEVERITY_PROCESS_EXIT: Error; the simulation is aborted (numerical value: 5)
nActDiff | The calculated difference between the digests generated by TrueLog Explorer and by Silk Performer at the actual run (optional).

Example

Const
  // generated by TrueLog Explorer
  HTML_DIGEST_1 :=
  "\h014100000000012000008AA2D9017AFBFD03000000000000000000000000000000004A03"
  "\h0101020401010408030201010606051904070A0405040910080F0C140502010101"; dcluser  user
    WebUser  transactions
    TWeb : 1;  dcltrans
  transaction TWeb
  begin
    WebVerifyHtmlDigest( HTML_DIGEST_1, STRING_COMPLETE, 0, 0, NULL, SEVERITY_ERROR);
    WebPageUrl("http://mycompany.com/");
  end TWeb;
Parent topic: Response Verification Functions
Related reference
WebVerifyDataDigest Function


WebVerifyHtmlTitle Function

Action

Parses the <TITLE> tag of the HTML response and compares its content with the provided string. If it does not match, an error is raised. The severity of this error can be specified. The verification result can be retrieved by an optional out-parameter. A subsequent low-level web function will not return a value until the request has finished. If a page consists of more than one HTML document, the sub frames that are checked for the title can be specified with the nDocNum parameter.

When verifying/parsing an HTML page that consists of multiple frames (HTML documents), you can specify which frame document to verify/parse by specifying the nDocNum parameter. By default (1) the top document (e.g. a frameset) is scanned. This applies to HTML pages that are retrieved through a page-level command like WebPageUrl or WebPageLink.

It is important to know that all parsing and verification functions must be specified before the Web API call for which the response data should be parsed/verified. You can specify multiple parse/verification functions before a Web API call. The order of the parse/verification functions is not relevant (Exception: WebParseDataBound and WebVerifyDataBound using the flag WEB_FLAG_SYNCHRON).

This verification feature can be enabled/disabled globally (Profile Settings / Web / Verification / HTML / Title verification).

Note: This function can be added automatically to your script using the visual verification functionality of TrueLog Explorer.

Include file

WebAPI.bdh

Syntax

WebVerifyHtmlTitle( in  sVerify   : string,
                    in  nOptions  : number optional,
                    in  nDocNum   : number optional,
                    in  nSeverity : number optional := SEVERITY_ERROR,
                    out bSuccess  : boolean optional );
Parameter | Description
sVerify | String to compare with the parsed title.
nOptions

(optional)

WEB_FLAG_CONTAINS
The actual parsed HTML title must contain the specified string. Otherwise the verification fails.
WEB_FLAG_CONTAINS_NOT
The actual parsed HTML title must not contain the specified string. Otherwise the verification fails.
WEB_FLAG_IS_DIFFERENT
The actual parsed HTML title must not be equal to the specified string. Otherwise the verification fails.
WEB_FLAG_EQUAL
The actual parsed HTML title must be equal to the specified string. Otherwise the verification fails. If none of the above 3 flags are specified, the WEB_FLAG_EQUAL flag is used.
WEB_FLAG_CASE_SENSITIVE
If this flag is set the string compare operation is case sensitive.
WEB_FLAG_IGNORE_WHITE_SPACE
If this flag is set all white spaces are ignored.
WEB_FLAG_RULE
Specify this flag to perform the verification on every subsequent web function. Verification functions with this flag are usually located in the TInit transaction. Call WebCancelAllRules() to disable all verification rules.
Note: The option WEB_FLAG_RULE should only be used in the INIT transaction or in combination with the WebCancelAllRules function!
nDocNum | Specifies the document to check the title for (optional). The default (1) specifies the top document (e.g. a frameset).
nSeverity Optional: Severity of the error that is raised if the verification fails. Can be one of the following values:
  • SEVERITY_SUCCESS: Success; no error (numerical value: 0)
  • SEVERITY_INFORMATIONAL: Informational; no error (numerical value: 1)
  • SEVERITY_WARNING: Warning; no error (numerical value: 2)
  • SEVERITY_ERROR: (Default) Error; simulation continues (numerical value: 3)
  • SEVERITY_TRANS_EXIT: Error; the active transaction is aborted (numerical value: 4)
  • SEVERITY_PROCESS_EXIT: Error; the simulation is aborted (numerical value: 5)
bSuccess | If a variable is provided, it will receive the result of the verification (optional).

Example

dcltrans
  transaction TMain
  var
    bResult: boolean;
  begin
    WebVerifyHtmlTitle("Silk Performer Test Site");
    WebPageUrl("http://mycompany.com/");
    WebVerifyHtmlTitle("ShopIt - Greeting",
WEB_FLAG_CASE_SENSITIVE, 1, SEVERITY_WARNING, bResult);
    WebUrl("http://mycompany.com/Shop/default.htm");
    if not bResult then
      print("Verification failed");
    end
    WebVerifyHtmlTitle("FrameA", 0, 1); // base frameset
verification
    WebVerifyHtmlTitle("Buy It", 0, 3); // second frame
    WebPageUrl("http://mycompany.com/frame/framea.html");
  end TMain;
Parent topic: Response Verification Functions


WebVerifyTable Function

Action

Parses HTML tables and compares its cell content with the provided string. If it does not match, an error is raised. The severity of this error can be specified. The verification result can be retrieved by an optional out-parameter. A subsequent low-level function will not return a value until the request has finished.

When verifying/parsing an HTML page that consists of multiple frames, you can specify which frame document to verify/parse by specifying the sFrame parameter. By default, all HTML documents of the HTML page are scanned. This applies to HTML pages that are retrieved through a page-level command like WebPageUrl or WebPageLink.

It is important to know that all parsing and verification functions must be specified before the Web API call for which the response data should be parsed/verified. You can specify multiple parse/verification functions before a Web API call. The order of the parse/verification functions is not relevant (Exception: WebParseDataBound and WebVerifyDataBound using the flag WEB_FLAG_SYNCHRON).

This verification feature can be enabled/disabled globally (Profile Settings / Web / Verification / HTML / Table verification).

Note: This function can be added automatically to your script using the visual verification functionality of TrueLog Explorer.

Include file

WebAPI.bdh

Syntax

WebVerifyTable( in  nTableNum  : number,
                in  nRow       : number,
                in  nColumn    : number,
                in  sVerify    : string,
                in  nOptions   : number optional,
                in  sFrame     : string optional,
                in  nSeverity  : number optional := SEVERITY_ERROR,
                out bSuccess   : boolean optional );

Return value

  • none

Parameter | Description
nTableNum | The nTableNum th table is checked.
nRow | Specifies the row of the cell to verify.
nColumn | Specifies the column of the cell to verify.
sVerify | String to compare with the parsed cell.
nOptions

(optional)

WEB_FLAG_CONTAINS
The actual parsed table cell must contain the specified string. Otherwise the verification fails.
WEB_FLAG_CONTAINS_NOT
The actual parsed table cell must not contain the specified string. Otherwise the verification fails.
WEB_FLAG_IS_DIFFERENT
The actual parsed table cell must not be equal to the specified string. Otherwise the verification fails.
WEB_FLAG_EQUAL
The actual parsed table cell must be equal to the specified string. Otherwise the verification fails. If none of the above 3 flags are specified, the WEB_FLAG_EQUAL flag is used.
WEB_FLAG_CASE_SENSITIVE
If this flag is set the string compare operation is case sensitive.
WEB_FLAG_IGNORE_WHITE_SPACE
If this flag is set all white spaces are ignored.
WEB_FLAG_DONT_FORCE_LOAD
Specify this option to enable caching for subsequent request. Note that this may lead to unpredictable behaviour, because the verification may only cover certain parts (that are loaded) of a page.
sFrame | Frame that gets searched for the specified table (optional). If this parameter is omitted the whole page is scanned.
nSeverity Optional: Severity of the error that is raised if the verification fails. Can be one of the following values:
  • SEVERITY_SUCCESS: Success; no error (numerical value: 0)
  • SEVERITY_INFORMATIONAL: Informational; no error (numerical value: 1)
  • SEVERITY_WARNING: Warning; no error (numerical value: 2)
  • SEVERITY_ERROR: (Default) Error; simulation continues (numerical value: 3)
  • SEVERITY_TRANS_EXIT: Error; the active transaction is aborted (numerical value: 4)
  • SEVERITY_PROCESS_EXIT: Error; the simulation is aborted (numerical value: 5)
bSuccess | If a variable is provided, it will receive the result of the verification (optional).

Example

dcltrans
  transaction TMain
  var
    bResult: boolean;
  begin
    WebVerifyTable(1, 3, 4, "1200");
    WebPageUrl("http://mycompany.com/");
    WebVerifyTable(2, 1, 1, "error",
WEB_FLAG_CONTAINS_NOT, "FrameRight", SEVERITY_WARNING, bResult);
    WebUrl("http://mycompany.com/Shop/default.htm");
    if not bResult then
      print("Verification failed");
    end;
    WebVerifyTable(2, 2, 2, "sum");
    WebVerifyTable(3, 2, 3, "1455");
    WebPageUrl("http://mycompany.com/frame/framea.html");
  end TMain;
Parent topic: Response Verification Functions


WebVerifyTableVLookup Function

Action

Parses HTML tables and compares its cell content with the provided string. If it does not match, an error is raised. The severity of this error can be specified. In contrast to the function WebVerifyTable, the row number is determined dynamically through the content of a search column. The Verification result can be retrieved by an optional out-parameter. A subsequent low-level function will not return a value until the request has finished.

When verifying/parsing an HTML page that consists of multiple frames, you can specify which frame document to verify/parse by specifying the sFrame parameter. By default, all HTML documents of the HTML page are scanned. This applies to HTML pages that are retrieved through a page-level command like WebPageUrl or WebPageLink.

It is important to know that all parsing and verification functions must be specified before the Web API call for which the response data should be parsed/verified. You can specify multiple parse/verification functions before a Web API call. The order of the parse/verification functions is not relevant (Exception: WebParseDataBound and WebVerifyDataBound using the flag WEB_FLAG_SYNCHRON).

This verification feature can be enabled/disabled globally (Profile Settings / Web / Verification / HTML / Table verification).

Include file

WebAPI.bdh

Syntax

WebVerifyTableVLookup( in  nTableNum      : number,
                       in  nSearchColumn  : number,
                       in  sSearchText    : string,
                       in  nSearchOptions : number,
                       in  nResultColumn  : number,
                       in  sVerify        : string,
                       in  nResultOptions : number optional,
                       in  sFrame         : string optional,
                       in  nSeverity      : number optional := SEVERITY_ERROR,
                       out bSuccess       : boolean optional );

Return value

  • none

Parameter | Description
nTableNum | The nTableNum th table is checked.
nSearchColumn | Specifies, in which column to look for sSearchText.
sSearchText | The search text identifies the correct row. If multiple rows match the search text, the verification is performed for the first matching row.
nSearchOptions
WEB_FLAG_CONTAINS
The actual parsed table cell must contain the specified string. Otherwise the verification fails.
WEB_FLAG_CONTAINS_NOT
The actual parsed table cell must not contain the specified string. Otherwise the verification fails.
WEB_FLAG_IS_DIFFERENT
The actual parsed table cell must not be equal to the specified string. Otherwise the verification fails.
WEB_FLAG_EQUAL
The actual parsed table cell must be equal to the specified string. Otherwise the verification fails. If none of the above 3 flags are specified, the WEB_FLAG_EQUAL flag is used.
WEB_FLAG_CASE_SENSITIVE
If this flag is set the string compare operation is case sensitive.
WEB_FLAG_IGNORE_WHITE_SPACE
If this flag is set all white spaces are ignored.
WEB_FLAG_DONT_FORCE_LOAD
Specify this option to enable caching for subsequent request. Note that this may lead to unpredictable behaviour, because the verification may only cover certain parts (that are loaded) of a page.
nResult Column | Specifies the column of the cell to verify.
sVerify | String to compare with the parsed cell.
nResultOptions

(optional)

WEB_FLAG_CONTAINS
The actual parsed table cell must contain the specified string. Otherwise the verification fails.
WEB_FLAG_CONTAINS_NOT
The actual parsed table cell must not contain the specified string. Otherwise the verification fails.
WEB_FLAG_IS_DIFFERENT
The actual parsed table cell must not be equal to the specified string. Otherwise the verification fails.
WEB_FLAG_EQUAL
The actual parsed table cell must be equal to the specified string. Otherwise the verification fails. If none of the above 3 flags are specified, the WEB_FLAG_EQUAL flag is used.
WEB_FLAG_CASE_SENSITIVE
If this flag is set the string compare operation is case sensitive.
WEB_FLAG_IGNORE_WHITE_SPACE
If this flag is set all white spaces are ignored.
sFrame | Frame that gets searched for the specified table (optional). If this parameter is omitted the whole page is scanned.
nSeverity Optional: Severity of the error that is raised if the verification fails. Can be one of the following values:
  • SEVERITY_SUCCESS: Success; no error (numerical value: 0)
  • SEVERITY_INFORMATIONAL: Informational; no error (numerical value: 1)
  • SEVERITY_WARNING: Warning; no error (numerical value: 2)
  • SEVERITY_ERROR: (Default) Error; simulation continues (numerical value: 3)
  • SEVERITY_TRANS_EXIT: Error; the active transaction is aborted (numerical value: 4)
  • SEVERITY_PROCESS_EXIT: Error; the simulation is aborted (numerical value: 5)
bSuccess | If a variable is provided, it will receive the result of the verification (optional).

Example

/* Table #3 on the page:
Number  Name                         Price
  1000  3 Person Dome Tent        $ 299.99
  1001  External Frame Backpack   $ 179.95
  1002  Glacier Sun Glasses        $ 67.99
  1003  Padded Socks               $ 19.99
  1004  Hiking Boots              $ 109.90
  1005  Back Country Shorts        $ 24.95
*/

  transaction TMain
  var
    bResult : boolean;
  begin
    WebVerifyTableVLookup(3, 1, "1003", WEB_FLAG_EQUAL, 2, "Padded Socks");
    WebPageUrl("http://demo.borland.com/gmopost/online-catalog.htm", "OnLine Catalog");

    WebVerifyTableVLookup(3, 1, "003", WEB_FLAG_CONTAINS, 2, "Padded Socks", WEB_FLAG_EQUAL, NULL, SEVERITY_ERROR, bResult);
    WebPageUrl("http://demo.borland.com/gmopost/online-catalog.htm", "OnLine Catalog");
    if not bResult then
      print("Verification failed");
    end;

    WebVerifyTableVLookup(3, 1, "1003", WEB_FLAG_EQUAL, 2, "wrong text", WEB_FLAG_CONTAINS_NOT, NULL, SEVERITY_ERROR, bResult);
    WebPageUrl("http://demo.borland.com/gmopost/online-catalog.htm", "OnLine Catalog");
    if not bResult then
      print("Verification failed");
    end;
  end TMain;
Parent topic: Response Verification Functions


WebVerifyData Function

Action

Parses the server response data and counts the appearance of the specified content with the provided string. If the verification condition is not met, an error is raised. The severity of this error can be specified. The appearance count of the specified content can be retrieved by an optional out-parameter. A subsequent low-level web function will not return a value until the request has finished. A cache hit is not performed unless the WEB_FLAG_DONT_FORCE_LOAD option is set. The verification is done even if this option is set and the verified request or a certain part of a page is a cache hit.

When verifying/parsing an HTML page that consists of multiple frames (HTML documents), you can specify which frame document to verify/parse by specifying the nDocNum parameter. By default (1) the top document (e.g. a frameset) is scanned. This applies to HTML pages that are retrieved through a page-level command like WebPageUrl or WebPageLink.

It is important to know that all parsing and verification functions must be specified before the Web API call for which the response data should be parsed/verified. You can specify multiple parse/verification functions before a Web API call. The order of the parse/verification functions is not relevant (Exception: WebParseDataBound and WebVerifyDataBound using the flag WEB_FLAG_SYNCHRON).

This verification feature can be enabled/disabled globally (Profile Settings / Web / Verification / Data / Data verification).

Note: This function can be added automatically to your script using the visual verification functionality of TrueLog Explorer.

Include file

WebAPI.bdh

Syntax

WebVerifyData( in  sVerify     : string,
               in  nAppearance : number optional,
               in  nOptions    : number optional,
               in  nDocNum     : number optional,
               in  nSeverity   : number optional := SEVERITY_ERROR,
               out nResult     : number optional ) ;
Parameter | Description
sVerify | String to compare with the parsed HTML content.
nAppearance | Value to which the actual appearance of the specified content string is compared (see nOptions)(optional). If this parameter is omitted, the specified string must appear at least once to meet the verification rules.
nOptions

(optional)

WEB_FLAG_EQUAL
The verification succeeds if the actual appearance is equal to nAppearance.
WEB_FLAG_GREATER (default)
The verification succeeds if the actual appearance is greater than nAppearance.
WEB_FLAG_SMALLER
The verification succeeds if the actual appearance is smaller than nAppearance.
WEB_FLAG_CASE_SENSITIVE
If this flag is set the string compare operation is case sensitive.
WEB_FLAG_IGNORE_WHITE_SPACE
If this flag is set all white spaces are ignored.
WEB_FLAG_DONT_FORCE_LOAD
Specify this option to enable caching for subsequent requests. Note that this may lead to unpredictable behaviour, because the verification may only cover certain parts (which are loaded) of a page.
WEB_FLAG_ALL_RESPONSES
If this flag is specified all server responses are scanned (even redirection responses, which are normally not displayed by a browser).
WEB_FLAG_INCLUDE_EMBEDDED
If this flag is specified, even embedded documents can be specified by the nDocNum parameter. Normally the number of a document is defined by the occurrence of the source definition in an HTML document (src=...). If this flag is specified every embedded object increases this counter, which assigns higher numbers to subsequent frames.
WEB_FLAG_INCLUDE_HEADER
If this flag is specified the response header can also be verified.
WEB_FLAG_HEADER_ONLY.
If this flag is specified only the response header is verified.
WEB_FLAG_RULE
Specify this flag to perform the verification on every subsequent web function. Verification functions with this flag are usually located in the TInit transaction. Call WebCancelAllRules() to disable all verification rules.
Note: The option WEB_FLAG_RULE should only be used in the INIT transaction or in combination with the WebCancelAllRules function!
nDocNum | Specifies the document to verify (optional). Specify WEB_DOC_ALL if you want to verify all documents. If this parameter is omitted, the first document gets verified. (see the above definition of FLAG_INCLUDE_EMBEDDED)
nSeverity Optional: Severity of the error that is raised if the verification fails. Can be one of the following values:
  • SEVERITY_SUCCESS: Success; no error (numerical value: 0)
  • SEVERITY_INFORMATIONAL: Informational; no error (numerical value: 1)
  • SEVERITY_WARNING: Warning; no error (numerical value: 2)
  • SEVERITY_ERROR: (Default) Error; simulation continues (numerical value: 3)
  • SEVERITY_TRANS_EXIT: Error; the active transaction is aborted (numerical value: 4)
  • SEVERITY_PROCESS_EXIT: Error; the simulation is aborted (numerical value: 5)
nResult | If a variable is provided, it will receive the number of appearances of the specified content string (optional).

Example

dcltrans
  transaction TMain
  var
    nResult: number;
  begin
    WebVerifyData("<a href=sun.gif");
    WebPageUrl("http://mycompany.com/");
    WebVerifyData("<b>Begin</b>", 0, 0, 0, SEVERITY_WARNING);
    WebVerifyData("Shop</a>", 2, WEB_FLAG_EQUAL | WEB_FLAG_GREATER);
    WebUrl("http://mycompany.com/Shop/default.htm");
    WebVerifyData("<Html>", 2, WEB_FLAG_CASE_SENSITIVE | WEB_FLAG_SMALLER, 2, SEVERITY_ERROR, nResult);
    WebPageUrl("http://mycompany.com/frame/framea.html");
    Print(string(nResult));
  end TMain;
Parent topic: Response Verification Functions


WebVerifyDataBound Function

Action

Parses the server response data and verifies the specified string within the boundaries if the string starts with the given parameter. If the verification condition is not met, an error is raised. The severity of this error can be specified. The result of the verification can be retrieved by an optional out-parameter. A subsequent low-level web function will not return a value until the request has finished. A cache hit is not performed unless the WEB_FLAG_DONT_FORCE_LOAD option is set. The verification is done even if this option is set and the verified request or a certain part of a page is a cache hit.

When verifying/parsing an HTML page that consists of multiple frames (HTML documents), you can specify which frame document to verify/parse by specifying the nDocNum parameter. By default (1) the top document (for example, a frameset) is scanned. This applies to HTML pages that are retrieved through a page-level command like WebPageUrl or WebPageLink.

It is important to know that all parsing and verification functions must be specified before the Web API call for which the response data should be parsed/verified. You can specify multiple parse/verification functions before a Web API call. The order of the parse/verification functions is not relevant (Exception: WebParseDataBound and WebVerifyDataBound using the flag WEB_FLAG_SYNCHRON).

This verification feature can be enabled/disabled globally (Profile Settings / Web / Verification / Data / Data verification).

Note: This function can be added automatically to your script using the visual verification functionality of TrueLog Explorer.

Include file

WebAPI.bdh

Syntax

WebVerifyDataBound( in  sLeftBoundary  : string,
                    in  sRightBoundary : string,
                    in  sVerify        : string,
                    in  nOptions       : number optional,
                    in  nDocNum        : number optional,
                    in  nSeverity      : number optional := SEVERITY_ERROR,
                    out bSuccess       : boolean optional );
Parameter | Description
sLeftBoundary | Left boundary of the data to compare.
sRightBoundary | Right boundary of the data to compare.
sVerify | String to compare with the parsed data.
nOptions

(optional)

WEB_FLAG_CASE_SENSITIVE
If this flag is set the string compare operation is case sensitive.
WEB_FLAG_IGNORE_WHITE_SPACE
If this flag is set all white spaces are ignored.
WEB_FLAG_DONT_FORCE_LOAD
Specify this option to enable caching for subsequent request. Note that this may lead to unpredictable behaviour, because the verification may only cover certain parts (which are loaded) of a page.
WEB_FLAG_SYNCHRON
Verifications with this flag set, are done in a sequential way. The second verification is not executed before the boundaries of the first one have been found.
WEB_FLAG_ALL_RESPONSES
If this flag is specified, all server responses are scanned (even redirection responses, which are normally not displayed by a browser).
WEB_FLAG_INCLUDE_EMBEDDED
If this flag is specified, even embedded documents can be specified by the nDocNum parameter. Normally the number of a document is defined by the occurrence of the source definition in an HTML document (src=...). If this flag is specified every embedded object increases this counter, which assigns higher numbers to subsequent frames
WEB_FLAG_INCLUDE_HEADER
If this flag is specified the response header can also be verified.
WEB_FLAG_HEADER_ONLY
If this flag is specified only the response header is verified.
WEB_FLAG_RULE
Specify this flag to perform the verification on every subsequent web function. Verification functions with this flag are usually located in the TInit transaction. Call WebCancelAllRules() to disable all verification rules.
Note: The option WEB_FLAG_RULE should only be used in the INIT transaction or in combination with the WebCancelAllRules function!
nDocNum | Specifies the document to verify (optional). Specify WEB_DOC_ALL if you want to verify all documents. If this parameter is omitted, the first document gets verified. (see the above definition of FLAG_INCLUDE_EMBEDDED)
nSeverity Optional: Severity of the error that is raised if the verification fails. Can be one of the following values:
  • SEVERITY_SUCCESS: Success; no error (numerical value: 0)
  • SEVERITY_INFORMATIONAL: Informational; no error (numerical value: 1)
  • SEVERITY_WARNING: Warning; no error (numerical value: 2)
  • SEVERITY_ERROR: (Default) Error; simulation continues (numerical value: 3)
  • SEVERITY_TRANS_EXIT: Error; the active transaction is aborted (numerical value: 4)
  • SEVERITY_PROCESS_EXIT: Error; the simulation is aborted (numerical value: 5)
bSuccess | If a variable is provided, it will receive result of the verification (optional).

Example

dcltrans
  transaction TMain
  var
    bResult: boolean;
  begin
    WebVerifyDataBound("<b>Begin", "X.X</b>", "End ");
    WebPageUrl("http://mycompany.com/");
    WebVerifyDataBound("<b>Begin","X.X</b>", "End ", 0, 0, SEVERITY_WARNING);
    WebVerifyDataBound("<html>","</html>", "no body", WEB_FLAG_CASE_SENSITIVE | WEB_FLAG_IGNORE_WHITE_SPACE);
    WebUrl("http://mycompany.com/Shop/default.htm");
    WebVerifyDataBound("Name:", "\r\n", "Smith",WEB_FLAG_IGNORE_WHITE_SPACE, 2, SEVERITY_Error, bResult);
    WebPageUrl("http://mycompany.com/frame/framea.html");
    if not bResult then
       Print("Verification failed");
    end;
  end TMain;
Parent topic: Response Verification Functions


WebVerifyDataBoundEx function

Action

Parses the server response data and verifies the specified string within the boundaries if the string starts with the given parameter. If the verification condition is not met, an error is raised. The severity of this error can be specified. The result of the verification can be retrieved by an optional out-parameter. If nLeftOccurrence is greater than 1 (default is one) the sLeftBoundary has to be found nLeftOccurrence times, before the verification process starts and the right boundary is searched. A subsequent low-level web function will not return a value until the request has finished. A cache hit is not performed unless the WEB_FLAG_DONT_FORCE_LOAD option is set. The verification is done even if this option is set and the verified request or a certain part of a page is a cache hit.

When verifying/parsing an HTML page that consists of multiple frames (HTML documents), you can specify which frame document to verify/parse by specifying the nDocNum parameter. By default (1) the top document (e.g. a frameset) is scanned. This applies to HTML pages that are retrieved through a page-level command like WebPageUrl or WebPageLink.

It is important to know that all parsing and verification functions must be specified before the Web API call for which the response data should be parsed/verified. You can specify multiple parse/verification functions before a Web API call. The order of the parse/verification functions is not relevant (Exception: WebParseDataBound and WebVerifyDataBound using the flag WEB_FLAG_SYNCHRON).

This verification feature can be enabled/disabled globally (Profile Settings > Web > Verification > Data > Data verification).

Note: This function can be added automatically to your script using the visual verification functionality of TrueLog Explorer.

Include file

WebAPI.bdh

Syntax

WebVerifyDataBoundEx( in sLeftBoundary    : string,
                      in  nLeftOccurrence : number,
                      in  sRightBoundary  : string,
                      in  sVerify         : string,
                      in  nOptions        : number optional,
                      in  nDocNum         : number optional,
                      in  nSeverity       : number optional := SEVERITY_ERROR,
                      out bSuccess        : boolean optional );

Parameter

Description

sLeftBoundary | Left boundary of the data to compare.
nLeftOccurrence | The sLeftBoundary has to be found nLeftOccurrence times, before the verification process starts and the right boundary is searched (optional). The default value is one. Provide WEB_OCCURENCE_LAST to specify the last occurrence.
sRightBoundary | Right boundary of the data to compare.
sVerify | String to compare with the parsed data.
nOptions

(optional)

WEB_FLAG_CASE_SENSITIVE
If this flag is set the string compare operation is case sensitive.
WEB_FLAG_IGNORE_WHITE_SPACE
If this flag is set all white spaces are ignored.
WEB_FLAG_DONT_FORCE_LOAD
Specify this option to enable caching for subsequent request. Note that this may lead to unpredictable behaviour, because the verification may only cover certain parts (which are loaded) of a page.
WEB_FLAG_SYNCHRON
Verifications with this flag set, are done in a sequential way. The second verification is not executed before the boundaries of the first one have been found.
WEB_FLAG_ALL_RESPONSES
If this flag is specified, all server responses are scanned (even redirection responses, which are normally not displayed by a browser).
WEB_FLAG_INCLUDE_EMBEDDED
If this flag is specified, even embedded documents can be specified by the nDocNum parameter. Normally the number of a document is defined by the occurrence of the source definition in an HTML document (src=...). If this flag is specified every embedded object increases this counter, which assigns higher numbers to subsequent frames.
WEB_FLAG_INCLUDE_HEADER
If this flag is specified the response header can also be verified.
WEB_FLAG_HEADER_ONLY
If this flag is specified only the response header is verified.
WEB_FLAG_RULE
Specify this flag to perform the verification on every subsequent web function. Verification functions with this flag are usually located in the TInit transaction. Call WebCancelAllRules() to disable all verification rules.
Important: The option WEB_FLAG_RULE should only be used in the INIT transaction or in combination with the WebCancelAllRules function.
nDocNum

(optional)

Specifies the document to verify. Specify WEB_DOC_ALL if you want to verify all documents. If this parameter is omitted, the first document gets verified. (see the above definition of FLAG_INCLUDE_EMBEDDED)

nSeverity Optional: Severity of the error that is raised if the verification fails. Can be one of the following values:
  • SEVERITY_SUCCESS: Success; no error (numerical value: 0)
  • SEVERITY_INFORMATIONAL: Informational; no error (numerical value: 1)
  • SEVERITY_WARNING: Warning; no error (numerical value: 2)
  • SEVERITY_ERROR: (Default) Error; simulation continues (numerical value: 3)
  • SEVERITY_TRANS_EXIT: Error; the active transaction is aborted (numerical value: 4)
  • SEVERITY_PROCESS_EXIT: Error; the simulation is aborted (numerical value: 5)
bSuccess

(optional)

If a variable is provided, it will receive the result of the verification.

Example

dcltrans
  transaction TMain
  var   bResult: boolean;
  begin WebVerifyDataBoundEx("<b>Begin",2,"X.X</b>", "End ");
    WebPageUrl("http://mycompany.com/");
    WebVerifyDataBoundEx("<b>Begin",2,"X.X</b>", "End ", 0, 0, SEVERITY_WARNING);
    WebVerifyDataBound("<html>","</html>", "no body", WEB_FLAG_CASE_SENSITIVE | WEB_FLAG_IGNORE_WHITE_SPACE);
    WebUrl("http://mycompany.com/Shop/default.htm");
    WebVerifyDataBound("Name:", "\r\n", "Smith",WEB_FLAG_IGNORE_WHITE_SPACE, 2, SEVERITY_Error, bResult);
    WebPageUrl("http://mycompany.com/frame/framea.html");
    if not bResult then
      Print("Verification failed");
    end;
  end TMain;
Parent topic: Response Verification Functions


WebVerifyDataDigest Function

Action

Checks whether the Internet traffic that Silk Performer receives differs from the traffic that the Recorder captured during an earlier recording session. As the Recorder does, Silk Performer generates a digest containing information about the occurrence of each character, and compares the results with the digest generated by the Recorder. Using this function, it is possible to check whether Silk Performer receives the same data as the client application did during recording.

When verifying/parsing an HTML page that consists of multiple frames (HTML documents), you can specify which frame document to verify/parse by specifying the nDocNum parameter. By default (1) the top document (e.g. a frameset) is scanned. This applies to HTML pages that are retrieved through a page-level command like WebPageUrl or WebPageLink.

It is important to know that all parsing and verification functions must be specified before the Web API call for which the response data should be parsed/verified. You can specify multiple parse/verification functions before a Web API call. The order of the parse/verification functions is not relevant (Exception: WebParseDataBound and WebVerifyDataBound using the flag WEB_FLAG_SYNCHRON).

Include file

WebAPI.bdh

Syntax

WebVerifyDataDigest( in  sDigest     : string,
                     in  nDigestLen  : number optional,
                     in  nDifference : number optional,
                     in  nOptions    : number optional,
                     in  nDocNum     : number optional,
                     in  nSeverity   : number optional := SEVERITY_ERROR,
                     out nActDiff    : number optional) : boolean;

Return value

  • true if the parsing modifier was created successfully.

  • false otherwise.

Parameter | Description
sDigest | Digest generated by the Recorder. When the corresponding option in the Recorder Settings tab is enabled, the Internet Recorder generates a constant string called sDigest in the const section of the test script, which is suitable for this function.
nDigestLen | Size of the digest generated by the Recorder (optional, default = STRING_COMPLETE).
nDifference | Upper tolerance level for the response verification (optional). For each digest entry, this function calculates the difference between the Recorder and the Silk Performer digests. Finally, this function calculates the sum total of the differences of the Recorder and the Silk Performer digests. If this sum total is greater than the tolerance level you specified, Silk Performer reports it as an error. If you want to ensure that both the Recorder and the Silk Performer digests are compatible, you must specify a negative value (e.g.: -1). If you do not specify a value, or if you set it to zero, the default setting will be used instead.
nOptions (optional)
WEB_FLAG_DONT_FORCE_LOAD
Specify this option to enable caching for subsequent request. Note that this may lead to unpredictable behaviour, because the verification may only cover certain parts (which are loaded) of a page.
WEB_FLAG_ALL_RESPONSES
If this flag is specified all server responses are scanned (even redirection responses, which are normally not displayed by a browser).
WEB_FLAG_INCLUDE_EMBEDDED
If this flag is specified, even embedded documents can be specified by the nDocNum parameter. Normally the number of a document is defined by the occurrence of the source definition in an HTML document (src=...). If this flag is specified every embedded object increases this counter, which assigns higher numbers to subsequent frames.
WEB_FLAG_INCLUDE_HEADER
If this flag is specified the response header can also be verified.
WEB_FLAG_HEADER_ONLY
If this flag is specified only the response header is verified.
nDocNum | Specifies the document to verify (optional). Specify WEB_DOC_ALL if you want to verify all documents. If this parameter is omitted, the first document gets verified. (see the above definition of FLAG_INCLUDE_EMBEDDED)
nSeverity Optional: Severity of the error that is raised if the verification fails. Can be one of the following values:
  • SEVERITY_SUCCESS: Success; no error (numerical value: 0)
  • SEVERITY_INFORMATIONAL: Informational; no error (numerical value: 1)
  • SEVERITY_WARNING: Warning; no error (numerical value: 2)
  • SEVERITY_ERROR: (Default) Error; simulation continues (numerical value: 3)
  • SEVERITY_TRANS_EXIT: Error; the active transaction is aborted (numerical value: 4)
  • SEVERITY_PROCESS_EXIT: Error; the simulation is aborted (numerical value: 5)
nActDiff | The calculated difference between the Recorder and the Silk Performer digests.

Example

When capturing Internet traffic, the Recorder receives the following characters:

A A B B B C C C C E F F G G G

Therefore it generates the digest shown below.

A | B | C | D | E | F | G
2 | 3 | 4 | 0 | 1 | 2 | 3

When replaying the script, Silk Performer receives the following character stream from the server:

A A B A B C C C C E F F F F G

Silk Performer then generates the digest shown below.

A | B | C | D | E | F | G
3 | 2 | 4 | 0 | 1 | 4 | 1

The differences between the both digests are shown below.

A | B | C | D | E | F | G
1 | 1 | 0 | 0 | 0 | 2 | 2

In this case, the sum of differences is 6. Consequently, the first Web function call that follows the function call

WebVerifyDataDigest(sDigest, STRING_COMPLETE, 0);

reports an error. However, the first Web function call that follows the function call

WebVerifyDataDigest(sDigest, STRING_COMPLETE, 6);

does not report an error.

Example

const
  DATA_DIGEST_1 :=    "\h01420000000083F0AFF5FEF2FD01FEFBFF0300000000000000000000000000000000D201"

   "\h01009800010009003D00AC0009000500060003000100010002003C004B004C004B000200"

   "\h0500020001000A0002000400020001001200050003000400070009003A00050004000200"

   "\h02000200BB000E003C0049000F010700650036007100040038007900A700D600A3000100"

   "\h6800D000F200390005001A001C001B00";
dcltrans
  transaction TMain
  begin
    ...
    WebVerifyDataDigest(DATA_DIGEST_1, 160, 0, 0, 1, SEVERITY_ERROR);
    WebUrl("http://lab21/MSSoapSamples/State/Service/Rpc/IsapiVb/State.wsdl", 0.44);
    ...
  end TMain;
Parent topic: Response Verification Functions


WebVerifyResponseData Function

Action

Checks whether the Internet traffic Silk Performer receives differs from the traffic the Recorder captured during a former recording session. As the Recorder does, Silk Performer generates a digest containing information about the occurrence of each character, and compares the results with the digest generated by the Recorder. Using this function, it is possible to check whether Silk Performer receives the same data as the client application did during recording.

It is important to know that all parsing and verification functions must be specified before the Web API call for which the response data should be parsed/verified. You can specify multiple parse/verification functions before a Web API call. The order of the parse/verification functions is not relevant (Exception: WebParseDataBound and WebVerifyDataBound using the flag WEB_FLAG_SYNCHRON).

Note: This function is obsolete. It can still be used, although it's recommended to use the WebVerifyDataDigest function instead.

Include file

WebAPI.bdh

Syntax

WebVerifyResponseData( in  sDigest     : string,
                       in  nDigestSize : number,
                       in  nDifference : number optional,
                       out nResult     : number optional ): boolean;

Return value

  • true if the parsing modifier was created successfully.

  • false otherwise.

Parameter | Description
sDigest | Digest generated by the Recorder. When the corresponding option in the Recorder Settings tab is enabled, the Internet Recorder generates in the const section of the test script a constant string called sDigest, suitable for this function.
nDigestSize | Size of the digest generated by the Recorder.
nDifference | Upper tolerance level for the response verification (optional). For each digest entry, this function calculates the difference between the Recorder and the Silk Performer digests; finally, this function calculates the sum total of the differences of the Recorder and the Silk Performer digests. If this sum total is greater than the tolerance level you specified, Silk Performer reports it as an error. If you want to ensure that both the Recorder and the Silk Performer digests are compatible, you must specify a negative value, for example, -1. If you do not specify this value, or if you set it to zero, the default setting will be used instead.
nResult | Variable that receives the sum total of the differences between the Recorder and the Silk Performer digests (optional). If you specify a variable here, the subsequent low-level web function call will not return until the request has finished.

Example

When capturing Internet traffic, the Recorder receives the following characters:

A A B B B C C C C E F F G G G

Therefore it generates the digest shown below.

A | B | C | D | E | F | G
2 | 3 | 4 | 0 | 1 | 2 | 3

When replaying the script, Silk Performer receives the following character stream from the server:

A A B A B C C C C E F F F F G

Silk Performer then generates the digest shown below.

A | B | C | D | E | F | G
3 | 2 | 4 | 0 | 1 | 4 | 1

The differences between the both digests are shown below.

A | B | C | D | E | F | G
1 | 1 | 0 | 0 | 0 | 2 | 2

In this case, the sum of differences is 6. Consequently, the first Web function call that follows the function call

WebVerifyResponseData(sDigest, sizeof(sDigest), 0);

reports an error. However, the first Web function call that follows the function call

WebVerifyResponseData(sDigest, sizeof(sDigest), 6);

does not report an error.

Sample scripts

WebVerification01.bdf

Parent topic: Response Verification Functions
Related reference
WebVerifyDataDigest Function


WebVerifyTitle Function

Action

Parses the <TITLE> tag of the HTML response and compares its content with the provided string. If it does not match, an error is raised; the severity of this error can be specified. The parsed title can be retrieved by an optional out-parameter. If this parameter is provided, a subsequent low-level web function will not return until the request has finished. If it is omitted, a subsequent low-level web function will not wait for the completion of the request. If a page consists of more than one HTML document, additional calls of the WebVerifyTitle function check the title of the sub frames.

It is important to know that all parsing and verification functions must be specified before the Web API call for which the response data should be parsed/verified. You can specify multiple parse/verification functions before a Web API call. The order of the parse/verification functions is not relevant. An exception to this rule is using WebParseDataBound and WebVerifyDataBound with the flag WEB_FLAG_SYNCHRON).

This verification feature can be disabled globally using the response title verification option in the verification category of the Web profile settings.

Note: This function is obsolete. It can still be used, though it is recommended that you use the WebVerifyHtmlTitle function instead.

Include file

WebAPI.bdh

Syntax

WebVerifyTitle( in  sTitle        : string optional,
                in  nSeverity     : number optional := SEVERITY_ERROR,
                out sResult       : string optional,
                in  nMaxResultLen : number optional,
                in  nModeCompare  : number optional ): boolean;

Return value

  • true if the parsing modifier could be created successfully

  • false otherwise

Parameter | Description
sTitle | String to compare with the parsed title (optional). If this parameter is omitted, no error is raised (useful for pages with sub frames only).
nSeverity Optional: Severity of the error that is raised if the verification fails. Can be one of the following values:
  • SEVERITY_SUCCESS: Success; no error (numerical value: 0)
  • SEVERITY_INFORMATIONAL: Informational; no error (numerical value: 1)
  • SEVERITY_WARNING: Warning; no error (numerical value: 2)
  • SEVERITY_ERROR: (Default) Error; simulation continues (numerical value: 3)
  • SEVERITY_TRANS_EXIT: Error; the active transaction is aborted (numerical value: 4)
  • SEVERITY_PROCESS_EXIT: Error; the simulation is aborted (numerical value: 5)
sResult | If a variable is provided, it will receive the parsed title (optional).
nMaxResultLen | Maximum length of the string to return. This value must be less than or equal to the size of the string variable sResult (optional). If this parameter is omitted, the string length is unlimited.
nModeCompare | If this parameter is set to WEB_VER_FLAG_CASE_SENSITIVE, the compare operation is case sensitive (optional). If this parameter is omitted, the compare operation is not case sensitive.

Example

dcltrans
  transaction TMain
  var
    sResult: string;
  begin
    WebVerifyTitle("Silk Performer Test Site");
    WebPageUrl("http://mycompany.com/");
    WebVerifyTitle("ShopIt - Greeting", SEVERITY_WARNING,
                   sResult, STRING_COMPLETE, WEB_VER_FLAG_CASE_SENSITIVE);
    WebUrl("http://mycompany.com/Shop/default.htm");
    Print(sResult);
    WebVerifyTitle("FrameA"); // base frameset
    WebVerifyTitle(); // first frame - perform no verification
    WebVerifyTitle("Buy It"); // second frame
    WebPageUrl("http://mycompany.com/frame/framea.html");
  end TMain;
Parent topic: Response Verification Functions
Related reference
WebVerifyContent Function
WebVerifyResponseData Function
WebParseResponseTagContent Function
WebVerifyHtmlTitle Function


WebVerifyContent Function

Action

Parses the HTML response and counts the appearance of the specified content with the provided string. If the verification condition is not met, an error is raised; the severity of this error can be specified. The appearance count of the specified content can be retrieved by an optional out-parameter. If this parameter is provided, a subsequent low-level web function will not return until the request has finished. If it is omitted, a subsequent low-level web function will not wait for the completion of the request. If the verified request is a cache hit or a conditional cache hit, the content is not verified, an informational message is displayed, and the optional out parameter retrieves a -1. If the bForceLoad parameter is set to true the page must not be found in the cache and has to be requested; the result is provided under all circumstances.

When verifying/parsing an HTML page that consists of multiple frames, you can specify which frame document to verify/parse by specifying the sFrame parameter. By default, all HTML documents of the HTML page are scanned. This applies to HTML pages that are retrieved through a page-level command like WebPageUrl or WebPageLink.

It is important to know that all parsing and verification functions must be specified before the Web API call for which the response data should be parsed/verified. You can specify multiple parse/verification functions before a Web API call. The order of the parse/verification functions is not relevant (Exception: WebParseDataBound and WebVerifyDataBound using the flag WEB_FLAG_SYNCHRON).

Note: This function is obsolete. It can still be used, although it's recommended to use the WebVerifyHtml function instead.

Include file

WebAPI.bdh

Syntax

WebVerifyContent( in    sContent     : string,
                  in    nAppearance  : number optional,
                  in    sFrame       : string optional,
                  in    nModeCompare : number optional,
                  in    nSeverity    : number optional := SEVERITY_ERROR,
                  in    bForceLoad   : boolean optional,
                  inout nResult      : number optional ) : boolean;

Return value

  • true if the parsing modifier could be created successfully

  • false otherwise

Parameter | Description
sContent | String to compare with the parsed HTML content.
nAppearance | Value to which the actual appearance of the specified content string is compared (see nModeCompare)(optional). If this parameter is omitted, the specified string must appear at least once to fulfill the verification rules.
sFrame | Frame where the content string is to be searched for (optional). If this parameter is omitted the whole page is scanned.
nModeCompare

Specifies how the compare operation is performed. Can be a combination of the following values:

WEB_VER_FLAG_CASE_SENSITIVE
If this flag is set the string compare operation is case sensitive.
WEB_VER_FLAG_CONTENT_EQUAL
The verification succeeds if the actual appearance is equal to nAppearance.
WEB_VER_FLAG_CONTENT_GREATER (default)
The verification succeeds if the actual appearance is greater than nAppearance.
WEB_VER_FLAG_CONTENT_SMALLER
The verification succeeds if the actual appearance is smaller than nAppearance.
nSeverity Optional: Severity of the error that is raised if the verification fails. Can be one of the following values:
  • SEVERITY_SUCCESS: Success; no error (numerical value: 0)
  • SEVERITY_INFORMATIONAL: Informational; no error (numerical value: 1)
  • SEVERITY_WARNING: Warning; no error (numerical value: 2)
  • SEVERITY_ERROR: (Default) Error; simulation continues (numerical value: 3)
  • SEVERITY_TRANS_EXIT: Error; the active transaction is aborted (numerical value: 4)
  • SEVERITY_PROCESS_EXIT: Error; the simulation is aborted (numerical value: 5)
bForceLoad | If this parameter is true, the page has to be loaded (no cache hit possible).
nResult | If a variable is provided, it will receive the number of appearances of the specified content string (optional).

Example

dcltrans
  transaction TMain
  var
    nResult: number;
  begin
    WebVerifyContent("Begin");
    WebPageUrl("http://mycompany.com/");
    WebVerifyContent("Begin");
    WebVerifyContent("Shop", 2, 0, WEB_VER_FLAG_CONTENT_EQUAL);
    WebUrl("http://mycompany.com/Shop/default.htm");
    WebVerifyContent("Html", 3, "Right", WEB_VER_FLAG_CONTENT_SMALLER,
                     SEVERITY_ERROR, true, nResult);
    WebPageUrl("http://mycompany.com/frame/framea.html");
    Print(string(nResult));
  end TMain;
Parent topic: Response Verification Functions
Related reference
WebVerifyTitle Function
WebVerifyResponseData Function
WebParseResponseTagContent Function
WebVerifyHtml Function


MMS Functions

  • WebPostMms Function
Parent topic: Web Functions Reference


WebPostMms Function

Action

Posts the MMS to the specified MMSC by means of HTTP POST. The returned value only indicates whether or not the post operation was successful. To determine if the MMSC answered with a response status of OK, locate the response (WebParseDataBound), parse the MMS (MmsParseMms) and check its response status header (MmsGetHeader).

Include file

MmsLib.bdh

Syntax

WebPostMms( in sUrl : string,
            in hMms : number ): boolean;

Return value

  • true if successful

  • false otherwise

Parameter | Description
sUrl | Complete URL to the MMSC.
hMms | Handle for the MMS returned by a call to MmsCreateMms.

Example

transaction TInit
  var
    hMms : number;
  begin
    MmsCreateMms(hMms);
    MmsSetHeader(hMms, MMS_HEADER_MsgType, MMS_M_SEND_REQ);
    MmsSetHeader(hMms, MMS_HEADER_MmsVersion, MMS_MSGVERSION_10);
    MmsSetHeader(hMms, MMS_HEADER_ContentType,
        WAP_CONTENT_ApplicationVndWapMultipartRelated);
    MmsSetHeaderString(hMms, MMS_HEADER_From, "31743678001");
    MmsSetHeaderString(hMms, MMS_HEADER_To, "31743689031");
    MmsSetHeaderString(hMms, MMS_HEADER_TransactionId, "17");
    MmsAddFile(hMms, "smile.gif", WAP_CONTENT_ImageGif,
        "smile.gif", "smile.gif");
    WebPostMms("http://10.5.8.12:8899/mmsc", hMms);
    MmsDeleteMms(hMms);
  end TInit;
Parent topic: MMS Functions


XML Functions Reference

Silk Performer Web API provides functions for parsing/verifying node and attribute values of a Web response.

  • WebXmlGetDocument Function
    If the next web request returns an XML document, the document will be parsed by the XML dom parser and the handle to the document will be stored in hDocument.
  • WebXmlParseNodeAttribute Function
    Parses the response document with the defined content type (default: text/xml) and returns the XML attribute value of nodes attribute of the passed X-Path.
  • WebXmlParseNodeValue Function
    Parses the response document with the defined content type (default: text/xml) and returns the XML node value of the passed X-Path.
  • WebXmlVerifyNodeAttribute Function
    Verifies a nodes attribute value of the nOccurrence'd document matching the sContentType.
  • WebXmlVerifyNodeValue Function
    Verifies a nodes value of the nOccurrence'd document matching the sContentType.
Parent topic: Internet Functions


WebXmlGetDocument Function

Action

If the next web request returns an XML document, the document will be parsed by the XML dom parser and the handle to the document will be stored in hDocument. If there is no document that can be parsed, the handle will be 0.

nOccurrence specifies that the nOccurrence'd document of the next request that matches the content type should be parsed. Default value is 1.

If sContentType is defined only documents of that content type will be parsed. Default value is "text/xml".

Note: Use the XmlFreeHandle function in your script to free any open handles and to avoid increasing memory usage.

Include file

WebAPI.bdh

Syntax

WebXmlGetDocument( out hDocument    : number,
                   in  nOccurrence  : number optional,
                   in  sContentType : string optional ): boolean;

Return value

  • true if successful

  • false otherwise

Parameter | Description
hDocument | Will hold the handle to the parsed document after the next web request.
nOccurrence | (optional) If defined, the nOccurrence'd document that matches the content type will be parsed. Default value is 1.
sContentType | (optional) Default: text/xml Only documents of the passed content type will be parsed. If you pass a blank, all content types will be accepted.

Example

dcltrans
  transaction TMain
  var
    hObject, hDoc : number;
    sXML          : string;
  begin
    WebXmlGetDocument(hDoc);
    WebPageUrl("http://localhost/productsandbooks.xml");
    if(hDoc <> 0) then
      XmlGetXml(hDoc, sXML);
      writeln(sXML);
    end;
  end TMain;

XML Document for the sample above

<?xml version="1.0" ?>
<ProductsBooks>
<Products>
<Product name='Product1'>This is product1</Product>
<Product name='Product2'>This is product2</Product>
</Products>
<Books xmlns:bookns='http://book'>
<bookns:Book price='20.95'>Lord of the Rings</bookns:Book>
<bookns:Book price='18.70'>Star Wars - Episode I</bookns:Book>
</Books>
</ProductsBooks>
Parent topic: XML Functions Reference


WebXmlParseNodeAttribute Function

Action

Parses the response document with the defined content type (default: text/xml) and returns the XML attribute value of nodes attribute of the passed X-Path. The response document has to be a valid XML document for the function to work properly. If the X-Path query string contains any elements with namespace prefixes, the namespaces have to be passed in sNamespaces. sBuffer will receive the parsed value.

Include file

WebAPI.bdh

Syntax

WebXmlParseNodeAttribute( out sBuffer      : string,
                          in  nBufferLen   : number,
                          in  sXPath       : string,
                          in  sAttribute   : string,
                          in  nOptions     : number optional,
                          in  sNamespaces  : string optional,
                          in  nOccurence   : number optional,
                          in  sContentType : string optional,
                          out nParsedBytes : number optional );
Parameter | Description
sBuffer | String variable that will receive the parsed XML attribute value
nBufferLen | Maximum length of the string to return. If this parameter is omitted or set to STRING_COMPLETE all available data is stored in sResult.
sXPath | X-Path query that specifies which XML node to parse
sAttribute | Attribute of the resulting node of the X-Path query which value should be returned
nOptions | (optional) WEB_FLAG_DONT_FORCE_LOAD: Specify this option to enable caching for subsequent requests. Note that this may lead to unpredictable behaviour, because the verification may only cover certain parts (which are loaded) of a page.
sNamespaces | (optional) Namespaces that should be recognized by the XML parser. If the x-path query contains any namespace prefixes, these prefixes have to be defined in this namespace string in the way xmlns:prefix=namespace. Multiple namespaces can be defined by separating them with a blank: xmlns:ns1='http://www.MyCompany.com/ns1' xmlns:ns2='http://www.MyCompany.com/ns2'
nOccurence | (optional) If defined, the nOccurrence'd document that matches the content type will be parsed. Default value is 1.
sContentType | (optional) Default: text/xml Only documents of the passed content type will be parsed. If you pass a blank, all content types will be accepted.
nParsedBytes | (optional) Number of bytes parsed into sBuffer

Example

dcltrans
  transaction TMain
  var
    hObject : number;
    sParsedValue1, sParsedValue2 : string;
  begin
    WebXmlParseNodeAttribute(sParsedValue1, STRING_COMPLETE, "/ProductsBooks/Products/Product[2]",,"name");
    WebXmlParseNodeAttribute(sParsedValue2, STRING_COMPLETE, "/ProductsBooks/Books/ns1:Book", "price", WEB_FLAG_DONT_FORCE_LOAD, "xmlns:ns1='http://book'");
    WebPageUrl("http://localhost/productsandbooks.xml");
  end TMain;

XML Document for the sample above:

<?xml version="1.0" ?>
<ProductsBooks>
<Products>
<Product name='Product1'>This is product1</Product>
<Product name='Product2'>This is product2</Product>
</Products>
<Books xmlns:bookns='http://book'>
<bookns:Book price='20.95'>Lord of the Rings</bookns:Book>
<bookns:Book price='18.70'>Star Wars - Episode I</bookns:Book>
</Books>
</ProductsBooks>
Parent topic: XML Functions Reference
Related reference
WebXmlParseNodeValue Function


WebXmlParseNodeValue Function

Action

Parses the response document with the defined content type (default: text/xml) and returns the XML node value of the passed X-Path. The response document has to be a valid XML document for the function to work properly. If the X-Path query string contains any elements with namespace prefixes, the namespaces have to be passed in sNamespaces. sBuffer will receive the parsed value.

Include file

WebAPI.bdh

Syntax

WebXmlParseNodeValue( out sBuffer      : string,
                      in  nBufferLen   : number,
                      in  sXPath       : string,
                      in  nOptions     : number optional,
                      in  sNamespaces  : string optional,
                      in  nOccurrence  : number optional,
                      in  sContentType : string optional,
                      out nParsedBytes : number optional);
Parameter | Description
sBuffer | String variable that will receive the parsed XML node value
nBufferLen | Maximum length of the string to return. If this parameter is omitted or set to STRING_COMPLETE all available data is stored in sResult.
sXPath | X-Path query that specifies which XML node to parse
nOptions | (optional) WEB_FLAG_DONT_FORCE_LOAD: Specify this option to enable caching for subsequent requests. Note that this may lead to unpredictable behaviour, because the verification may only cover certain parts (which are loaded) of a page.
sNamespaces | (optional) Namespaces that should be recognized by the XML parser. If the x-path query contains any namespace prefixes, these prefixes have to be defined in this namespace string in the way xmlns:prefix=namespace. Multiple namespaces can be defined by separating them with a blank: xmlns:ns1='http://www.MyCompany.com/ns1' xmlns:ns2='http://www.MyCompany.com/ns2'
nOccurrence | (optional) If defined, the nOccurrence'd document that matches the content type will be parsed. Default value is 1.
sContentType | (optional) Default: text/xml Only documents of the passed content type will be parsed. If you pass a blank, all content types will be accepted.
nParsedBytes | (optional) Number of bytes parsed into sBuffer

Example

dcltrans
  transaction TMain
  var
    hObject : number;
    sParsedValue1, sParsedValue2, sParsedValue3 : string;
  begin
    WebXmlParseNodeValue(sParsedValue1, STRING_COMPLETE,"/ProductsBooks/Products/Product [2]");
    WebXmlParseNodeValue(sParsedValue2, STRING_COMPLETE,"/ProductsBooks/Products/Product [@name='Product1']");
    WebXmlParseNodeValue(sParsedValue3, STRING_COMPLETE,"/ProductsBooks/Books/ns1:Book", WEB_FLAG_DONT_FORCE_LOAD, "xmlns:ns1='http://book'");
    WebPageUrl("http://localhost/productsandbooks.xml");
  end TMain;

XML Document for the sample above

<?xml version="1.0" ?>
<ProductsBooks>
<Products>
<Product name='Product1'>This is product1</Product>
<Product name='Product2'>This is product2</Product>
</Products>
<Books xmlns:bookns='http://book'>
<bookns:Book price='20.95'>Lord of the Rings</bookns:Book>
<bookns:Book price='18.70'>Star Wars - Episode I</bookns:Book>
</Books>
</ProductsBooks>
Parent topic: XML Functions Reference
Related reference
WebXmlParseNodeAttribute Function


WebXmlVerifyNodeAttribute Function

Action

Verifies a nodes attribute value of the nOccurrence'd document matching the sContentType. Default sContentType is text/xml. The value of the resulting X-Path query node will be verified against the sValue parameter value. The response document has to be a valid XML document for the function to work properly. If the X-Path query string contains any elements with namespace prefixes, the namespaces have to be passed in sNamespaces.

Include file

WebAPI.bdh

Syntax

WebXmlVerifyNodeAttribute( in  sXPath       : string,
                           in  sAttribute   : string,
                           in  sValue       : string,
                           in  nAppearance  : number optional,
                           in  nOptions     : number optional,
                           in  sNamespaces  : string optional,
                           in  nOccurrence  : number optional,
                           in  sContentType : string optional,
                           in  nSeverity    : number optional := SEVERITY_ERROR,
                           out nResult      : number optional );
Parameter | Description
sXPath | X-Path query that specifies which XML node
sAttribute | Name of the attribute of the resulting XML node that will be verified
sValue | String to compare with the parsed node value
nAppearance (optional)

Value to which the actual appearance of the specified content string is compared (see nOptions)(optional). If this parameter is omitted, the specified string must appear at least once to meet the verification rules.

nOptions

(optional)

WEB_FLAG_EQUAL
The verification succeeds if the actual appearance is equal to nAppearance.
WEB_FLAG_GREATER (default)
The verification succeeds if the actual appearance is greater than nAppearance.
WEB_FLAG_SMALLER
The verification succeeds if the actual appearance is smaller than nAppearance.
WEB_FLAG_CASE_SENSITIVE
If this flag is set the string compare operation is case sensitive.
WEB_FLAG_IGNORE_WHITE_SPACE
If this flag is set all whites paces are ignored.
WEB_FLAG_DONT_FORCE_LOAD
Specify this option to enable caching for subsequent requests. Note that this may lead to unpredictable behaviour, because the verification may only cover certain parts (which are loaded) of a page.
WEB_FLAG_ALL_RESPONSES
If this flag is specified all server responses are scanned (even redirection responses, which are normally not displayed by a browser).
WEB_FLAG_INCLUDE_EMBEDDED
If this flag is specified, even embedded documents can be specified by the nDocNum parameter. Normally the number of a document is defined by the occurrence of the source definition in an HTML document (src=...). If this flag is specified every embedded object increases this counter, which assigns higher numbers to subsequent frames.
WEB_FLAG_INCLUDE_HEADER
If this flag is specified the response header can also be verified.
WEB_FLAG_HEADER_ONLY
If this flag is specified only the response header is verified.
WEB_FLAG_RULE
Specify this flag to perform the verification on every subsequent web function. Verification functions with this flag are usually located in the TInit transaction. Call WebCancelAllRules() to disable all verification rules.
Note: The option WEB_FLAG_RULE should only be used in the INIT transaction or in combination with the WebCancelAllRules function!
sNamespaces (optional)

Namespaces that should be recognized by the XML parser. If the x-path query contains any namespace prefixes, these prefixes have to be defined in this namespace string in the way xmlns:prefix=namespace. Multiple namespaces can be defined by separating them with a blank: xmlns:ns1= 'http://www.MyCompany.com/ns1' xmlns:ns2= 'http://www.MyCompany.com/ns2'

nOccurrence (optional)

If defined, the nOccurrence'd document that matches the content type will be parsed. Default value is 1.

sContentType (optional)

Default: text/xml

Only documents of the passed content type will be parsed. If you pass a blank, all content types will be accepted.

nSeverity Optional: Severity of the error that is raised if the verification fails. Can be one of the following values:
  • SEVERITY_SUCCESS: Success; no error (numerical value: 0)
  • SEVERITY_INFORMATIONAL: Informational; no error (numerical value: 1)
  • SEVERITY_WARNING: Warning; no error (numerical value: 2)
  • SEVERITY_ERROR: (Default) Error; simulation continues (numerical value: 3)
  • SEVERITY_TRANS_EXIT: Error; the active transaction is aborted (numerical value: 4)
  • SEVERITY_PROCESS_EXIT: Error; the simulation is aborted (numerical value: 5)
nResult (optional)

If a variable is provided, it will receive the number of appearances of the specified content string.

Example

dcltrans
  transaction TMain
  var
    hObject : number;
    sParsedValue1, sParsedValue2, sParsedValue3 : string;
  begin
    WebXmlVerifyNodeAttribute("/ProductsBooks/Products/Product[2]", "name", "Product2");
    WebXmlVerifyNodeAttribute("/ProductsBooks/Products/Product[@name= 'Product1']", "name","Product1");
    WebXmlVerifyNodeAttribute( "/ProductsBooks/Books/ns1:Book", "price", "20.95", 1,0, "xmlns:ns1='http://book'");
    WebPageUrl("http://localhost/productsandbooks.xml");
  end TMain;

XML Document for the sample above

<?xml version="1.0" ?>
<ProductsBooks>
<Products>
<Product name='Product1'>This is product1</Product>
<Product name='Product2'>This is product2</Product>
</Products>
<Books xmlns:bookns='http://book'>
<bookns:Book price='20.95'>Lord of the Rings</bookns:Book>
<bookns:Book price='18.70'>Star Wars - Episode I</bookns:Book>
</Books>
</ProductsBooks>
Parent topic: XML Functions Reference
Related reference
WebXmlVerifyNodeValue Function


WebXmlVerifyNodeValue Function

Action

Verifies a node's value in the nOccurrence'd document that matches the sContentType. Default sContentType is text/xml.

The value of the resulting X-Path query node will be verified against the sValue parameter value.

The response document has to be a valid XML document for the function to work properly. If the X-Path query string contains any elements with namespace prefixes, the namespaces have to be passed in sNamespaces.

Include file

WebAPI.bdh

Syntax

WebXmlVerifyNodeValue( in  sXPath       : string,
                       in  sValue       : string,
                       in  nAppearance  : number optional,
                       in  nOptions     : number optional,
                       in  sNamespaces  : string optional,
                       in  nOccurrence  : number optional,
                       in  sContentType : string optional,
                       in  nSeverity    : number optional := SEVERITY_ERROR,
                       out nResult      : number optional );
Parameter | Description
sXPath | X-Path query that specifies which XML node to verify
sValue | String to compare with the parsed node value
nAppearance (optional)

Value to which the actual appearance of the specified content string is compared (see nOptions). If this parameter is omitted, the specified string must appear at least once to meet the verification rules.

nOptions

(optional)

WEB_FLAG_EQUAL
The verification succeeds if the actual appearance is equal to nAppearance.
WEB_FLAG_GREATER (default)
The verification succeeds if the actual appearance is greater than nAppearance.
WEB_FLAG_SMALLER
The verification succeeds if the actual appearance is smaller than nAppearance.
WEB_FLAG_CASE_SENSITIVE
If this flag is set the string compare operation is case sensitive.
WEB_FLAG_IGNORE_WHITE_SPACE
If this flag is set all whites paces are ignored.
WEB_FLAG_DONT_FORCE_LOAD
Specify this option to enable caching for subsequent requests. Note that this may lead to unpredictable behaviour, because the verification may only cover certain parts (which are loaded) of a page.
WEB_FLAG_ALL_RESPONSES
If this flag is specified all server responses are scanned (even redirection responses, which are normally not displayed by a browser).
WEB_FLAG_INCLUDE_EMBEDDED
If this flag is specified, even embedded documents can be specified by the nDocNum parameter. Normally the number of a document is defined by the occurrence of the source definition in an HTML document (src=...). If this flag is specified every embedded object increases this counter, which assigns higher numbers to subsequent frames.
WEB_FLAG_INCLUDE_HEADER
If this flag is specified the response header can also be verified.
WEB_FLAG_HEADER_ONLY
If this flag is specified only the response header is verified.
WEB_FLAG_RULE
Specify this flag to perform the verification on every subsequent web function. Verification functions with this flag are usually located in the TInit transaction. Call WebCancelAllRules() to disable all verification rules.
Note: The option WEB_FLAG_RULE should only be used in the INIT transaction or in combination with the WebCancelAllRules function!
sNamespaces (optional)

Namespaces that should be recognized by the XML parser. If the x-path query contains any namespace prefixes, these prefixes have to be defined in this namespace string in the way xmlns:prefix=namespace. Multiple namespaces can be defined by separating them with a blank: xmlns:ns1= 'http://www.MyCompany.com/ns1' xmlns:ns2= 'http://www.MyCompany.com/ns2'

nOccurrence (optional)

If defined, the nOccurrence'd document that matches the content type will be parsed. Default value is 1.

sContentType (optional)

Default: text/xml

Only documents of the passed content type will be parsed. If you pass a blank, all content types will be accepted.

nSeverity Optional: Severity of the error that is raised if the verification fails. Can be one of the following values:
  • SEVERITY_SUCCESS: Success; no error (numerical value: 0)
  • SEVERITY_INFORMATIONAL: Informational; no error (numerical value: 1)
  • SEVERITY_WARNING: Warning; no error (numerical value: 2)
  • SEVERITY_ERROR: (Default) Error; simulation continues (numerical value: 3)
  • SEVERITY_TRANS_EXIT: Error; the active transaction is aborted (numerical value: 4)
  • SEVERITY_PROCESS_EXIT: Error; the simulation is aborted (numerical value: 5)
nResult (optional)

If a variable is provided, it will receive the number of appearances of the specified content string.

Example

dcltrans
  transaction TMain
  var
    hObject       : number;
    sParsedValue1 : string;
    sParsedValue2 : string;
    sParsedValue3 : string;
  begin
    WebXmlVerifyNodeValue("/ProductsBooks/Products/Product[2]", "This is product2");
    WebXmlVerifyNodeValue("/ProductsBooks/Products/Product[@name='Product1']","This is product1");
    WebXmlVerifyNodeValue("/ProductsBooks/Books/ns1:Book", "Lord of the Rings", 1, 0, "xmlns:ns1='http://book'");
    WebPageUrl("http://localhost/productsandbooks.xml");
  end TMain;

XML Document for the sample above

<?xml version="1.0" ?>
<ProductsBooks>
<Products>
<Product name='Product1'>This is product1</Product>
<Product name='Product2'>This is product2</Product>
</Products>
<Books xmlns:bookns='http://book'>
<bookns:Book price='20.95'>Lord of the Rings</bookns:Book>
<bookns:Book price='18.70'>Star Wars - Episode I</bookns:Book>
</Books>
</ProductsBooks>
Parent topic: XML Functions Reference
Related reference
WebXmlVerifyNodeAttribute Function


Java Framework Functions

As a powerful extension to Silk Performer’s Benchmark Description Language, the Java Framework enables you to implement user behavior in Java. When testing an existing Java application you do not need to spend much time creating test scripts. The only effort required is embedding existing Java source code into the framework.

To generate a benchmark executable and run a test with the help of the Java framework, two source files are normally required:

  • A Java class that implements the behavior of a virtual user

  • A Silk Performer test script that invokes Java method calls

Note: Both source files need to have the same name, with extensions indicating the file types (.bdf for the Silk Performer test script and .java for the Java source file).

With Silk Performer it is possible to call Java functions on any Java object from a BDL context with any number and type of parameter and return parameter. When a Java function returns a complex object, a handle for the Java object is returned in its place. The handle can be passed to other function calls as an input parameter, or public methods may be invoked on the object. There is also support for static methods, cast operations, and exception handling.

Silk Performer provides the following functions for invoking the methods of a Java class from within a test script:

  • JavaSetOption Function
    Sets options for the Java Virtual Machine.
  • JavaCreateJavaVM Function
    Initializes and starts the Java Virtual Machine (JVM).
  • JavaLoadObject Function
    Instantiates a Java object and returns a handle on it.
  • JavaLoadSilkPerformer Function
    Instantiates the Java object silk.performer.SilkPerformer and returns a handle on it.
  • JavaLoadString Function
    Instantiates a Java string object and returns a handle on it.
  • JavaCallMethod Function
    Invokes either a dynamic or a static Java method.
  • JavaFreeObject Function
    Frees a java object. Must be called on all objects instantiated with JavaLoadObject or retrieved with JavaGetObject.
  • JavaCastObject Function
    Casts an object to a type of your choice.
  • JavaClearParameterList Function
    When calling a Java method that takes parameters, the parameters are added one by one to a parameter list.
  • JavaGetBoolean Function
    Retrieves the boolean return value of the last call of JavaCallMethod on the specified object or class.
  • JavaGetByteArray Function
    Retrieves the byte array return value of the last call of JavaCallMethod on the specified object or class.
  • JavaGetChar Function
    Retrieves the ordinal number of the char return value of the last call of JavaCallMethod on the specified object or class.
  • JavaGetFloat Function
    Retrieves the float return value of the last call of JavaCallMethod on the specified object or class.
  • JavaGetNumber Function
    Retrieves the int return value of the last call of JavaCallMethod on the specified object or class.
  • JavaGetObject Function
    Retrieves a handle on the object returned by the last call of JavaCallMethod on the specified object or class.
  • JavaGetString Function
    Retrieves the string return value of the last call of JavaCallMethod on the specified object or class.
  • JavaGetUserObject Function
    Returns the handle on the JavaUser object loaded by JavaUserInit command.
  • JavaSetBoolean Function
    Sets a boolean parameter for the next function or constructor call.
  • JavaSetChar Function
    Sets a char parameter for the next function or constructor call.
  • JavaSetFloat Function
    Sets a float parameter for the next function or constructor call.
  • JavaSetLogOption Function
    Sets logging options for the Java Framework.
  • JavaSetNumber Function
    Sets a numeric parameter for the next function or constructor call.
  • JavaSetObject Function
    Sets an object parameter for the next function or constructor call.
  • JavaSetString function
    Sets a string parameter for the next function or constructor call.
  • JavaSetByteArray Function
    Convenience function derived from JavaSetString function.
  • JavaSetCharArray Function
    Convenience function derived from JavaSetString function.
  • JavaUserInit Function
    Calls the JavaUserInit method of the Java class that implements the behavior of the virtual user.
  • JavaUserRun Function
    Calls the JavaUserRun method of the Java class that implements the behavior of the virtual user.
  • JavaUserMethod Function
    Calls an additional method of the Java class that implements the behavior of the virtual user.
  • JavaUserShutdown Function
    Calls the JavaUserShutdown method of the Java class that implements the behavior of the virtual user.
  • JavaRegisterException Function
    Registers a Java exception string under a custom error number.
  • JavaUnregisterException Function
    Unregisters an exception message.
  • JavaUnregisterErrorNumber Function
    Unregisters exception messages.
  • JavaGetLastException Function
    Retrieves the last exception message.
  • JUnitCallMethod Function
    Invokes a JUnit conform method of a class derived from junit.framework.TestCase.
  • JUnitExecuteTest Function
    Starts a JUnit test execution.
  • JUnitLoadClass Function
    Instantiates a Java object and returns a handle of the runtime class.
  • Deprecated Java Framework Functions
    Lists the deprecated functions from the previous version of the Java Framework.
Parent topic: Benchmark Description Language (BDL) Reference


JavaSetOption Function

Action

Sets options for the Java Virtual Machine. This function has to be called prior to the JavaCreateJavaVM or JoltInit functions.

Include file

javabase.bdh

Syntax

JavaSetOption( in nOption : number,
               in sValue  : string ): boolean;

Return value

  • true if successful

  • false otherwise

nOption

Determines the option to be set. This parameter is one of the following flags:

JAVA_VERSION. Specifies the version number of the Java Virtual Machine. This option is obligatory. Valid option(s) are:

  • JAVA_V11

  • JAVA_V12

  • JAVA_V13

  • JAVA_V14

  • JAVA_V15

  • JAVA_V16

  • JAVA_V17

  • JAVA_V18

JAVA_HOME. Specifies the installation directory of the Java Virtual Machine. This option enables the Java Virtual Machine to be loaded for a different path than specified in the PATH environment, so that it is possible to switch between various Java Virtual Machines without changing the system PATH environment.

JAVA_CLASSPATH. Specifies the class path for the Java Virtual Machine. By default the class path is set to the system class path.

JAVA_DLL. Specifies a Dynamic Link Library (.dll) that implements the Java Virtual Machine to be used.

JAVA_VERBOSE. Sets the verbose option of the Java Virtual Machine. By default this option is disabled.

JAVA_DISABLE_COMPILER. Disables the Just In Time (JIT) compiler of the Java Virtual Machine. By default the Just In Time compiler is enabled.

JAVA_CMDLINE_OPTIONS. Specifies any command line options to be passed to the Java Virtual Machine.

JAVA_USE_SYSTEM_CLASSPATH. Determines that the system class path is used. This option is enabled by default.

JAVA_DESTROY_JVM_ON_SHUTDOWN. If it is not set (default), the current thread is detached from the JVM at shutdown, but the JVM is not destroyed. If it is set, all java threads are killed and JVM is destroyed on shutdown; to use this, JVMDI has to be enabled by setting -Xdebug -Xnoagent -Djava.compiler=NONE as commandline options. For getting profiling information with -Xrunhprof this flag has to be enabled.

JAVA_SUPPRESS_EXCEPTIONS. If it is not set (default), java exception will raise a bdl error. If it is set, java exceptions must be checked manually with JavaGetLastException command.

JAVA_ARCHITECTURE_VERSION. Specifies Java architecture version. Use the value JAVA_ARCH_32BIT for 32-bit Java (default) or JAVA_ARCH_64BIT for 64-bit Java.

sValue Value of the option to be set.

Example

dcltrans
  transaction TInit
  begin
    JavaSetOption(JAVA_VERSION, JAVA_V17);
    JavaSetOption(JAVA_HOME, "c:/Program Files/Java/jdk1.7.0");
    JavaSetOption(JAVA_CLASSPATH, "c:/myApplication/classes;c:/myTools/tools.zip");
    JavaSetOption(JAVA_DISABLE_COMPILER, YES);
    JavaSetOption(JAVA_CMDLINE_OPTIONS, "-ss8K -oss50K-DanyProperty=aValue");
    JavaSetOption(JAVA_ARCHITECTURE_VERSION, JAVA_ARCH_64BIT);
    JavaCreateJavaVM();
  end TInit;
Parent topic: Java Framework Functions
Related reference
JoltInit Function
JavaCreateJavaVM Function


JavaCreateJavaVM Function

Action

Initializes and starts the Java Virtual Machine (JVM). Silk Performer requires the JVM from Sun Microsystems.

Include file

Java.bdh

Syntax

JavaCreateJavaVM( in nVersion   : number optional ): boolean;

Return value

  • true if successful

  • false otherwise

Parameter Description
nVersion

Version number of the Java Virtual Machine (optional). This parameter can be one of the following:

  • JAVA_V1. Java 1 Platform (Java 1.1.x)

  • JAVA_V2. Java 2 Platform (Java 1.2.x and later versions)

By default, the VM version, specified by the profile settings, is used.

Note: The JavaSetOption function overrides the profile setting.

Example

dcltrans
  transaction TInit
  begin
    JavaSetOption(JAVA_VERSION, JAVA_V17);
    JavaSetOption(JAVA_HOME, "c:/Program Files/Java/jdk1.7.0");
    JavaSetOption(JAVA_CLASSPATH, "c:/myApplication/classes;c:/myTools/tools.zip");
    JavaCreateJavaVM();
    JavaUserInit("SilkPerformerUser");
  end TInit;

  transaction TRun
  begin
    JavaUserRun();
  end TRun;

  transaction TMyTransaction
  begin
    JavaUserMethod("MyMethod");
  end TMyTransaction;

  transaction TShutdown
  begin
    JavaUserShutdown();
  end TShutdown;
Parent topic: Java Framework Functions
Related reference
JavaSetOption Function


JavaLoadObject Function

Action

Instantiates a Java object and returns a handle on it. The Java object must be released by the JavaFreeObject command.

Include file

Java.bdh

Syntax

JavaLoadObject( in sClassSpecifier : string,
                in sTimerName      : string optional ): number;

Return value

  • Handle on the Java object.

Parameter | Description
sClassSpecifier | Fully qualified name of the class to instantiate. The class must be available via the classpath. The ‘/’ character has to be used as package separator. Example: java/lang/String.
sTimerName | (optional) Creates a custom time measure with the specified name for this function.

Example

var
  hTestObj   : number;

dcltrans
  transaction TInit
  begin
      // Load and start the JVM.
      JavaCreateJavaVM();

      // instantiate the java class
      hTestObj := JavaLoadObject("Test");
  end TInit;

  transaction THello
  begin
    JavaCallMethod(hTestObj, "doHello");
  end THello;

  transaction TEnd
  begin
    JavaFreeObject(hTestObj);
  end TEnd;

Sample scripts

JavaFrameworkBankSample.bdf

BankSample.java, Account.java, Customer.java, PremiumCustomer.java

Parent topic: Java Framework Functions
Related reference
JavaFreeObject Function


JavaLoadSilkPerformer Function

Action

Instantiates the Java object silk.performer.SilkPerformer and returns a handle on it. The Java object must be released by the JavaFreeObject function.

Include file

Java.bdh

Syntax

JavaLoadSilkPerformer(): number;

Return value

  • Handle on the Java object.

Example

var
  hPerf  : number;

dcltrans
  transaction TInit
  begin
      // Load and start the JVM.
      JavaCreateJavaVM();

      // instantiate the SilkPerformer java class
      hPerf := JavaLoadSilkPerformer();
  end TInit;

  transaction THello
  begin
    JavaSetString(hPerf, "Print with SilkPerformer object");
    JavaCallMethod(hPerf, "doHello");
  end THello;

  transaction TEnd
  begin
    JavaFreeObject(hPerf);
  end TEnd;
Parent topic: Java Framework Functions


JavaLoadString Function

Action

Instantiates a Java string object and returns a handle on it. The Java string must be released by the JavaFreeObject() command.

Include file

Java.bdh

Syntax

JavaLoadString( in sInitValue : string,
                in sTimerName : string optional ): number;

Return value

Handle on the Java string.

Parameter | Description
sInitValue | Init value of the string to create.
sTimerName | (optional) Creates a custom time measure with the specified name for this function.

Example

  transaction TInit
  begin
    JavaCreateJavaVM();
    JavaUserInit("SilkPerformerUser");
  end TInit;

  transaction TMyJavaTrans
  var
    hObj     : number;
    hJKeyStr : number;
  begin
    hJKeyStr := JavaLoadString("hello");

    ThinkTime(0.2);
    JavaCallMethod(JavaGetUserObject(), "myComplexMethod");
    hObj := JavaGetObject(JavaGetUserObject());
  end TMyJavaTrans;
Parent topic: Java Framework Functions


JavaCallMethod Function

Action

Invokes either a dynamic or a static Java method. If parameters have been set with the JavaSetXX methods, these parameters will be passed to the method. To invoke static methods, the JAVA_STATIC_METHOD constant is passed instead of an object handle to the function. The method call will fail if no method signature matching the passed parameters is found.

Include file

Java.bdh

Syntax

JavaCallMethod( in hObject : number,
                in sMethod : string,
                in sTimerName      : string optional ): boolean;

Return value

  • true if the method call succeeded

  • false otherwise

Parameter | Description
hObject | Valid handle to a java object or JAVA_STATIC_METHOD.
sMethod | Name of the method to invoke for dynamic methods, or package/subpackage/class_name.static_method_name for static methods. Example: toString Example: java/lang/String.valueOf
sTimerName | (optional) Creates a custom time measure with the specified name for this function.

Example

var
  hTestObj   : number;

dcltrans
  transaction TInit
  begin
        // Load and start the JVM.
        JavaCreateJavaVM();

        // instantiate the java class
        hTestObj := JavaLoadObject("Test");
  end TInit;

  transaction THello
  begin
    JavaCallMethod(hTestObj, "doHello");
  end THello;

  transaction TEnd
  begin
    JavaFreeObject(hTestObj);
  end TEnd;

Sample scripts

JavaFrameworkBankSample.bdf

BankSample.java, Account.java, Customer.java, PremiumCustomer.java

Parent topic: Java Framework Functions


JavaFreeObject Function

Action

Frees a java object. Must be called on all objects instantiated with JavaLoadObject or retrieved with JavaGetObject.

Include file

Java.bdh

Syntax

JavaFreeObject( in hObject: number ): boolean;

Return value

  • true if the object could be released

  • false otherwise

Parameter | Description
hObject | Valid handle to a java object.

Example

var
  hTestObj   : number;

dcltrans
  transaction TInit
  begin
      // Load and start the JVM.
      JavaCreateJavaVM();

      // instantiate the java class
      hTestObj := JavaLoadObject("Test");
  end TInit;

  transaction THello
  begin
    JavaCallMethod(hTestObj, "doHello");
  end THello;

  transaction TEnd
  begin
    JavaFreeObject(hTestObj);
  end TEnd;

Sample scripts

JavaFrameworkBankSample.bdf

BankSample.java, Account.java, Customer.java, PremiumCustomer.java

Parent topic: Java Framework Functions
Related reference
JavaLoadObject Function
JavaGetObject Function


JavaCastObject Function

Action

Casts an object to a type of your choice. Class cast will be valid for all further JavaCallMethod or JavaSetObject calls.

Include file

Java.bdh

Syntax

JavaCastObject( in hObject         : number,
                in sClassSpecifier : string ): boolean;

Return value

  • True if successful

  • false otherwise

Parameter | Description
hObject | Valid handle to a java object.
sClassSpecifier | Fully qualified classname to cast to. Example: fw60sample/Account

Example

dcltrans
  transaction TInit
  begin
        // Load and start the JVM.
        JavaCreateJavaVM();

  end TInit;

  transaction TPureBdl
  var hJTable    : number;
      hJKeyStr   : number;
      hJValueStr : number;
      hJRetVal   : number;
      sBuffer    : string;
  begin
    // prepare the key/value pair
    // String jKeyStr = "hello";
    // String jValueStr = "world";
    hJKeyStr := JavaLoadString("hello");
    hJValueStr := JavaLoadString("world");

    // instantiate a Hashtable
    // Hashtable jTable = new Hashtable();
    hJTable := JavaLoadObject("java/util/Hashtable");

    // insert an Object into the Hashtable
    // jTable.put(jKeyStr, jValueStr);
    JavaCastObject(hJKeyStr, "java/lang/Object");
    JavaSetObject(hJTable, hJKeyStr);
    JavaSetObject(hJTable, hJValueStr, "java/lang/Object");
    JavaCallMethod(hJTable, "put");

    // retrieve an Object from the Hashtable
    // Object jRetVal = jTable.get(jKeyStr);
    JavaSetObject(hJTable, hJKeyStr);
    JavaCallMethod(hJTable, "get");
    hJRetVal := JavaGetObject(hJTable);

    // retrieve print out the java string object
    // System.out.println("Found value \""+jRetVal+"\" in Hashtable.");
    JavaCallMethod(hJRetVal, "toString");
    JavaGetString(hJRetVal, sBuffer);
    Print("Found value \""+sBuffer+"\" in Hashtable.");

    // Free all objects
    JavaFreeObject(hJTable);
    JavaFreeObject(hJKeyStr);
    JavaFreeObject(hJValueStr);
    JavaFreeObject(hJRetVal);
  end TPureBdl;

  transaction TEnd
  begin
  end TEnd;

Sample scripts

JavaFrameworkBankSample.bdf

BankSample.java, Account.java, Customer.java, PremiumCustomer.java

Parent topic: Java Framework Functions


JavaClearParameterList Function

Action

When calling a Java method that takes parameters, the parameters are added one by one to a parameter list. There is a parameter list for each Java object, and a list for all static method or constructor calls. Parameter lists are automatically cleared when a method or constructor is invoked.

In some cases, for example when an event handler is used, the actual transaction may be over before the method or constructor is invoked, so the parameter list is not cleared. In such cases, the parameter list must be cleared by hand before new parameters are set for the next method or constructor call.

Include file

JavaBase.bdh

Syntax

JavaClearParameterList( in hObject: number ): boolean;

Return value

  • true if successful

  • false otherwise

Parameter | Description
hObject | Valid handle to a Java object or JAVA_STATIC_METHOD.

Example

dcluser
  user
    JavaUser
  transactions
    TInit               : begin;
    TMyJavaTransBad     : 1;
    TMyJavaTransGood    : 1;
    TEnd                : end;

dclevent
  handler Handler1 <EVENT_RAISE_ERROR>
  var
    hStrGood, hStrBad :number;
    buffer            :string;
  begin
    if GetErrorCode(GetLastError()) = 9999 then
      Print("Here we are");
      // first the bad example
      hStrGood := JavaLoadObject("java/lang/String");
      Print("something messed us up here; we wanted to create an empty String, but will get something unexpected:");
      JavaCallMethod(hStrGood, "toString");
      JavaGetString(hStrGood, buffer);
      Print("buffer = '"+buffer+"'");
    else
    if GetErrorCode(GetLastError()) = 9998 then
      // then the good example
      JavaClearParameterList(JAVA_STATIC_METHOD);
      hStrGood := JavaLoadObject("java/lang/String");
      Print("there should be an empty String if JavaClearParameterList() worked");      JavaCallMethod(hStrGood, "toString");
      JavaGetString(hStrGood, buffer);
      Print("buffer = '"+buffer+"'");
    else
      throw;
    end;
  end;
  end Handler1;

// Java Framework Transactions Section
dcltrans
  transaction TInit
  var
    hPerf : number;
  begin
    JavaCreateJavaVM();
  end TInit;

  transaction TMyJavaTransBad
  var
    hSomeJavaObject : number;
  begin
    JavaSetString(JAVA_STATIC_METHOD, "some text");
    // let’s assume, code execution jumps to event handler from here
    RaiseError(9999, "just wanted to show event handler sample");
    // if no event is raised, execution continues here
    hSomeJavaObject := JavaLoadObject("java/lang/String");
    JavaFreeObject(hSomeJavaObject);
  end TMyJavaTransBad;

  transaction TMyJavaTransGood
  var
    hSomeJavaObject : number;
  begin
    JavaSetString(JAVA_STATIC_METHOD, "some text");
    // let’s assume, code execution jumps to event handler from here
    RaiseError(9998, "just wanted to show event handler sample");
    // if no event is raised, execution continues here
    hSomeJavaObject := JavaLoadObject("java/lang/String");
    JavaFreeObject(hSomeJavaObject);
  end TMyJavaTransGood;

  transaction TEnd
  begin
  end TEnd;
Parent topic: Java Framework Functions


JavaGetBoolean Function

Action

Retrieves the boolean return value of the last call of JavaCallMethod on the specified object or class.

Include file

Java.bdh

Syntax

JavaGetBoolean( in hObject: number ): boolean;

Return value

  • Returns the result of the last call of JavaCallMethod.

Parameter | Description
hObject | Valid handle to a java object or JAVA_STATIC_METHOD.

Example

var
  hTestObj   : number;

dcltrans
  transaction TInit
  begin
      // Load and start the JVM.
      JavaCreateJavaVM();

      // instantiate the java class
      hTestObj := JavaLoadObject("Test");
  end TInit;

  transaction TPureBdl
  var hJTable    : number;
      hJKeyStr   : number;
      hJValueStr : number;
      hJRetVal   : number;
      sBuffer    : string;
      bHasNext   : boolean;
  begin
    // prepare the key/value pair
    // String jKeyStr = "hello";
    // String jValueStr = "world";
    hJKeyStr := JavaLoadString("hello");
    hJValueStr := JavaLoadString("world");

    // instantiate a Hashtable
    // Hashtable jTable = new Hashtable();
    hJTable := JavaLoadObject("java/util/Hashtable");

    // insert an Object into the Hashtable
    // jTable.put(jKeyStr, jValueStr);
    JavaCastObject(hJKeyStr, "java/lang/Object");
    JavaSetObject(hJTable, hJKeyStr);
    JavaSetObject(hJTable, hJValueStr, "java/lang/Object");
    JavaCallMethod(hJTable, "put");

    // retrieve an Object from the Hashtable
    // Object jRetVal = jTable.get(jKeyStr);
    JavaSetObject(hJTable, hJKeyStr);
    JavaCallMethod(hJTable, "get");
    hJRetVal := JavaGetObject(hJTable);

    JavaCallMethod(hJRetVal, "hasNext");
    bHasNext := JavaGetBoolean(hJRetVal);

    // Free all objects
    JavaFreeObject(hJTable);
    JavaFreeObject(hJKeyStr);
    JavaFreeObject(hJValueStr);
    JavaFreeObject(hJRetVal);
  end TPureBdl;

  transaction TEnd
  begin
    JavaFreeObject(hTestObj);
  end TEnd;

Sample scripts

JavaFrameworkBankSample.bdf

BankSample.java, Account.java, Customer.java, PremiumCustomer.java

Parent topic: Java Framework Functions
Related reference
JavaCallMethod Function
JavaSetBoolean Function


JavaGetByteArray Function

Action

Retrieves the byte array return value of the last call of JavaCallMethod on the specified object or class.

Include file

JavaBase.bdh

Syntax

JavaGetByteArray(
    in  hObject : number,
    out sBuffer : string,
    in nBufLen : number optional );
Parameter | Description
hObject | Valid handle to a java object or JAVA_STATIC_METHOD.
sBuffer | String buffer that will receive the return value of the last call of JavaCallMethod.
nBufLen | Length of the buffer (optional).

Example

benchmark SampleDocu
use "Kernel.bdh"
use "Java.bdh"

// Workload Section
dcluser
  user
    JavaUser

  transactions
    TInit               : begin;
    TMyJavaTrans        : 1;

// Java Framework Transactions Section
dcltrans
  transaction TInit
  begin
    JavaCreateJavaVM();
  end TInit;

  transaction TMyJavaTrans
  var
    hStr    : number;
    sBuffer : string;
  begin

    // creating a Java string
    hStr := JavaLoadString("a sample string containing a currency symbol €");
    // getting bytes array
    JavaCallMethod(hStr, "getBytes");
    // storing byte array
    JavaGetByteArray(hStr, sBuffer);
    // print to virtual user output
    Print(sBuffer);
  end TMyJavaTrans;
Parent topic: Java Framework Functions
Related reference
JavaCallMethod Function
JavaSetByteArray Function


JavaGetChar Function

Action

Retrieves the ordinal number of the char return value of the last call of JavaCallMethod on the specified object or class.

Include file

Java.bdh

Syntax

JavaGetChar( in hObject: number ): number;

Return value

  • Returns the result of the last call of JavaCallMethod.

Paremeter | Description
hObject | Valid handle to a java object or JAVA_STATIC_METHOD.

Example

var
  hTestObj : number;

dcltrans
  transaction TInit
  begin
    // Load and start the JVM.
    JavaCreateJavaVM();
    // instantiate the java class: java.lang.Character
    JavaSetChar(JAVA_STATIC_METHOD, ord('c'));
    hTestObj := JavaLoadObject("java/lang/Character");
  end TInit;

  transaction TMyJavaTrans
  var
    charNum : number;
  begin
    // calling charValue() method of java.lang.Character object
    JavaCallMethod(hTestObj, "charValue");
    charNum := JavaGetChar(hTestObj);
  end TMyJavaTrans;

  transaction TEnd
  begin
    JavaFreeObject(hTestObj);
  end TEnd;
Parent topic: Java Framework Functions
Related reference
JavaCallMethod Function
JavaSetChar Function


JavaGetFloat Function

Action

Retrieves the float return value of the last call of JavaCallMethod on the specified object or class.

Include file

Java.bdh

Syntax

JavaGetFloat( in hObject: number ): float;

Return value

  • Returns the result of the last call of JavaCallMethod.

Parameter | Description
hObject | Valid handle to a java object or JAVA_STATIC_METHOD.

Example

var
  hTestObj   : number;

dcltrans
  transaction TInit
  begin
        // Load and start the JVM.
        JavaCreateJavaVM();

        // instantiate the java class
        hTestObj := JavaLoadObject("Test");
  end TInit;

  transaction TMyJavaTrans
  var
    fValue : float;
  begin
    ThinkTime(0.2);
    // set the first parameter
    JavaSetString(hTestObj, "1");
    // set the second parameter
    JavaSetNumber(hTestObj, 1, JAVA_BYTE);
    // invoke the method    JavaCallMethod(hTestObj, "doFoo");
    // retrieve the result    fValue := JavaGetFloat(hTestObj);
    Print("doFoo returned "+String(fValue));
  end TMyJavaTrans;

  transaction TEnd
  begin
    JavaFreeObject(hTestObj);
  end TEnd;

Sample scripts

JavaFrameworkBankSample.bdf

BankSample.java, Account.java, Customer.java, PremiumCustomer.java

Parent topic: Java Framework Functions
Related reference
JavaCallMethod Function
JavaSetFloat Function


JavaGetNumber Function

Action

Retrieves the int return value of the last call of JavaCallMethod on the specified object or class.

Include file

Java.bdh

Syntax

JavaGetNumber( in hObject: number ): number;

Return value

  • Returns the result of the last call of JavaCallMethod.

Parameter | Description
hObject | Valid handle to a java object or JAVA_STATIC_METHOD.

Example

var
  hTestObj   : number;

dcltrans
  transaction TInit
  begin
      // Load and start the JVM.
      JavaCreateJavaVM();

      // instantiate the java class
      hTestObj := JavaLoadObject("Test");
  end TInit;

  transaction TStaticMethods
  var
    str    : string;
    nConv1 : number;
    nConv2 : number;
    hJStr  : number;
  begin
    str := "123";

    nConv1 := Number(str);

    JavaSetString(JAVA_STATIC_METHOD, str);
    JavaCallMethod(JAVA_STATIC_METHOD, "java/lang/Integer.parseInt");
    nConv2 := JavaGetNumber(JAVA_STATIC_METHOD);

    if nConv1 = nConv2 then
      Print("Both conversion delievered the same result! ("+String(nConv1)+" = "+String(nConv2)+")");
    end;
  end TStaticMethods;

  transaction TEnd
  begin
    JavaFreeObject(hTestObj);
  end TEnd;

Sample scripts

JavaFrameworkBankSample.bdf

BankSample.java, Account.java, Customer.java, PremiumCustomer.java

Parent topic: Java Framework Functions
Related reference
JavaCallMethod Function
JavaSetNumber Function


JavaGetObject Function

Action

Retrieves a handle on the object returned by the last call of JavaCallMethod on the specified object or class. The object retrieved may be reused for further calls of or JavaSetObject and must be released with JavaFreeObject.

Include file

Java.bdh

Syntax

JavaGetObject( in hObject : number ): number;

Return value

  • Returns a handle on the result of the last call of JavaCallMethod.

Parameter | Description
hObject | Valid handle to a java object or JAVA_STATIC_METHOD.

Example

dcltrans
  transaction TInit
  begin
    // Load and start the JVM.
    JavaCreateJavaVM();

  end TInit;

  transaction TPureBdl
  var hJTable    : number;
    hJKeyStr   : number;
    hJValueStr : number;
    hJRetVal   : number;
    sBuffer    : string;
  begin
    // prepare the key/value pair
    // String jKeyStr = "hello";
    // String jValueStr = "world";
    hJKeyStr := JavaLoadString("hello");
    hJValueStr := JavaLoadString("world");

    // instantiate a Hashtable
    // Hashtable jTable = new Hashtable();
    hJTable := JavaLoadObject("java/util/Hashtable");

    // insert an Object into the Hashtable
    // jTable.put(jKeyStr, jValueStr);
    JavaCastObject(hJKeyStr, "java/lang/Object");
    JavaSetObject(hJTable, hJKeyStr);
    JavaSetObject(hJTable, hJValueStr, "java/lang/Object");
    JavaCallMethod(hJTable, "put");

    // retrieve an Object from the Hashtable
    // Object jRetVal = jTable.get(jKeyStr);
    JavaSetObject(hJTable, hJKeyStr);
    JavaCallMethod(hJTable, "get");
    hJRetVal := JavaGetObject(hJTable);

    // retrieve print out the java string object
    // System.out.println("Found value \""+jRetVal+"\" in Hashtable.");
    JavaCallMethod(hJRetVal, "toString");
    JavaGetString(hJRetVal, sBuffer);
    Print("Found value \""+sBuffer+"\" in Hashtable.");

    // Free all objects
    JavaFreeObject(hJTable);
    JavaFreeObject(hJKeyStr);
    JavaFreeObject(hJValueStr);
    JavaFreeObject(hJRetVal);
  end TPureBdl;

  transaction TEnd
  begin
  end TEnd;

Sample scripts

JavaFrameworkBankSample.bdf

BankSample.java, Account.java, Customer.java, PremiumCustomer.java

Parent topic: Java Framework Functions
Related reference
JavaCallMethod Function
JavaSetObject Function


JavaGetString Function

Action

Retrieves the string return value of the last call of JavaCallMethod on the specified object or class.

Include file

Java.bdh

Syntax

JavaGetString( in  hObject : number,
               out sBuffer : string,
               in  nBufLen : number optional );
Parameter | Description
hObject | Valid handle to a java object or JAVA_STATIC_METHOD.
sBuffer | String buffer that will receive the return value of the last call of JavaCallMethod.
nBufLen | Length of the buffer (optional).

Example

dcltrans
  transaction TInit
  begin
        // Load and start the JVM.
        JavaCreateJavaVM();

  end TInit;

  transaction TPureBdl
  var hJTable    : number;
      hJKeyStr   : number;
      hJValueStr : number;
      hJRetVal   : number;
      sBuffer    : string;
  begin
   // prepare the key/value pair
    // String jKeyStr = "hello";
    // String jValueStr = "world";
    hJKeyStr := JavaLoadString("hello");
    hJValueStr := JavaLoadString("world");

    // instantiate a Hashtable
    // Hashtable jTable = new Hashtable();
    hJTable := JavaLoadObject("java/util/Hashtable");

    // insert an Object into the Hashtable
    // jTable.put(jKeyStr, jValueStr);
    JavaCastObject(hJKeyStr, "java/lang/Object");
    JavaSetObject(hJTable, hJKeyStr);
    JavaSetObject(hJTable, hJValueStr, "java/lang/Object");
    JavaCallMethod(hJTable, "put");

    // retrieve an Object from the Hashtable
    // Object jRetVal = jTable.get(jKeyStr);
    JavaSetObject(hJTable, hJKeyStr);
    JavaCallMethod(hJTable, "get");
    hJRetVal := JavaGetObject(hJTable);

    // retrieve print out the java string object
    // System.out.println("Found value \""+jRetVal+"\" in Hashtable.");
    JavaCallMethod(hJRetVal, "toString");
    JavaGetString(hJRetVal, sBuffer);
    Print("Found value \""+sBuffer+"\" in Hashtable.");

    // Free all objects
    JavaFreeObject(hJTable);
    JavaFreeObject(hJKeyStr);
    JavaFreeObject(hJValueStr);
    JavaFreeObject(hJRetVal);
  end TPureBdl;

  transaction TEnd
  begin
  end TEnd;

Sample scripts

JavaFrameworkBankSample.bdf

BankSample.java, Account.java, Customer.java, PremiumCustomer.java

Parent topic: Java Framework Functions
Related reference
JavaCallMethod Function
JavaSetObject Function


JavaGetUserObject Function

Action

Returns the handle on the JavaUser object loaded by JavaUserInit command. This handle can be used to exploit the new Java Framework functionality with the existing JavaUserFramework script of prior Silk Performer versions.

Include file

Java.bdh

Syntax

JavaGetUserObject( ): number;

Return value

Handle on the JavaUser object.

Example

  transaction  TInit
  begin
    JavaCreateJavaVM();
    JavaUserInit("SilkPerformerUser");
  end TInit;

  transaction TMyJavaTrans
  var
    hObj : number;
  begin
    ThinkTime(0.2);
    JavaCallMethod(JavaGetUserObject(), "myComplexMethod");
    hObj := JavaGetObject(JavaGetUserObject());
  end TMyJavaTrans;
Parent topic: Java Framework Functions
Related reference
JavaCallMethod Function


JavaSetBoolean Function

Action

Sets a boolean parameter for the next function or constructor call.

Note: Parameters must exactly match the method signature and have to be in order.

Include file

Java.bdh

Syntax

JavaSetBoolean( in hObject : number,
                in bParam  : boolean );
Parameter | Description
hObject | Valid handle to a java object or JAVA_STATIC_METHOD.
bParam | The boolean value to be set as parameter.

Example

var
  hTestObj   : number;

dcltrans
  transaction TInit
  begin
      // Load and start the JVM.
      JavaCreateJavaVM();
      // instantiate the java class
      hTestObj := JavaLoadObject("Test");
  end TInit;

  transaction TMyJavaTrans
  var
    fValue : float;
  begin
    ThinkTime(0.2);
    // set the first parameter
    JavaSetString(hTestObj, "1");
    // set the second parameter
    JavaSetBoolean(hTestObj, true);
    // invoke the method
    JavaCallMethod(hTestObj, "doFoo");
    // retrieve the result
    fValue := JavaGetFloat(hTestObj);
    Print("doFoo returned "+String(fValue));
  end TMyJavaTrans;

  transaction TEnd
  begin
    JavaFreeObject(hTestObj);
  end TEnd;

Sample scripts

JavaFrameworkBankSample.bdf

BankSample.java, Account.java, Customer.java, PremiumCustomer.java

Parent topic: Java Framework Functions
Related reference
JavaCallMethod Function
JavaGetBoolean Function


JavaSetChar Function

Action

Sets a char parameter for the next function or constructor call.

Note: Parameters must exactly match the method signature and be in order.

Include file

Java.bdh

Syntax

JavaSetChar( in hObject : number,
             in nParam  : number );
Parameter | Description
hObject | Valid handle to a java object or JAVA_STATIC_METHOD.
nParam | The ordinal number of the char value to be set as parameter.

Example

var
  hTestObj : number;

dcltrans
  transaction TInit
  begin
    // Load and start the JVM.
    JavaCreateJavaVM();
    // instantiate the java class: java.lang.Character
    JavaSetChar(JAVA_STATIC_METHOD, ord('c'));
    hTestObj := JavaLoadObject("java/lang/Character");
  end TInit;

  transaction TMyJavaTrans
  var
    charNum : number;
  begin
    // calling charValue() method of java.lang.Character object
    JavaCallMethod(hTestObj, "charValue");
    charNum := JavaGetChar(hTestObj);
  end TMyJavaTrans;

  transaction TEnd
  begin
    JavaFreeObject(hTestObj);
  end TEnd;
Parent topic: Java Framework Functions
Related reference
JavaCallMethod Function
JavaGetChar Function


JavaSetFloat Function

Action

Sets a float parameter for the next function or constructor call.

Note: Parameters must exactly match the method signature and be in order. Use the third optional parameter to distinguish between the different float data types of the Java language.

Include file

Java.bdh

Syntax

JavaSetFloat( in hObject: number,
              in fParam : float,
              in sType  : string optional );
Parameter | Description
hObject | Valid handle to a java object or JAVA_STATIC_METHOD.
fParam | The float value to be set as parameter.
sType

(optional)

Can be:

  • JAVA_FLOAT (default)

  • JAVA_DOUBLE

Example

var
  hTestObj   : number;

dcltrans
  transaction TInit
  begin
    // Load and start the JVM.
    JavaCreateJavaVM();

    // instantiate the java class
    hTestObj := JavaLoadObject("Test");
  end TInit;

  transaction TMyJavaTrans
  var
    fValue : float;
  begin
    ThinkTime(0.2);
    // set the first parameter
    JavaSetString(hTestObj, "1");
    // set the second parameter
    JavaSetFloat(hTestObj, 1.1, JAVA_FLOAT);
    // invoke the method
    JavaCallMethod(hTestObj, "doFoo");
    // retrieve the result
    fValue := JavaGetFloat(hTestObj);
    Print("doFoo returned "+String(fValue));
  end TMyJavaTrans;

  transaction TEnd
  begin
    JavaFreeObject(hTestObj);
  end TEnd;

Sample scripts

JavaFrameworkBankSample.bdf

BankSample.java, Account.java, Customer.java, PremiumCustomer.java

Parent topic: Java Framework Functions
Related reference
JavaCallMethod Function
JavaGetFloat Function


JavaSetLogOption Function

Action

Sets logging options for the Java Framework. It can be used, for example, to completely suppress all logging. This is useful when a complete API is based on the Java framework (for example, Silk Performer's Jacada support.

Include file

Java.bdh

Syntax

JavaSetLogOption( in nOption : number ): boolean;

Return value

  • true if successful

  • false otherwise

Parameter Description
nOption

Determines the logging option to be set. This parameter is one of the following flags:

  • JAVA_LOG_OPTION_DEFAULT. Logging is performed as configured via GUI or SetLogOption (default).

  • JAVA_LOG_OPTION_LOGFILE_ONLY. Suppresses any Java Framework output on the virtual user's output pane. However, log file writing is done as usual (if configured).

  • JAVA_LOG_OPTION_SILENT. Any Java Framework related logging is suppressed.

Example

dcltrans
  transaction TInit
  begin
    JavaSetLogOption(JAVA_LOG_OPTION_SILENT);
    JavaCreateJavaVM();
  end TInit;

Output

No output is generated.

Parent topic: Java Framework Functions
Related reference
JavaCallMethod Function
JavaGetLastException Function


JavaSetNumber Function

Action

Sets a numeric parameter for the next function or constructor call.

Note: Parameters must exactly match the method signature and be in order. Use the third optional parameter to distinguish between the different numeric data types of the Java language.

Include file

Java.bdh

Syntax

JavaSetNumber( in hObject : number,
               in nParam  : number,
               in sType   : string optional );
Parameter | Description
hObject | Valid handle to a java object or JAVA_STATIC_METHOD.
nParam | The number to be set as parameter.
sType

(optional)

Can be:

  • JAVA_BYTE

  • JAVA_SHORT

  • JAVA_INT (default)

  • JAVA_LONG

Example

var
  hTestObj   : number;

dcltrans
  transaction TInit
  begin
    // Load and start the JVM.
    JavaCreateJavaVM();
    // instantiate the java class
    hTestObj := JavaLoadObject("Test");
  end TInit;

  transaction TMyJavaTrans
  var
    fValue : float;
  begin
    ThinkTime(0.2);
    // set the first parameter
    JavaSetString(hTestObj, "1");
    // set the second parameter
    JavaSetNumber(hTestObj, 1, JAVA_BYTE);
    // invoke the method
    JavaCallMethod(hTestObj, "doFoo");
    // retrieve the result
    fValue := JavaGetFloat(hTestObj);
    Print("doFoo returned "+String(fValue));
  end TMyJavaTrans;

  transaction TEnd
  begin
    JavaFreeObject(hTestObj);
  end TEnd;

Sample scripts

JavaFrameworkBankSample.bdf

BankSample.java, Account.java, Customer.java, PremiumCustomer.java

Parent topic: Java Framework Functions
Related reference
JavaCallMethod Function
JavaGetNumber Function


JavaSetObject Function

Action

Sets an object parameter for the next function or constructor call.

Note: Parameters must exactly match the method signature and they must be in order. Use the third optional parameter to specify the formal data type of the parameter.

Include file

Java.bdh

Syntax

JavaSetObject( in hObject : number,
               in hParam  : number,
               in sType   : string optional );
Parameter | Description
hObject | Valid handle to a java object or JAVA_STATIC_METHOD.
hParam | The object handle to be set as parameter.
sType | (Optional) The object will be treated as being of the type specified here for next method or constructor call. Syntax for the class signature must be package/subpackage/classname. Example: java/lang/String

Example

dcltrans
  transaction TInit
  begin
    // Load and start the JVM.
    JavaCreateJavaVM();

  end TInit;

  transaction TPureBdl
  var hJTable    : number;
      hJKeyStr   : number;
      hJValueStr : number;
      hJRetVal   : number;
      sBuffer    : string;
  begin
    // prepare the key/value pair
    // String jKeyStr = "hello";
    // String jValueStr = "world";
    hJKeyStr := JavaLoadString("hello");
    hJValueStr := JavaLoadString("world");

    // instantiate a Hashtable
    // Hashtable jTable = new Hashtable();
    hJTable := JavaLoadObject("java/util/Hashtable");

    // insert an Object into the Hashtable
    // jTable.put(jKeyStr, jValueStr);
    JavaCastObject(hJKeyStr, "java/lang/Object");
    JavaSetObject(hJTable, hJKeyStr);
    JavaSetObject(hJTable, hJValueStr, "java/lang/Object");
    JavaCallMethod(hJTable, "put");

    // retrieve an Object from the Hashtable
    // Object jRetVal = jTable.get(jKeyStr);
    JavaSetObject(hJTable, hJKeyStr);
    JavaCallMethod(hJTable, "get");
    hJRetVal := JavaGetObject(hJTable);

    // retrieve print out the java string object
    // System.out.println("Found value \""+jRetVal+"\" in Hashtable.");
    JavaCallMethod(hJRetVal, "toString");
    JavaGetString(hJRetVal, sBuffer);
    Print("Found value \""+sBuffer+"\" in Hashtable.");

    // Free all objects
    JavaFreeObject(hJTable);
    JavaFreeObject(hJKeyStr);
    JavaFreeObject(hJValueStr);
    JavaFreeObject(hJRetVal);
  end TPureBdl;

  transaction TEnd
  begin
  end TEnd;

Sample scripts

JavaFrameworkBankSample.bdf

BankSample.java, Account.java, Customer.java, PremiumCustomer.java

Parent topic: Java Framework Functions
Related reference
JavaCallMethod Function
JavaGetObject Function
JavaGetString Function


JavaSetString function

Action

Sets a string parameter for the next function or constructor call.

Note: Parameters must exactly match the method signature and have to be in order.

Include file

Java.bdh

Syntax

JavaSetString( in hObject : number,
               in sParam  : string allownull,
               in nLen    : number optional,
               in eType   : string optional );
Parameter | Description
hObject | Valid handle to a java object or JAVA_STATIC_METHOD.
sParam | The string to be set as parameter.
nLen | The length of the string parameter (optional). Should be used if the string contains null bytes.
eType

(optional)

Can be:

  • JAVA_STRING (default)

  • JAVA_BYTE_ARRAY

  • JAVA_CHAR_ARRAY

Example

var
  hTestObj   : number;

dcltrans
  transaction TInit
  begin
    // Load and start the JVM.
    JavaCreateJavaVM();

    // instantiate the java class
    hTestObj := JavaLoadObject("Test");
  end TInit;

  transaction TMyJavaTrans
  var
    fValue : float;
  begin
    ThinkTime(0.2);
    // set the first parameter
    JavaSetString(hTestObj, "1");
    // set the second parameter
    JavaSetNumber(hTestObj, 1, JAVA_BYTE);
     // invoke the method
    JavaCallMethod(hTestObj, "doFoo");
    // retrieve the result
    fValue := JavaGetFloat(hTestObj);
    Print("doFoo returned "+String(fValue));
  end TMyJavaTrans;

  transaction TEnd
  begin
    JavaFreeObject(hTestObj);
  end TEnd;

Sample scripts

JavaFrameworkBankSample.bdf

BankSample.java, Account.java, Customer.java, PremiumCustomer.java

Parent topic: Java Framework Functions
Related reference
JavaCallMethod Function


JavaSetByteArray Function

Action

Convenience function derived from JavaSetString function. Sets a byte array parameter for the next function or constructor call.

Note: Parameters must exactly match the method signature and be in order.

Include file

Java.bdh

Syntax

JavaSetByteArray( in hObject : number,
                  in sParam  : string allownull,
                  in nLen    : number optional );
Parameter | Description
hObject | Valid handle to a java object or JAVA_STATIC_METHOD.
sParam | The string to be set as parameter.
nLen | The length of the string parameter (optional). Should be used if the string contains null bytes.

Example

var
  hTestObj   : number;

dcltrans
  transaction TInit
  begin
    // Load and start the JVM.
    JavaCreateJavaVM();

    // instantiate the java class
    hTestObj := JavaLoadObject("Test");
  end TInit;

  transaction TMyJavaTrans
    var
    str : string init "abc hello world äöü";
  begin
     // calling Java method doFoo(char[] chars)
    JavaSetByteArray(hTestObj, str, 19);

    JavaCallMethod(hTestObj, "doFoo");
    // calling Java method doFoo(char[] chars)
    JavaSetString(hTestObj, str, 19, JAVA_BYTE_ARRAY);
    JavaCallMethod(hTestObj, "doFoo");
  end TMyJavaTrans;

  transaction TEnd
  begin
    JavaFreeObject(hTestObj);
  end TEnd;
Parent topic: Java Framework Functions
Related reference
JavaCallMethod Function
JavaGetByteArray Function


JavaSetCharArray Function

Action

Convenience function derived from JavaSetString function. Sets a character array parameter for the next function or constructor call.

Note: Parameters must exactly match the method signature and be in order.

Include file

Java.bdh

Syntax

JavaSetCharArray( in hObject : number,
                  in sParam  : string allownull,
                  in nLen    : number optional );
Parameter | Description
hObject | Valid handle to a java object or JAVA_STATIC_METHOD.
sParam | The string to be set as parameter.
nLen | The length of the string parameter (optional). Should be used if the string contains null bytes.

Example

var  hTestObj   : number;

dcltrans
  transaction TInit
  begin
    // Load and start the JVM.
    JavaCreateJavaVM();

    // instantiate the java class
    hTestObj := JavaLoadObject("Test");
  end TInit;

  transaction TMyJavaTrans
  var
    str : string init "abc hello world äöü";
  begin
    // calling Java method doFoo(char[] chars)
    JavaSetCharArray(hTestObj, str, strlen(str));
    JavaCallMethod(hTestObj, "doFoo");
    // calling Java method doFoo(char[] chars)
    JavaSetString(hTestObj, str, 0, JAVA_CHAR_ARRAY);
    JavaCallMethod(hTestObj, "doFoo");
  end TMyJavaTrans;

   transaction TEnd
   begin
    JavaFreeObject(hTestObj);
  end TEnd;
Parent topic: Java Framework Functions
Related reference
JavaCallMethod Function


JavaUserInit Function

Action

Calls the JavaUserInit method of the Java class that implements the behavior of the virtual user. This function must be called in the initialization transaction of your test script.

Include file

Java.bdh

Syntax

JavaUserInit( in sClassName: string ): boolean;

Return value

  • true if successful

  • false otherwise

Parameter | Description
sClassName | The name of the Java class that implements the behavior of the virtual user.

Example

dcltrans
  transaction TInit
  begin
    JavaSetOption(JAVA_VERSION, JAVA_V11);
    JavaSetOption(JAVA_HOME, "c:/jdk1.1.7");
    JavaSetOption(JAVA_CLASSPATH, "c:/myApplication/classes;c:/myTools/tools.zip");
    JavaCreateJavaVM();
    JavaUserInit("SilkPerformerUser");
  end TInit;

  transaction TRun
  begin
    JavaUserRun();
  end TRun;

  transaction TMyTransaction
  begin
    JavaUserMethod("MyMethod");
  end TMyTransaction;

  transaction TShutdown
  begin
    JavaUserShutdown();
  end TShutdown;
Parent topic: Java Framework Functions
Related reference
JavaUserMethod Function
JavaUserRun Function
JavaUserShutdown Function


JavaUserRun Function

Action

Calls the JavaUserRun method of the Java class that implements the behavior of the virtual user. This function must be called in the main transaction of your test script.

Include file

Java.bdh

Syntax

JavaUserRun(): boolean;

Return value

  • true if successful

  • false otherwise

Example

dcltrans
  transaction TInit
  begin
    JavaSetOption(JAVA_VERSION, JAVA_V11);
    JavaSetOption(JAVA_HOME, "c:/jdk1.1.7");
    JavaSetOption(JAVA_CLASSPATH, "c:/myApplication/classes;c:/myTools/tools.zip");
    JavaCreateJavaVM();
    JavaUserInit("SilkPerformerUser");
  end TInit;

  transaction TRun
  begin
    JavaUserRun();
  end TRun;

  transaction TMyTransaction
  begin
    JavaUserMethod("MyMethod");
  end TMyTransaction;

  transaction TShutdown
  begin
    JavaUserShutdown();
  end TShutdown;
Parent topic: Java Framework Functions
Related reference
JavaUserInit Function
JavaUserMethod Function
JavaUserShutdown Function


JavaUserMethod Function

Action

Calls an additional method of the Java class that implements the behavior of the virtual user. This function may be called in any additional transaction of your test script.

Include file

Java.bdh

Syntax

JavaUserMethod( in sName : string ): boolean;

Return value

  • true if successful

  • false otherwise

Parameter | Description
sName | Name of the method that is to be called.

Example

dcltrans
  transaction TInit
  begin
    JavaSetOption(JAVA_VERSION, JAVA_V11);
    JavaSetOption(JAVA_HOME, "c:/jdk1.1.7");
    JavaSetOption(JAVA_CLASSPATH, "c:/myApplication/classes;c:/myTools/tools.zip");
    JavaCreateJavaVM();
    JavaUserInit("SilkPerformerUser");
  end TInit;

  transaction TRun
  begin
    JavaUserRun();
  end TRun;

  transaction TMyTransaction
  begin
    JavaUserMethod("MyMethod");
  end TMyTransaction;

  transaction TShutdown
  begin
    JavaUserShutdown();
  end TShutdown;
Parent topic: Java Framework Functions
Related reference
JavaUserInit Function
JavaUserRun Function
JavaUserShutdown Function


JavaUserShutdown Function

Action

Calls the JavaUserShutdown method of the Java class that implements the behavior of the virtual user. This function must be called in the shutdown transaction of your test script.

Include file

Java.bdh

Syntax

JavaUserShutdown(): boolean;

Return value

  • true if successful

  • false otherwise

Example

dcltrans
  transaction TInit
  begin
    JavaSetOption(JAVA_VERSION, JAVA_V11);
    JavaSetOption(JAVA_HOME, "c:/jdk1.1.7");
    JavaSetOption(JAVA_CLASSPATH, "c:/myApplication/classes;c:/myTools/tools.zip");
    JavaCreateJavaVM();
    JavaUserInit("SilkPerformerUser");
  end TInit;

  transaction TRun
  begin
    JavaUserRun();
  end TRun;

  transaction TMyTransaction
  begin
    JavaUserMethod("MyMethod");
  end TMyTransaction;

  transaction TShutdown
  begin
    JavaUserShutdown();
  end TShutdown;
Parent topic: Java Framework Functions
Related reference
JavaUserInit Function
JavaUserMethod Function
JavaUserRun Function


JavaRegisterException Function

Action

Registers a Java exception string under a custom error number. This error number can later be used to specify a custom severity for the exception. See also ErrorAdd function.

Note It is possible to register several exception messages to one error number.

Include file

Java.bdh

Syntax

JavaRegisterException( in nErrNumber    : number,
                       in sExceptionMsg : string,
                       in nFlag         : number optional ): boolean;

Return value

  • true if exception message could be registered und the specified error number

  • false otherwise

Parameter | Description
nErrNumber | Error number of exception to register.
sExceptionMsg | Exception message to register.
nFlag

By passing one of the following parameters to the function, it is possible to determine when an exception raises an error:

  • JAVA_OPTION_MATCH_EXACT: The text of the raised exception must be equal to sExceptionMsg.

  • JAVA_OPTION_MATCH_SUBSTRING: The text of the raised exception must contain sExceptionMsg.

If no parameter is specified then the function is using JAVA_OPTION_MATCH_EXACT per default.

Example

var
  hTestObj    : number;

dcltrans
  transaction TInit
  begin
    JavaCreateJavaVM();
    hTestObj := JavaLoadObject("TestClass");
  end TInit;

  transaction TException
  var
    sBuffer : string;
    bRetVal : boolean;
  begin
    JavaRegisterException(500, "java.lang.RuntimeException");
    ErrorAdd(FACILITY_NATIVE_JAVA, 500, SEVERITY_INFORMATIONAL);
    bRetVal := JavaCallMethod(hTestObj, "doException");
    JavaGetLastException(hTestObj, sBuffer);

    if not bRetVal then
      Print(sBuffer);
    end;
  end TException;
Parent topic: Java Framework Functions
Related reference
ErrorAdd Function
JavaUnregisterErrorNumber Function
JavaUnregisterException Function


JavaUnregisterException Function

Action

Unregisters an exception message.

Include file

Java.bdh

Syntax

JavaUnregisterException( in sExceptionMsg : string ): boolean;

Return value

  • true if the exception message specified by sExceptionMsg could be unregistered

  • false if there was no exception registered under the specified sExceptionMsg

Parameter | Description
sExceptionMsg | Exception message to unregister.

Example

dcltrans
  transaction TInit
  begin
    JavaCreateJavaVM();
  end TInit;

  transaction TException
  begin
    JavaRegisterException(500, "java.lang.RuntimeException");
    JavaUnregisterException("java.lang.RuntimeException");
  end TException;
Parent topic: Java Framework Functions
Related reference
JavaUnregisterErrorNumber Function
JavaRegisterException Function


JavaUnregisterErrorNumber Function

Action

Unregisters exception messages.

Include file

Java.bdh

Syntax

JavaUnregisterErrorNumber( in nErrNumber : number ): boolean;

Return value

  • true if the exception messages of the specified error number could be unregistered

  • false if there was no exception registered under the specified error number

Parameter | Description
nErrNumber | Error number of exception to unregister.

Example

dcltrans
transaction TInit
  begin
    JavaCreateJavaVM();
  end TInit;

  transaction TException
  begin
    JavaRegisterException(500, "java.lang.RuntimeException");
    JavaUnregisterErrorNumber(500);
  end TException;
Parent topic: Java Framework Functions
Related reference
JavaCallMethod Function
JavaRegisterException Function
JavaUnregisterException Function


JavaGetLastException Function

Action

Retrieves the last exception message.

Include file

Java.bdh

Syntax

JavaGetLastException( in  hHandle     : number,
                      out sBuffer     : string,
                      in  nBufferSize : number optional ): boolean;

Return value

  • true if the method call was successful, false otherwise

  • false otherwise

Parameter | Description
hHandle | Can be a handle to a java object or JAVA_STATIC_METHOD.
sBuffer | Buffer to retrieve the last exception message.
nBufferSize | (optional) Maximum number of bytes to retrieve.

Example

var
  hTestObj    : number;

dcltrans
  transaction TInit
  begin
    JavaCreateJavaVM();
    hTestObj := JavaLoadObject("TestClass");
  end TInit;

  transaction TException
  var
    sBuffer : string;
    bRetVal : boolean;
  begin
    JavaRegisterException(500, "java.lang.RuntimeException");
    ErrorAdd(FACILITY_NATIVE_JAVA, 500, SEVERITY_INFORMATIONAL);
    bRetVal := JavaCallMethod(hTestObj, "doException");
    JavaGetLastException(hTestObj, sBuffer);

    if not bRetVal then
      Print(sBuffer);
    end;
  end TException;
Parent topic: Java Framework Functions
Related reference
JavaCallMethod Function
JavaSetLogOption Function


JUnitCallMethod Function

Action

Invokes a JUnit conform method of a class derived from junit.framework.TestCase. Prepares the method execution by invoking the setUp() method and finishes the test by invoking the tearDown() method.

Include file

Java.bdh

Syntax

JUnitCallMethod(
  in hObject    : number,
  in sName      : string,
  in sTimerName : string optional): boolean;

Return value

  • true if the method call succeeded

  • false otherwise

Parameter | Description
hObject | Valid handle to a java object derived from junit.framework.TestCase.
sName | Name of the method to invoke. JUnit comform methods always start with “test” prefix and do not have a return value.
sTimerName | Optional. Creates a custom time measure with the specified name for this function.

Example

var
  ghTestObj : number;

dcltrans
  transaction TInit
  var
    hPerf : number;
  begin
    JavaCreateJavaVM();
    JavaSetString(JAVA_STATIC_METHOD, "myString");
    ghTestObj := JavaLoadObject("JUTestClass");
  end TInit;

  transaction TMain
  begin
    JUnitCallMethod(ghTestObj, "testTestCase");
  end TMain;

  transaction TEnd
  begin
    JavaFreeObject(ghTestObj);
  end TEnd;
Parent topic: Java Framework Functions


JUnitExecuteTest Function

Action

Starts a JUnit test execution.

Include file

Java.bdh

Syntax

JUnitExecuteTest( in hTestClass  : number;
                  in sMethodName : string;
                  in sTimerName  : string optional ): number;

Return value

  • true if successful
  • false otherwise
Parameter | Description
hTestClass | The handle of the runtime class.
sMethodName | The name of the test you want to execute. If omitted, the whole class is executed.
sTimerName | The name of the timer for the JUnitExecuteTest function.

Example

var
  hTestClass : number;

dcltrans
  transaction TInit
  begin
      // Load and start the JVM.
      JavaCreateJavaVM();

      // instantiate the java class
      hTestClass := JUnitLoadClass("com/microfocus/Test");
  end TInit;

  transaction THello
  begin
    JUnitExecuteTest(hTestClass, "doHello", "doHello_timer");
    JUnitExecuteTest(hTestClass, "", "Test_timer");
  end THello;

  transaction TEnd
  begin
    JavaFreeObject(hTestClass);
  end TEnd;
Parent topic: Java Framework Functions


JUnitLoadClass Function

Action

Instantiates a Java object and returns a handle of the runtime class. The Java runtime class can be released by using the JavaFreeObject function.

Include file

Java.bdh

Syntax

JUnitLoadClass( in sClassSpecifier : string ): number;

Return value

  • Handle of the Java object class.
Parameter | Description
sClassSpecifier | Fully qualified name of the class to instantiate. The class must be available through the classpath. Use the / character as package separator. For example: java/lang/String

Example

var
  hTestClass : number;

dcltrans
  transaction TInit
  begin
      // Load and start the JVM.
      JavaCreateJavaVM();

      // instantiate the java class
      hTestClass := JUnitLoadClass("com/microfocus/Test");
  end TInit;

  transaction THello
  begin
    JUnitExecuteTest(hTestClass, "doHello", "doHello_timer");
  end THello;

  transaction TEnd
  begin
    JavaFreeObject(hTestClass);
  end TEnd;
Parent topic: Java Framework Functions


Deprecated Java Framework Functions

The following functions from the previous version of the Java Framework have been deprecated, however they are still supported.

  • JavaUserInit: Calls the JavaUserInit method of the Java class that implements the behavior of the virtual user.

  • JavaUserRun: Calls the JavaUserRun method of the Java class that implements the behavior of the virtual user.

  • JavaUserMethod: Calls an additional method of the Java class that implements the behavior of the virtual user.

  • JavaUserShutdown: Calls the JavaUserShutdown method of the Java class that implements the behavior of the virtual user.

Parent topic: Java Framework Functions


JMS Functions Reference

Silk Performer provides JMS API functions to write and run scripts for testing JMS applications and providers.

You can create a normal JMS project and a JMS project with a comprehensive example:
  • To create a normal JMS project: Click File in the menu, click New Project, select Java > Java Message Service (JMS) . This project includes a short example script.
  • To create a JMS project with a comprehensive example: Click File in the menu, click New Project, select Samples > JMS. This project includes a comprehensive example script. The examples are connected to demo.borland.com (ActiveMQ server) and require a .jar file, which is included in the project. However, for other servers the client requires a different .jar file.
Note the following when working with JMS functions:
  • The first call in the TInit must be the function JavaCreateJavaVM to set a JVM.
  • TInit must include only the function JmsStartUp or both the functions JmsSetJndiEnvironment and JmsInit. If you want to specify only the JNDI Naming Factory Initial, you can use JmsStartUp. Otherwise, set the JNDI parameters with JmsSetJndiEnvironment and init JMS with JmsInit.
  • TEnd must include the function JmsShutDown to shut down the connection to the messaging service.
  • (Optional) Clear the queue to make sure there are no messages left.
  • (Optional) Clear the message before you use it or reuse it.
  • (Optional) Use the constants that are defined in the Jms.bdh file for the message types and message header properties.
  • Initializing/Creating/Destroying Functions
  • Miscellaneous JMS Functions
Parent topic: Benchmark Description Language (BDL) Reference


Initializing/Creating/Destroying Functions

The JmsStartUp function is equivalent to the functions JmsSetJndiEnvironment and JmsInit. However, in JmsStartUp you can specify only one Jndi environment property, the property sJndiNamingFactoryInitial.

The following functions are mandatory and must be used in TInit: JmsInit, JmsSetJndiEnvironment, JmsStartUp.
Note: You must either use both the functions JmsInit and JmsSetJndiEnvironment or only the function JmsStartUp. You do not need all three functions.

The following function is mandatory and must be used in TEnd: JmsShutDown.

  • JmsInit Function
    Creates a JNDI context, looks up the connection factory, creates a connection and a session, and starts the session. Use this function in the TInit.
  • JmsSetJndiEnvironment Function
    Manually sets the JNDI environment. Another option is to set a jndi.property file in the classpath. Use this function in the TInit.
  • JmsStartUp Function
    Starts JMS. Use this function in the TInit.
  • JmsShutDown Function
    Closes the connection. Use this function in the TEnd.
Parent topic: JMS Functions Reference


JmsInit Function

Action

Creates a JNDI context, looks up the connection factory, creates a connection and a session, and starts the session.

Include file

Jms.bdh

Syntax

JmsInit( in sJndiConnectionFactoryName : string );
Parameter | Description
sJndiConnectionFactoryName | The name of the JNDI connection factory

Example

JmsInit("ConnectionFactory");

Sample scripts

JmsSample.bdf, JmsSample.java

Parent topic: Initializing/Creating/Destroying Functions


JmsSetJndiEnvironment Function

Action

Manually sets the JNDI environment. Another option is to set a jndi.property file in the classpath. (mandatory).

Include file

Jms.bdh

Syntax

JmsSetJndiEnvironment( in sKey   : string,
                       in SValue : string);
Parameter | Description
sKey | The key of the JNDI environment
sValue | The value of the JNDI environment

Example

transaction TInit
  var hPerf : number;
  begin
    JavaCreateJavaVM();

    hPerf := JavaLoadObject("silk/performer/SilkPerformer");
    JavaSetObject(JAVA_STATIC_METHOD, hPerf);
    ghJmsSampleObj := JavaLoadObject("JmsSample");
    JavaFreeObject(hPerf);

    JmsSetJndiEnvironment(JNDI_NAMING_FACTORY_INITIAL_KEY, "org.apache.activemq.jndi.ActiveMQInitialContextFactory");
    JmsSetJndiEnvironment("java.naming.provider.url", "tcp://demo.borland.com:61616");

    JmsSetJndiEnvironment("queue.TestQueue", csQueue);

    JmsInit("ConnectionFactory");
  end TInit;

Sample scripts

JmsSample.bdf, JmsSample.java

Parent topic: Initializing/Creating/Destroying Functions


JmsStartUp Function

Action

Starts JMS. Use this function in the TInit.

Include file

Jms.bdh

Syntax

JmsStartUp( in sJndiConnectinoFactoryName : string,
            in sJndiNamingFactoryInitial  : string optional);
Parameter | Description
sJndiConnectionFactoryName | The name of the JNDI Connection Factory
sJndiNamingFactoryInitial | (optional) The JNDI Naming Factory Initial Environment value

Example

transaction TInit
begin
  JavaCreateJavaVM();
  JmsStartUp("jms/ConnectionFactory", "com.sun.enterprise.naming.impl.SerialInitcontextFactory");
end TInit

Sample scripts

JmsSample.bdf, JmsSample.java

Parent topic: Initializing/Creating/Destroying Functions


JmsShutDown Function

Action

Closes the connection. Use this function in the TEnd.

Include file

Jms.bdh

Syntax

JmsShutDown();

Example

 transaction TEnd
  begin
    JmsShutDown();
    JavaFreeObject(ghJmsSampleObj);
  end TEnd;

Sample scripts

JmsSample.bdf, JmsSample.java

Parent topic: Initializing/Creating/Destroying Functions


Miscellaneous JMS Functions

  • JmsClearMessage Function
    Clears out the header, body, and properties of the current message.
  • JmsClearMessageProperties Function
    Sets the header and the message properties of the current message.
  • JmsEmptyQueue Function
    Empties the given queue of a message.
  • JmsGetConsumerMessageListener Function
    Gets the listener of the given destination.
  • JmsGetMessageHandle Function
    Gets the handle of the received message.
  • JmsGetMessageObject Function
    Gets the object from the last received message.
  • JmsGetReceivedMessageProperty Function
    Gets the header and message properties of the current message.
  • JmsGetMessageSelector Function
    Gets the message selector of the consumer.
  • JmsGetMessageText Function
    Gets the message text from the last received message.
  • JmsReceiveMessage Function
    Receives the first message from the given destination and returns the message type.
  • JmsSendObjectMessage Function
    Sends an object message to the given destination.
  • JmsSendTextMessage Function
    Sends a text message to the given destination.
  • JmsSetConsumerMessageListener Function
    Attaches a listener for the given destination.
  • JmsSetMessageHandle Function
    Sets the message to be sent.
  • JmsSetMessageProperty Function
    Sets the header and the message properties for the current message.
  • JmsSetMessageSelector Function
    Sets the message selector for the consumer.
  • JmsVerifyMessageText Function
    Checks if the received text is the expected text. If not, returns an error.
Parent topic: JMS Functions Reference


JmsClearMessage Function

Action

Clears the header, body, and properties of the current message.

Include file

Jms.bdh

Syntax

JmsClearMessage( in sMessageSelector : string );
Parameter | Description
sMessageSelector | Only messages with properties matching the message selector expression are delivered. A value of null or an empty string indicates that there is no message selector for the message consumer.

Example

transaction TExampleSendReceiveObjectMessage
  var hObject : number;
      hObjectReturned : number;
      sReturnType : number;
  begin
    JavaCallMethod(ghJmsSampleObj, "generateObject");
    hObject := JavaGetObject(ghJmsSampleObj);

    JmsClearMessage();

    JmsSendObjectMessage(hObject, csQueue);
    sReturnType := JmsReceiveMessage(csQueue, -1);

    if (sReturnType = JMS_MSG_TYPE_OBJECT) then
      hObjectReturned := JmsGetMessageObject();
      JavaCastObject(hObjectReturned, "java/lang/Object");
      JavaSetObject(ghJmsSampleObj, hObjectReturned);
      JavaCallMethod(ghJmsSampleObj, "handleObject");
    else
      RepMessage("ObjectMessage expected!", SEVERITY_ERROR);
    end;
  end TExampleSendReceiveObjectMessage;

Sample scripts

JmsSample.bdf, JmsSample.java

Parent topic: Miscellaneous JMS Functions


JmsClearMessageProperties Function

Action

This function clears the message properties.

Include file

Jms.bdh

Syntax

JmsClearMessageProperties;

Example

JmsClearMessageProperties();

Sample scripts

JmsSample.bdf, JmsSample.java

Parent topic: Miscellaneous JMS Functions


JmsEmptyQueue Function

Action

Empties the given queue of a message.

Include file

Jms.bdh

Syntax

JmsEmptyQueue( in sJndiDestinationName : string );
Parameter | Description
sJndiDestinationName | The Jndi destination name

Return value

Returns the given header or message property of the current message.

Example

transaction TExampleEmptyQueue
  begin
      JmsEmptyQueue(csQueue);
end TExampleEmptyQueue;

Sample scripts

JmsSample.bdf, JmsSample.java

Parent topic: Miscellaneous JMS Functions


JmsGetConsumerMessageListener Function

Action

Gets the listener of the given destination.

Include file

Jms.bdh

Syntax

JmsGetConsumerMessageListener( in sJndiDestinationName : string ): number;
Parameter | Description
sJndiDestinationName | The destination for which we want to attach the listener

Return value

Returns the handle of the given destination's listener.

Example

  transaction TExampleGetMessageAsynchronously
  var hHandle : number;
  begin
    JavaCallMethod(ghJmsSampleObj, "getMessageListener");
    hHandle := JavaGetObject(ghJmsSampleObj);

    JmsSetConsumerMessageListener(csQueue, hHandle);
    JmsClearMessage();
    JmsSendTextMessage("Text message 1 for the message listener!", csQueue);
    JmsSendTextMessage("Text message 2 for the message listener!", csQueue);
    JmsSendTextMessage("Text message 3 for the message listener!", csQueue);
    if (JmsGetConsumerMessageListener(csQueue) = 0) then
      RepMessage("No message listener set for " + csQueue, SEVERITY_WARNING);
    else
      // We have to wait for the 3 messages to get to the listener
      Wait 5.0;
    end;
  end TExampleGetMessageAsynchronously;

Sample scripts

JmsSample.bdf, JmsSample.java

Parent topic: Miscellaneous JMS Functions


JmsGetMessageHandle Function

Action

Gets the handle of the received message.

Include file

Jms.bdh

Syntax

JmsGetMessageHandle(): number;

Return value

Returns the handle of the received message.

Example

  transaction TExampleHandleUnknownMessage
  var ret : number;
      sMessage : string;
      hObj : number;
      hHandle:number;
  begin
    JmsSendTextMessage("Text message!", csQueue, "ExampleHandleUnknownMessage_Send");
    ret := JmsReceiveMessage(csQueue, -1, "ExampleHandleUnknownMessage_Receive");
    if ret = JMS_MSG_TYPE_TEXT then
       sMessage := JmsGetMessageText();
    elseif ret = JMS_MSG_TYPE_OBJECT then
       hObj := JmsGetMessageObject();
    elseif ret = JMS_TIMEOUT then
      RepMessage("Timeout", SEVERITY_INFORMATIONAL);
    elseif ret = JMS_UNKNOWN then
      RepMessage("Unknown return value!", SEVERITY_ERROR);
    else
      hHandle := JmsGetMessageHandle();
    end;
  end TExampleHandleUnknownMessage;

Sample scripts

JmsSample.bdf, JmsSample.java

Parent topic: Miscellaneous JMS Functions


JmsGetMessageObject Function

Action

Gets the object from the last received message.

Include file

Jms.bdh

Syntax

JmsGetMessageObject(): string;

Return value

Returns the handle of the object sent with the message.

Example

  transaction TExampleSendReceiveObjectMessage
  var hObject : number;
      hObjectReturned : number;
      sReturnType : number;
  begin
    JavaCallMethod(ghJmsSampleObj, "generateObject");
    hObject := JavaGetObject(ghJmsSampleObj);

    JmsClearMessage();

    JmsSendObjectMessage(hObject, csQueue);
    sReturnType := JmsReceiveMessage(csQueue, -1);

    if (sReturnType = JMS_MSG_TYPE_OBJECT) then
      hObjectReturned := JmsGetMessageObject();
      JavaCastObject(hObjectReturned, "java/lang/Object");
      JavaSetObject(ghJmsSampleObj, hObjectReturned);
      JavaCallMethod(ghJmsSampleObj, "handleObject");
    else
      RepMessage("ObjectMessage expected!", SEVERITY_ERROR);
    end;
  end TExampleSendReceiveObjectMessage;

Sample scripts

JmsSample.bdf, JmsSample.java

Parent topic: Miscellaneous JMS Functions


JmsGetReceivedMessageProperty Function

Action

Gets the header and message properties of the current message.

Include file

Jms.bdh

Syntax

JmsGetReceivedMessageProperty( sKey  : string,
                       iType : number optional ): string;
Parameter | Description
sKey The name of the property. Can be a string or one of the following values:
  • JMS_MSG_HDR_CORRELATIONID: JMSCorrelationID
  • JMS_MSG_HDR_DELIVERYMODE: JMSDeliveryMode
  • JMS_MSG_HDR_EXPIRATION: JMSExpiration
  • JMS_MSG_HDR_MESSAGEID: JMSMessageID
  • JMS_MSG_HDR_PRIORITY: JMSPriority
  • JMS_MSG_HDR_REDELIVERED: JMSRedelivered
  • JMS_MSG_HDR_TIMESTAMP: JMSTimestamp
  • JMS_MSG_HDR_TYPE: JMSType
iType | (Optional) The property type. Default is string.

Return value

Returns the given header or message property of the current message.

Example

  transaction TExampleUsingSelector
  var sMessage : string;
      sMessageId : string;
      sMessageSelector : string;
      sReturnType : number;
      hHandle : number;
  begin
    JmsSetMessageSelector("MESSAGEID = '12345'", csQueue);

    JmsSetMessageProperty("MESSAGEID","12345");
    JmsSendTextMessage("Welcome1!", csQueue);
    JmsReceiveMessage(csQueue, 5000);
    sMessage := JmsGetMessageText();
    if (Strlen(sMessage) = 0) then
      RepMessage("ERR: Should have receive the message!", SEVERITY_ERROR);
    end;

    JmsClearMessage();
    JmsSendTextMessage("Welcome2!", csQueue);
    sReturnType := JmsReceiveMessage(csQueue, 5000);
    if sReturnType <> JMS_TIMEOUT then
      sMessage := JmsGetMessageText();
      sMessageId := JmsGetReceivedMessageProperty("MESSAGEID");
      sMessageSelector := JmsGetMessageSelector(csQueue);
      Print("Return type: " + string(sReturnType) + "; message text: " + sMessage + "; messageid: " + sMessageId + "; messageSelector: " + sMessageSelector);
      RepMessage("ERR: Should have not receive the message!", SEVERITY_ERROR);
    end;

    JmsSetMessageProperty("MESSAGEID","12345");
    JmsSendTextMessage("Welcome3!", csQueue);
    JmsReceiveMessage(csQueue, -1);
    JmsVerifyMessageText("Welcome3!");
  end TExampleUsingSelector;

Sample scripts

JmsSample.bdf, JmsSample.java

Parent topic: Miscellaneous JMS Functions


JmsGetMessageSelector Function

Action

Gets the message selector of the consumer.

Include file

Jms.bdh

Syntax

JmsGetMessageSelector( in sJndiDestinationName : string ): string;
Parameter | Description
sJndiDestinationName | The Jndi destination name

Return value

Returns the message selector of the given destination's consumer.

Example

transaction TExampleUsingSelector
  var sMessage : string;
      sMessageId : string;
      sMessageSelector : string;
      sReturnType : number;
      hHandle : number;
  begin
    JmsSetMessageSelector("MESSAGEID = '12345'", csQueue);

    JmsSetMessageProperty("MESSAGEID","12345");
    JmsSendTextMessage("Welcome1!", csQueue);
    JmsReceiveMessage(csQueue, 5000);
    sMessage := JmsGetMessageText();
    if (Strlen(sMessage) = 0) then
      RepMessage("ERR: Should have receive the message!", SEVERITY_ERROR);
    end;

    JmsClearMessage();
    JmsSendTextMessage("Welcome2!", csQueue);
    sReturnType := JmsReceiveMessage(csQueue, 5000);
    if sReturnType <> JMS_TIMEOUT then
      sMessage := JmsGetMessageText();
      sMessageId := JmsGetMessageProperty("MESSAGEID");
      sMessageSelector := JmsGetMessageSelector(csQueue);
      Print("Return type: " + string(sReturnType) + "; message text: " + sMessage + "; messageid: " + sMessageId + "; messageSelector: " + sMessageSelector);
      RepMessage("ERR: Should have not receive the message!", SEVERITY_ERROR);
    end;

    JmsSetMessageProperty("MESSAGEID","12345");
    JmsSendTextMessage("Welcome3!", csQueue);
    JmsReceiveMessage(csQueue, -1);
    JmsVerifyMessageText("Welcome3!");
  end TExampleUsingSelector;

Sample scripts

JmsSample.bdf, JmsSample.java

Parent topic: Miscellaneous JMS Functions


JmsGetMessageText Function

Action

Gets the message text from the last received message.

Include file

Jms.bdh

Syntax

JmsGetMessageText(): string;

Return value

Returns the text sent with the message.

Example

transaction TExampleSendReceiveTextMessage
  var sRet : number;
      sMessage : string;
  begin
    JmsSendTextMessage("Welcome1!", csQueue);
    sRet := JmsReceiveMessage(csQueue, -1);
    if (sRet = JMS_MSG_TYPE_TEXT) then
      sMessage := JmsGetMessageText();
    else
      RepMessage("TextMessage expected!", SEVERITY_ERROR);
    end;
  end TExampleSendReceiveTextMessage;

Sample scripts

JmsSample.bdf, JmsSample.java

Parent topic: Miscellaneous JMS Functions


JmsReceiveMessage Function

Action

Receives the first message from the given destination and returns the message type.

Include file

Jms.bdh

Syntax

JmsReceiveMessage( sJndiDestinationName :  string,
                   lTimeout             :  number,
                   sMeasureName         :  string optional ): number;
Parameter | Description
sJndiDestinationName | The source of the message
ITimeout | The timeout value (in milliseconds). < 0 - wait forever, 0 - do not wait, > 0 - wait specified milliseconds
sMeasureName | (optional) The name of this measure. Default is the method name.

Return value

Returns the message type
  • JMS_MSG_TYPE_TEXT := 0;
  • JMS_MSG_TYPE_BYTES := 1;
  • JMS_MSG_TYPE_MAP := 2;
  • JMS_MSG_TYPE_OBJECT := 3;
  • JMS_MSG_TYPE_STREAM := 4;
  • JMS_TIMEOUT := 5;
  • JMS_UNKNOWN := 6;

Example

transaction TExampleSendReceiveTextMessage
  var sRet : number;
      sMessage : string;
  begin
    JmsSendTextMessage("Welcome1!", csQueue);
    sRet := JmsReceiveMessage(csQueue, -1);
    if (sRet = JMS_MSG_TYPE_TEXT) then
      sMessage := JmsGetMessageText();
    else
      RepMessage("TextMessage expected!", SEVERITY_ERROR);
    end;
  end TExampleSendReceiveTextMessage;

Sample scripts

JmsSample.bdf, JmsSample.java

Parent topic: Miscellaneous JMS Functions


JmsSendObjectMessage Function

Action

Sends an object message to the given destination.

Include file

Jms.bdh

Syntax

JmsSendObjectMessage( in objMessage           : number,
                      in sJndiDestinationName : string,
                      in sMeasureName         : string optional );
Parameter | Description
objMessage | The handler of the object to send
sJndiDestinationName | The destination to send this message to
sMeasureName | (optional) The name of this measure. Default is the method name.

Example

transaction TExampleSendReceiveObjectMessage
  var hObject : number;
      hObjectReturned : number;
      sReturnType : number;
  begin
    JavaCallMethod(ghJmsSampleObj, "generateObject");
    hObject := JavaGetObject(ghJmsSampleObj);

    JmsClearMessage();

    JmsSendObjectMessage(hObject, csQueue);
    sReturnType := JmsReceiveMessage(csQueue, -1);

    if (sReturnType = JMS_MSG_TYPE_OBJECT) then
      hObjectReturned := JmsGetMessageObject();
      JavaCastObject(hObjectReturned, "java/lang/Object");
      JavaSetObject(ghJmsSampleObj, hObjectReturned);
      JavaCallMethod(ghJmsSampleObj, "handleObject");
    else
      RepMessage("ObjectMessage expected!", SEVERITY_ERROR);
    end;
  end TExampleSendReceiveObjectMessage;

Sample scripts

JmsSample.bdf, JmsSample.java

Parent topic: Miscellaneous JMS Functions


JmsSendTextMessage Function

Action

Sends a text message to the given destination.

Include file

Jms.bdh

Syntax

JmsSendTextMessage( in sMessage             : string,
                    in sJndiDestinationName : string,
                    in sMeasure             : string optional );
Parameter | Description
sMessage | The text to send
sJndiDestinationName | The destination of the message
sMeasurename | (optional) The name of this measure. Default is the method name.

Example

transaction TExampleSendReceiveTextMessage
  var sRet : number;
      sMessage : string;
  begin
    JmsSendTextMessage("Welcome1!", csQueue);
    sRet := JmsReceiveMessage(csQueue, -1);
    if (sRet = JMS_MSG_TYPE_TEXT) then
      sMessage := JmsGetMessageText();
    else
      RepMessage("TextMessage expected!", SEVERITY_ERROR);
    end;
  end TExampleSendReceiveTextMessage;

Sample scripts

JmsSample.bdf, JmsSample.java

Parent topic: Miscellaneous JMS Functions


JmsSetConsumerMessageListener Function

Action

Attaches a listener for the given destination.

Include file

Jms.bdh

Syntax

JmsSetConsumerMessgaeListener( in sJndiDestinationName : string,
                                  hHandle              : number );
Parameter | Description
sJndiDestinationName | The destination for which you want to attach the listener
hHandle | The handle of the listener

Example

  transaction TExampleGetMessageAsynchronously
  var hHandle : number;
  begin
    JavaCallMethod(ghJmsSampleObj, "getMessageListener");
    hHandle := JavaGetObject(ghJmsSampleObj);

    JmsSetConsumerMessageListener(csQueue, hHandle);
    JmsClearMessage();
    JmsSendTextMessage("Text message 1 for the message listener!", csQueue);
    JmsSendTextMessage("Text message 2 for the message listener!", csQueue);
    JmsSendTextMessage("Text message 3 for the message listener!", csQueue);
    if (JmsGetConsumerMessageListener(csQueue) = 0) then
      RepMessage("No message listener set for " + csQueue, SEVERITY_WARNING);
    else
      // We have to wait for the 3 messages to get to the listener
      Wait 5.0;
    end;
  end TExampleGetMessageAsynchronously;

Sample scripts

JmsSample.bdf, JmsSample.java

Parent topic: Miscellaneous JMS Functions


JmsSetMessageHandle Function

Action

Sets the message to be sent.

Include file

Jms.bdh

Syntax

JmsSetMessageHandle( in hHandle : number );
Parameter | Description
hHandle | The handle of the message to be sent

Example

transaction TExampleGetSetHandleMessage
  var hHandle : number;
  begin
    hHandle := JmsGetMessageHandle();
    JmsSetMessageHandle(hHandle);
  end TExampleGetSetHandleMessage;

Sample scripts

JmsSample.bdf, JmsSample.java

Parent topic: Miscellaneous JMS Functions


JmsSetMessageProperty Function

Action

Sets the header and the properties for the current message.

Include file

Jms.bdh

Syntax

JmsSetMessageProperty( sKey   : string,
                       sValue : string,
                       iType  : number optional );
Parameter | Description
sKey The name of the property. Can be a string or one of the following values:
  • JMS_MSG_HDR_CORRELATIONID: JMSCorrelationID
  • JMS_MSG_HDR_DELIVERYMODE: JMSDeliveryMode
  • JMS_MSG_HDR_EXPIRATION: JMSExpiration
  • JMS_MSG_HDR_MESSAGEID: JMSMessageID
  • JMS_MSG_HDR_PRIORITY: JMSPriority
  • JMS_MSG_HDR_REDELIVERED: JMSRedelivered
  • JMS_MSG_HDR_TIMESTAMP: JMSTimestamp
  • JMS_MSG_HDR_TYPE: JMSType
sValue | The value of the property
iType | (Optional) The type of the property. Default is String

Example

transaction TExampleUsingSelector
  var sMessage : string;
      sMessageId : string;
      sMessageSelector : string;
      sReturnType : number;
      hHandle : number;
  begin
    JmsSetMessageSelector("MESSAGEID = '12345'", csQueue);

    JmsSetMessageProperty("MESSAGEID","12345");
    JmsSendTextMessage("Welcome1!", csQueue);
    JmsReceiveMessage(csQueue, 5000);
    sMessage := JmsGetMessageText();
    if (Strlen(sMessage) = 0) then
      RepMessage("ERR: Should have receive the message!", SEVERITY_ERROR);
    end;

    JmsClearMessage();
    JmsSendTextMessage("Welcome2!", csQueue);
    sReturnType := JmsReceiveMessage(csQueue, 5000);
    if sReturnType <> JMS_TIMEOUT then
      sMessage := JmsGetMessageText();
      sMessageId := JmsGetMessageProperty("MESSAGEID");
      sMessageSelector := JmsGetMessageSelector(csQueue);
      Print("Return type: " + string(sReturnType) + "; message text: " + sMessage + "; messageid: " + sMessageId + "; messageSelector: " + sMessageSelector);
      RepMessage("ERR: Should have not receive the message!", SEVERITY_ERROR);
    end;

    JmsSetMessageProperty("MESSAGEID","12345");
    JmsSendTextMessage("Welcome3!", csQueue);
    JmsReceiveMessage(csQueue, -1);
    JmsVerifyMessageText("Welcome3!");
  end TExampleUsingSelector;

Sample scripts

JmsSample.bdf, JmsSample.java

Parent topic: Miscellaneous JMS Functions


JmsSetMessageSelector Function

Action

Sets the message selector for the consumer.

Include file

Jms.bdh

Syntax

JmsSetMessageSelector( in sMessageSelector : string );
Parameter | Description
sMessageSelector | Only messages with properties matching the message selector expression are delivered. A value of null or an empty string indicates that there is no message selector for the message consumer.

Example

transaction TExampleUsingSelector
  var sMessage : string;
      sMessageId : string;
      sMessageSelector : string;
      sReturnType : number;
      hHandle : number;
  begin
    JmsSetMessageSelector("MESSAGEID = '12345'", csQueue);

    JmsSetMessageProperty("MESSAGEID","12345");
    JmsSendTextMessage("Welcome1!", csQueue);
    JmsReceiveMessage(csQueue, 5000);
    sMessage := JmsGetMessageText();
    if (Strlen(sMessage) = 0) then
      RepMessage("ERR: Should have receive the message!", SEVERITY_ERROR);
    end;

    JmsClearMessage();
    JmsSendTextMessage("Welcome2!", csQueue);
    sReturnType := JmsReceiveMessage(csQueue, 5000);
    if sReturnType <> JMS_TIMEOUT then
      sMessage := JmsGetMessageText();
      sMessageId := JmsGetMessageProperty("MESSAGEID");
      sMessageSelector := JmsGetMessageSelector(csQueue);
      Print("Return type: " + string(sReturnType) + "; message text: " + sMessage + "; messageid: " + sMessageId + "; messageSelector: " + sMessageSelector);
      RepMessage("ERR: Should have not receive the message!", SEVERITY_ERROR);
    end;

    JmsSetMessageProperty("MESSAGEID","12345");
    JmsSendTextMessage("Welcome3!", csQueue);
    JmsReceiveMessage(csQueue, -1);
    JmsVerifyMessageText("Welcome3!");
  end TExampleUsingSelector;

Sample scripts

JmsSample.bdf, JmsSample.java

Parent topic: Miscellaneous JMS Functions


JmsVerifyMessageText Function

Action

Checks if the received text is the expected text. If not, returns an error.

Include file

Jms.bdh

Syntax

JmsVerifyMessageText( in sExpectedMessage : string );
Parameter | Description
sExpectedMessage | The expected message

Example

  transaction TExampleUsingSelector
  var sMessage : string;
      sMessageId : string;
      sMessageSelector : string;
      sReturnType : number;
      hHandle : number;
  begin
    JmsSetMessageSelector("MESSAGEID = '12345'", csQueue);

    JmsSetMessageProperty("MESSAGEID","12345");
    JmsSendTextMessage("Welcome1!", csQueue);
    JmsReceiveMessage(csQueue, 5000);
    sMessage := JmsGetMessageText();
    if (Strlen(sMessage) = 0) then
      RepMessage("ERR: Should have receive the message!", SEVERITY_ERROR);
    end;

    JmsClearMessage();
    JmsSendTextMessage("Welcome2!", csQueue);
    sReturnType := JmsReceiveMessage(csQueue, 5000);
    if sReturnType <> JMS_TIMEOUT then
      sMessage := JmsGetMessageText();
      sMessageId := JmsGetMessageProperty("MESSAGEID");
      sMessageSelector := JmsGetMessageSelector(csQueue);
      Print("Return type: " + string(sReturnType) + "; message text: " + sMessage + "; messageid: " + sMessageId + "; messageSelector: " + sMessageSelector);
      RepMessage("ERR: Should have not receive the message!", SEVERITY_ERROR);
    end;

    JmsSetMessageProperty("MESSAGEID","12345");
    JmsSendTextMessage("Welcome3!", csQueue);
    JmsReceiveMessage(csQueue, -1);
    JmsVerifyMessageText("Welcome3!");
  end TExampleUsingSelector;

Sample scripts

JmsSample.bdf, JmsSample.java

Parent topic: Miscellaneous JMS Functions


Monitoring Functions

  • PDCE Functions Overview
    The PDCE (Performance Data Collection Engine) is an internal engine of Performance Explorer used for online monitoring. Its interface can also be used in the BDL of Silk Performer for monitoring PDCE data sources.
  • Performance Monitor Functions Overview
    Windows NT Performance Monitor counters collect and present information about the system performance.
  • SNMP Functions
    Lists functions for monitoring SNMP connections.
Parent topic: Benchmark Description Language (BDL) Reference


PDCE Functions Overview

The PDCE (Performance Data Collection Engine) is an internal engine of Performance Explorer used for online monitoring. Its interface can also be used in the BDL of Silk Performer for monitoring PDCE data sources.

Therefore all measures that Performance Explorer is able to monitor in real-time can also be used the same way with the BDL of Performance Explorer. After the execution of some registering functions you are able to get the data out of the PDCE through the provided polling functions. These functions provide data, status information, and a description for the measures (if available).

Terminology

Client | Any source that is registered in the Performance Data Collection Engine for collecting measure data (Silk Performance Manager, Silk Performer, Performance Explorer, TSD Writer).
Measure | A measure is the data object that stores the collected data of the queries with corresponding statistic data (sum, min, max, avg, stdev,...). It provides access to this data, and additional information about the measure itself (measure type, description, status,...).
Measure Group | Measure groups are a collection of all measures that are of the same measure type and have the same update interval. Such a group has all the logic to perform the necessary queries for measure updates and to provide this data to the clients.
Interval Manager | The Interval Manager adds new subscribed measures to the correct measure group. Additionally, it contains a scheduler that initiates the queries for measure updates for every Measure Group.
Performance Data Collection Engine | A library, that allows multiple clients to register different types of measures (NT System Data, SNMP Data, Silk Performer data,...) for data collection. This data is either provided to the clients for real time monitoring or for writing to a Timeseries Data file (TSD Writer).

Example

//-------------------------------------------------------
// Performance monitoring script uses polling functions of PDCE interface
// for monitoring all supported performance data source of the PDCE.
//-------------------------------------------------------
//-------------------------------------------------------
benchmark SilkPerformer Pdce
use "pdce.bdh"

const
    STRING_SIZE := 1024;
    NUMBER_OF_MEASURES := 7;

    // sample measure strings for different data sources
    RSTAT_SAMPLE_MEASURE := "RStat:Total Cpu@localhost";
    SNMP_SAMPLE_MEASURE := "SNMP:1.3.6.1.4.1.3068.1.7.3.16.0@localhost";
    PERFMON_SAMPLE_MEASURE := "PERFMON:\\Processor(_Total)\\% Processor Time@localhost";
    REXEC_SAMPLE_MEASURE := "REXEC:VMSTAT:0\\9@localhost";
    WEBSPHERE_SAMPLE_MEASURE := "WS35:localhost.Default Server.runtime.resources.memFree@localhost:900";
    PMI_SAMPLE_MEASURE := "PMI:localhost\\Default Server\\jvmRuntimeModule\\1@localhost:900";
    PERFSERVLET_MEASURE := "PERFSERVLET:vangelis\Default Server\jvmRuntimeModule\totalMemory\@vangelis:80?/wasPerfTool/servlet/perfservlet"

// Definition of global variables: string, number, float, boolean, array
var
    pClient      :number;
    pMeasure     :array[NUMBER_OF_MEASURES] of number;
    sMeasureName :array[NUMBER_OF_MEASURES] of string;

    fMeasureLastValue :float;
    fMeasureSum   :float;
    fMeasureMin   :float;
    fMeasureMax   :float;
    fMeasureAvg   :float;
    fMeasureStDev :float;

    uiMeasureTimeStamp :number;
    uiMeasureStatus    :number;

    sDescription :string(STRING_SIZE);
    sErrorText   :string(STRING_SIZE);
    sMeasureKey  :string;
    uiErrorCode  :number;

    uiPdceInternalQueryInterval : number init 5000;  //msec
    fPdceInitInterval           : float init 5.0;  //sec
    fMonitoringInterval         : float init 3.0;  //sec
    uiTimeStamp                 : number;
    uiNewPdceInternalQueryInterval : number init 10000; //msec

// Workload Section
dcluser
    user
      VPdceMonitor
    transactions
      TInit        : begin; // Initialization
      TPdceMonitor : 10; // Transactions
      TEnd         : end; // Termination

// Transactions Section -------------------
dcltrans
    transaction TInit
    begin
      // Insert here the initial statements
      PdceStartup();
      PdceClientRegister(pClient, uiPdceInternalQueryInterval);

      sMeasureKey := PERFMON_SAMPLE_MEASURE;
      sMeasureName[1] := "PerfmonMeasure1";
          PdceAddMeasure(pClient, sMeasureName[1], sMeasureKey, pMeasure[1]);

// samples for other datasources, different handle "pMeasure" needed for every measure
/*
      sMeasureKey     := RSTAT_SAMPLE_MEASURE;
      sMeasureName[2] := "RstatMeasure1";
      PdceAddMeasure(pClient,sMeasureName[2],sMeasureKey,pMeasure[2]);

      sMeasureKey    := SNMP_SAMPLE_MEASURE;
      sMeasureName[3] := "SnmpMeasure1";
      PdceAddMeasure(pClient,sMeasureName[3],sMeasureKey,pMeasure[3]);

      sMeasureKey     := REXEC_SAMPLE_MEASURE;
      sMeasureName[4] := "RexecMeasure1";
      PdceAddMeasure(pClient,sMeasureName[4],sMeasureKey,pMeasure[4]);
      sMeasureKey    := WEBSPHERE_SAMPLE_MEASURE;
      sMeasureName[5] := "WebSphereMeasure1";
      PdceAddMeasure(pClient, sMeasureName[5], sMeasureKey, pMeasure[5]);

      sMeasureKey     := PMI_SAMPLE_MEASURE;
      sMeasureName[6] := "PmiMeasure1";
      PdceAddMeasure(pClient, sMeasureName[6], sMeasureKey, pMeasure[6]);

      sMeasureKey     := PERFSERVLET_SAMPLE;    sMeasureName[7] := "PerfServletMeasure1";
      PdceAddMeasure(pClient, sMeasureName[7], sMeasureKey, pMeasure[7]);
*/

      wait(fPdceInitInterval);

      // get time stamp
      PdceGetStartTickCount(uiTimeStamp);
      write("Timestamp:");
      write(uiTimeStamp, 10);

      // change interval
      PdceClientInterval(pClient, uiNewPdceInternalQueryInterval);

      // get description of measures and write to output file
      // ... do for every measure of which you want a detailed description
      PdceMeasureQueryInfo(pMeasure[1], sDescription, STRING_SIZE);
      write(sMeasureName[1]);    write(":  ");
      writeln(sDescription);
      writeln;
    end TInit;

//------------------------------------------
    transaction TPdceMonitor
    begin
      // get actual status of measure
      PdceMeasureQueryStatus(pMeasure[1], uiErrorCode, sErrorText, STRING_SIZE);

      // get actual values of measure
      PdceMeasureQueryValue(pMeasure[1], fMeasureLastValue, fMeasureSum, fMeasureMin, fMeasureMax,      fMeasureAvg, fMeasureStDev, uiMeasureTimeStamp, uiMeasureStatus);

      // write to output file
      write(sMeasureName[1]);
      write(": Timestamp:");
      write(uiMeasureTimeStamp, 10);
      write(" Value: ");
      write(fMeasureLastValue, 8, 2);
      write(" Sum: ");
      write(fMeasureSum, 10, 2);
      write(" Min: ");
      write(fMeasureMin, 8, 2);
      write(" Max: ");
      write(fMeasureMax, 8, 2);
      write(" Avg: ");
      write(fMeasureAvg, 8, 2);
      write(" StDev: ");
      write(fMeasureStDev, 8, 2);
      write(" Status: ");
      writeln(sErrorText);

      wait(fMonitoringInterval);
    end TPdceMonitor;

//------------------------------------------

transaction TEnd
    begin
      // every measure has to be unsubscribed;
      PdceMeasureUnSubscribe(pMeasure[1]);
      PdceClientUnRegister(pClient);
      PdceCleanup();
    end TEnd;
  • Monitoring BEA Weblogic Application Servers
    This section briefly explains how BEA WebLogic servers can be monitored using Silk Performance Explorer and some important WebLogic performance measures.
  • Monitoring IBM WebSphere Application Servers
    This section briefly explains how IBM WebSphere application servers can be monitored using Performance Explorer and specific performance measures.
  • Monitoring Oracle Forms Application Servers
  • PdceStartup Function
    This function initializes the PDCE and increases the reference counter.
  • PdceCleanup Function
    This function decreases the reference counter.
  • PdceGetStartTickCount Function
    This function returns the timestamp of the interval manager creation.
  • PdceRegisterClient Function
    This function registers any client to the data collection engine.
  • PdceClientRegister Function
    This function registers any client to the data collection engine.
  • PdceClientUnRegister Function
    This function unregisters a client from the data collection engine.
  • PdceClientInterval Function
    This function changes the interval in which the PDCE collects data for a registered client.
  • PdceAddMeasure Function
    This function adds a new measure to a client.
  • PdceMeasureSubscribe Function
    This function adds a new measure to a client. At every interval, the data for the added measure is collected from the client.
  • PdceMeasureUnSubscribe Function
    This function removes a registered measure from a client.
  • PdceMeasureQueryInfo Function
    This function returns an information string for a given measure if the measure provides such a string.
  • PdceMeasureQueryStatus Function
    This function provides the status for a given measure for the last collection cycle.
  • PdceMeasureQueryValue Function
    This function provides the actual values for a given measure.
  • PdceGetMeasureValue Function
    This function provides the last queried values for a given measure.
Parent topic: Monitoring Functions


Monitoring BEA Weblogic Application Servers

This section briefly explains how BEA WebLogic servers can be monitored using Performance Explorer and some important WebLogic performance measures.

By default, the WebLogic SNMP agent is inactive. SNMP support can be enabled using the WebLogic Administration Console. With a Web browser you can launch the console by visiting http://weblogichost:port/console. In the left-hand menu tree, select the SNMP node. This brings up the SNMP configuration page. Using this page, verify that the SNMP agent is enabled. You must restart WebLogic to enable SNMP support.

  1. From Performance Explorer select, Monitor > Add Data Source . The Data Source Wizard dialog opens.
  2. Check Select from predefined Data Sources and click Next.
  3. This displays a selection of available monitoring data sources.
  4. From Application Server, select the preconfigured BEA WebLogic option and click Next.
  5. Specify the host and port where BEA WebLogic is running and click Next.
  6. This brings up a dialog that offers browsing for SNMP measures published by BEA WebLogic. This dialog only shows SNMP measures that are relevant for monitoring and ensure the reliability and performance of BEA WebLogic server environments.
Parent topic: PDCE Functions Overview


Monitoring IBM WebSphere Application Servers

With Silk Performer the following IBM WebSphere Application Servers can be monitored:

  • IBM WebSphere Application Server Advanced Edition 3.5

  • IBM WebSphere Application Server Advanced Edition 4.0

  • IBM WebSphere Application Server 4.x via Performance Servlet

  • IBM WebSphere Application Server 5.0 via Performance Servlet

Monitoring IBM WebSphere Application Servers 3.5 has been tested under NT, Win2000 and Ret Hat Linux platforms. Monitoring IBM WebSphere Application Servers 4.0 has been tested under NT and Win2000.

Parent topic: PDCE Functions Overview

To Monitor IBM WebSphere Application Server 3.5

  1. Start Performance Explorer and click the Monitor Server button in the workflow bar. Select the Select from predefined Data Sources radio button. Do not use the Have Data Sources detected radio button as the Data Source detection module does not detect IBM WebSphere Application Servers.
  2. Select Application Servers/IBM WebSphere Application Server/IBM WebSphere Application Server 3.5 and connect to the host running the Application Server. Performance Explorer connects to a daemon or service named IBM WS AdminServer. This service is runs by default unless the Standard Edition of IBM WebSphere Application Server 3.5 is used.
Once the connection to the server is established (this may take 3 to 5 seconds), the dialog shows the root nodes of the WebSphere Administrative domain. Such a domain administers several hosts where each host may run as many applications as needed. Select performance counters and click the Add button to add them to the monitoring template.

Typical performance measures for WebSphere Application Servers 3.5:

  • Runtime Module: Contains performance counters related to the Java Virtual Machine

  • Thread Pool: Answers questions like how many threads are currently active or how many threads were created, this includes idle and active threads.

  • Bean Data: Specific performance information about deployed EJBs. For example how many beans were created or the response time of method invocations.

  • Transaction Data: Contains everything about transactions like how many transactions are currently in progress or the average time it takes to execute one transaction.

  • Connection Manager:Contains performance counters for JDBC connections.

  • Servlet Engine: Contains performance counters giving an idea how deployed servlets and JSPs perform.

To Monitor IBM WebSphere Application Server 4.0

  1. Start Performance Explorer and click the Monitor Server button on the workflow bar. Select theSelect from predefined Data Sources radio button. Do not use the Have Data Sources detected radio button as the Data Source detection module does not detect IBM WebSphere Application Servers.
  2. Select Application Servers/IBM WebSphere Application Servers/IBM WebSphere Application Server 4.0 and connect to the host where the application server is running. Once the connection to the server is established the dialog shows the root nodes of the WebSphere Administrative domain. Such a domain administers several hosts where each host may be running as many applications as needed. Select performance counters and click the Add button to add them to the monitoring template.
Performance Explorer connects to a daemon or service named IBM AdminService. This service runs by default unless the Standard Edition of IBM WebSphere Application Server 4.0 is used.

To Monitor IBM WebSphere Application Server 4.x via Performance Servlet

  1. Open the WebSphere Administrative Console.
  2. Expand and right-click the Enterprise Applications node.
  3. Select Install Enterprise Application from the context menu.
  4. A dialog displays. Browse to the perfservlet application that is delivered by default with the WebSphere package. The application to be installed is named perfServletApp.ear and is usually located under WebSphere\AppServer\installableApps\perfServletApp.ear. Browse to the package and open it.
  5. Click Next repeatedly until you can select the host. Select default_host and Click Next.
  6. Select the server the perfservlet application is to be installed (for example, Default Server(yourhost)) and click Finish. Now the package is deployed. If everything has been set up correct, a message box will appears, confirming a successful installation.
  7. Right click the installed perfservlet application and select Start from the context menu.
  8. By default monitoring is turned off for WebSphere application servers. You may enable and change the granularity of performance measures to be retrieved from your WebSphere installation. To do this open the IBM Resource Analyzer tool.
  9. Expand the root node and select the server where the perfservlet application is installed. Right-click the node and select Monitoring Settings from the context menu.
  10. You may select from the following granularity options: Maximum, High, Medium, Low, and None.
  11. To double check whether the perfservlet application is returning valid performance information, open an XML compatible Internet browser and verify the following URL: http://yourhost/wasPerfTool/servlet/perfservlet.
  12. Now that your WebSphere installation is configured for monitoring, start Performance Explorer and click the Monitor Server button on the workflow bar. Select the Select from predefined Data Sources radio button. Do not use the Have Data Sources detected radio button as the Data Source detection module does not detect IBM WebSphere Application Servers.
  13. Select Application Servers/IBM WebSphere Application Servers/IBM WebSphere Application Server 4.x (PerfServlet) and connect to the host that is running the application server.

Typical performance measures for WebSphere Application Servers 4.x:

  • BeanModule: Specific data about deployed EJBs. For example how many beans were created.

  • ConnectionPoolModule:This module contains performance counters about JDBC connections like how many JDBC connetions are currently in the pool.

  • JvmRuntimeModule:Java Virtual Machine specific performance counters.

  • ServletSessionModule: This module contains performance counters about servlet sessions. For example how many sessions are active or the average session live time.

  • TransactionModule: This module contains performance counters giving information how many transactions are in progress or the average time it takes to execute one transaction.

  • WebApplicationModule: Provides information about deployed servlets and JSPs. For example the average time it takes the servlet to process requests.

To Monitor IBM WebSphere Application Server 5.0 via Performance Servlet

  1. Open the Administrative Console.
  2. Expand Applications and click Install New Application.
  3. Install the perfservlet application. To do this, click the browse button and search for a file called PerfServletApp.ear. It is usually under WebSphere\AppServer\installableApps\PerfServletApp.ear. Press Next.
  4. The wizard guides you through the installation. Check the Generate Default Binding check box. Type in the virtual host name (for example default_host). Click Next.
  5. The next step is called AppDeployment Options. Accept the settings and click Next.
  6. Map virtual hosts for web modules: Check the WebModule and perfservlet checkboxes. Select the virtual host (or example, default_host) and click Next.
  7. Map modules to application servers: Check the Module and perfservlet checkboxes. Click Next.
  8. Map security roles to users/groups: Allow all roles by checking all check boxes. Click Next.
  9. Summary: Click Finish.
  10. The perfservlet application is now deployed, but it is not yet running. Click the Save to Master configuration link and save your settings.
  11. Expand the Applications node and click Enterprise Applications. From the list, check the perfservlet application and click Start.
  12. Monitoring is disabled by default with WebSphere 5.0. To enable monitoring expand the Servers node and select Application Servers.
  13. Click the server where monitoring has to be enabled (for example, server1). Under Additional Properties click the Performance Monitoring Service link. Check the Startup checkbox so that monitoring will always enabled on startup. Also specify the specification level (the granularity of performance measures to be retrieved).
  14. Click OK and save your settings to the master configuration.
  15. To verify that the perfservlet application was successfully deployed, open an XML-compatible Internet browser and type in the following URL http://yourHost[:port]/wasPerfTool/servlet/perfservlet.
  16. Assuming that everything has been successfully deployed, open Performance Explorer.
  17. Click the Monitor Server button on the workflow bar. Select the Select from predefined Data Sources radio button. Do not use the Have Data Sources detected radio button as the Data Source detection module does not detect IBM WebSphere Application Servers.
  18. Select Application Servers/IBM WebSphere Application Servers/IBM WebSphere Application Server 5.0 (PerfServlet) and connect to the host that is running the application server.

Typical performance measures for WebSphere Application Servers 5.0:

  • BeanModule: Specific data about deployed EJBs. For example how many beans were created.

  • ConnectionPoolModule: This module contains performance counters about JDBC connections like how many JDBC connetions are currently in the pool.

  • JvmRuntimeModule: Java Virtual Machine specific performance counters.

  • ServletSessionModule: This module contains performance counters about servlet sessions. For example how many sessions are active or the average session live time.

  • TransactionModule: This module contains performance counters giving information how many transactions are in progress or the average time it takes to execute one transaction.

WebApplicationModule: Provides information about deployed servlets and JSPs. For example the average time it takes the servlet to process requests


Monitoring Oracle Forms Application Servers

Parent topic: PDCE Functions Overview


PdceStartup Function

Action

This function initializes the PDCE and increases the reference counter. An interval manager is created on the first call to PdceStartup(). It should be called in a TInit transaction before all other PDCE function calls.

Include file

Pdce.bdh

Syntax

PdceStartup( ): boolean;

Return value

  • true if successful

  • false otherwise

Example

Const
  STRING_SIZE            := 1024;
  PERFMON_SAMPLE_MEASURE := "PERFMON:\\Processor(_Total)\\% Processor Time@localhost";

dcltrans
  transaction TInit
  var
    sMeasureKey        : string;
    sMeasureName       : array[10] of string;
    sDescription       : string;

begin
    // Insert here the initial statements
    PdceStartup();
    PdceClientRegister(pClient, uiPdceInternalQueryInterval);
    sMeasureKey := PERFMON_SAMPLE_MEASURE;
    sMeasureName[1] := "PerfmonMeasure1";
    PdceAddMeasure(pClient, sMeasureName[1], sMeasureKey, pMeasure[1]);

    PdceMeasureQueryInfo(pMeasure[1], sDescription, STRING_SIZE);
    write(sMeasureName[1]);
    write(": ");
    writeln(sDescription);
    writeln;
end TInit;
Parent topic: PDCE Functions Overview


PdceCleanup Function

Action

This function decreases the reference counter. If the reference counter reaches 0 it deletes the interval manager. For every PdceStartup() function that gets called in a script there should be a PdceCleanup() function call in the TEnd transaction.

Include file

Pdce.bdh

Syntax

PdceCleanup( ): boolean;

Return value

  • true if successful

  • false otherwise

Example

dcltrans
    transaction TEnd
    begin
      // every measure has to be unsubscribed;
      PdceMeasureUnSubscribe(pMeasure[1]);
      PdceClientUnRegister(pClient);
      PdceCleanup();
  end TEnd;
Parent topic: PDCE Functions Overview


PdceGetStartTickCount Function

Action

This function returns the timestamp of the interval manager creation. The interval manager of the PDCE manages all clients and initiates the data collection to the different intervals of any registered client.

Include file

Pdce.bdh

Syntax

PdceGetStartTickCount( out nTick : number ): boolean;

Return value

  • true if successful

  • false otherwise

Parameter | Description
nTick | Specifies the timestamp value of the interval manager creation.

Example

const
  STRING_SIZE            := 1024;
  PERFMON_SAMPLE_MEASURE := "PERFMON:\\Processor(_Total)\\% Processor Time@localhost";

dcltrans
  transaction TInit
  var
    sMeasureKey       : string;
    sMeasureName      : array[10] of string;
    sDescription      : string;    fPdceInitInterval : float;
    uiTimeStamp       : number;
begin
    PdceStartup();
    PdceClientRegister(pClient, uiPdceInternalQueryInterval);
    sMeasureKey     := PERFMON_SAMPLE_MEASURE;
    sMeasureName[1] := "PerfmonMeasure1";
    PdceAddMeasure(pClient, sMeasureName[1], sMeasureKey, pMeasure[1]);
    wait(fPdceInitInterval);
    // get time stamp
    PdceGetStartTickCount(uiTimeStamp);
    write("Timestamp:");
    write(uiTimeStamp, 10);
    PdceMeasureQueryInfo(pMeasure[1], sDescription,  STRING_SIZE);
    write(sMeasureName[1]);
    write(": ");
    writeln(sDescription);
    writeln;
  end TInit;
Parent topic: PDCE Functions Overview


PdceRegisterClient Function

Action

This function registers any client to the data collection engine.

The first parameter returns a handle that is needed for further PDCE functions.

The second parameter returns the interval in seconds, in which the PDCE collects data for the client. The default update interval for collecting the monitor data is 60 seconds, but you can adjust the monitoring interval by opening the Project Attribute Dialog (Project > Project Attributes) and changing the attribute value of the attribute MeasureCollectionInterval. This interval can also be changed any time by the PdceClientInterval() function.

Note: Collecting data in a smaller interval than 1 second is not allowed and results in an error.

Include file

Pdce.bdh

Syntax

PdceRegisterClient( inout hClient   : number,
                      out   nInterval : number ): boolean;

Return value

  • true if successful

  • false otherwise

Parameter | Description
hClient | Specifies the client's handle.
nInterval | Specifies a number for the determined query interval (in seconds).

Example

benchmark Collect
use "pdce.bdh"

const
  MEASURE_NAME01 := "PE_% Processor Time(0)@LAB35";
  MEASURE_KEY01  := "PERFMON:\\Processor(0)\\% Processor Time@LAB35";

var
  nInterval  : number;
  hClient01  : number;
  hMeasure01 : number;

dcluser
  user
    Collect
  transactions
    NoTRT_TStartup : begin;
    NoTRT_TCollect : 5;
    NoTRT_TEnd     : end;

dcltrans
  transaction NoTRT_TStartup
  begin
   PdceStartUp();
   PdceRegisterClient(hClient01, nInterval);
   PdceAddMeasure(hClient01, MEASURE_NAME01, MEASURE_KEY01, hMeasure01);
   Wait(float(2*nInterval));
 end NoTRT_TStartup;

  transaction NoTRT_TCollect
  begin
   PdceGetMeasureValue(hMeasure01, MEASURE_NAME01);
   if (GetWorkloadModel() <> WORKLOAD_MONITORING) then
     Wait(float(nInterval));
   end;
 end NoTRT_TCollect;

  transaction NoTRT_TEnd  begin
   PdceMeasureUnSubscribe(hMeasure01);
   PdceClientUnRegister(hClient01);
   PdceCleanUp();
 end NoTRT_TEnd;
Parent topic: PDCE Functions Overview


PdceClientRegister Function

Action

This function registers any client to the data collection engine. The first parameter returns a handle that is needed for further PDCE functions. The second parameter specifies the interval in milliseconds, in which the PDCE collects data for the client. This interval can be changed any time by the PdceClientInterval() function. Usually, it makes sense to register your clients in the TInit transaction after the PdceStartup(). The last three parameters have to be NULL, as they are used for callback functionality. Note that callbacks are not supported in Silk Performer scripts.

Note: If you collect data in a smaller interval than 1000 milliseconds, your result measures may have wrong values.

Include file

Pdce.bdh

Syntax

PdceClientRegister( out hPdce     : number,
                    in  uInterval : number ) : boolean;

Return value

  • true if successful

  • false otherwise

Parameter | Description
hPdce | Specifies the client's handle.
uInterval | Specifies an unsigned integer for the query interval.

Example

const
  STRING_SIZE            := 1024;
  PERFMON_SAMPLE_MEASURE := "PERFMON:\\Processor(_Total)\\% Processor Time@localhost";

dcltrans
  transaction TInit
  var
    sMeasureKey       : string;
    sMeasureName      : array[10] of string;
    sDescription      : string;
    fPdceInitInterval : float;
  begin
    // Insert here the initial statements
    PdceStartup();    PdceClientRegister(pClient, uiPdceInternalQueryInterval);
    sMeasureKey     := PERFMON_SAMPLE_MEASURE;
    sMeasureName[1] := "PerfmonMeasure1";
    PdceAddMeasure(pClient, sMeasureName[1], sMeasureKey, pMeasure[1]);
    wait(fPdceInitInterval);
    PdceMeasureQueryInfo(pMeasure[1], sDescription, STRING_SIZE);
    write(sMeasureName[1]);
    write(": ");
    writeln(sDescription);
    writeln;
  end TInit;
Parent topic: PDCE Functions Overview


PdceClientUnRegister Function

Action

This function unregisters a client from the data collection engine. It should be called when no further client data is needed. Usually, this can be done for all clients in the TEnd transaction before the PdceCleanup().

Include file

Pdce.bdh

Syntax

PdceClientUnRegister( in hPdce : number ): boolean;

Return value

  • true if successful

  • false otherwise

Parameter | Description
hPdce | Specifies the client's handle, from the PdceClientRegister or PdceRegisterClient function.

Example

dcltrans
  transaction TEnd
  begin
    // every measure has to be unsubscribed;
    PdceMeasureUnSubscribe(pMeasure[1]);
    PdceClientUnRegister(pClient);
    PdceCleanup();
  end TEnd;
Parent topic: PDCE Functions Overview


PdceClientInterval Function

Action

This function changes the interval in which the PDCE collects data for a registered client. The interval must be provided in milliseconds.

Note: If you collect data in a smaller interval than 1000 milliseconds, your result measures may have incorrect values.

Include file

Pdce.bdh

Syntax

PdceClientInterval( in hPdce     :number,
                    in nInterval : number ): boolean;

Return value

  • true if successful

  • false otherwise

Parameter | Description
hPdce | Specifies the client's handle, from the PdceClientRegister or PdceRegisterClient function.
nInterval | Specifies an unsigned integer new for the query interval.

Example

const
  STRING_SIZE            := 1024;
  PERFMON_SAMPLE_MEASURE := "PERFMON:\\Processor(_Total)\\% Processor Time@localhost";

dcltrans
  transaction TInit
  var
    sMeasureKey       : string;
    sMeasureName      : array[10] of string;
    sDescription      : string;
    fPdceInitInterval : float;
  begin
    PdceStartup();
    PdceClientRegister(pClient, uiPdceInternalQueryInterval);
    sMeasureKey     := PERFMON_SAMPLE_MEASURE;
    sMeasureName[1] := "PerfmonMeasure1";
    PdceAddMeasure(pClient, sMeasureName[1], sMeasureKey, pMeasure[1]);
    wait(fPdceInitInterval);

    // change interval
    PdceClientInterval(pClient, uiNewPdceInternalQueryInterval);
    PdceMeasureQueryInfo(pMeasure[1], sDescription, STRING_SIZE);

    write(sMeasureName[1]);
    write(": ");
    writeln(sDescription);
    writeln;
end TInit;
Parent topic: PDCE Functions Overview


PdceAddMeasure Function

Action

This function adds a new measure to a client. It is a wrapper for PdceMeasureSubscribe that hides unused parameters.

At every interval, the data for the added measure is collected from the client. The interval can be changed any time by the PdceClientInterval() function. The query functions of the PDCE enable you to retrieve the values and statuses of the last collection cycle from the client. After subscribing a measure, you should wait for one interval length before querying data from the measure. This is done to give the PDCE time for initializing the new measure with the first value. The subscription of your measures can also be done in the TInit transaction after you have registered your client.

Include file

Pdce.bdh

Syntax

PdceAddMeasure( in    hClient      : number,
                inout sMeasureName : string,
                inout sMeasureKey  : string,
                inout hMeasure     : number ): boolean;

Return value

  • true if successful

  • false otherwise

Parameter | Description
hClient | Specifies the client's handle, from the PdceRegisterClient or PdceClientRegister function.
sMeasureName | Specifies the name for the measure.
sMeasureKey | Specifies the string that defines the measure.
hMeasure | Specifies the measure's handle (needed for other measure functions).

Example

benchmark Collect
use "pdce.bdh"

const
  MEASURE_NAME01 := "PE_% Processor Time(0)@LAB35";
  MEASURE_KEY01  := "PERFMON:\\Processor(0)\\% Processor Time@LAB35";

var
  nInterval  : number;
  hClient01  : number;
  hMeasure01 : number;

dcluser
  user
    Collect
  transactions
    NoTRT_TStartup  : begin;
    NoTRT_TCollect  : 5;
    NoTRT_TEnd      : end;

dcltrans
  transaction NoTRT_TStartup
  begin
    PdceStartUp();
    PdceRegisterClient(hClient01, nInterval);
    PdceAddMeasure(hClient01, MEASURE_NAME01, MEASURE_KEY01, hMeasure01);

    Wait(float(2*nInterval));
  end NoTRT_TStartup;

  transaction NoTRT_TCollect
  begin
    PdceGetMeasureValue(hMeasure01, MEASURE_NAME01);

    if (GetWorkloadModel() <> WORKLOAD_MONITORING) then
      Wait(float(nInterval));
    end;
  end NoTRT_TCollect;

  transaction NoTRT_TEnd
  begin
    PdceMeasureUnSubscribe(hMeasure01);
    PdceClientUnRegister(hClient01);
    PdceCleanUp();
  end NoTRT_TEnd;
Parent topic: PDCE Functions Overview


PdceMeasureSubscribe Function

Action

This function adds a new measure to a client. At every interval, the data for the added measure is collected from the client. The interval can be changed any time by the PdceClientInterval() function. The query functions of the PDCE enable you to retrieve the values and statuses of the last collection cycle from the client. After subscribing a measure, you should wait for one interval length before querying data from the measure. This is done to give the PDCE time for initializing the new measure with the first value. The subscription of your measures can also be done in the TInit transaction after you have registered your client.

Include file

Pdce.bdh

Syntax

PdceMeasureSubscribe( in  hPdce        : number,
                      in  NULL         : number,
                      in  sMeasurename : string,
                      in  sKeyId       : string,
                      in  nOption      : number,
                      out hMeasure     : number ): boolean;

Return value

  • true if successful

  • false otherwise

Parameter | Description
hPdce | Specifies the client's handle, from the PdceClientRegister or PdceRegisterClient function.
NULL | Unused measure context handle.
sMeasurename | Specifies the name for the measure.
sKeyId | Specifies the string, that defines the measure.
nOption | Specifies an unsigned integer (not used by now = 0).
hMeasure | Specifies the measure's handle (needed for other measure functions).

Example

const
  STRING_SIZE            := 1024;
  PERFMON_SAMPLE_MEASURE := "PERFMON:\\Processor(_Total)\\% Processor Time@localhost";

 dcltrans
  transaction TInit
  var
    sMeasureKey        : string;
    sMeasureName       : array[10] of string;
    sDescription       : string;

  begin
    // Insert here the initial statements
    PdceStartup();
    PdceClientRegister(pClient, uiPdceInternalQueryInterval);
    sMeasureKey := PERFMON_SAMPLE_MEASURE;
    sMeasureName[1] := "PerfmonMeasure1";
    PdceMeasureSubscribe(pClient, NULL, sMeasureName[1], sMeasureKey, 0, pMeasure[1]);

    PdceMeasureQueryInfo(pMeasure[1], sDescription, STRING_SIZE);

    write(sMeasureName[1]);
    write(": ");
    writeln(sDescription);
    writeln;
  end TInit;
Parent topic: PDCE Functions Overview


PdceMeasureUnSubscribe Function

Action

This function removes a registered measure from a client. The client stops collecting data for the removed measure. This can also be done in the TEnd transaction before un-registering the client.

Include file

Pdce.bdh

Syntax

PdceMeasureUnSubscribe( in hMeasure : number ) : boolean;

Return value

  • true if successful

  • false otherwise

Parameter | Description
hMeasure | Specifies the measure's handle, from the PdceMeasureSubscribe or PdceAddMeasure function.

Example

dcltrans
  transaction TEnd
  begin
    // every measure has to be unsubscribed;
    PdceMeasureUnSubscribe(pMeasure[1]);
    PdceClientUnRegister(pClient);
    PdceCleanup();
  end TEnd;
Parent topic: PDCE Functions Overview


PdceMeasureQueryInfo Function

Action

This function returns an information string for a given measure if the measure provides such a string (for example, the description of NT performance counters).

Include file

Pdce.bdh

Syntax

PdceMeasureQueryInfo( in  hMeasure     : number,
                      out sDescription : string,
                      in  uSize        :number optional ): boolean;

Return value

  • true if successful

  • false otherwise

Parameter | Description
hMeasure | Specifies the measure's handle, from the PdceMeasureSubscribe or PdceAddMeasure function.
sDescription | Specifies the buffer to receive the measure's description.
uSize | Specifies an unsigned integer providing the size of the buffer (optional).

Example

Const
    STRING_SIZE            := 1024;
    PERFMON_SAMPLE_MEASURE := "PERFMON:\\Processor(_Total)\\% Processor Time@localhost";

dcltrans
    transaction TInit
    var
      sMeasureKey       : string;
      sMeasureName      : array[10] of string;
      sDescription      : string;
      fPdceInitInterval : float;
      uiTimeStamp       : number;
    begin
      // Insert here the initial statements
      PdceStartup();
      PdceClientRegister(pClient, uiPdceInternalQueryInterval);
      sMeasureKey     := PERFMON_SAMPLE_MEASURE;
      sMeasureName[1] := "PerfmonMeasure1";
      PdceAddMeasure(pClient, sMeasureName[1], sMeasureKey, pMeasure[1]);
      wait(fPdceInitInterval);
      PdceMeasureQueryInfo(pMeasure[1], sDescription);
      write(sMeasureName[1]);
      write(": ");
      writeln(sDescription);
      writeln;
    end TInit;
Parent topic: PDCE Functions Overview


PdceMeasureQueryStatus Function

Action

This function provides the status for a given measure for the last collection cycle.

Include file

Pdce.bdh

Syntax

PdceMeasureQueryStatus( in  hMeasure   : number,
                        out uErrorCode : number,
                        out sErrorText : string,
                        in  uSize      : number optional ): boolean;

Return value

  • true if successful

  • false otherwise

Parameter | Description
hMeasure | Specifies the measure's handle, from the PdceMeasureSubscribe or PdceAddMeasure function.
uErrorCode | Specifies an unsigned integer to receive the error code.
sErrorText | Specifies the buffer to receive the measure's error text.
uSize | Specifies an unsigned integer providing the size of the buffer (optional).

Example

dcltrans
  transaction TPdceMonitor
  var
      sMeasureKey        : string;
      sMeasureName       : array[10] of string;
      sDescription       : string;
      fMeasureLastValue  : float;
      fMeasureSum        : float;
      fMeasureMin        : float;
      fMeasureMax        : float;
      fMeasureAvg        : float;
      fMeasureStDev      : float;
      uiMeasureTimeStamp : number;
      uiMeasureStatus    : number;
      uiErrorCode        : number;
      sErrorText         : string;
  begin
    // get actual status of measure
    PdceMeasureQueryStatus(pMeasure[1], uiErrorCode, sErrorText);
    // get actual values of measure
    PdceMeasureQueryValue(pMeasure[1], fMeasureLastValue, fMeasureSum, fMeasureMin, fMeasureMax,
    fMeasureAvg, fMeasureStDev, uiMeasureTimeStamp, uiMeasureStatus);
    // write to output file
    write(sMeasureName[1]);
    write(": Timestamp:");
    write(uiMeasureTimeStamp,10);
    write(" Value: ");
    write(fMeasureLastValue,8,2);
    write(" Sum: ");
    write(fMeasureSum,10,2);
    write(" Min: ");
    write(fMeasureMin,8,2);
    write(" Max: ");
    write(fMeasureMax,8,2);
    write(" Avg: ");
    write(fMeasureAvg,8,2);
    write(" StDev: ");
    write(fMeasureStDev,8,2);
    write(" Status: ");
    writeln(sErrorText);
  end TPdceMonitor;
Parent topic: PDCE Functions Overview


PdceMeasureQueryValue Function

Action

This function provides the actual values for a given measure. If it gets called more than once for one interval of the registered client, it will return always the same values.

Include file

Pdce.bdh

Syntax

PdceMeasureQueryValue( in  hMeasure          : number,
                       out fMeasureLastValue : float,
                       out fMeasureSum       : float,
                       out fMeasureMin       : float,
                       out fMeasureMax       : float,
                       out fMeasureAvg       : float,
                       out fMeasureStDev     : float,
                       out nMeasureTimeStamp : number,
                       out nMeasureStatus    : number ): boolean;

Return value

  • true if successful

  • false otherwise

Parameter | Description
hMeasure | Specifies the measure's handle, from the PdceMeasureSubscribe or PdceAddMeasure function.
fMeasureLastValue | Specifies a floating point to receive the last queried value.
fMeasureSum | Specifies a floating point to receive the sum of all queried values.
fMeasureMin | Specifies a floating point to receive the minimum of all queried values.
fMeasureMax | Specifies a floating point to receive the maximum of all queried values.
fMeasureAvg | Specifies a floating point to receive the average of all queried values.
fMeasureStDev | Specifies a floating point to receive the standard deviation of all queried values.
uMeasureTimeStamp | Specifies an unsigned integer to receive the timestamp of the last queried value.
uMeasureStatus | Specifies an unsigned integer to receive the status of the last queried value.

Example

const
  STRING_SIZE            := 1024;
  PERFMON_SAMPLE_MEASURE := "PERFMON:\\Processor(_Total)\\% Processor Time@localhost";

 dcltrans
  transaction TPdceMonitor
  var
    sMeasureKey        : string;
    sMeasureName       : array[10] of string;
    sDescription       : string;
    fMeasureLastValue  : float;
    fMeasureSum        : float;
    fMeasureMin        : float;
    fMeasureMax        : float;
    fMeasureAvg        : float;
    fMeasureStDev      : float;
    uiMeasureTimeStamp : number;
    uiMeasureStatus    : number;
    uiErrorCode        : number;
    sErrorText         : string;
  begin
    // get actual status of measure
    PdceMeasureQueryStatus(pMeasure[1], uiErrorCode, sErrorText, STRING_SIZE);
    // get actual values of measure
    PdceMeasureQueryValue(pMeasure[1], fMeasureLastValue, fMeasureSum, fMeasureMin, fMeasureMax,
    fMeasureAvg, fMeasureStDev, uiMeasureTimeStamp, uiMeasureStatus);
    // write to output file
    write(sMeasureName[1]);
    write(": Timestamp:");
    write(uiMeasureTimeStamp,10);
    write(" Value: ");
    write(fMeasureLastValue,8,2);
    write(" Sum: ");
    write(fMeasureSum,10,2);    write(" Min: ");    write(fMeasureMin,8,2);    write(" Max: ");    write(fMeasureMax,8,2);
    write(" Avg: ");    write(fMeasureAvg,8,2);    write(" StDev: ");    write(fMeasureStDev,8,2);    write(" Status: ");    writeln(sErrorText);
  end TPdceMonitor;
Parent topic: PDCE Functions Overview


PdceGetMeasureValue Function

Action

This function provides the last queried values for a given measure. The last queried value is stored in a custom counter with the name specified by the second parameter.

Include file

Pdce.bdh

Syntax

PdceGetMeasureValue( in  hMeasure     : number,
                     in  sMeasureName : string,
                     in  nScaleFactor : number optional,
                     out fValue       : float optional ): boolean

Return value

  • true if successful

  • false otherwise

Parameter | Description
hMeasure | Specifies the measure's handle, from the PdceMeasureSubscribe or PdceAddMeasure function.
sMeasureName | Specifies the name for the custom counter where the last queried value is stored in.
nScaleFactor | Optional scale factor by which the retrieved value is divided.
fValue | Optional floating point value which is set to the current value.

Example

benchmark Collect
use "pdce.bdh"

const
    MEASURE_NAME01 := "PE_% Processor Time(0)@LAB35";
    MEASURE_KEY01  := "PERFMON:\\Processor(0)\\% Processor Time@LAB35";

var
    nInterval  : number;
    hClient01  : number;
    hMeasure01 : number;

dcluser
    user
      Collect
    transactions
      NoTRT_TStartup : begin;
      NoTRT_TCollect : 5;
      NoTRT_TEnd     : end;

dcltrans
      transaction NoTRT_TStartup
      begin
    PdceStartUp();
    PdceRegisterClient(hClient01, nInterval);
    PdceAddMeasure(hClient01, MEASURE_NAME01, MEASURE_KEY01, hMeasure01);
    Wait(float(2*nInterval));
end NoTRT_TStartup;

      transaction NoTRT_TCollect
      begin
    PdceGetMeasureValue(hMeasure01, MEASURE_NAME01);
    if (GetWorkloadModel() <> WORKLOAD_MONITORING) then
      Wait(float(nInterval));
    end;
end NoTRT_TCollect;

      transaction NoTRT_TEnd
      begin
     PdceMeasureUnSubscribe(hMeasure01);
     PdceClientUnRegister(hClient01);
     PdceCleanUp();
end NoTRT_TEnd;
Parent topic: PDCE Functions Overview


Performance Monitor Functions Overview

Windows NT Performance Monitor counters collect and present information about the system performance. The counters are useful for identifying performance problems or bottlenecks that affect the operating system or installed applications.

Silk Performer provides the following functions to retrieve the values of Performance Monitor counters and write these values to report and time series data files: PerfMonAdd, PerfMonGet, and PerfMonClose.

  • PerfMonAdd Function
    Opens a Windows NT performance counter and returns a handle to the counter.
  • PerfMonGet Function
    Retrieves the value of a Windows NT Performance Monitor counter and writes the value to both report and time series data files.
  • PerfMonClose Function
    Closes a handle to a Windows NT Performance Monitor counter.
Parent topic: Monitoring Functions


PerfMonAdd Function

Action

Opens a Windows NT performance counter and returns a handle to the counter.

Include file

Kernel.bdh

Syntax

PerfMonAdd( out hPerf     : number,
            in  sComputer : string,
            in  sObject   : string,
            in  sCounter  : string,
            in  sInstance : string optional ): boolean;

Return value

  • true if successful

  • false otherwise

Parameter | Description
hPerf | Variable receiving the handle to the specified Performance Monitor counter.
sComputer | Name of the computer you want to monitor.
sObject | Name of the performance object. An object defines the set of counters that monitor the behavior of a specific hardware or software component, such as a processor or a thread.
sCounter | Counter type. The counter type determines how the counter data is calculated and averaged.
sInstance | Specifies an instance of the Performance Monitor counter to monitor (optional).

Example

var
  hCounter: array [3] of number;

dcltrans
  transaction TInit
  begin
    PerfMonAdd(hCounter[1], "localhost", "System",
               "% Total Processor Time");
    PerfMonAdd(hCounter[2], "localhost", "Processor",
               "% Processor Time", "0");
    PerfMonAdd(hCounter[3], "localhost", "Memory",
               "Committed Bytes");
  end TInit;
Parent topic: Performance Monitor Functions Overview


PerfMonGet Function

Action

Retrieves the value of a Windows NT Performance Monitor counter and writes the value to both report and time series data files.

Include file

Kernel.bdh

Syntax

PerfMonGet( in  hPerf     :number,
            in  nScale    : number optional,
            out sName     : string optional,
            in  sNameSize : number optional ): float;

Return value

The current value of the specified Performance Monitor counter.

Parameter | Description
hPerf | Handle to a Performance Monitor counter that was created with PerfMonAdd.
nScale | Scale for the counter (optional). For example, set this parameter to 1024 to retrieve the amount of data in KB instead of in bytes.
sName | String receiving the name of the custom counter that is used for writing the counter to report and time series data files (optional). The name is required to retrieve the counter value with the MeasureGet function as well.
nNameSize | Size of the string that receives the name of the custom counter (optional).

Example

var  hCounter: array [3] of number;

dcltrans
  transaction TInit
  begin
    PerfMonAdd(hCounter[1], "localhost", "System",
               "% Total Processor Time");
    PerfMonAdd(hCounter[2], "localhost", "Processor",
               "% Processor Time", "0");
    PerfMonAdd(hCounter[3], "localhost", "Memory",
               "Committed Bytes");
  end TInit;

  transaction TMain
  var
    i: number;
  begin
    ThinkTime(1.0);
    for i := 1 to 3 do PerfMonGet(hCounter[i]) end;
  end TMain;
Parent topic: Performance Monitor Functions Overview


PerfMonClose Function

Action

Closes a handle to a Windows NT Performance Monitor counter.

Include file

Kernel.bdh

Syntax

PerfMonClose( in hPerf : number ): boolean;

Return value

  • true if successful

  • false otherwise

Parameter | Description
hPerf | Handle to a Performance Monitor counter that was created with PerfMonAdd.

Example

var
  hCounter: array [3] of number;

dcltrans
  transaction TInit
  begin
    PerfMonAdd(hCounter[1], "localhost", "System",
               "% Total Processor Time");
    PerfMonAdd(hCounter[2], "localhost", "Processor",
               "% Processor Time", "0");
    PerfMonAdd(hCounter[3], "localhost", "Memory",
               "Committed Bytes");
  end TInit;

transaction TShutdown
  var
    i: number;
  begin
    for i := 1 to 3 do PerfMonClose(hCounter[i]) end;
  end TShutdown;
Parent topic: Performance Monitor Functions Overview


SNMP Functions

  • SnmpOpenConnection Function
    This function opens a new connection to a target machine with access to SNMP data for the provided MIB.
  • SnmpOpenConnectionEx Function
    This function opens a new connection to a target machine with access to SNMP data for the provided MIB. It supports both SNMPv1/2c and SNMP3.
  • SnmpCreatePdceKey Function
    This function returns a valid PDCE key.
  • SnmpCreatePdceKeyEx Function
    This function returns a valid PDCE key.
  • SnmpCloseConnection Function
    This function closes the connection established by a call of SnmpOpenConnection().
  • SnmpGetNextInstanceOid Function
    Subsequent calls of this function return the next existing instance after a successful SnmpGetFirstInstanceOid() on target machine. If no instance was found the function fails.
  • SnmpGetMibOid Function
    For each SNMP node, this function returns the corresponding OID in dotted notation from the MIB.
  • SnmpGetValue Function
    This function returns for a provided OID the actual value.
  • SnmpGetValueOid Function
    This function uses a provided SNMP node and searches all instances of it until its value matches the desired value.
Parent topic: Monitoring Functions


SnmpOpenConnection Function

Action

This function opens a new connection to a target machine with access to SNMP data for the provided MIB. It returns a handle required by all other BDL SNMP extension functions. This function only supports SNMP version 1/2c.

Include file

Snmp.bdh

Syntax

SnmpOpenConnection( in sMachine   : string,
                    in sMib       : string,
                    in sCommunity : string,
                    in sVersion   : string ): number;

Return value

Handle for open connection ( 0 on failure )

Parameter | Description
sMachine | Specifies target machine and port on which the smnp server is listening.
sMib | Specifies the name of the MIB.
sCommunity | Specifies the community of the SNMP data.
sVersion | Specifies the version of the SNMP data.

Example

benchmark Collect

use "pdce.bdh"
use "snmp.bdh"

const
  MEASURE_COMMUNITY   := "public";
  MEASURE_VERSION     := "V1";
  MEASURE_NAME        := "System/Services";
  MEASURE_MACHINE     := "machineName:161";
  MEASURE_MIB         := "RFC1213-MIB";
  MEASURE_OID_NAME    := "system.sysServices";

var
  nInterval         : number;
  hClient1          : number;
  hMeasure1         : number;
    sKey1             : string(1024);

dcluser
user
  Collect
transactions
  NoTRT_TStartup : begin;
  NoTRT_TCollect : 5;
  NoTRT_TEnd     : end;

dclfunc
  function PdceGetSnmpKey(sKey : string;
                          sMachine : string;
                          sMib : string;
                          sCommunity : string;
                          sVersion : string;
                          sOidName : string;
                          nInstance : number optional) : boolean

  var
    sMibOid        : string(1024);
    sInstanceOid   : string(1024);
    sValue         : string(1024);
    sOid           : string(1024);
    hSnmp          : number;        // SNMP connection handle
  begin

    hSnmp := SnmpOpenConnection(sMachine, sMib, sCommunity, sVersion);

    if ( hSnmp <> 0 ) then
      SnmpGetMibOid(hSnmp, sOidName, sMibOid);

      Print("OID for " + sOidName + " : " + sMibOid);

      SnmpGetFirstInstanceOid(hSnmp, sMibOid, sInstanceOid);
      sOid := sMibOid + "." + sInstanceOid;

      Print("OID with first instance: " + sOid);

      if SnmpGetValue(hSnmp, sOid, sValue) then
        Print("Value: " + sValue);
      end;

      sKey :=  "SNMP:" + sOid +"@" + MEASURE_MACHINE + "?" + SNMP_COMMUNITY_PUBLIC + "&" + SNMP_VERSION_1;
      PdceGetSnmpKey := true;

      SnmpCloseConnection( hSnmp )
    end;

    PdceGetSnmpKey := false;
  end PdceGetSnmpKey;

dcltrans
  transaction NoTRT_TStartup
  begin

      PdceGetSnmpKey( sKey1, MEASURE_Machine, MEASURE_MIB, MEASURE_COMMUNITY, MEASURE_VERSION, MEASURE_OID_NAME);

      PdceStartUp();
      PdceRegisterClient(hClient1, nInterval);
      PdceAddMeasure(hClient1, MEASURE_NAME, sKey1, hMeasure1);

      Wait(float(2*nInterval));
    end NoTRT_TStartup;

    transaction NoTRT_TCollect
    var
    fLastValue, fSum, fMin, fMax, fAvg, fStDev : float;
    uTimeStamp, uStatus  : number;
  begin
    PdceGetMeasureValue(hMeasure1, MEASURE_NAME);
    if (GetWorkloadModel() <> WORKLOAD_MONITORING) then
      Wait(float(nInterval));
    end;

    if PdceMeasureQueryValue(hMeasure1, fLastValue, fSum, fMin, fMax, fAvg, fStDev, uTimeStamp, uStatus) then
      Print("Query value: " + String(fLastValue) );
    end;
  end NoTRT_TCollect;

  transaction NoTRT_TEnd
  begin
    PdceMeasureUnSubscribe(hMeasure1);
    PdceClientUnRegister(hClient1);
    PdceCleanUp();
  end NoTRT_TEnd;
Parent topic: SNMP Functions


SnmpOpenConnectionEx Function

Action

This function opens a new connection to a target machine with access to SNMP data for the provided MIB. It returns a handle required by all other BDL SNMP extension functions. It supports both SNMPv1/2c and SNMP3.

Include file

Snmp.bdh

Syntax

SnmpOpenConnectionEx( in sMachine         : string,
                      in sMib             : string,
                      in sVersion         : string,
                      in sCommunity       : string optional,
                      in sAuthProtocol    : string optional,
                      in sPrivProtocol    : string optional,
                      in sAuthPassword    : string optional,
                      in sPrivPassword    : string optional,
                      in sSecurityName    : string optional,
                      in sSecurityLevel   : string optional,
                      in sSecurityModel   : string optional,
                      in sContextName     : string optional,
                      in sContextEngineID : string optional ): number;

Return value

Handle for open connection (0 on failure)

Parameter | Description
sMachine | Specifies target machine and port on which the smnp server is listening.
sMib | Specifies the name of the MIB.
sVersion | Specifies the version of the SNMP data.
sCommunity | Specifies the community of the SNMP data.
sAuthProtocol | Specifies the Authentication protocol of the SNMP data. (Version 3)
sPrivProtocol | Specifies the Privacy Protocol of the SNMP data. (Version 3)
sAuthPassword | Specifies the Authentication Password of the SNMP data. (Version 3)
sPrivPassword | Specifies the Privacy Password of the SNMP data. (Version 3)
sSecurityName | Specifies the Security Name of the SNMP data. (Version 3)
sSecurityLevel | Specifies the Security Level of the SNMP data. (Version 3)
sSecurityModel | Specifies the Security Model of the SNMP data. (Version 3)
sContextName | Specifies the Context Name of the SNMP data. (Version 3)
sContextEngineID | Specifies the Context Engine ID of the SNMP data. (Version 3)

Example

benchmark Collect

use "pdce.bdh"
use "snmp.bdh"

var
  measureMachine : string;
  measureMachineServer : string;
  measureMachinePort : string;

const
  MEASURE_VERSION             := "V3";
  MEASURE_NAME                := "System/Services";
  MEASURE_MIB                 := "SNMPv2-MIB";
  MEASURE_OID_NAME            := "system.sysServices";
  MEASURE_PRIVPWD             := "pwd12345678";
  MEASURE_AUTHPWD             := "pwd12345678";
  MEASURE_SECURITY_LEVEL      := "3";
  MEASURE_SECURITY_MODEL      := "3";
  MEASURE_SECURITY_NAME       := "testuser";
  MEASURE_CONTEXT_NAME        := "";
  MEASURE_CONTEXT_ENGINE_ID   := "";
  MEASURE_AUTH_PROTOCOL       := "MD5";
  MEASURE_PRIV_PROTOCOL       := "DES";

var
  nInterval         : number;
  hClient1          : number;
  hMeasure1         : number;
  sKey1             : string(1024);

dcluser
user
  Collect
transactions
  NoTRT_TStartup : begin;
  NoTRT_TCollect : 5;
  NoTRT_TEnd     : end;

dclfunc
  function PdceGetSnmpKey(sKey : string;
                          sMachine : string;
                          sMib : string;
                          sAuthProtocol : string;
                          sPrivProtocol : string;
                          sAuthPassword : string;
                          sPrivPassword : string;
                          sSecurityName : string;
                          sSecurityLevel : string;
                          sSecurityModel : string;
                          sContextName : string;
                          sContextEngineID : string;
                          sVersion : string;
                          sOidName : string;
                          nInstance : number optional) : boolean
  var
    sMibOid        : string(1024);
    sInstanceOid   : string(1024);
    sValue         : string(1024);
    sOid,sOid_old  : string(1024);
    hSnmp          : number;        // SNMP connection handle
    sKey_old       : string(1024);
  begin
    hSnmp := SnmpOpenConnectionEx(sMachine, sMib, sVersion, "",
                                sAuthProtocol, sPrivProtocol,
                                sAuthPassword, sPrivPassword,
                                sSecurityName, sSecurityLevel, sSecurityModel,
                                sContextName, sContextEngineID);
    if ( hSnmp <> 0 ) then
      if not SnmpGetMibOid(hSnmp, sOidName, sMibOid) then
        RepMessage("SnmpGetMibOid failed: "+sMibOid,SEVERITY_ERROR);
      end;

      Print("OID for " + sOidName + " : " + sMibOid);
      SnmpGetFirstInstanceOid(hSnmp, sMibOid, sInstanceOid);

      //old version
      Print("InstanceOid: " + sInstanceOid);
      sOid_old := sMibOid + "." + sInstanceOid;
      Print("Old Oid: " + sOid_old);
      sOid := SnmpGetValueOid(hSnmp, MEASURE_OID_NAME, "72", MEASURE_OID_NAME);
      Print("OID with first instance: " + sOid);
      if Stricmp(sOid,sOid_old) <> 0 then
        RepMessage("SnmpGetValueOid failed: "+sOid,SEVERITY_ERROR);
      end;
      if SnmpGetValue(hSnmp, sOid, sValue) then
        Print("Value: " + sValue);
      end;

      sKey := SnmpCreatePdceKeyEx(sOid, measureMachine, sVersion, "",
                                sAuthProtocol, sPrivProtocol,
                                sAuthPassword, sPrivPassword,
                                sSecurityName, sSecurityLevel, sSecurityModel,
                                sContextName, sContextEngineID);
      print(sKey);

//      manually added - no next interface available
      if SnmpGetNextInstanceOid(hSnmp, sInstanceOid) then
        print(sInstanceOid);
      else
        RepMessage("SnmpGetNextInstanceOid didn't find a next instance. "+sInstanceOid,SEVERITY_WARNING);
      end;

      PdceGetSnmpKey := true;
      SnmpCloseConnection( hSnmp )
    end;
    PdceGetSnmpKey := false;
  end PdceGetSnmpKey;

dcltrans
  transaction NoTRT_TStartup
  begin
    AttributeGetString("SNMPTestServer", measureMachineServer);
    AttributeGetString("SNMPTestServerPort", measureMachinePort);
    measureMachine := measureMachineServer+":"+measureMachinePort;
    print(measureMachine);
    PdceGetSnmpKey( sKey1, measureMachine, MEASURE_MIB, MEASURE_AUTH_PROTOCOL, MEASURE_PRIV_PROTOCOL,
                                MEASURE_AUTHPWD, MEASURE_PRIVPWD,
                                MEASURE_SECURITY_NAME, MEASURE_SECURITY_LEVEL, MEASURE_SECURITY_MODEL,
                                MEASURE_CONTEXT_NAME, MEASURE_CONTEXT_ENGINE_ID, MEASURE_VERSION, MEASURE_OID_NAME);
    PdceStartUp();
    PdceRegisterClient(hClient1, nInterval);
    PdceAddMeasure(hClient1, MEASURE_NAME, sKey1, hMeasure1);
    Wait(float(2*nInterval));
  end NoTRT_TStartup;

  transaction NoTRT_TCollect
  var
    fLastValue, fSum, fMin, fMax, fAvg, fStDev : float;
    uTimeStamp, uStatus  : number;
  begin
    PdceGetMeasureValue(hMeasure1, MEASURE_NAME);
    if (GetWorkloadModel() <> WORKLOAD_MONITORING) then
      Wait(float(nInterval));
    end;

    if PdceMeasureQueryValue(hMeasure1, fLastValue, fSum, fMin, fMax, fAvg, fStDev, uTimeStamp, uStatus) then
      Print("Query value: " + String(fLastValue) );
    end;
  end NoTRT_TCollect;

  transaction NoTRT_TEnd
  begin
    PdceMeasureUnSubscribe(hMeasure1);
    PdceClientUnRegister(hClient1);
    PdceCleanUp();
  end NoTRT_TEnd;
Parent topic: SNMP Functions


SnmpCreatePdceKey Function

Action

This function returns a valid PDCE key. The provided OID (snmp node in dotted notation), the target machine, the required community and the snmp protocol version are used to generate a key string, that can directly be used in the PdceAddMeasure() or PdceMeasureSubscribe() functions. For this function, sCommunity and sVersion have to be encoded in Base64.

Include file

Snmp.bdh

Syntax

SnmpCreatePdceKey( in sOid       : string,
                   in sMachine   : string,
                   in sCommunity : string,
                   in sVersion   : string ) : string;

Return value

A valid key string generated from provided data which can be used in further PDCE function calls.

Parameter | Description
sOid | Specifies SNMP OID in dotted notation.
sMachine | Specifies target machine and port on which the smnp server is listening.
sCommunity | Specifies the community of the SNMP data.
sVersion | Specifies the version of the SNMP data.

Example

benchmark Collect

 use "pdce.bdh"
 use "snmp.bdh"

const
  MEASURE_COMMUNITY   := "public";
  MEASURE_VERSION     := "V1";
  MEASURE_NAME        := "System/Services";
  MEASURE_MACHINE     := "machineName:161";
  MEASURE_MIB         := "RFC1213-MIB";
  MEASURE_OID_NAME    := "system.sysServices";

var
  nInterval         : number;
  hClient1          : number;
  hMeasure1         : number;
  sKey1             : string(1024);

dcluser
user
  Collect
transactions
  NoTRT_TStartup : begin;
  NoTRT_TCollect : 5;
  NoTRT_TEnd     : end;

dclfunc
  function PdceGetSnmpKey(sKey       : string;
                          sMachine   : string;
                          sMib       : string;
                          sCommunity : string;
                          sVersion   : string;
                          sOidName   : string;
                          nInstance  : number optional) : boolean

var
    sMibOid        : string(1024);
    sInstanceOid   : string(1024);
    sValue         : string(1024);
    sOid           : string(1024);
    hSnmp          : number;        // SNMP connection handle
begin

    hSnmp := SnmpOpenConnection(sMachine, sMib, sCommunity, sVersion);

    if ( hSnmp <> 0 ) then
                  SnmpGetMibOid(hSnmp, sOidName, sMibOid);

                  Print("OID for " + sOidName + " : " + sMibOid);

                  SnmpGetFirstInstanceOid(hSnmp, sMibOid, sInstanceOid);
                  while SnmpGetNextInstanceOid(hSnmp, sInstanceOid) do
                     sOid := sMibOid + "." + sInstanceOid;
                  end;

                  Print("OID with first instance: " + sOid);

                  if SnmpGetValue(hSnmp, sOid, sValue) then
                    Print("Value: " + sValue);
                  end;

                  sKey := SnmpCreatePdceKey(sOid, MEASURE_MACHINE, SNMP_COMMUNITY_PUBLIC, SNMP_VERSION_1);
                  PdceGetSnmpKey := true;

                  SnmpCloseConnection( hSnmp )
           end;

             PdceGetSnmpKey := false;

end PdceGetSnmpKey;

dcltrans
  transaction NoTRT_TStartup
  begin
       PdceGetSnmpKey( sKey1, MEASURE_Machine, MEASURE_MIB, MEASURE_COMMUNITY, MEASURE_VERSION, MEASURE_OID_NAME);
       PdceStartUp();
       PdceRegisterClient(hClient1, nInterval);
       PdceAddMeasure(hClient1, MEASURE_NAME, sKey1, hMeasure1);

      Wait(float(2*nInterval));
  end NoTRT_TStartup;

 transaction NoTRT_TCollect
  var
    fLastValue, fSum, fMin, fMax, fAvg, fStDev : float;
    uTimeStamp, uStatus  : number;
 begin
    PdceGetMeasureValue(hMeasure1, MEASURE_NAME);
    if (GetWorkloadModel() <> WORKLOAD_MONITORING) then
      Wait(float(nInterval));
 end;

  if PdceMeasureQueryValue(hMeasure1, fLastValue, fSum, fMin, fMax, fAvg, fStDev, uTimeStamp, uStatus) then
      Print("Query value: " + String(fLastValue) );
  end;
end NoTRT_TCollect;

transaction NoTRT_TEnd
begin
    PdceMeasureUnSubscribe(hMeasure1);
    PdceClientUnRegister(hClient1);
    PdceCleanUp();
end NoTRT_TEnd;

Parent topic: SNMP Functions


SnmpCreatePdceKeyEx Function

Action

This function returns a valid PDCE key. The provided OID (snmp node in dotted notation), the target machine, the snmp protocol version, and the required community (if version 1/2c) or the authentication details in terms of authentication protocol, privacy protocol, authentication password, privacy password, the security name, the securtiy level, teh security model, the context name, the context engine ID (if version 3) are used to generate a key s tring, that can directly be used in the PdceAddMeasure() or PdceMeasureSubscribe() functions. This function requires raw strings, not Base64-encoded strings.

Include file

Snmp.bdh

Syntax

SnmpCreatePdceKeyEx( in sOid             : string,
                     in sMachine         : string,
                     in sVersion         : string,
                     in sCommunity       : string,
                     in sAuthProtocol    : string,
                     in sPrivProtocol    : string,
                     in sAuthPassword    : string,
                     in sPrivPassword    : string,
                     in sSecurityName    : string,
                     in sSecurityLevel   : string,
                     in sSecurityModel   : string,
                     in sContextName     : string,
                     in sContextEngineID : string ) : string;

Return value

A valid key string generated from provided data which can be used in further PDCE function calls.

Parameter | Description
sOid | Specifies SNMP OID in dotted notation.
sMachine | Specifies target machine and port on which the smnp server is listening.
sVersion | Specifies the version of the SNMP data.
sCommunity | Specifies the community of the SNMP data. (version 1/2c)
sAuthProtocol | Specifies the authentication protocol of the SNMP data. (version 3)
sPrivProtocol | Specifies the privacy protocol of the SNMP data. (version 3)
sAuthPassword | Specifies the authentication protocol of the SNMP data. (version 3)
sPrivPassword | Specifies the privacy password of the SNMP data. (version 3)
sSecurityName | Specifies the security name of the SNMP data. (version 3)
sSecurityLevel | Specifies the securtiy level of the SNMP data. (version 3)
sSecurityModel | Specifies the security model of the SNMP data. (version 3)
sContextName | Specifies the context name of the SNMP data. (version 3)
sContextEngineID | Specifies the context engine ID of the SNMP data. (verison 3)

Example

benchmark Collect

use "pdce.bdh"
use "snmp.bdh"

var
  measureMachine : string;
  measureMachineServer : string;
  measureMachinePort : string;

const
  MEASURE_VERSION             := "V3";
  MEASURE_NAME                := "System/Services";
  MEASURE_MIB                 := "SNMPv2-MIB";
  MEASURE_OID_NAME            := "system.sysServices";
  MEASURE_PRIVPWD             := "pwd12345678";
  MEASURE_AUTHPWD             := "pwd12345678";
  MEASURE_SECURITY_LEVEL      := "3";
  MEASURE_SECURITY_MODEL      := "3";
  MEASURE_SECURITY_NAME       := "testuser";
  MEASURE_CONTEXT_NAME        := "";
  MEASURE_CONTEXT_ENGINE_ID   := "";
  MEASURE_AUTH_PROTOCOL       := "MD5";
  MEASURE_PRIV_PROTOCOL       := "DES";

var
  nInterval         : number;
  hClient1          : number;
  hMeasure1         : number;
  sKey1             : string(1024);

dcluser
user
  Collect
transactions
  NoTRT_TStartup : begin;
  NoTRT_TCollect : 5;
  NoTRT_TEnd     : end;

dclfunc
  function PdceGetSnmpKey(sKey : string;
                          sMachine : string;
                          sMib : string;
                          sAuthProtocol : string;
                          sPrivProtocol : string;
                          sAuthPassword : string;
                          sPrivPassword : string;
                          sSecurityName : string;
                          sSecurityLevel : string;
                          sSecurityModel : string;
                          sContextName : string;
                          sContextEngineID : string;
                          sVersion : string;
                          sOidName : string;
                          nInstance : number optional) : boolean
  var
    sMibOid        : string(1024);
    sInstanceOid   : string(1024);
    sValue         : string(1024);
    sOid,sOid_old  : string(1024);
    hSnmp          : number;        // SNMP connection handle
    sKey_old       : string(1024);
  begin
    hSnmp := SnmpOpenConnectionEx(sMachine, sMib, sVersion, "",
                                sAuthProtocol, sPrivProtocol,
                                sAuthPassword, sPrivPassword,
                                sSecurityName, sSecurityLevel, sSecurityModel,
                                sContextName, sContextEngineID);
    if ( hSnmp <> 0 ) then
      if not SnmpGetMibOid(hSnmp, sOidName, sMibOid) then
        RepMessage("SnmpGetMibOid failed: "+sMibOid,SEVERITY_ERROR);
      end;

      Print("OID for " + sOidName + " : " + sMibOid);
      SnmpGetFirstInstanceOid(hSnmp, sMibOid, sInstanceOid);

      //old version
      Print("InstanceOid: " + sInstanceOid);
      sOid_old := sMibOid + "." + sInstanceOid;
      Print("Old Oid: " + sOid_old);
      sOid := SnmpGetValueOid(hSnmp, MEASURE_OID_NAME, "72", MEASURE_OID_NAME);
      Print("OID with first instance: " + sOid);
      if Stricmp(sOid,sOid_old) <> 0 then
        RepMessage("SnmpGetValueOid failed: "+sOid,SEVERITY_ERROR);
      end;
      if SnmpGetValue(hSnmp, sOid, sValue) then
        Print("Value: " + sValue);
      end;

      sKey := SnmpCreatePdceKeyEx(sOid, measureMachine, sVersion, "",
                                sAuthProtocol, sPrivProtocol,
                                sAuthPassword, sPrivPassword,
                                sSecurityName, sSecurityLevel, sSecurityModel,
                                sContextName, sContextEngineID);
      print(sKey);

//      manually added - no next interface available
      if SnmpGetNextInstanceOid(hSnmp, sInstanceOid) then
        print(sInstanceOid);
      else
        RepMessage("SnmpGetNextInstanceOid didn't find a next instance. "+sInstanceOid,SEVERITY_WARNING);
      end;

      PdceGetSnmpKey := true;
      SnmpCloseConnection( hSnmp )
    end;
    PdceGetSnmpKey := false;
  end PdceGetSnmpKey;

dcltrans
  transaction NoTRT_TStartup
  begin
    AttributeGetString("SNMPTestServer", measureMachineServer);
    AttributeGetString("SNMPTestServerPort", measureMachinePort);
    measureMachine := measureMachineServer+":"+measureMachinePort;
    print(measureMachine);
    PdceGetSnmpKey( sKey1, measureMachine, MEASURE_MIB, MEASURE_AUTH_PROTOCOL, MEASURE_PRIV_PROTOCOL,
                                MEASURE_AUTHPWD, MEASURE_PRIVPWD,
                                MEASURE_SECURITY_NAME, MEASURE_SECURITY_LEVEL, MEASURE_SECURITY_MODEL,
                                MEASURE_CONTEXT_NAME, MEASURE_CONTEXT_ENGINE_ID, MEASURE_VERSION, MEASURE_OID_NAME);
    PdceStartUp();
    PdceRegisterClient(hClient1, nInterval);
    PdceAddMeasure(hClient1, MEASURE_NAME, sKey1, hMeasure1);
    Wait(float(2*nInterval));
  end NoTRT_TStartup;

  transaction NoTRT_TCollect
  var
    fLastValue, fSum, fMin, fMax, fAvg, fStDev : float;
    uTimeStamp, uStatus  : number;
  begin
    PdceGetMeasureValue(hMeasure1, MEASURE_NAME);
    if (GetWorkloadModel() <> WORKLOAD_MONITORING) then
      Wait(float(nInterval));
    end;

    if PdceMeasureQueryValue(hMeasure1, fLastValue, fSum, fMin, fMax, fAvg, fStDev, uTimeStamp, uStatus) then
      Print("Query value: " + String(fLastValue) );
    end;
  end NoTRT_TCollect;

  transaction NoTRT_TEnd
  begin
    PdceMeasureUnSubscribe(hMeasure1);
    PdceClientUnRegister(hClient1);
    PdceCleanUp();
  end NoTRT_TEnd;

Parent topic: SNMP Functions


SnmpCloseConnection Function

Action

This function closes the connection established by a call of SnmpOpenConnection().

Include file

Snmp.bdh

Syntax

SnmpCloseConnection( in hSnmp : number ): boolean;

Return value

  • true if successful

  • false otherwise

Parameter | Description
hSnmp | Handle from SnmpOpenConnection().

Example

benchmark Collect

use "pdce.bdh"
use "snmp.bdh"

const
  MEASURE_COMMUNITY   := "public";
  MEASURE_VERSION     := "V1";
  MEASURE_NAME        := "System/Services";
  MEASURE_MACHINE     := "machineName:161";
  MEASURE_MIB         := "RFC1213-MIB";
  MEASURE_OID_NAME    := "system.sysServices";

var
  nInterval         : number;
  hClient1          : number;
  hMeasure1         : number;
  sKey1             : string(1024);

dcluser
user
  Collect
transactions
  NoTRT_TStartup : begin;
  NoTRT_TCollect : 5;
  NoTRT_TEnd     : end;

dclfunc
  function PdceGetSnmpKey(sKey : string;
                          sMachine : string;
                          sMib : string;
                          sCommunity : string;
                            sVersion : string;
                          sOidName : string;
                          nInstance : number optional) : boolean

var
    sMibOid        : string(1024);
    sInstanceOid   : string(1024);
    sValue         : string(1024);
    sOid           : string(1024);
    hSnmp          : number;        // SNMP connection handle
begin

            hSnmp := SnmpOpenConnection(sMachine, sMib, sCommunity, sVersion);

            if ( hSnmp <> 0 ) then
                  SnmpGetMibOid(hSnmp, sOidName, sMibOid);

                  Print("OID for " + sOidName + " : " + sMibOid);

                  SnmpGetFirstInstanceOid(hSnmp, sMibOid, sInstanceOid);
                  sOid := sMibOid + "." + sInstanceOid;

                  Print("OID with first instance: " + sOid);

                  if SnmpGetValue(hSnmp, sOid, sValue) then
                    Print("Value: " + sValue);
                  end;

               sKey :=  "SNMP:" + sOid +"@" + MEASURE_MACHINE + "?" + SNMP_COMMUNITY_PUBLIC + "&" + SNMP_VERSION_1;
               PdceGetSnmpKey := true;

               SnmpCloseConnection( hSnmp )
            end;

              PdceGetSnmpKey := false;
            end PdceGetSnmpKey;

dcltrans
  transaction NoTRT_TStartup
  begin

           PdceGetSnmpKey( sKey1, MEASURE_Machine, MEASURE_MIB, MEASURE_COMMUNITY, MEASURE_VERSION, MEASURE_OID_NAME);

           PdceStartUp();
           PdceRegisterClient(hClient1, nInterval);
           PdceAddMeasure(hClient1, MEASURE_NAME, sKey1, hMeasure1);

           Wait(float(2*nInterval));
  end NoTRT_TStartup;

  transaction NoTRT_TCollect
      var    fLastValue, fSum, fMin, fMax, fAvg, fStDev : float;
    uTimeStamp, uStatus  : number;
  begin
    PdceGetMeasureValue(hMeasure1, MEASURE_NAME);
    if (GetWorkloadModel() <> WORKLOAD_MONITORING) then
      Wait(float(nInterval));
    end;

     if PdceMeasureQueryValue(hMeasure1, fLastValue, fSum, fMin, fMax, fAvg, fStDev, uTimeStamp, uStatus) then
       Print("Query value: " + String(fLastValue) );
    end;
  end NoTRT_TCollect;

  transaction NoTRT_TEnd
  begin
    PdceMeasureUnSubscribe(hMeasure1);
    PdceClientUnRegister(hClient1);
    PdceCleanUp();
  end NoTRT_TEnd;
Parent topic: SNMP Functions


SnmpGetNextInstanceOid Function

Action

Subsequent calls of this function return the next existing instance after a successful SnmpGetFirstInstanceOid() on target machine. If no instance was found the function fails.

Include file

Snmp.bdh

Syntax

SnmpGetNextInstanceOid( in  hSnmp        : number,
                        out sInstanceOid : string,
                        in  nInstOidSize : number optional ): boolean;

Return value

  • true if successful and instance was found

  • false otherwise

Parameter | Description
hSnmp | Handle from SnmpOpenConnection().
sInstanceOid | Returns the next instance.
nInstOidSize | Size of the buffer sInstanceOid (optional).

Example

  benchmark Collect

use "pdce.bdh"
use "snmp.bdh"

const
  MEASURE_COMMUNITY   := "public";
  MEASURE_VERSION     := "V1";
  MEASURE_NAME        := "System/Services";
  MEASURE_MACHINE     := "machineName:161";
  MEASURE_MIB         := "RFC1213-MIB";
  MEASURE_OID_NAME    := "system.sysServices";

var
  nInterval         : number;
  hClient1          : number;
  hMeasure1         : number;
  sKey1             : string(1024);

dcluser
user
  Collect
transactions
  NoTRT_TStartup : begin;
  NoTRT_TCollect : 5;
  NoTRT_TEnd     : end;

dclfunc
  function PdceGetSnmpKey(sKey : string;
                          sMachine : string;
                          sMib : string;
                          sCommunity : string;
                          sVersion : string;
                          sOidName : string;
                          nInstance : number optional) : boolean

var
    sMibOid        : string(1024);
    sInstanceOid   : string(1024);
    sValue         : string(1024);
    sOid           : string(1024);
    hSnmp          : number;        // SNMP connection handle
begin

    hSnmp := SnmpOpenConnection(sMachine, sMib, sCommunity, sVersion);

    if ( hSnmp <> 0 ) then
      SnmpGetMibOid(hSnmp, sOidName, sMibOid);

      Print("OID for " + sOidName + " : " + sMibOid);

      SnmpGetFirstInstanceOid(hSnmp, sMibOid, sInstanceOid);
      while SnmpGetNextInstanceOid(hSnmp, sInstanceOid) do
      sOid := sMibOid + "." + sInstanceOid;
      end;

      Print("OID with first instance: " + sOid);

      if SnmpGetValue(hSnmp, sOid, sValue) then
        Print("Value: " + sValue);
      end;

      sKey :=  "SNMP:" + sOid +"@" + MEASURE_MACHINE + "?" + SNMP_COMMUNITY_PUBLIC + "&" + SNMP_VERSION_1;
      PdceGetSnmpKey := true;

      SnmpCloseConnection( hSnmp )
    end;

    PdceGetSnmpKey := false;
  end PdceGetSnmpKey;

dcltrans
  transaction NoTRT_TStartup
  begin

    PdceGetSnmpKey( sKey1, MEASURE_Machine, MEASURE_MIB, MEASURE_COMMUNITY, MEASURE_VERSION, MEASURE_OID_NAME);

    PdceStartUp();
    PdceRegisterClient(hClient1, nInterval);
    PdceAddMeasure(hClient1, MEASURE_NAME, sKey1, hMeasure1);

    Wait(float(2*nInterval));
  end NoTRT_TStartup;

   transaction NoTRT_TCollect
   var
    fLastValue, fSum, fMin, fMax, fAvg, fStDev : float;
    uTimeStamp, uStatus  : number;
  begin
    PdceGetMeasureValue(hMeasure1, MEASURE_NAME);
    if (GetWorkloadModel() <> WORKLOAD_MONITORING) then
      Wait(float(nInterval));
    end;

    if PdceMeasureQueryValue(hMeasure1, fLastValue, fSum, fMin, fMax, fAvg, fStDev, uTimeStamp, uStatus) then
      Print("Query value: " + String(fLastValue) );
    end;
  end NoTRT_TCollect;

  transaction NoTRT_TEnd
  begin
    PdceMeasureUnSubscribe(hMeasure1);
    PdceClientUnRegister(hClient1);
    PdceCleanUp();
  end NoTRT_TEnd;
Parent topic: SNMP Functions


SnmpGetMibOid Function

Action

For each SNMP node, this function returns the corresponding OID in dotted notation from the MIB.

Include file

Snmp.bdh

Syntax

SnmpGetMibOid( in  hSnmp       : number,
               in  sOidName    : string,
               out sMibOid     : string,
               in  nMibOidSize : number optional ): boolean;

  • true if successful

  • false otherwise

Parameter | Description
hSnmp | Handle from SnmpOpenConnection().
sOidName | Name of the SNMP node in dotted notation.
sMibOid | Returns the OID in dotted notation.
nMibOidSize | Size of the buffer sMibOid (optional).

Example

benchmark Collect

use "pdce.bdh"
use "snmp.bdh"

const
  MEASURE_COMMUNITY   := "public";
  MEASURE_VERSION     := "V1";
  MEASURE_NAME        := "System/Services";
  MEASURE_MACHINE     := "machineName:161";
  MEASURE_MIB         := "RFC1213-MIB";
  MEASURE_OID_NAME    := "system.sysServices";

var
  nInterval         : number;
  hClient1          : number;
  hMeasure1         : number;
  sKey1             : string(1024);

dcluser
user
  Collect
transactions
  NoTRT_TStartup : begin;
  NoTRT_TCollect : 5;
  NoTRT_TEnd     : end;

dclfunc
  function PdceGetSnmpKey(sKey       : string;
                          sMachine   : string;
                          sMib       : string;
                          sCommunity : string;
                          sVersion   : string;
                          sOidName   : string;
                          nInstance  : number optional) : boolean

var
    sMibOid        : string(1024);
    sInstanceOid   : string(1024);
    sValue         : string(1024);
    sOid           : string(1024);
    hSnmp          : number;        // SNMP connection handle
begin

    hSnmp := SnmpOpenConnection(sMachine, sMib, sCommunity, sVersion);

    if ( hSnmp <> 0 ) then
      SnmpGetMibOid(hSnmp, sOidName, sMibOid);

      Print("OID for " + sOidName + " : " + sMibOid);

      SnmpGetFirstInstanceOid(hSnmp, sMibOid, sInstanceOid);
      sOid := sMibOid + "." + sInstanceOid;

      Print("OID with first instance: " + sOid);

      if SnmpGetValue(hSnmp, sOid, sValue) then
        Print("Value: " + sValue);
      end;

      sKey :=  "SNMP:" + sOid +"@" + MEASURE_MACHINE + "?" + SNMP_COMMUNITY_PUBLIC + "&" + SNMP_VERSION_1;
      PdceGetSnmpKey := true;

      SnmpCloseConnection( hSnmp )
    end;

    PdceGetSnmpKey := false;

  end PdceGetSnmpKey;

dcltrans
  transaction NoTRT_TStartup
  begin

    PdceGetSnmpKey( sKey1, MEASURE_Machine, MEASURE_MIB, MEASURE_COMMUNITY, MEASURE_VERSION, MEASURE_OID_NAME);
    PdceStartUp();
    PdceRegisterClient(hClient1, nInterval);
    PdceAddMeasure(hClient1, MEASURE_NAME, sKey1, hMeasure1);

    Wait(float(2*nInterval));
  end NoTRT_TStartup;

  transaction NoTRT_TCollect
  var
    fLastValue, fSum, fMin, fMax, fAvg, fStDev : float;
    uTimeStamp, uStatus  : number;
  begin
    PdceGetMeasureValue(hMeasure1, MEASURE_NAME);
    if (GetWorkloadModel() <> WORKLOAD_MONITORING) then
      Wait(float(nInterval));
    end;

    if PdceMeasureQueryValue(hMeasure1, fLastValue, fSum, fMin, fMax, fAvg, fStDev, uTimeStamp, uStatus) then
      Print("Query value: " + String(fLastValue) );
    end;
  end NoTRT_TCollect;

  transaction NoTRT_TEnd
  begin
    PdceMeasureUnSubscribe(hMeasure1);
    PdceClientUnRegister(hClient1);
    PdceCleanUp();
  end NoTRT_TEnd;
Parent topic: SNMP Functions


SnmpGetValue Function

Action

This function returns for a provided OID the actual value.

Include file

Snmp.bdh

Syntax

SnmpGetValue( in  hSnmp      : number,
              in  sOid       : string,
              out sValue     : string,
              in  nValueSize : number optional ): boolean;

Return value

  • true if successful

  • false otherwise

Parameter | Description
hSnmp | Handle from SnmpOpenConnection().
sOid | OID in dotted notation.
sValue | Returns actual value.
nValueSize | Size of the buffer sValue (optional).

Example

  benchmark Collect

use "pdce.bdh"
use "snmp.bdh"

const
  MEASURE_COMMUNITY   := "public";
  MEASURE_VERSION     := "V1";
  MEASURE_NAME        := "System/Services";
  MEASURE_MACHINE     := "machineName:161";
  MEASURE_MIB         := "RFC1213-MIB";
  MEASURE_OID_NAME    := "system.sysServices";

var
  nInterval         : number;
  hClient1          : number;
  hMeasure1         : number;
  sKey1             : string(1024);

dcluser
user
  Collect
transactions
  NoTRT_TStartup : begin;
  NoTRT_TCollect : 5;
  NoTRT_TEnd     : end;

dclfunc
  function PdceGetSnmpKey(sKey       : string;
                          sMachine   : string;
                          sMib       : string;
                          sCommunity : string;
                          sVersion   : string;
                          sOidName   : string;
                          nInstance  : number optional) : boolean

  var
    sMibOid        : string(1024);
    sInstanceOid   : string(1024);
    sValue         : string(1024);
    sOid           : string(1024);
    hSnmp          : number;         // SNMP connection handle
  begin

    hSnmp := SnmpOpenConnection(sMachine, sMib, sCommunity, sVersion);

    if ( hSnmp <> 0 ) then
      SnmpGetMibOid(hSnmp, sOidName, sMibOid);

      Print("OID for " + sOidName + " : " + sMibOid);

      SnmpGetFirstInstanceOid(hSnmp, sMibOid, sInstanceOid);
      while SnmpGetNextInstanceOid(hSnmp, sInstanceOid) do
        sOid := sMibOid + "." + sInstanceOid;
      end;

      Print("OID with first instance: " + sOid);

      if SnmpGetValue(hSnmp, sOid, sValue) then
        Print("Value: " + sValue);
      end;

      sKey :=  "SNMP:" + sOid +"@" + MEASURE_MACHINE + "?" + SNMP_COMMUNITY_PUBLIC + "&" + SNMP_VERSION_1;
      PdceGetSnmpKey := true;

      SnmpCloseConnection( hSnmp )
    end;

    PdceGetSnmpKey := false;

  end PdceGetSnmpKey;

dcltrans
  transaction NoTRT_TStartup
  begin

      PdceGetSnmpKey( sKey1, MEASURE_Machine, MEASURE_MIB, MEASURE_COMMUNITY, MEASURE_VERSION, MEASURE_OID_NAME);

      PdceStartUp();
      PdceRegisterClient(hClient1, nInterval);
      PdceAddMeasure(hClient1, MEASURE_NAME, sKey1, hMeasure1);

      Wait(float(2*nInterval));
  end NoTRT_TStartup;

transaction NoTRT_TCollect
var
    fLastValue, fSum, fMin, fMax, fAvg, fStDev : float;
    uTimeStamp, uStatus  : number;
  begin
    PdceGetMeasureValue(hMeasure1, MEASURE_NAME);
    if (GetWorkloadModel() <> WORKLOAD_MONITORING) then
      Wait(float(nInterval));
    end;

    if PdceMeasureQueryValue(hMeasure1, fLastValue, fSum, fMin, fMax, fAvg, fStDev, uTimeStamp, uStatus) then
      Print("Query value: " + String(fLastValue) );
    end;
  end NoTRT_TCollect;

  transaction NoTRT_TEnd
  begin
    PdceMeasureUnSubscribe(hMeasure1);
    PdceClientUnRegister(hClient1);
    PdceCleanUp();
  end NoTRT_TEnd;
Parent topic: SNMP Functions


SnmpGetValueOid Function

Action

This function uses a provided SNMP node and searches all instances of it until its value matches the desired value. Then this instance is used for the second SNMP node query and the valid OID (in dotted notation) for this node is returned. If some error occurs or no match is found an empty string is returned.

Include file

Snmp.bdh

Syntax

SnmpGetValueOid( in hSnmp          : number,
                 in sKeyOidName    : string,
                 in sKeyMatchValue : string,
                 in sParamName     : string ): string;

Return value

SNMP OID including instance for provided SNMP node in sValueOidName. Values for all instances for sKeyOidName are compared with provided sKeyMatchValue, and if a match is found, that instance is added to the OID of sValueOidName and returned. Otherwise an empty string is returned.

Parameter | Description
hSnmp | Handle from SnmpOpenConnection().
sKeyOidName | Name of SNMP node in dotted notation.
sKeyMatchValue | String that is used for comparison with values for instances of sKeyOidNames.
sParamName | Name of SNMP node in dotted notation.

Example

benchmark Collect

use "pdce.bdh"
use "snmp.bdh"

const
  MEASURE_MACHINE   := "machinename:161";    // machine + port
  MEASURE_COMMUNITY := "public";
  MEASURE_VERSION   := "V1";
  MEASURE_MIB       := "BEA-WEBLOGIC-MIB";
  MEASURE_OID_NAME1 := "bea.wls.webServerTable.webServerEntry.webServerLogFileFlushSecs";
  MEASURE_NAME01    := "webServer/LogFileFlushSeconds";
  MEASURE_OID_NAME2 := "bea.wls.webServerTable.webServerEntry.webServerName";
  MEASURE_OID_VALUE2:= "PIA";

var
  nInterval         : number;
  hClient01         : number;
  hMeasure01        : number;
  sKey1             : string(1024);

dcluser
user
  Collect
transactions
  NoTRT_TStartup : begin;
  NoTRT_TCollect : 5;
  NoTRT_TEnd     : end;

dclfunc
  function PdceGetSnmpKey(sKey       : string;
                          sMachine   : string;
                          sMib       : string;
                          sCommunity : string;
                          sVersion   : string;
                          sOidName   : string;
                          nInstance  : number optional) : boolean

  var
    sMibOid        : string(1024);
    sInstanceOid   : string(1024);
    sValue         : string(1024);
    sOid           : string(1024);
    bFoundInstance : boolean;
    hSnmp          : number;

   begin
    hSnmp := SnmpOpenConnection(sMachine, sMib, sCommunity, sVersion);

    if ( hSnmp <> 0 ) then
      SnmpGetMibOid(hSnmp, sOidName, sMibOid, sizeof(sMibOid));

      sOid := SnmpGetValueOid(hSnmp, MEASURE_OID_NAME2, MEASURE_OID_VALUE2, MEASURE_OID_NAME1);

      if SnmpGetValue(hSnmp, sOid, sValue, sizeof(sValue)) then
        Print("Test Value : " + sValue);
      end;

       sKey := SnmpCreatePdceKey(sOid, sMachine, sCommunity, sVersion);

       PdceGetSnmpKey := true;
       SnmpCloseConnection( hSnmp );

     end;

     PdceGetSnmpKey := false;

   end PdceGetSnmpKey;

dcltrans
  transaction NoTRT_TStartup
  begin
    PdceGetSnmpKey( sKey1, MEASURE_Machine, MEASURE_MIB, MEASURE_COMMUNITY, MEASURE_VERSION, MEASURE_OID_NAME1);

     PdceStartUp();
     PdceRegisterClient(hClient01, nInterval);
     PdceAddMeasure(hClient01, MEASURE_NAME01, sKey1, hMeasure01);

     Wait(float(2*nInterval));
  end NoTRT_TStartup;

   transaction NoTRT_TCollect
  var
    fLastValue, fSum, fMin, fMax, fAvg, fStDev : float;
    uTimeStamp, uStatus                        : number;
  begin
    PdceGetMeasureValue(hMeasure01, MEASURE_NAME01);

    if (GetWorkloadModel() <> WORKLOAD_MONITORING) then
      Wait(float(nInterval));
    end;

     if PdceMeasureQueryValue(hMeasure01, fLastValue, fSum, fMin, fMax, fAvg, fStDev, uTimeStamp, uStatus) then
      Print("Query value: " + String(fLastValue) );
    end;

   end NoTRT_TCollect;

   transaction NoTRT_TEnd
   begin
    PdceMeasureUnSubscribe(hMeasure01);
    PdceClientUnRegister(hClient01);
    PdceCleanUp();
  end NoTRT_TEnd;
Parent topic: SNMP Functions


.NET Framework Functions

Silk Performer provides the following functions for interaction with .NET objects:

  • DotNetLoadObject Function
    Loads a .NET Assembly and creates an instance of a .NET type.
  • DotNetFreeObject Function
    Releases the object handle, so that the garbage collector will free the object.
  • DotNetSetObject Function
    Sets an object as parameter for the next DotNetCallMethod or DotNetLoadObject call in an internal parameter array.
  • DotNetGetObject Function
    Gets the handle to the object returned by the last DotNetCallMethod call.
  • DotNetSetBool Function
    Sets a boolean parameter for the next DotNetCallMethod or DotNetLoadObject call in an internal parameter array.
  • DotNetGetBool Function
    Gets the boolean return value of the last DotNetCallMethod call in bReturn.
  • DotNetSetInt Function
    Sets an integer parameter for the next DotNetCallMethod or DotNetLoadObject call in an internal parameter array.
  • DotNetGetInt Function
    Gets the integer return value of the last DotNetCallMethod call in nReturn.
  • DotNetSetFloat Function
    Sets a float parameter for the next DotNetCallMethod or DotNetLoadObject call in an internal parameter array.
  • DotNetGetFloat Function
    Gets the float return value of the last DotNetCallMethod call in fReturn.
  • DotNetSetString Function
    Sets a string parameter for the next DotNetCallMethod or DotNetLoadObject call in an internal parameter array.
  • DotNetGetString Function
    Gets the string return value of the last DotNetCallMethod call in sReturn.
  • DotNetUnitTestCallMethod Function
    Calls a test method on a valid unit test object.
  • DotNetUnitTestFreeObject Function
    Releases the object handle, so that the garbage collector will free the object.
  • DotNetUnitTestLoadObject Function
    Loads a .NET Assembly and creates an instance of a .NET type.
  • DotNetCallMethod Function
    Calls a public method on the .NET object or a static method of a .NET type.
Parent topic: Benchmark Description Language (BDL) Reference


DotNetLoadObject Function

Action

Loads a .NET Assembly and creates an instance of a .NET type. A handle to this created object will be returned. When creating the object, the default constructor will be called. If you want to call a constructor that takes parameters you have to set these parameters with the DotNetSetXX functions prior to the call to DotNetLoadObject.

Include file

DotNetAPI.bdh

Syntax

DotNetLoadObject( in sAssemblyFile : string,
                  in sTypeName     : string,
                  in sTimer        : string optional ): number;

Return value

  • object handle if successful

  • 0 otherwise

Parameter | Description
sAssemblyFile | Path to the assembly file that contains the specified type. The path can be either absolute or relative. If the path is relative, it is either relative to the project or the data directory.
sTypeName | Full qualified type name (Namespace + TypeName) of the type that should be instantiated.
sTimer | (optional) If defined – a custom timer will be generated to measure the creation time of the object.

Example

dcltrans
  transaction TMain
  var
    hObject : number;
begin
  hObject := DotNetLoadObject("bin\\Release\\MyDotNet.dll", "MyDotNet.TestClass");
  DotNetCallMethod(hObject,"TestMethod");
  DotNetFreeObject(hObject);
end TMain;
Parent topic: .NET Framework Functions
Parent topic: Available BDL Functions for .NET Interoperability
Related reference
DotNetCallMethod Function
DotNetFreeObject Function


DotNetFreeObject Function

Action

Releases the object handle, so that the garbage collector will free the object.

Include file

DotNetAPI.bdh

Syntax

DotNetFreeObject( in hObject : number ): boolean;

Return value

  • true if successful

  • false otherwise

Parameter | Description
hObject | Handle to a .NET Object that will be released

Example

dcltrans
  transaction TMain
  var
    hObject : number;
begin
  hObject := DotNetLoadObject("bin\\Release\\MyDotNet.dll", "MyDotNet.TestClass");
  DotNetCallMethod(hObject,"TestMethod");
  DotNetFreeObject(hObject);
end TMain;
Parent topic: .NET Framework Functions
Parent topic: Available BDL Functions for .NET Interoperability
Related reference
DotNetCallMethod Function
DotNetLoadObject Function


DotNetSetObject Function

Action

Sets an object as parameter for the next DotNetCallMethod or DotNetLoadObject call in an internal parameter array. The parameters will be passed in the order they have been set to the internal array. After calling DotNetCallMethod or DotNetLoadObject the internal parameter array will be cleared.

Include file

DotNetAPI.bdh

Syntax

DotNetSetObject( in hObject : number,
                 in hParam  : number );
Parameter | Description
hObject | Handle to a .NET Object to set the parameter for the next DotNetCallMethod call or DOTNET_CONSTRUCTOR to set the parameter for the next DotNetLoadObject call.
hParam | .NET Object handle that should be passed as parameter to the next DotNetCallMethod on the passed .NET Object

Example

dcltrans
  transaction TMain
  var
    hObject, hObject2 : number;
    sReturnValue      : string;
  begin
    DotNetSetString(hObject, "ConstrValue1");

    hObject := DotNetLoadObject("bin\\Release\\MyDotNet.dll", "MyDotNet.TestClass");
    hObject2 := DotNetLoadObject("bin\\Release\\MyDotNet.dll", "MyDotNet.ParamClass");
    DotNetSetFloat(hObject, 1.23);
    DotNetSetInt(hObject, 123);
    DotNetSetBool(hObject, false);
    DotNetSetObject(hObject, hObject2);
    DotNetCallMethod(hObject,"TestMethod");
    DotNetGetString(hObject, sReturnValue);
    DotNetFreeObject(hObject);
    DotNetFreeObject(hObject2);
  end TMain;
Parent topic: .NET Framework Functions
Parent topic: Available BDL Functions for .NET Interoperability
Related reference
DotNetGetObject Function


DotNetGetObject Function

Action

Gets the handle to the object returned by the last DotNetCallMethod call. The returned object handle has to be freed with DotNetFreeObject.

Include file

DotNetAPI.bdh

Syntax

DotNetGetObject( in hObject  : number,
                 in nParamIx : number optional ): number;

Return value

  • object handle if successful

  • 0 otherwise

Parameter | Description
hObject | Handle to a .NET Object
nParamIx | Optional: If specified, gets the parameter index, else gets the last return value.

Example

dcltrans
  transaction TMain
  var
    hObject, hObject2 : number;
    hReturn           : number;
  begin
    DotNetSetString(hObject, "ConstrValue1");

    hObject := DotNetLoadObject("bin\\Release\\MyDotNet.dll", "MyDotNet.TestClass");
    hObject2 := DotNetLoadObject("bin\\Release\\MyDotNet.dll", "MyDotNet.ParamClass");
    DotNetSetFloat(hObject, 1.23);
    DotNetSetInt(hObject, 123);
    DotNetSetBool(hObject, false);
    DotNetSetObject(hObject, hObject2);
    DotNetCallMethod(hObject,"TestMethod");

    hReturn := DotNetGetObject(hObject);

    DotNetFreeObject(hObject);
    DotNetFreeObject(hObject2);
    DotNetFreeObject(hReturn);
  end TMain;
Parent topic: .NET Framework Functions
Parent topic: Available BDL Functions for .NET Interoperability
Related reference
DotNetSetObject Function


DotNetSetBool Function

Action

Sets a boolean parameter for the next DotNetCallMethod or DotNetLoadObject call in an internal parameter array. The parameters will be passed in the order they have been set to the internal array. After calling DotNetCallMethod or DotNetLoadObject the internal parameter array will be cleared.

Include file

DotNetAPI.bdh

Syntax

DotNetSetBool( in hObject : number,
               in bParam  : boolean );
Parameter | Description
hObject | Handle to a .NET Object to set the parameter for the next DotNetCallMethod call or DOTNET_CONSTRUCTOR to set the parameter for the next DotNetLoadObject call.
bParam | Boolean value that should be passed as parameter to the next DotNetCallMethod on the passed .NET Object

Example

dcltrans
  transaction TMain
  var
    hObject, hObject2 : number;
    sReturnValue      : string;
  begin
    DotNetSetString(hObject, "ConstrValue1");

    hObject := DotNetLoadObject("bin\\Release\\MyDotNet.dll", "MyDotNet.TestClass");
    hObject2 := DotNetLoadObject("bin\\Release\\MyDotNet.dll", "MyDotNet.ParamClass");
    DotNetSetFloat(hObject, 1.23);
    DotNetSetInt(hObject, 123);
    DotNetSetBool(hObject, false);
    DotNetSetObject(hObject, hObject2);
    DotNetCallMethod(hObject,"TestMethod");
    DotNetGetString(hObject, sReturnValue);
    DotNetFreeObject(hObject);
    DotNetFreeObject(hObject2);
  end TMain;
Parent topic: .NET Framework Functions
Parent topic: Available BDL Functions for .NET Interoperability
Related reference
DotNetGetBool Function


DotNetGetBool Function

Action

Gets the boolean return value of the last DotNetCallMethod call in bReturn.

Include file

DotNetAPI.bdh

Syntax

DotNetGetBool( in    hObject : number,
               inout bReturn : boolean ): boolean;

Return value

  • true if successful

  • false otherwise

Parameter | Description
hObject | Handle to a .NET Object
bReturn | Boolean variable that will receive the return value of the last DotNetCallMethod call

Example

dcltrans
  transaction TMain
  var
    hObject, hObject2 : number;
    bReturn           : boolean;
  begin
    DotNetSetString(hObject, "ConstrValue1");
    hObject := DotNetLoadObject("bin\\Release\\MyDotNet.dll", "MyDotNet.TestClass");
    hObject2 := DotNetLoadObject("bin\\Release\\MyDotNet.dll", "MyDotNet.ParamClass");
    DotNetSetFloat(hObject, 1.23);
    DotNetSetInt(hObject, 123);
    DotNetSetBool(hObject, false);
    DotNetSetObject(hObject, hObject2);
    DotNetCallMethod(hObject,"TestMethod");
    DotNetGetBool(hObject, bReturn);
    DotNetFreeObject(hObject);
    DotNetFreeObject(hObject2);
  end TMain;
Parent topic: .NET Framework Functions
Parent topic: Available BDL Functions for .NET Interoperability
Related reference
DotNetSetBool Function


DotNetSetInt Function

Action

Sets an integer parameter for the next DotNetCallMethod or DotNetLoadObject call in an internal parameter array. The parameters will be passed in the order they have been set to the internal array. After calling DotNetCallMethod or DotNetLoadObject the internal parameter array will be cleared.

Include file

DotNetAPI.bdh

Syntax

DotNetSetInt( in hObject : number,
              in nParam  : number );
Parameter | Description
hObject | Handle to a .NET Object to set the parameter for the next DotNetCallMethod call or DOTNET_CONSTRUCTOR to set the parameter for the next DotNetLoadObject call.
nParam | Integer value that should be passed as parameter to the next DotNetCallMethod on the passed .NET Object

Example

dcltrans
  transaction TMain
  var
    hObject, hObject2 : number;
    sReturnValue      : string;
  begin
    DotNetSetString(hObject, "ConstrValue1");

    hObject := DotNetLoadObject("bin\\Release\\MyDotNet.dll", "MyDotNet.TestClass");
    hObject2 := DotNetLoadObject("bin\\Release\\MyDotNet.dll", "MyDotNet.ParamClass");
    DotNetSetFloat(hObject, 1.23);
    DotNetSetInt(hObject, 123);
    DotNetSetBool(hObject, false);
    DotNetSetObject(hObject, hObject2);
    DotNetCallMethod(hObject,"TestMethod");
    DotNetGetString(hObject, sReturnValue);
    DotNetFreeObject(hObject);
    DotNetFreeObject(hObject2);
  end TMain;
Parent topic: .NET Framework Functions
Parent topic: Available BDL Functions for .NET Interoperability
Related reference
DotNetGetInt Function


DotNetGetInt Function

Action

Gets the integer return value of the last DotNetCallMethod call in nReturn.

Include file

DotNetAPI.bdh

Syntax

DotNetGetInt( in    hObject : number,
              inout nReturn : number ): boolean;

Return value

  • true if successful

  • false otherwise

Parameter | Description
hObject | Handle to a .NET Object
nReturn | Integer variable that will receive the return value of the last DotNetCallMethod call

Example

dcltrans
  transaction TMain
  var
    hObject, hObject2 : number;
    nReturn           : number;
  begin
    DotNetSetString(hObject, "ConstrValue1");

    hObject := DotNetLoadObject("bin\\Release\\MyDotNet.dll", "MyDotNet.TestClass");
    hObject2 := DotNetLoadObject("bin\\Release\\MyDotNet.dll", "MyDotNet.ParamClass");
    DotNetSetFloat(hObject, 1.23);
    DotNetSetInt(hObject, 123);
    DotNetSetBool(hObject, false);
    DotNetSetObject(hObject, hObject2);
    DotNetCallMethod(hObject,"TestMethod");
    DotNetGetInt(hObject, nReturn);
    DotNetFreeObject(hObject);
    DotNetFreeObject(hObject2);
  end TMain;
Parent topic: .NET Framework Functions
Parent topic: Available BDL Functions for .NET Interoperability
Related reference
DotNetSetInt Function


DotNetSetFloat Function

Action

Sets a float parameter for the next DotNetCallMethod or DotNetLoadObject call in an internal parameter array. The parameters will be passed in the order they have been set to the internal array. After calling DotNetCallMethod or DotNetLoadObject the internal parameter array will be cleared.

Include file

DotNetAPI.bdh

Syntax

DotNetSetFloat( in hObject : number,
                in fParam  : float );
Parameter | Description
hObject | Handle to a .NET Object to set the parameter for the next DotNetCallMethod call or DOTNET_CONSTRUCTOR to set the parameter for the next DotNetLoadObject call.
fParam | Float value that should be passed as parameter to the next DotNetCallMethod on the passed .NET Object

Example

dcltrans
  transaction TMain
  var
    hObject, hObject2 : number;
    sReturnValue      : string;
  begin
    DotNetSetString(hObject, "ConstrValue1");

    hObject := DotNetLoadObject("bin\\Release\\MyDotNet.dll", "MyDotNet.TestClass");
    hObject2 := DotNetLoadObject("bin\\Release\\MyDotNet.dll", "MyDotNet.ParamClass");
    DotNetSetFloat(hObject, 1.23);
    DotNetSetInt(hObject, 123);
    DotNetSetBool(hObject, false);
    DotNetSetObject(hObject, hObject2);
    DotNetCallMethod(hObject,"TestMethod");
    DotNetGetString(hObject, sReturnValue);
    DotNetFreeObject(hObject);
    DotNetFreeObject(hObject2);
  end TMain;
Parent topic: .NET Framework Functions
Parent topic: Available BDL Functions for .NET Interoperability
Related reference
DotNetGetFloat Function


DotNetGetFloat Function

Action

Gets the float return value of the last DotNetCallMethod call in fReturn.

Include file

DotNetAPI.bdh

Syntax

DotNetGetFloat( in    hObject : number,
                inout fReturn : float ): boolean;

Return value

  • true if successful

  • false otherwise

Parameter | Description
hObject | Handle to a .NET Object
fReturn | Float variable that will receive the return value of the last DotNetCallMethod call

Example

dcltrans
  transaction TMain
  var
    hObject, hObject2 : number;
    fReturn : float;
  begin
    DotNetSetString(hObject, "ConstrValue1");

    hObject := DotNetLoadObject("bin\\Release\\MyDotNet.dll", "MyDotNet.TestClass");
    hObject2 := DotNetLoadObject("bin\\Release\\MyDotNet.dll", "MyDotNet.ParamClass");
    DotNetSetFloat(hObject, 1.23);
    DotNetSetInt(hObject, 123);
    DotNetSetBool(hObject, false);
    DotNetSetObject(hObject, hObject2);
    DotNetCallMethod(hObject,"TestMethod");
    DotNetGetFloat(hObject, fReturn);
    DotNetFreeObject(hObject);
    DotNetFreeObject(hObject2);
  end TMain;
Parent topic: .NET Framework Functions
Parent topic: Available BDL Functions for .NET Interoperability
Related reference
DotNetSetFloat Function


DotNetSetString Function

Action

Sets a string parameter for the next DotNetCallMethod or DotNetLoadObject call in an internal parameter array. The parameters will be passed in the order they have been set to the internal array. After calling DotNetCallMethod or DotNetLoadObject the internal parameter array will be cleared.

Include file

DotNetAPI.bdh

Syntax

DotNetSetString( in hObject : number,
                 in sParam  : string );
Parameter | Description
hObject | Handle to a .NET Object to set the parameter for the next DotNetCallMethod call or DOTNET_CONSTRUCTOR to set the parameter for the next DotNetLoadObject call.
sParam | String value that should be passed as parameter to the next DotNetCallMethod on the passed .NET Object

Example

dcltrans
  transaction TMain
  var
    hObject, hObject2 : number;
    sReturnValue      : string;
  begin
    DotNetSetString(hObject, "ConstrValue1");

    hObject := DotNetLoadObject("bin\\Release\\MyDotNet.dll", "MyDotNet.TestClass");
    hObject2 := DotNetLoadObject("bin\\Release\\MyDotNet.dll", "MyDotNet.ParamClass");
    DotNetSetFloat(hObject, 1.23);
    DotNetSetInt(hObject, 123);
    DotNetSetBool(hObject, false);
    DotNetSetObject(hObject, hObject2);
    DotNetCallMethod(hObject,"TestMethod");
    DotNetGetString(hObject, sReturnValue);
    DotNetFreeObject(hObject);
    DotNetFreeObject(hObject2);
  end TMain;
Parent topic: .NET Framework Functions
Parent topic: Available BDL Functions for .NET Interoperability
Related reference
DotNetGetString Function


DotNetGetString Function

Action

Gets the string return value of the last DotNetCallMethod call in sReturn. Parameter sRetLen defines the size of the sReturn string buffer.

Include file

DotNetAPI.bdh

Syntax

DotNetGetString( in    hObject : number,
                 inout sReturn : string,
                 in    nRetLen : number optional ) :boolean;

Return value

  • true if successful

  • false otherwise

Parameter | Description
hObject | Handle to a .NET Object.
sReturn | String buffer that will receive the return value of the last DotNetCallMethod call.
nRetLen | Size of the string buffer passed in sReturn (optional).

Example

dcltrans
  transaction TMain
  var
    hObject, hObject2 : number;
    sReturnValue : string;
  begin
    DotNetSetString(hObject, "ConstrValue1");

    hObject := DotNetLoadObject("bin\\Release\\MyDotNet.dll", "MyDotNet.TestClass");
    hObject2 := DotNetLoadObject("bin\\Release\\MyDotNet.dll", "MyDotNet.ParamClass");
    DotNetSetFloat(hObject, 1.23);
    DotNetSetInt(hObject, 123);
    DotNetSetBool(hObject, false);
    DotNetSetObject(hObject, hObject2);
    DotNetCallMethod(hObject,"TestMethod");
    DotNetGetString(hObject, sReturnValue);
    DotNetFreeObject(hObject);
    DotNetFreeObject(hObject2);
  end TMain;
Parent topic: .NET Framework Functions
Parent topic: Available BDL Functions for .NET Interoperability
Related reference
DotNetSetString Function


DotNetUnitTestCallMethod Function

Action

This method can be used to call a test method on a valid unit test object. The object needs to be loaded with DotNetUnitTestLoadObject in order to perform all actions that the execution engine of a unit testing framework. DotNetUnitTestLoadObject gathers all information about special Initialize(SetUp) and Cleanup (TearDown) methods that will be called right before and right after the test method.

The supported unit testing frameworks are:

  • Silk Performer .NET Framework

  • NUnit Test Framework

  • Microsoft's unit testing framework (Microsoft Visual Studio 2013, 2015, 2017)

All frameworks offer the functionality of those Initialize and Cleanup methods that will be called by this method call if they exist. Furthermore - Ignore and Expected Exception attriutes will also be handled.

Exceptions that will be catched - either expected or not - will be logged to the TrueLog and to the output log file. If Console redirection is enabled - the standard and error console output will also be logged to the TrueLog and respectivly to the .wrt and .err file.

Methods with the Ignore attribute will not be called. DotNetUnitTestCallMethod will raise an error with severity warning.

DotNetUnitTestCallMethod will raise an error if a method throws an unexpected exceptions.

Include file

DotNetAPI.bdh

Syntax

DotNetUnitTestCallMethod( in    hObject     : number,
                          inout sMethodName : string,
                          in    sTimer      : string optional ): boolean;

Return value

  • true if successful

  • false otherwise

Parameter | Description
hObject | Handle to a .NET Object
sMethodName | Method that should be called
sTimer | (optional) If defined – a custom timer will be generated to measure the creation time of the object. If the Unit Test class defines a SetUp and/or TearDown method, additional measures will be generated for these additional method calls. The measure name will be {sTimer}_SetUp and {sTimer}_TearDown.

Example

dcltrans
  transaction TMain
  var
    hObject : number;
  begin
    DotNetSetOption(DOTNET_OPT_REDIRECT_CONSOLE, 1);
    hObject := DotNetUnitTestLoadObject("bin\\Release\\MyDotNet.dll", "MyDotNet.TestClass");
    DotNetUnitTestCallMethod(hObject,"TestMethod");
    DotNetUnitTestFreeObject(hObject);
  end TMain;
Parent topic: .NET Framework Functions
Related reference
DotNetUnitTestFreeObject Function
DotNetUnitTestLoadObject Function


DotNetUnitTestFreeObject Function

Action

Releases the object handle, so that the garbage collector will free the object. The object should be loaded with DotNetUnitTestLoadObject in order to work correctly.

Before the object is freed it is possible that a global CleanUp method will be called. Following unit testing frameworks support a unit-test wide CleanUp method:

  • Silk Performer .NET Framework

  • NUnit Test Framework

  • Microsoft's unit testing framework (Microsoft Visual Studio 2013, 2015, 2017)

During DotNetUnitTestLoadObject the information about such a method is gathered. If such a method exists, it will be called right before the object is freed.

Include file

DotNetAPI.bdh

Syntax

DotNetUnitTestFreeObject( in hObject: number,
                          in sTimer : string optional ): boolean;

Return value

  • true if successful

  • false otherwise

Parameter | Description
hObject | Handle to a .NET Object that will be released.
sTimer | (optional) If the Unit Test class defines a global TearDown method an additional measure will be generated for this additional method call. The measure name will be {sTimer}_GlobalTearDown.

Example

dcltrans
  transaction TMain
  var
    hObject : number;
  begin
    DotNetSetOption(DOTNET_OPT_REDIRECT_CONSOLE, 1);
    hObject := DotNetUnitTestLoadObject("bin\\Release\\MyDotNet.dll", "MyDotNet.TestClass");
    DotNetUnitTestCallMethod(hObject,"TestMethod");
    DotNetUnitTestFreeObject(hObject);
  end TMain;
Parent topic: .NET Framework Functions
Related reference
DotNetUnitTestCallMethod Function
DotNetUnitTestLoadObject Function


DotNetUnitTestLoadObject Function

Action

Loads a .NET Assembly and creates an instance of a .NET type. A handle to this created object will be returned.

When creating the object, the default constructor will be called. If you want to call a constructor that takes parameters you have to set these parameters with the DotNetSetXX functions prior to the call to DotNetLoadObject.

The difference to DotNetLoadObject is that this method checks whether the instantiated type is unit test conform. Currently - 3 unit testing frameworks are supported:

  • Silk Performer .NET Framework

  • NUnit Test Framework

  • Microsoft's unit testing framework (Microsoft Visual Studio 2013, 2015, 2017)

The method inspects the type for the custom attributes of the above mentioned test frameworks. If the class defines a method that should be called once the class is loaded - the method will be called right after it is instantiated. If there is a corresponding cleanup method - the cleanup method will be called when the object is unloaded with DotNetUnitTestFreeObject.

Initialize (SetUp) and CleanUp (TearDown) methods will be called by DotNetUnitTestCallMethod.

It is recommended to redirect the console output to Silk Performer logfile's. This should be done because above mentioned test framework do it as well. Redirection can be enabled by the new option DOTNET_OPT_REDIRECT_CONSOLE which can be set with DotNetSetOption.

Include file

DotNetAPI.bdh

Syntax

DotNetUnitTestLoadObject( inout sAssemblyFile : string,
                          inout sTypeName     : string,
                          in    sTimer        : string optional ): number;

Return value

  • object handle if successful

  • 0 otherwise

Parameter | Description
sAssemblyFile | Path to the assembly file that contains the specified type. The path can be either absolute or relative. If the path is relative, it is either relative to the project or the data directory.
sTypeName | Full qualified type name (Namespace + TypeName) of the type that should be instantiated.
sTimer | (optional) If defined – a custom timer will be generated to measure the creation time of the object. If the Unit Test class defines a global SetUp method an additional measure will be generated for this additional method call. The measure name will be {sTimer}_GlobalSetUp.

Example

dcltrans
  transaction TMain
  var
    hObject : number;
  begin
    DotNetSetOption(DOTNET_OPT_REDIRECT_CONSOLE, 1);
    hObject := DotNetUnitTestLoadObject("bin\\Release\\MyDotNet.dll", "MyDotNet.TestClass");
    DotNetUnitTestCallMethod(hObject,"TestMethod");
    DotNetUnitTestFreeObject(hObject);
  end TMain;
Parent topic: .NET Framework Functions
Related reference
DotNetUnitTestCallMethod Function
DotNetUnitTestFreeObject Function


DotNetCallMethod Function

Action

Calls a public method on the .NET object or a static method of a .NET type. If parameters have been set with the DotNetSetXX methods, these parameters will be passed in the order of the DotNetSetXX calls. If you want to call a static method you have to use the constant DOTNET_STATIC_METHOD as object handle for the DotNetCallMethod and the DotNetSetXX methods. Another way to pass parameters to and from the method is to use the AttributeXX functions. The .NET Method can use the perfDotNetFW.dll to call into the Silk Performer runtime to get/set attributes (Bdl.AttributeGet, Bdl.AttributeSet).

If the function returns a value, this value can be retrieved with the DotNetGetXX methods. Again - if calling a static method - use DOTNET_STATIC_METHOD as object handle.

Include file

DotNetAPI.bdh

Syntax

DotNetCallMethod( in hObject     : number,
                  in sMethodName : string,
                  in sTypeName   : string optional,
                  in sAssembly   : string optional,
                  in sTimer      : string optional ): boolean;

Return value

  • true if successful

  • false otherwise

Parameter | Description
hObject

Handle to a .NET Object

or

DOTNET_STATIC_METHOD if you want to call a static method. In this case you have to at least specify the name of the .NET type (class) you want to call the method.

sMethodName | Method that should be called
sTypeName

(optional)

If you want to call a static method this parameter specifies the .NET type (class) of the method.
sAssembly

(optional)

If you want to call a static method and this parameter is omitted the type specified in sTypeName is searched in the currently loaded assemblies.

If you haven't loaded the assembly where sTypeName is implemented you can specify the assembly file here and it will be loaded. Assemblies are normally loaded during DotNetLoadObject.

The basic .NET assembly (mscorlib) is always loaded - so you can access all static methods of the basic classes.
sTimer

(optional)

If defined – a custom timer will be generated to measure the execution time of the method call.

Example

dcltrans
  transaction TMain
  var
    hObject, nValue : number;
  begin
    // load an object and call a method on this instance
    hObject := DotNetLoadObject("C:\\MyDotNet\\Bin\\Release\\MyDotNet.dll", "MyDotNet.TestClass");
    DotNetCallMethod(hObject,"TestMethod");
    DotNetFreeObject(hObject);
    // call a static method - no additional assembly needs to be loaded because DateTime is defined in mscorlib
    DotNetSetInt(DOTNET_STATIC_METHOD, 2003);
    DotNetSetInt(DOTNET_STATIC_METHOD, 2);
    DotNetCallMethod(DOTNET_STATIC_METHOD, "DaysInMonth", "System.DateTime");
    DotNetGetInt(DOTNET_STATIC_METHOD, nValue);
  end TMain;
Parent topic: .NET Framework Functions
Parent topic: Available BDL Functions for .NET Interoperability
Related reference
DotNetLoadObject Function
DotNetFreeObject Function


GUI-Level Testing Functions

  • Silk Test Automation Functions Overview
    Via its own session manager, Silk Performer uses Silk Test, Micro Focus’s functional testing tool, to communicate with and control sessions (Silk Test likewise communicates with Silk Performer via the session manager).
  • UFT Developer (Silk4J) Functions Overview
    Via its own session manager, Silk Performer uses UFT Developer (Silk4J) to test JUnit tests.
  • Silk4NET Functions Overview
    Via its own session manager, Silk Performer uses UFT Developer (Silk4NET) to test MSTest unit tests.
  • Silk Keyword-driven Testing Functions Overview
Parent topic: Benchmark Description Language (BDL) Reference


Silk Test Automation Functions Overview

Silk Performer supports load testing of fat-client applications. To load test these applications, Silk Performer uses Windows Terminal Services to connect to and open client sessions on agent computers. Via its own session manager, Silk Performer uses Silk Test, Micro Focus’s functional testing tool, to communicate with and control sessions (Silk Test likewise communicates with Silk Performer via the session manager). Silk Test launches clients, runs GUI-level tests, and communicates results back to Silk Performer via the session manager. Silk Performer ultimately collects the results and makes them available to end-users.

  • StExecuteTestcase Function
    Starts an execution in Silk Test and collects the results of the execution.
  • StInit Function
    The StInit function starts Silk Test.
  • StInitSession Function
    Connects to a Windows Terminal Server session and opens a remote desktop user session.
  • StLoadProject Function
    Instructs Silk Test to load a Silk Test package file.
  • StLogoffSession Function
    Closes Silk Test and disconnects from the Windows Terminal Server session.
  • StResetSilkTest Function
    Closes Silk Test and then restarts it.
  • StSetConnectionTimeOut Function
    Sets a timeout for connection to a Windows Terminal Server session.
  • StSetExecutionTimeOut Function
    Sets the timeout for the execution of a testcase.
  • StSetOption Function
    Sets Silk Test-specific options.
Parent topic: GUI-Level Testing Functions
Related concepts
GUI-Level Testing Support


StExecuteTestcase Function

Action

StExecuteTestcase starts an execution in Silk Test and collects the results of the execution. The script file can be provided with an absolute path if no project has been loaded. When a package is loaded by Silk Test, the relative path of the script within the package must be used.

Include file

StAutomation.bdh

Syntax

StExecuteTestcase(
      in sScript   : string,
      in sTestCase : string,
      in sTestData : string,
      in sTimer    : string ): boolean;

Return value

  • true if the execution was successful

  • false otherwise

Parameter | Description
sScript | The script name of the Silk Test script. If a package has been loaded, the relative path (within the package) of the script must be provided. If no package has been loaded, the script should be added to the data files and only the name of the script must be provided.
sTestCase | The name of the testcase you want to execute.
sTestData | The test data that must be passed to the testcase. Strings that are passed must begin and end with an \".
sTimer | The name of the timer for the StExecuteTestcase function. The timer starts when Silk Test gets the information to execute a testcase and stops when Silk Test finishes the execution.

Example

transaction TMain
var
  sUser     : string;
  sPassword : string;
begin
  AttributeGetString("Username", sUser);
  AttributeGetString("Password", sPassword);
  if(StInitSession(sUser, sPassword)) then
    StLoadProject("package.stp");
    StSetOption(ST_OPTION_TRUELOG_OPTIONS,ST_TRUELOG_ALL);
    StExecuteTestcase("scriptFile.t", "testcase", "\" testdata\",10", "MyTimer1");
    StLogoffSession();
  end;
end TMain;
Parent topic: Silk Test Automation Functions Overview


StInit Function

Action

The StInit function starts Silk Test. It is used only for web application testing (but not for mobile) and does not start a new session. Therefore, you need to enable Use particular user account in the system settings: Click Settings > System > Agents > Advanced and enable the option. All started virtual users are using the same Silk Test process within the current session.
Note: Browser type settings defined using this function override profile settings that were configured in the profile settings: Profile settings > GUI-Level Testing > Execution > Browser type setting. When the optional uBrowserType parameter is omitted, the profile settings are used. The default browser type is the one that was specified during the import of the test.

Include file

StAutomation.bdh

Syntax

StInit( uBrowserType : in number optional := BROWSER_TYPE_DEFAULT ): boolean;

Return value

  • true if successful

  • false otherwise

Parameter Description
uBrowserType Optional: Sets the browser type. Possible values are:
  • BROWSER_TYPE_DEFAULT := 0;
  • BROWSER_TYPE_CHROME := 1;
  • BROWSER_TYPE_FIREFOX := 2;
  • BROWSER_TYPE_PHANTOMJS := 3;

Example

dcltrans
  transaction TInit
  begin
    StInit();
  end TInit;

  transaction TTest
  begin
    StLoadProject("package.stp");
    StSetOption(ST_OPTION_TRUELOG_OPTIONS,ST_TRUELOG_ALL);
    StExecuteTestcase("scriptFile.t", "testcase", "\" testdata\",10", "MyTimer1");
    StLogoffSession();

  end TTest;
Parent topic: Silk Test Automation Functions Overview


StInitSession Function

Action

The StInitSession function connects to a Windows Terminal Server session and opens a remote desktop user session. When the connection is established, Silk Test is started in the session. If no username or password are provided, the function uses the user name and password that are saved in the profile settings. If you want to run the test on your local console, do not set user credentials in the profile settings or the script.
Note: Color depth settings defined using this function override profile settings configured via Silk Performer at Profile settings > GUI-Level Testing > General > Session settings. When the optional uColorDepth parameter is omitted, profile settings are used. The default color-depth setting is 16 bit.

The server may limit maximum color depth. The client can not force a color depth setting that is higher than is supported by the server. Please see Terminal Services Configuration documentation for details about your server version's color-depth limitations.

By default StInitSession raises an error with the severity SEVERITY_PROCESS_EXIT if the function fails to start a valid session. The severity of that error can be adjusted by a custom event handler function (see "Event Handler Section"). When an error with SEVERITY_PROCESS_EXIT occurs the rest of the script is ignored and no unsaved results data or measurements will be saved.

Include file

StAutomation.bdh

Syntax

StInitSession( sUser          : in string optional,
               sPassword      : in string optional,
               uColorDepth    : in number optional,
               uDesktopWidth  : in number optional,
               uDesktopHeight : in number optional ): boolean;

Return value

  • true if successful

  • false otherwise

Parameter | Description
sUser | Optional: The username of the remote desktop user. If no username or password are provided, the function uses the user name and password that are saved in the profile settings.
sPassword | Optional: The password of the remote desktop user. If no username or password are provided, the function uses the user name and password that are saved in the profile settings.
uColorDepth Optional: The remote session's color depth setting. The default color-depth setting is 16 bit. Possible values are one of following constants of StAutomation.bdh:
ST_COLOR_256     := 8;
  ST_COLOR_15bit   := 15;
  ST_COLOR_16bit   := 16;
  ST_COLOR_24bit   := 24;
  ST_COLOR_32bit   := 32;
uDesktopWidth | Optional: The remote session's screen width resolution size in pixels. Default is 1024.
uDesktopHeight | Optional: The remote session's screen height resolution size in pixels. Default is 768.

Example

transaction TMain
var
  sUser     : string;
  sPassword : string;
begin
  AttributeGetString("Username", sUser);
  AttributeGetString("Password", sPassword);
  if (StInitSession(sUser, sPassword, ST_COLOR_16bit, 1600, 1200)) then
    StLoadProject("package.stp");
    StSetOption(ST_OPTION_TRUELOG_OPTIONS,ST_TRUELOG_ALL);
    StExecuteTestcase("scriptFile.t", "testcase", "\" testdata\",10", "MyTimer1");
    StLogoffSession();
  end;
end TMain;
Parent topic: Silk Test Automation Functions Overview
Related tasks
Setting GUI-Level Testing Options
Related reference
Event Handler Section


StLoadProject Function

Action

The StLoadProject function instructs Silk Test to load a Silk Test package file. Only packages can be loaded. When a package is being added to Silk Performer data files, you do not have to use an absolute path. In addition to loading the package, some basic Silk Test settings are set with this function.

Include file

StAutomation.bdh

Syntax

StLoadProject( in sProject : string): boolean;

Return value

  • true if all settings have been set successfully and the package can be loaded by Silk Test

  • false otherwise

Parameter | Description
sProject | The path to the Silk Test package file. An absolute or a relative path can be provided. However, if the path is relative, the package must be added to the data files.

Example

transaction TMain
var
  sUser     : string;
  sPassword : string;
begin
  AttributeGetString("Username", sUser);
  AttributeGetString("Password", sPassword);
  if (StInitSession(sUser, sPassword)) then
    StLoadProject("package.stp");
    StSetOption(ST_OPTION_TRUELOG_OPTIONS,ST_TRUELOG_ALL);
    StExecuteTestcase("scriptFile.t", "testcase", "\" testdata\",10", "MyTimer1");
    StLogoffSession();
  end;
end TMain;
Parent topic: Silk Test Automation Functions Overview


StLogoffSession Function

Action

The StLogoffSession closes Silk Test and disconnects from the Windows Terminal Server session.

Include file

StAutomation.bdh

Syntax

StLogoffSession()

Example

transaction TMain
var
  sUser     : string;
  sPassword : string;
begin
  AttributeGetString("Username", sUser);
  AttributeGetString("Password", sPassword);
  if (StInitSession(sUser, sPassword)) then
    StLoadProject("package.stp");
    StSetOption(ST_OPTION_TRUELOG_OPTIONS, ST_TRUELOG_ALL);
    StExecuteTestcase("scriptFile.t", "testcase", "\" testdata\",10", "MyTimer1");
    StLogoffSession();
  end;
end TMain;
Parent topic: Silk Test Automation Functions Overview


StResetSilkTest Function

Action

StResetSilkTest closes Silk Test and then restarts it. In addition to resetting Silk Test, it is also possible to reset the session.

Include file

StAutomation.bdh

Syntax

StResetSilkTest( in bResetConnection : boolean optional ): boolean;

Return value

  • true if reset worked

  • false otherwise

Parameter | Description
bResetConnection | If bResetConnection is set to true, the session will be closed and reopened using the same settings. Optionally, only Silk Test can be reset.

Example

transaction TInit
var
  sUser     : string;
  sPassword : string;
begin
  AttributeGetString("Username", sUser);
  AttributeGetString("Password", sPassword);
  StInitSession(sUser, sPassword);
end TInit;

transaction TMain
begin
  StLoadProject("package.stp");
  StSetOption(ST_OPTION_TRUELOG_OPTIONS, ST_TRUELOG_ALL);
  StExecuteTestcase("scriptFile.t", "testcase", "\" testdata\",10", "MyTimer1");
  StResetSilkTest(true);
end TMain;
Parent topic: Silk Test Automation Functions Overview


StSetConnectionTimeOut Function

Action

Sets a timeout for connection to a Windows Terminal Server session.

Include file

StAutomation.bdh

Syntax

StSetConnectionTimeOut( in nTimeOut : number );
Parameter | Description
nTimeOut | Connection timeout in seconds. Null means unlimited timeout.

Example

transaction TMain
var
  sUser     : string;
  sPassword : string;
begin
  AttributeGetString("Username", sUser);
  AttributeGetString("Password", sPassword);
  StSetConnectionTimeOut(60000);
  if (StInitSession(sUser, sPassword)) then
    StLoadProject("package.stp");
    StSetOption(ST_OPTION_TRUELOG_OPTIONS, ST_TRUELOG_ALL);
    StExecuteTestcase("scriptFile.t", "testcase", "\" testdata\",10", "MyTimer1");
    StLogoffSession();
  end;
end TMain;
Parent topic: Silk Test Automation Functions Overview


StSetExecutionTimeOut Function

Action

Sets the timeout for the execution of a testcase.

Include file

StAutomation.bdh

Syntax

StSetExecutionTimeOut( in nTimeOut : number );

Return value

  • true if successful

  • false otherwise

Parameter | Description
nTimeOut | Execution timeout in seconds. Null means unlimited timeout.

Example

transaction TMain
var
  sUser     : string;
  sPassword : string;
begin
  AttributeGetString("Username", sUser);
  AttributeGetString("Password", sPassword);
  if (StInitSession(sUser, sPassword)) then
    StLoadProject("package.stp");
    StSetExecutionTimeOut(50000);
    StSetOption(ST_OPTION_TRUELOG_OPTIONS, ST_TRUELOG_ALL);
    StExecuteTestcase("scriptFile.t", "testcase", "\" testdata\",10", "MyTimer1");
    StLogoffSession();
  end;
end TMain;
Parent topic: Silk Test Automation Functions Overview


StSetOption Function

Action

With the StSetOption function, it is possible to set Silk Test-specific options. Most of the options that are necessary for StLoadProject are already set. To change them you have to call StSetOption after the StLoadProject call.

Include file

StAutomation.bdh

Syntax

StSetOption( in sOption : string,
             in sValue  : string ): boolean;

Return value

  • true if successful

  • false otherwise

Parameter | Description
sOption The option name you want to set. The following constants can be set:
  • ST_OPTION_OPENFILE: Opens any file in a Silk Test child window.
  • ST_OPTION_OPTIONSET: Opens an option set file.
  • ST_OPTION_WORKDIR: Sets the Silk Test working directory.
  • ST_OPTION_SETHOSTNAME: Sets the remote host name for TCP/IP networks.
  • ST_OPTION_TRUELOG_OPTIONS: Sets Truelog options for the writing of TrueLogs. Use the option ST_TRUELOG_ALL to log everything. Otherwise, create your own option string. For detailed information, go to: Truelog option strings.
    Note: This option only supports the Classic Agent of Silk Test. If you run tests with the Open Agent, this setting has no impact.
sValue | The value of the option.

Truelog option strings

The syntax of a Truelog option string is:

OptionString  = "<name pair>{,<name pair>{,<name pair>{...}}}"
Name Pair = <sub-option name>=<option value>
Sub-option Name | Option Value | Description
RecordingLevel | Error | Warning | All | Result file recording level for prompts and warnings.
BitMapsOnError | TRUE | FALSE | Record bit maps when errors occur.
BitMaps | TRUE | FALSE | Record bit maps for all selected controls, etc.
DeskTopBitMap | TRUE | FALSE | Record a bitmap of the desktop.
CallStackTrace | TRUE | FALSE | Record call stack.
AgentRecord | TRUE | FALSE | Enable recording of selected controls.
SetText | NONE | BEFORE | AFTER | BOTH | Record the SetText method.
SetMultiText | NONE | BEFORE | AFTER | BOTH | Record the SetMultiText method.
Select | NONE | BEFORE | AFTER | BOTH | Record the Select method.
PickMenu | NONE | BEFORE | AFTER | BOTH | Record the MenuPick method.
TypeKeys | NONE | BEFORE | AFTER | BOTH | Record the TypeKeys method.
MouseClick | NONE | BEFORE | AFTER | BOTH | Record the MouseClick method.
PresRelKeys | NONE | BEFORE | AFTER | BOTH | Record the Press or Release Keys method.
PresRelMouse | NONE | BEFORE | AFTER | BOTH | Record the Press or Release Mouse method.
SetActive | NONE | BEFORE | AFTER | BOTH | Record the SetActive method.
DoubleClick | NONE | BEFORE | AFTER | BOTH | Record the DoubleClíck method.
DoubleSelect | NONE | BEFORE | AFTER | BOTH | Record the DoubleSelect method.
CreateWindow | NONE | BEFORE | AFTER | BOTH | Record the CreateWindow method
CloseWindow | NONE | BEFORE | AFTER | BOTH | Record the CloseWindow method.
LowLevelEnable | TRUE | FALSE | Enable low level action recording.
RecordObjects | TRUE | FALSE | Record Control Objects.
RecordStaticText | TRUE | FALSE | Record Static Text (mostly browsers)
TrackObjects | TRUE | FALSE | Record Object Tracking (add / delete)
BrowserDownLoad | TRUE | FALSE | Record DOM download events.
BrowserNavigate | TRUE | FALSE | Record DOM navigate events.
BrowserTerminate | TRUE | FALSE | Record DOM terminate events.
BrowserNewWindow | TRUE | FALSE | Record DOM new window events.
BrowserRecStat | TRUE | FALSE | Record DOM Rec Stat events.
BrowserJavaScript | TRUE | FALSE | Record Java events
WindowDelay | INT Value | Windows delay for Java
Example:
"BitMaps=TRUE,AgentRecord=TRUE,SetText=AFTER"

Example

transaction TMain
var
  sUser     : string;
  sPassword : string;
begin
  AttributeGetString("Username", sUser);
  AttributeGetString("Password", sPassword);
  if (StInitSession(sUser, sPassword)) then
    StLoadProject("package.stp");
    StSetOption(ST_OPTION_TRUELOG_OPTIONS, ST_TRUELOG_ALL);
    StSetOption(ST_OPTION_WORKDIR,"<path>");
    StExecuteTestcase("scriptFile.t", "testcase", "\" testdata\",10", "MyTimer1");
    StLogoffSession();
  end;
end TMain;
Parent topic: Silk Test Automation Functions Overview


UFT Developer (Silk4J) Functions Overview

Silk Performer supports load testing of fat-client applications. To load test these applications, Silk Performer uses Microsoft Windows Terminal Services to connect to and open client sessions on agent computers. Via its own session manager, Silk Performer uses UFT Developer (Silk4J), Micro Focus's functional testing tool, to test JUnit tests. UFT Developer (Silk4J) runs GUI-level tests and communicates results back to Silk Performer via the session manager. Silk Performer ultimately collects the results and makes them available to end-users.

GUI-level testing runs on supported Microsoft Windows Server platforms.

  • Silk4JExecuteTestcase Function
    Starts an execution using UFT Developer (Silk4J) and collects the results of the execution.
  • Silk4JInit Function
    The Silk4JInit function loads the JVM and UFT Developer (Silk4J) is set up.
  • Silk4JInitSession Function
    Connects to a Windows Terminal Server session and opens a remote desktop user session.
Parent topic: GUI-Level Testing Functions


Silk4JExecuteTestcase Function

Action

Silk4JExecuteTestcase starts an execution using UFT Developer (Silk4J) and collects the results of the execution.

Include file

SilkTest.bdh

Syntax

Silk4JExecuteTestcase( in sClass    : string,
                       in sTestCase : string,
                       in sTimer    : string ): boolean;

Parameter | Description
sClass | The JUnit test class name
sTestCase | The name of the testcase you want to execute
sTimer | The name of the timer for the Silk4JExecuteTestcase function

Return value

  • true if successful

  • false otherwise

Example

dcltrans
  transaction TInit
  begin
    AttributeGetString("GLTusername",username);
    AttributeGetString("GLTpassword",password);
    Silk4JInitSession(username,password);
  end TInit;

  transaction TTest
  begin
    Silk4JExecuteTestcase("com.borland.silk4j.TestClass","testMethod","method testcase");
  endTTest;
Parent topic: UFT Developer (Silk4J) Functions Overview


Silk4JInit Function

Action

The Silk4JInit function loads the JVM and UFT Developer (Silk4J) is set up. This function is used only for web application testing (but not for mobile) and does not start a new session. Therefore, you need to enable Use particular user account in the system settings: Click Settings > System > Agents > Advanced and enable the option. All started virtual users are using the same Silk Test process within the current session.
Note: Browser type settings defined using this function override profile settings that were configured in the profile settings: Profile settings > GUI-Level Testing > Execution > Browser type setting. When the optional uBrowserType parameter is omitted, the profile settings are used. The default browser type is the one that was specified during the import of the test.

Include file

SilkTest.bdh

Syntax

Silk4JInit( uBrowserType : in number optional := BROWSER_TYPE_DEFAULT ): boolean;

Return value

  • true if successful

  • false otherwise

Parameter Description
uBrowserType Optional: Sets the browser type. Possible values are:
  • BROWSER_TYPE_DEFAULT := 0;
  • BROWSER_TYPE_CHROME := 1;
  • BROWSER_TYPE_FIREFOX := 2;
  • BROWSER_TYPE_PHANTOMJS := 3;

Example

dcltrans
  transaction TInit
  begin
    Silk4JInit();
  end TInit;

  transaction TTest
  begin
    Silk4JExecuteTestcase("com.borland.silk4j.TestClass", "testMethod", "method testcase");
  end TTest;
Parent topic: UFT Developer (Silk4J) Functions Overview


Silk4JInitSession Function

Action

The Silk4JInitSession function connects to a Windows Terminal Server session and opens a remote desktop user session. When the connection is established, JVM is loaded and UFT Developer (Silk4J) is set up. If no user name or password are provided, the function uses the user name and password that are saved in the profile settings. If you run the test on your local console, do not set user credentials in the profile settings or the script.

Note: Color depth settings using this function override profile settings that were configured in Silk Performer at Profile settings > GUI-Level Testing > General > Session settings. When the optional uColorDepth parameter is omitted, the profile settings are used. The default color-depth setting is 16 bit.

The server may limit maximum color depth. The client can not force a color depth setting that is higher than is supported by the server. See the Terminal Services Configuration documentation for details about the color-depth limitations f your server.

By default, Silk4JInitSession raises an error with the severity SEVERITY_PROCESS_EXIT if the function fails to start a valid session. You can adjust this severity by a custom event handler function. If an error with SEVERITY_PROCESS_EXIT occurs, the rest of the script is ignored and no unsaved results data or measurements will be saved.

Include file

SilkTest.bdh

Syntax

Silk4JInitSession( in sUser          : string optional,
                   in sPassword      : string optional,
                   in uColorDepth    : number optional,
                   in uDesktopWidth  : number optional,
                   in uDesktopHeight : number optional ): boolean;
Parameter | Description
sUser | Optional: The user name of the remote desktop user. If no user name or password are provided, the function uses the user name and password that are saved in the profile settings.
sPassword | Optional: The password of the remote desktop user. If no user name or password are provided, the function uses the user name and password that are saved in the profile settings.
uColorDepth Optional: The remote session's color depth setting. The default color-depth setting is 16 bit. Possible values are one of following constants of StAutomation.bdh.
  • ST_COLOR_256 := 8;
  • ST_COLOR_15bit := 15;
  • ST_COLOR_16bit := 16;
  • ST_COLOR_24bit := 24;
  • ST_COLOR_32bit := 32;
uDesktopWidth | Optional: The remote session's screen width resolution size in pixels. Default is 1024.
uDesktopHeight | Optional: The remote session's screen height resolution size in pixels. Default is 768.

Return value

  • true if successful

  • false otherwise

Example

dcltrans
  transaction TInit
  begin
    AttributeGetString("GLTusername", username);
    AttributeGetString("GLTpassword", password);
    Silk4JInitSession(username, password);
  end TInit;

  transaction TTest
  begin
    Silk4JExecuteTestcase("com.borland.silk4j.TestClass", "testMethod", "method testcase");
  end TTest;
Parent topic: UFT Developer (Silk4J) Functions Overview


Silk4NET Functions Overview

Silk Performer supports load testing of fat-client applications. To load test these applications, Silk Performer uses Microsoft Windows Terminal Services to connect to and open client sessions on agent computers. Via its own session manager, Silk Performer uses UFT Developer (Silk4NET), Micro Focus's functional testing tool, to test MSTest unit tests. UFT Developer (Silk4NET) runs GUI-level tests and communicates results back to Silk Performer via the session manager. Silk Performer ultimately collects the results and makes them available to end-users.

GUI-level testing runs on supported Microsoft Windows Server platforms.

  • Silk4NETExecuteTestcase Function
    Starts an execution using UFT Developer (Silk4NET) and collects the results.
  • Silk4NETInit Function
    The Silk4NETInit function sets up UFT Developer (Silk4NET).
  • Silk4NETInitSession Function
    Connects to a Windows Terminal Server session and opens a remote desktop user session.
Parent topic: GUI-Level Testing Functions


Silk4NETExecuteTestcase Function

Action

Starts an execution using UFT Developer (Silk4NET) and collects the results of the execution.

Include file

SilkTest.bdh

Syntax

Silk4NETExecuteTestcase( in sClass         : string,
                         in sTestCase      : string,
                         in sTimer         : string,
                         in uMSTestVersion : number optional ): boolean;
Parameter | Description
sClass | The MSTest unit test class name.
sTestCase | The name of the test case you want to execute.
sTimer | The name of the timer for the Silk4NETExecuteTestcase function. The timer starts when UFT Developer (Silk4NET) gets the information to execute a test case and stops when UFT Developer (Silk4NET) finishes the execution.
uMSTestVersion The version of MSTest or the Visual Studio version that was used to build the test (the .dll file). When this parameter is omitted, the latest version is automatically detected and used. You can use one of the following constants. These constants are also listed in the SilkTest.bdh file.
  • VISUAL_STUDIO_2017_ID := 150
  • VISUAL_STUDIO_2015_ID := 140
  • VISUAL_STUDIO_2013_ID := 120
  • VISUAL_STUDIO_2012_ID := 110
  • VISUAL_STUDIO_2011_ID := 100

Return value

  • true if successful

  • false otherwise

Example

dcltrans
  transaction TInit
  begin
    AttributeGetString("GLTusername",username);
    AttributeGetString("GLTpassword",password);
    Silk4NETInitSession(username,password);
  end TInit;

  transaction TTest
  begin
    Silk4NETExecuteTestcase("Silk4NETTest_v12.UnitTest_Notepad_v12","TestMethod_ShortTest",
                            "Timer_TestMethod_ShortTest", VISUAL_STUDIO_2012_ID);
  end TTest;
Parent topic: Silk4NET Functions Overview


Silk4NETInit Function

Action

The Silk4NETInit function sets up UFT Developer (Silk4NET). This function is used only for web application testing (but not for mobile) and does not start a new session. Therefore, you need to enable Use particular user account in the system settings: Click Settings > System > Agents > Advanced and enable the option. All started virtual users are using the same Silk Test process within the current session.
Note: Browser type settings defined using this function override profile settings that were configured in the profile settings: Profile settings > GUI-Level Testing > Execution > Browser type setting. When the optional uBrowserType parameter is omitted, the profile settings are used. The default browser type is the one that was specified during the import of the test.

Include file

SilkTest.bdh

Syntax

Silk4NETInit( uBrowserType : in number optional := BROWSER_TYPE_DEFAULT ): boolean;

Return value

  • true if successful

  • false otherwise

Parameter Description
uBrowserType Optional: Sets the browser type. Possible values are:
  • BROWSER_TYPE_DEFAULT := 0;
  • BROWSER_TYPE_CHROME := 1;
  • BROWSER_TYPE_FIREFOX := 2;
  • BROWSER_TYPE_PHANTOMJS := 3;

Example

dcltrans
  transaction TInit
  begin
    Silk4NETInit();
  end TInit;

  transaction TTest
  begin
    Silk4NETExecuteTestcase("Silk4NETTest_v12.UnitTest_Notepad_v12","TestMethod_ShortTest","Timer_TestMethod_ShortTest");

  end TTest;
Parent topic: Silk4NET Functions Overview


Silk4NETInitSession Function

Action

The Silk4NETInitSession function connects to a Windows Terminal Server session and opens a remote desktop user session. If no user name or password is provided, the function uses the user name and password that are saved in the profile settings. If you want to run the test on your local console, do not set user credentials in the profile settings or the script.

Note: Color depth settings defined using this function override profile settings configured in Silk Performer in the profile settings: Profile settings > GUI-Level Testing > General > Session settings. When the optional uColorDepth parameter is omitted, profile settings are used. The default color-depth setting is 16 bit.

The server may limit maximum color depth. The client cannot force a color depth setting that is higher than is supported by the server. See the Terminal Services Configuration documentation for details about the color-depth limitations of your server version.

By default Silk4NETInitSession raises an error with the severity SEVERITY_PROCESS_EXIT if the function fails to start a valid session. The severity of that error can be adjusted by a custom event handler function. When an error with SEVERITY_PROCESS_EXIT occurs, the rest of the script is ignored and no unsaved results data or measurements will be saved.

Include file

SilkTest.bdh

Syntax

Silk4NETInitSession( in sUser          : string optional,
                     in sPassword      : string optional,
                     in uColorDepth    : number optional,
                     in uDesktopWidth  : number optional,
                     in uDesktopHeight : number optional ): boolean;
Parameter | Description
sUser | Optional: The user name of the remote desktop user. If no user name or password is provide,d the function uses the user name and password that are saved in the profile settings.
sPassword | Optional: The password of the remote desktop user. If no user name or password is provided, the function uses the suer name and password that are saved in the profile settings.
uColorDepth Optional: The color depth setting of the remote session. The default color-depth setting is 16 bit. Possible values are one of the following constants of the SilkTest.bdh:
  • ST_COLOR_256 := 8;
  • ST_COLOR_15bit := 15;
  • ST_COLOR_16bit := 16;
  • ST_COLOR_24bit := 24;
  • ST_COLOR_32bit := 32;
uDesktopWidth | Optional: The width resolution of the remote session screen in pixels. Default is 1024.
uDesktopHeight | Optional: The height resolution of th e remote session screen in pixels. Default is 768.

Return value

  • true if successful

  • false otherwise

Example

dcltrans
  transaction TInit
  begin
    AttributeGetString("GLTusername",username);
    AttributeGetString("GLTpassword",password);
    Silk4NETInitSession(username,password);
  end TInit;

  transaction TTest
  begin
    Silk4NETExecuteTestcase("Silk4NETTest_v12.UnitTest_Notepad_v12","TestMethod_ShortTest","Timer_TestMethod_ShortTest");
  end TTest;
Parent topic: Silk4NET Functions Overview


Silk Keyword-driven Testing Functions Overview

  • SilkKDTInit Function
    The SilkKDTInit function loads the JVM and the keyword-driven test is set up.
  • SilkKDTInitSession Function
    The SilkKDTInitSession function connects to a Windows Terminal Server session and opens a remote desktop user session. When the connection is established, the JVM is loaded and the keyword-driven test is set up.
  • SilkKDTExecuteTest Function
    The SilkKDTExecuteTest function starts an execution using UFT Developer (Silk4J) and UFT Developer (Silk4NET) and collects the results of the execution.
  • SilkKDTSetThinkTime Function
    The SilkKDTSetThinkTime function sets the think times used between the keyword executions.
Parent topic: GUI-Level Testing Functions


SilkKDTInit Function

Action

The SilkKDTInit function loads the JVM and the keyword-driven test is set up. This function is used only for web application testing (but not for mobile) and does not start a new session. Therefore, you need to enable Use particular user account in the system settings: Click Settings > System > Agents > Advanced and enable the option. All started virtual users are using the same Silk Test process within the current session.
Note: Browser type settings defined using this function override profile settings that were configured in the profile settings: Profile settings > GUI-Level Testing > Execution > Browser type setting. When the optional uBrowserType parameter is omitted, the profile settings are used. The default browser type is the one that was specified during the import of the test.

Include file

SilkTest.bdh

Syntax

SilkKDTInit( uBrowserType : in number optional := BROWSER_TYPE_DEFAULT ): boolean;

Return value

  • true if successful

  • false otherwise

Parameter Description
uBrowserType Optional: Sets the browser type. Possible values are:
  • BROWSER_TYPE_DEFAULT := 0;
  • BROWSER_TYPE_CHROME := 1;
  • BROWSER_TYPE_FIREFOX := 2;
  • BROWSER_TYPE_PHANTOMJS := 3;

Example

dcltrans
  transaction TInit
  begin
    SilkKDTInit();
    SilkTestSetTinkTime(5.0);
  end TInit;
  transaction TTest
  var
    dataset : list of string;
  begin
    SilkKDTExecuteTest("library.zip", "KDTTest", dataset, "KDTTest_Timer");
  end TTest;
Parent topic: Silk Keyword-driven Testing Functions Overview


SilkKDTInitSession Function

Action

The SilkKDTInitSession function connects to a Windows Terminal Server session and opens a remote desktop user session. When the connection is established, the JVM is loaded and the keyword-driven test is set up. If no user name or password are provided, the function uses the user name and password that are saved in the profile settings. If you run the test on your local console, do not set user credentials in the profile settings or the script.
Note: Color depth settings defined using this function override profile settings that were configured in the profile settings: Profile settings > GUI-Level Testing > General > Session settings. When the optional uColorDepth parameter is omitted, the profile settings are used. The default color depth setting is 16 bit.

The server may limit maximum color depth. The client cannot force a color depth setting that is higher than is supported by the server. See the Terminal Services Configuration documentation for details about the color depth limitations of your server.

By default SilkKDTInitSession raises an error with the severity SEVERITY_PROCESS_EXIT if the function fails to start a valid session. The severity of that error can be adjusted by a custom event handler function (see "Event Handler Section"). When an error with SEVERITY_PROCESS_EXIT occurs the rest of the script is ignored and no unsaved results data or measurements will be saved.

Include file

SilkTest.bdh

Syntax

SilkKDTInitSession( in sUser          : string optional,
                    in sPassword      : string optional,
                    in uColorDepth    : number optional,
                    in uDesktopWidth  : number optional,
                    in uDesktopHeight : number optional ): boolean;

Return value

  • true if successful

  • false otherwise

Parameter | Description
sUser | Optional: The user name of the remote desktop user. If no user name or password are provided, the function uses the user name and password that are saved in the profile settings.
sPassword | Optional: The password of the remote desktop user. If no username or password are provided, the function uses the user name and password that are saved in the profile settings.
uColorDepth Optional: The remote session's color depth setting. The default color-depth setting is 16 bit. Possible values are one of following constants of StAutomation.bdh:
ST_COLOR_256     := 8;
  ST_COLOR_15bit   := 15;
  ST_COLOR_16bit   := 16;
  ST_COLOR_24bit   := 24;
  ST_COLOR_32bit   := 32;
uDesktopWidth | Optional: The remote session's screen width resolution size in pixels. Default is 1024.
uDesktopHeight | Optional: The remote session's screen height resolution size in pixels. Default is 768.

Example

dcltrans
  transaction TInit
  begin
    AttributeGetString("GLTusername", username);
    AttributeGetString("GLTpassword", password);
    SilkKDTInitSession(username, password);
    SilkTestSetTinkTime(5.0);
  end TInit;

  transaction Ttest
  var
    dataset : list of string;
  begin
    SilkKDTExecuteTest("library.zip", "KDTTest", dataset, "KDTTest_Timer");
  end TTest;
Parent topic: Silk Keyword-driven Testing Functions Overview


SilkKDTExecuteTest Function

Action

The SilkKDTExecuteTest function starts an execution using UFT Developer (Silk4J) and UFT Developer (Silk4NET) and collects the results of the execution.

Include file

SilkTest.bdh

Syntax

SilkKDTExecuteTest( sKdtLibrary : in string,
                    sTestCase   : in string,
                    lDataset    : in list,
                    sTimer      : in string): boolean;

Return value

  • true if successful

  • false otherwise

Parameter | Description
sKdtLibrary | The keyword-driven test library name.
sTestCase | The name of the test case you want to execute.
lDataset | The list of strings containing the global variables of the test.
sTimer | The name of the timer for the SilkKDTExecuteTest function.

Example

dcltrans
  transaction TInit
  begin
    AttributeGetString("GLTusername", username);
    AttributeGetString("GLTpassword", password);
    SilkKDTInitSession(username, password);
    SilkTestSetTinkTime(5.0);
    FileCSVLoadGlobal(hsub1t11, "library.csv", ";");
  end TInit;

  transaction Ttest
  var
    dataset : list of string;
  begin
    FileGetRndRow(hsub1t11);
    pssub1t11User := FileGetCol(hsub1t11, 1);
    ListAdd(dataset, "user=" + pssub1t11User);
    pssub1t11Password := FileGetCol(hsub1t11, 2);
    ListAdd(dataset, "password=" + pssub1t11Password);
    SilkKDTExecuteTest("library.zip", "KDTTest", dataset, "KDTTest_Timer");
  end TTest;
Parent topic: Silk Keyword-driven Testing Functions Overview


SilkKDTSetThinkTime Function

Action

The SilkKDTSetThinkTime function sets the think times used between the keyword executions.

Include file

SilkTest.bdh

Syntax

SilkKDTSetThinkTime( sTime : in double ): boolean;

Return value

  • true if successful

  • false otherwise

Parameter | Description
sTime | The think time used between keyword executions.

Example

dcltrans
  transaction TInit
  begin
    SilkKDTInit();
    SilkTestSetTinkTime(5.0);
  end TInit;
  transaction TTest
  var
    dataset : list of string;
  begin
    SilkKDTExecuteTest("library.zip", "KDTTest", dataset, "KDTTest_Timer");
  end TTest;
Parent topic: Silk Keyword-driven Testing Functions Overview


Terminal Services Functions

  • Citrix Functions Overview
    Details how Citrix facilitates real-time access to shared applications over networks and the Internet and provides a list of all the Citrix functions.
Parent topic: Benchmark Description Language (BDL) Reference


Citrix Functions Overview

Citrix facilitates real-time access to shared applications over networks and the Internet. Citrix Server enables multiple users to run shared applications simultaneously. Communication between Citrix clients and servers consists of exchange of user inputs (keyboard/mouse) and screen shots.

Silk Performer offers an API for load testing applications that are hosted via Citrix server terminal services.

The API is divided into 6 different subsections:

  • Connection Functions
    Lists the Citrix connection functions.
  • Mouse Functions
    Lists the Citrix mouse functions.
  • Keyboard Functions
    Lists the Citrix keyboard functions.
  • Window Functions
    Lists the Citrix window functions.
  • Synchronization Functions
    Lists the Citrix synchronization functions.
  • General Functions
    Lists the Citrix general functions.
Parent topic: Terminal Services Functions


Connection Functions

  • CitrixConnect Function
    Establishes a connection to a Citrix server, or server farm, using standard login credentials.
  • CitrixConnectIcaData Function
    Establishes a connection to a Citrix server, or server farm, using ICA file content provided in a string parameter.
  • CitrixConnectIcaFile Function
    Establishes a connection to a Citrix server, or server farm, using an ICA file.
  • CitrixLogoff Function
    Logs off an established ICA session.
  • CitrixDisconnect Function
    Disconnects an established ICA session.
  • CitrixInit Function
    Initializes a Citrix client. Must be called once to enable Citrix replay.
  • CitrixSetApplication Function
    When a connection to a published application is to be established, SetApplication must be called before CitrixConnect.
  • CitrixRunPublishedApplication Function
    Launches a published application within a connected session.
Parent topic: Citrix Functions Overview


CitrixConnect Function

Action

Establishes a connection to a Citrix MetaFrame server, or server farm, using standard login credentials. If the connection targets a published application, CitrixSetApplication should be called before CitrixConnect.

Include file

CitrixAPI.bdh

Syntax

CitrixConnect( in sServer   : string,
               in sUser     : string optional,
               in sPassword : string optional,
               in sDomain   : string optional,
               in nColor    : number optional ) : boolean;

Return value

  • true if successful

  • false otherwise

Parameter | Description
sServer | Name of the target server.
sUser | Username for login (optional)
sPassword | Password for login (optional)
sDomain | Domain for login (optional)
nColor

Color depth of the remote session. When scripts contain a screen synchronization function (CitrixWaitForScreen), it is necessary that replay color depth be identical to that used during recording. Specify one of the following values:

  • COLOR_16: 16 colors

  • COLOR_256: 256 colors

  • COLOR_16bit: 65536 colors

  • COLOR_24bit: 24 bit color value (16M)

  • COLOR_32bit: 32 bit color value (4G)

Example:

dcltrans
  transaction TMain
  var
  begin
    CitrixInit(640, 480);
    CitrixConnect("server1", "username", "password", "companydomain", COLOR_16bit);
    CitrixWaitForLogon();
    hWnd4 := CitrixWaitForWindowCreation("", MATCH_Exact, 0x96840000, -2, 452, 644, 30);
    hWnd5 := CitrixWaitForWindowCreation("ICA Seamless Host Agent", MATCH_Exact, 0x94C800C4, 0, 0,390, 223);
    CitrixWaitForWindow(hWnd5, EVENT_Activate);
    CitrixWaitForWindowCreation("Program Manager");
    ThinkTime(31.50);
    CitrixMouseClick(217, 192, hWnd5, MOUSE_ButtonLeft);
    CitrixWaitForWindow(hWnd5, EVENT_Destroy);
    CitrixDisconnect();
end TMain;
Parent topic: Connection Functions
Related reference
CitrixConnectIcaData Function
CitrixConnectIcaFile Function
CitrixLogoff Function
CitrixDisconnect Function
CitrixInit Function
CitrixSetApplication Function
CitrixRunPublishedApplication Function


CitrixConnectIcaData Function

Action

Establishes a connection to a Citrix MetaFrame server, or server farm, using ICA file content provided in a string parameter. This is especially useful when an ICA file is downloaded via a Web function. This function is scripted automatically when recording an NFuse connection establishment.

Include file

CitrixAPI.bdh

Syntax

CitrixConnectIcaData( in sData : string ) : boolean;

Return value

  • true if successful

  • false otherwise

Parameter | Description
sData | Content of an ICA file.

Example:

benchmark KDTBenchmarkName

use "webAPI.bdh"
use "CitrixAPI.bdh"

dcluser
  user
    VUser
  transactions
    TInit           : begin;
    TMain           : 1;

var

dclrand

dcltrans
  transaction TInit
  begin
    WebSetBrowser(WEB_BROWSER_MSIE6);
    WebModifyHttpHeader("Accept-Language", "en-us");
    //WebSetUserBehavior(WEB_USERBEHAVIOR_FIRST_TIME);
    //WebSetDocumentCache(true, WEB_CACHE_CHECK_SESSION);
  end TInit;

  transaction TMain
  var
    gsICAData : string;
    hWnd5 : number;
  begin
    //Redirecting -> (redir) http://citserver/Citrix/MetaFrame/Citrix/NFuse151/ASP/login.htm
    WebPageUrl("http://citserver/", "Citrix NFuse");

    ThinkTime(4.9);
    WebPageSubmit("Login", LOGIN001, "applist_nfuse.asp"); // Form 1

    WebParseDataBoundEx(gsICAData);
    ThinkTime(4.0);
    WebPageLink("Excel", "launch.asp", 1, "nfusemain"); // Link 3
    CitrixInit(800, 600);
    CitrixConnectICAData(gsICAData);
    CitrixWaitForLogon();
    hWnd5 := CitrixWaitForWindowCreation("Microsoft Excel - Book1", MATCH_Exact,0x14CF0000, 11, 26, 643, 492);
    ThinkTime(3.17);
    CitrixMouseClick(627, 9, hWnd5, MOUSE_ButtonLeft);
    CitrixWaitForWindow(hWnd5, EVENT_Destroy);
    ThinkTime(2.73);
    CitrixDisconnect();
  end TMain;

dclform
  LOGIN001:
    "CTX_Application"           := "Citrix.MPS.App.LinzFarm.MSExcel",
    "CTX_Token"                 := "CFEDA5A27579A0CC59737833F192DAF9",
    "LaunchId"                  := "1380105291129";
Parent topic: Connection Functions
Related reference
CitrixConnect Function
CitrixConnectIcaFile Function
CitrixLogoff Function
CitrixDisconnect Function
CitrixInit Function
CitrixSetApplication Function
CitrixRunPublishedApplication Function


CitrixConnectIcaFile Function

Action

Establishes a connection to a Citrix MetaFrame server, or server farm, using an ICA file. Note that the Recorder (when an ICA file is used) scripts the absolute path to the ICA file. Therefore, to enable the script to run on remote agents, the ICA file must be manually added to the data files.

Include file

CitrixAPI.bdh

Syntax

CitrixConnectIcaFile( in sFile : string ) : boolean

Return value

  • true if successful

  • false otherwise

Parameter | Description
sFile | Path to an ICA file. If the ICA file has been added to the data files no directory is required.

Example:

dcltrans
  transaction TMain
  var
  begin
    CitrixInit(640, 480);
    CitrixConnectICAFile("C:\\Citrix\\launch.ica");
    CitrixWaitForLogon();
    hWnd4 := CitrixWaitForWindowCreation("", MATCH_Exact, 0x96840000, -2, 452, 644, 30);
    hWnd5 := CitrixWaitForWindowCreation("ICA Seamless Host Agent", MATCH_Exact, 0x94C800C4, 0, 0, 390, 223);
    CitrixWaitForWindow(hWnd5, EVENT_Activate);
    CitrixWaitForWindowCreation("Program Manager");
    ThinkTime(31.50);
    CitrixMouseClick(217, 192, hWnd5, MOUSE_ButtonLeft);
    CitrixWaitForWindow(hWnd5,EVENT_Destroy);
    CitrixDisconnect();
end TMain;
Parent topic: Connection Functions
Related reference
CitrixConnect Function
CitrixConnectIcaData Function
CitrixLogoff Function
CitrixDisconnect Function
CitrixInit Function
CitrixSetApplication Function
CitrixRunPublishedApplication Function


CitrixLogoff Function

Action

Logs off an established ICA session.

Include file

CitrixAPI.bdh

Syntax

CitrixLogoff( ) : boolean;

Return value

  • true if successful

  • false otherwise

Example:

dcltrans
  transaction TMain
  var
  begin
    CitrixInit(640, 480);
    CitrixConnect("server1", "username", "password", "companydomain", COLOR_16bit);
    CitrixWaitForLogon();
    hWnd4 := CitrixWaitForWindowCreation("", MATCH_Exact, 0x96840000, -2, 452, 644, 30);
    hWnd5 := CitrixWaitForWindowCreation("ICA Seamless Host Agent", MATCH_Exact, 0x94C800C4, 0, 0,390, 223);
    CitrixWaitForWindow(hWnd5,EVENT_Activate);
    CitrixWaitForWindowCreation("Program Manager");
    ThinkTime(31.50);
    CitrixMouseClick(217, 192, hWnd5, MOUSE_ButtonLeft);
    CitrixWaitForWindow(hWnd5,EVENT_Destroy);
    CitrixLogoff();
end TMain;
Parent topic: Connection Functions
Related reference
CitrixConnect Function
CitrixConnectIcaData Function
CitrixConnectIcaFile Function
CitrixDisconnect Function
CitrixInit Function
CitrixSetApplication Function
CitrixRunPublishedApplication Function


CitrixDisconnect Function

Action

Disconnects an established ICA session. When the Gracefully disconnect session option is enabled, a log-off is first attempted, followed by a disconnect if needed, to help ensure that the session is gracefully terminated on the Citrix server.

Include file

CitrixAPI.bdh

Syntax

CitrixDisconnect( ) : boolean;

Return value

  • true if successful

  • false otherwise

Example:

dcltrans
  transaction TMain
  var
  begin
    CitrixInit(640, 480);
    CitrixConnect("server1", "username", "password", "companydomain", COLOR_16bit);
    CitrixWaitForLogon();
    hWnd4 := CitrixWaitForWindowCreation("", MATCH_Exact, 0x96840000, -2, 452, 644, 30);
    hWnd5 := CitrixWaitForWindowCreation("ICA Seamless Host Agent", MATCH_Exact, 0x94C800C4, 0, 0,390, 223);
    CitrixWaitForWindow(hWnd5,EVENT_Activate);
    CitrixWaitForWindowCreation("Program Manager");
    ThinkTime(31.50);
    CitrixMouseClick(217, 192, hWnd5, MOUSE_ButtonLeft);
    CitrixWaitForWindow(hWnd5,EVENT_Destroy);
    CitrixDisconnect();
end TMain;
Parent topic: Connection Functions
Related reference
CitrixConnect Function
CitrixConnectIcaData Function
CitrixConnectIcaFile Function
CitrixLogoff Function
CitrixInit Function
CitrixSetApplication Function
CitrixRunPublishedApplication Function


CitrixInit Function

Action

Initializes a Citrix client. Must be called once to enable Citrix replay (should be called from the TInit transaction). When a Try Script is run with the “Visual Citrix Client” option enabled, this function also launches the CitrixPlayer.

Include file

CitrixAPI.bdh

Syntax

CitrixInit( in nHRes : number,
            in nVRes : number,
            in nMode : number optional ) : boolean;

Return value

  • true if successful

  • false otherwise

Parameter | Description
nHRes | Horizontal screen resolution of the Citrix client.
nVRes | Vertical resolution of the Citrix client.
nMode

Specify one of the following values (optional):

  • Mode_Normal (Default)

  • Mode_Fast Use this mode to disable the Citrix client’s rendering functionality. This mode requires fewer resources, but disables screenshot functionality—meaning that there won’t be any images in the TrueLog and screen synchronization (WaitForScreen) will not be possible.

  • Mode_Gui Use this mode to make each Citrix client show its user interface.

Example:

dcltrans
  transaction TMain
  var
  begin
    CitrixInit(640, 480);
    CitrixConnect("server1", "username", "password", "companydomain", COLOR_16bit);
    CitrixWaitForLogon();
    hWnd4 := CitrixWaitForWindowCreation("", MATCH_Exact, 0x96840000, -2, 452, 644, 30);
    hWnd5 := CitrixWaitForWindowCreation("ICA Seamless Host Agent", MATCH_Exact, 0x94C800C4, 0, 0, 390, 223);
    CitrixWaitForWindow(hWnd5,EVENT_Activate);
    CitrixWaitForWindowCreation("Program Manager");
    ThinkTime(31.50);
    CitrixMouseClick(217, 192, hWnd5, MOUSE_ButtonLeft);
    CitrixWaitForWindow(hWnd5,EVENT_Destroy);
    CitrixDisconnect();
end TMain;
Parent topic: Connection Functions
Related reference
CitrixConnect Function
CitrixConnectIcaData Function
CitrixConnectIcaFile Function
CitrixLogoff Function
CitrixDisconnect Function
CitrixSetApplication Function
CitrixRunPublishedApplication Function


CitrixSetApplication Function

Action

When a connection to a published application is to be established, SetApplication must be called before CitrixConnect.

Include file

CitrixAPI.bdh

Syntax

CitrixSetApplication( in sApplication : string ) : boolean;

Return value

  • true if successful

  • false otherwise

Parameter | Description
sApplication | Name of the published application.

Example:

  transaction TMain
  var
  begin
    CitrixInit(640, 480);
    CitrixSetApplication("Excel");
    CitrixConnect("myserver", "myusername", "mypass", "mydomain", COLOR_16bit);
    CitrixWaitForLogon();
    hWnd4 := CitrixWaitForWindowCreation("Microsoft Excel – Book*", MATCH_Wildcard, 0x15CF0000, -4, -4, 648, 488);
    CitrixMouseClick(636, 14, hWnd4, MOUSE_ButtonLeft);
    CitrixWaitForWindow(hWnd4, EVENT_Destroy);
    ThinkTime(2.63);
    CitrixDisconnect();
  end TMain;
Parent topic: Connection Functions
Related reference
CitrixConnect Function
CitrixConnectIcaData Function
CitrixConnectIcaFile Function
CitrixLogoff Function
CitrixDisconnect Function
CitrixInit Function
CitrixRunPublishedApplication Function


CitrixRunPublishedApplication Function

Action

Launches a published application within a connected session. Use this function to test session sharing by driving multiple published applications inside one session.

Include file

CitrixAPI.bdh

Syntax

CitrixRunPublishedApplication(
    in sApp    : string,
    in sParams : string optional ) : boolean;

Return value

  • true if successful

  • false otherwise

Parameter | Description
sApp | Name of the published application to launch
sParams | Arguments of the published application (optional)

Example

dcltrans
  transaction TMain
  var
    hWnd4 : number;
    hWnd6 : number;
    hWnd7 : number;
  begin
    CitrixInit(800,600); // do not change the resolution
    CitrixSetApplication("notepad");
    CitrixConnect("citrix", "admin", Decrypt("8VX"), "MyDom", COLOR_32bit);
    CitrixWaitForLogon();
    hWnd4 := CitrixWaitForWindowCreation("Untitled - Notepad", MATCH_Exact, 0x15CF0000, -4, -4, 808, 608);
    CitrixWaitForWindow(hWnd4, EVENT_Activate);
    CitrixKeyString("Hello");
    CitrixRunPublishedApplication("excel");

    hWnd6 := CitrixWaitForWindowCreation("Microsoft Excel - Book*", MATCH_Wildcard, 0x14CF0000, -4, -4, 808, 580);
    CitrixMouseClick(791, 14, hWnd6, MOUSE_ButtonLeft);
    CitrixWaitForWindow(hWnd6, EVENT_Destroy);
    CitrixWaitForWindow(hWnd4, EVENT_Activate);
    CitrixMouseClick(795, 16, hWnd4, MOUSE_ButtonLeft);
    hWnd7 := CitrixWaitForWindowCreation("Notepad", MATCH_Exact, 0x94C801C5, 267, 258, 272, 126);
    CitrixWaitForWindow(hWnd7, EVENT_Activate);
    CitrixMouseClick(141, 99, hWnd7, MOUSE_ButtonLeft);
    CitrixWaitForDisconnect();
end TMain;
Parent topic: Connection Functions
Related reference
CitrixConnect Function
CitrixConnectIcaData Function
CitrixConnectIcaFile Function
CitrixLogoff Function
CitrixDisconnect Function
CitrixInit Function
CitrixSetApplication Function


Mouse Functions

  • CitrixMouseButtonDown Function
    Moves the mouse to a specified position and selects a specified button. To release the button, call CitrixMouseButtonUp.
  • CitrixMouseButtonUp Function
    Moves the mouse to a specified position and releases a button that was pressed by a prior CitrixMouseButtonDown call.
  • CitrixMouseClick Function
    Moves the mouse to a specified position and presses a specified button.
  • CitrixMouseDblClick Function
    Moves the mouse to a specified position and performs a double-click.
  • CitrixMouseMove Function
    Moves the mouse to a specified position.
Parent topic: Citrix Functions Overview


CitrixMouseButtonDown Function

Action

Moves the mouse to a specified position and selects a specified button. To release the button, call CitrixMouseButtonUp. Key modifiers (such as Ctrl and Alt) can be provided. Mouse speed can be specified in profile settings (Citrix / Simulation / Mouse) or by an appropriate call to the CitrixSetOption function. The coordinates can be specified absolutely or relatively to a window (by providing a window handle). The top left corner (of the screen or window) has the coordinates 0 / 0.

Include file

CitrixAPI.bdh

Syntax

CitrixMouseButtonDown( in nX        : number,
                       in nY        : number,
                       in nWindow   : number optional,
                       in nButton   : number optional,
                       in nModifier : number optional ) : boolean;

Return value

  • true if successful

  • false otherwise

Parameter | Description
nX | X coordinate of the position where the button is to be pressed.
nY | Y coordinate of the position where the button is to be pressed.
nWindow | Window handle returned by a call to CitrixWaitForWindowCreation (optional). When this parameter is omitted or DESKTOP is specified, the provided coordinates must be relative to the desktop. When a window handle is specified, the nX and nY parameters state a position relative to the top left corner of the window (wherever the window is on the desktop).
nButton

Specify one of the following values (optional):

  • MOUSE_ButtonLeft (default): Left mouse button

  • MOUSE_ButtonRight: Right mouse button

  • MOUSE_ButtonMiddle: Middle mouse button

nModifier

Specify one of the following values (optional):

  • MOD_None (default): No modifier

  • MOD_Shift: Shift key pressed in combination with the mouse button

  • MOD_Ctrl: Ctrl key pressed in combination with the mouse button

  • MOD_Alt: Alt key pressed in combination with the mouse button

Example:

transaction TMain
  var
  begin
    CitrixInit(640, 480);
    CitrixConnect("myserver", "myusername", "mypass", "mydomain", COLOR_16bit);
    CitrixWaitForLogon();
    hWnd6 := CitrixWaitForWindowCreation("ICA Seamless Host Agent", MATCH_Exact, 0x94C800C4, 0, 0, 390, 223);
    CitrixWaitForWindow(hWnd6, EVENT_Activate);
    CitrixWaitForWindowCreation("Program Manager");
    CitrixMouseClick(211, 197, hWnd6, MOUSE_ButtonLeft);
    CitrixWaitForWindow(hWnd6,EVENT_Destroy);
    CitrixMouseDblClick(41, 23, DESKTOP, MOUSE_ButtonLeft);
    hWnd8 := CitrixWaitForWindowCreation("My Documents", MATCH_Exact, 0x16CF0000, 171, 98, 328, 235);
    CitrixWaitForWindow(hWnd8,EVENT_Activate);
    CitrixMouseButtonDown(82, 13, hWnd8, MOUSE_ButtonLeft);
    CitrixMouseButtonUp(367, 44, false, DESKTOP, MOUSE_ButtonLeft);
    CitrixWaitForWindowPos(hWnd8,285, 31);
    ThinkTime(5.41);
    CitrixMouseClick(317, 13, hWnd8, MOUSE_ButtonLeft);
    CitrixWaitForWindow(hWnd8, EVENT_Destroy);
    CitrixDisconnect();
  end TMain;
Parent topic: Mouse Functions
Related reference
CitrixMouseButtonUp Function
CitrixMouseClick Function
CitrixMouseDblClick Function
CitrixMouseMove Function


CitrixMouseButtonUp Function

Action

Moves the mouse to a specified position and releases a button that was pressed by a prior CitrixMouseButtonDown call. If the specified button has not been pressed, an error will be raised. Key modifiers (such as Ctrl and Alt) can be provided. Mouse speed can be specified by profile settings (Citrix / Simulation / Mouse) or an appropriate call to the CitrixSetOption function. The position can be specified absolutely, relative to a window (by providing a window handle) or relative to the last mouse position (by setting the bRelative parameter to true).

The top left corner (of the screen or window) has the coordinates 0 / 0.

Include file

CitrixAPI.bdh

Syntax

CitrixMouseButtonUp( in nX        : number,
                     in nY        : number,
                     in bRelative : boolean optional,
                     in nWindow   : number optional,
                     in nButton   : number optional,
                     in nModifier : number optional ) : boolean;

Return value

  • true if successful

  • false otherwise

Parameter | Description
nX | X coordinate of the new mouse position (relative to the provided window or the entire desktop). When the bRelative parameter is set to true, the new mouse position is calculated by adding the specified X value to the current mouse position.
nY | Y coordinate of the new mouse position (relative to the provided window or the entire desktop). When the bRelative parameter is set to true, the new mouse position is calculated by adding the specified Y value to the current mouse position.
bRelative | Specify this parameter to calculate the new mouse position by adding the provided vector (nX, nY) to the current mouse position (optional). When this parameter is omitted, the nWindow parameter dictates how the new mouse position is calculated.
nWindow Window handle returned by a call to CitrixWaitForWindowCreation (optional). When this parameter is omitted or DESKTOP is specified, the provided coordinates must be relative to the desktop. When a window handle is specified, the nX and nY parameters state a position relative to the top left corner of the window (wherever the window is on the desktop).

When the bRelative parameter is set to true, this parameter is ignored.

nButton

Specify one of the following values (optional):

  • MOUSE_ButtonLeft (default): Left mouse button

  • MOUSE_ButtonRight: Right mouse button

  • MOUSE_ButtonMiddle: Middle mouse button

nModifier

Specify one of the following values (optional):

  • MOD_None (default): No modifier

  • MOD_Shift: Shift key pressed in combination with the mouse button

  • MOD_Ctrl: Ctrl key pressed in combination with the mouse button

  • MOD_Alt: Alt key pressed in combination with the mouse button

Example:

transaction TMain
  var
  begin
    CitrixInit(640, 480);
    CitrixConnect("myserver", "myusername", "mypass", "mydomain", COLOR_16bit);
    CitrixWaitForLogon();
    hWnd6 := CitrixWaitForWindowCreation("ICA Seamless Host Agent", MATCH_Exact, 0x94C800C4, 0, 0, 390, 223);
    CitrixWaitForWindow(hWnd6, EVENT_Activate);
    CitrixWaitForWindowCreation("Program Manager");
    CitrixMouseClick(211, 197, hWnd6, MOUSE_ButtonLeft);
    CitrixWaitForWindow(hWnd6, EVENT_Destroy);
    CitrixMouseDblClick(41, 23, DESKTOP, MOUSE_ButtonLeft);
    hWnd8 := CitrixWaitForWindowCreation("My Documents", MATCH_Exact, 0x16CF0000, 171, 98, 328, 235);
    CitrixWaitForWindow(hWnd8, EVENT_Activate);
    CitrixMouseButtonDown(82, 13, hWnd8, MOUSE_ButtonLeft);
    CitrixMouseButtonUp(367, 44, false, DESKTOP, MOUSE_ButtonLeft);
    CitrixWaitForWindowPos(hWnd8, 285, 31);
    ThinkTime(5.41);
    CitrixMouseClick(317, 13, hWnd8, MOUSE_ButtonLeft);
    CitrixWaitForWindow(hWnd8, EVENT_Destroy);
    CitrixDisconnect();
  end TMain;
Parent topic: Mouse Functions
Related reference
CitrixMouseButtonDown Function
CitrixMouseClick Function
CitrixMouseDblClick Function
CitrixMouseMove Function


CitrixMouseClick Function

Action

Moves the mouse to a specified position and presses a specified button. Optionally, the mouse can be specified to move while the button is pressed. Key modifiers (such as Ctrl and Alt) can be provided. Timing parameters (such as mouse speed and key-down time) can be specified in profile settings (Citrix / Simulation / Mouse) or by an appropriate call to the CitrixSetOption function. Coordinates can be specified absolutely or relatively to a window (by providing a window handle).

The top left corner (of the screen or window) has the coordinates 0 / 0.

Include file

CitrixAPI.bdh

Syntax

CitrixMouseClick( in nX        : number,
                  in nY        : number,
                  in nWindow   : number optional,
                  in nButton   : number optional,
                  in nModifier : number optional,
                  in nDX       : number optional,
                  in nDY       : number optional ) : boolean;

Return value

  • true if successful

  • false otherwise

Parameter | Description
nX | X coordinate of the click position.
nY | Y coordinate of the click position.
nWindow | Window handle returned by a call to CitrixWaitForWindowCreation (optional). When this parameter is omitted or DESKTOP is specified, the provided coordinates must be relative to the desktop. When a window handle is specified, the nX and nY parameters state a position relative to the top left corner of the window (wherever the window is on the desktop).
nButton

Specify one of the following values (optional):

  • MOUSE_ButtonLeft (default): Left mouse button

  • MOUSE_ButtonRight: Right mouse button

  • MOUSE_ButtonMiddle: Middle mouse button

nModifier

Specify one of the following values (optional):

  • MOD_None (default): No modifier

  • MOD_Shift: Shift key pressed in combination with the mouse button

  • MOD_Ctrl: Ctrl key pressed in combination with the mouse button

  • MOD_Alt: Alt key pressed in combination with the mouse button

nDX | Specifies how far the mouse moves on the X axis when the button is pressed (drag operation) (optional). When this parameter is omitted the mouse does not move after the button is pressed.
nDY | Specifies how far the mouse moves on the Y axis when the button is pressed (drag operation) (optional). When this parameter is omitted the mouse does not move after the button is pressed.

Example:

transaction TMain
  var
  begin
    CitrixInit(640, 480);
    CitrixConnect("myserver", "myusername", "mypass", "mydomain", COLOR_16bit);
    CitrixWaitForLogon();
    hWnd6 := CitrixWaitForWindowCreation("ICA Seamless Host Agent", MATCH_Exact, 0x94C800C4, 0, 0, 390, 223);
    CitrixWaitForWindow(hWnd6, EVENT_Activate);
    CitrixWaitForWindowCreation("Program Manager");
    CitrixMouseClick(211, 197, hWnd6, MOUSE_ButtonLeft);
    CitrixWaitForWindow(hWnd6, EVENT_Destroy);
    CitrixMouseDblClick(41, 23, DESKTOP, MOUSE_ButtonLeft);
    hWnd8 := CitrixWaitForWindowCreation("My Documents", MATCH_Exact, 0x16CF0000, 171, 98, 328, 235);
    CitrixWaitForWindow(hWnd8, EVENT_Activate);
    CitrixMouseButtonDown(82, 13, hWnd8, MOUSE_ButtonLeft);
    CitrixMouseButtonUp(367, 44, false, DESKTOP, MOUSE_ButtonLeft);
    CitrixWaitForWindowPos(hWnd8, 285, 31);
    ThinkTime(5.41);
    CitrixMouseClick(317, 13, hWnd8, MOUSE_ButtonLeft);
    CitrixWaitForWindow(hWnd8, EVENT_Destroy);
    CitrixDisconnect();
  end TMain;
Parent topic: Mouse Functions
Related reference
CitrixMouseButtonDown Function
CitrixMouseButtonUp Function
CitrixMouseDblClick Function
CitrixMouseMove Function


CitrixMouseDblClick Function

Action

Moves the mouse to a specified position and performs a double-click. Key modifiers (such as Ctrl and Alt) can be provided. Timing parameters (such as mouse speed, key-down time and double-click delay) can be specified by profile settings (Citrix / Simulation / Mouse) or an appropriate call to the CitrixSetOption function. The coordinates can be specified absolutely or relatively to a window (by providing a window handle).

The top left corner (of the screen or window) has the coordinates 0 / 0.

Include file

CitrixAPI.bdh

Syntax

CitrixMouseDblClick( in nX        : number,
                     in nY        : number,
                     in nWindow   : number optional,
                     in nButton   : number optional,
                     in nModifier : number optional ) : boolean

Return value

  • true if successful

  • false otherwise

Parameter | Description
nX | X coordinate of the click position.
nY | Y coordinate of the click position.
nWindow | Window handle returned by a call to CitrixWaitForWindowCreation (optional). When this parameter is omitted or DESKTOP is specified, the provided coordinates must be relative to the desktop. When a window handle is specified, the nX and nY parameters state a position relative to the top left corner of the window (wherever the window is on the desktop).
nButton

Specify one of the following values (optional):

  • MOUSE_ButtonLeft (default): Left mouse button

  • MOUSE_ButtonRight: Right mouse button

  • MOUSE_ButtonMiddle: Middle mouse button

nModifier

Specify one of the following values (optional):

  • MOD_None (default): No modifier

  • MOD_Shift: Shift key pressed in combination with the mouse button

  • MOD_Ctrl: Ctrl key pressed in combination with the mouse button

  • MOD_Alt: Alt key pressed in combination with the mouse button

Example:

transaction TMain
  var
  begin
    CitrixInit(640, 480);
    CitrixConnect("myserver", "myusername", "mypass", "mydomain", COLOR_16bit);
    CitrixWaitForLogon();
    hWnd6 := CitrixWaitForWindowCreation("ICA Seamless Host Agent", MATCH_Exact, 0x94C800C4, 0, 0, 390, 223);
    CitrixWaitForWindow(hWnd6, EVENT_Activate);
    CitrixWaitForWindowCreation("Program Manager");
    CitrixMouseClick(211, 197, hWnd6, MOUSE_ButtonLeft);
    CitrixWaitForWindow(hWnd6, EVENT_Destroy);
    CitrixMouseDblClick(41, 23, DESKTOP, MOUSE_ButtonLeft);
    hWnd8 := CitrixWaitForWindowCreation("My Documents", MATCH_Exact, 0x16CF0000, 171, 98, 328, 235);
    CitrixWaitForWindow(hWnd8, EVENT_Activate);
    CitrixMouseButtonDown(82, 13, hWnd8, MOUSE_ButtonLeft);
    CitrixMouseButtonUp(367, 44, false, DESKTOP, MOUSE_ButtonLeft);
    CitrixWaitForWindowPos(hWnd8, 285, 31);
    ThinkTime(5.41);
    CitrixMouseClick(317, 13, hWnd8, MOUSE_ButtonLeft);
    CitrixWaitForWindow(hWnd8, EVENT_Destroy);
    CitrixDisconnect();
  end TMain;
Parent topic: Mouse Functions
Related reference
CitrixMouseButtonDown Function
CitrixMouseButtonUp Function
CitrixMouseClick Function
CitrixMouseMove Function


CitrixMouseMove Function

Action

Moves the mouse to a specified position. This function does not change the button state. Therefore it can be used to move the mouse between a call to CitrixMouseButtonDown or CitrixMouseButtonUp. Key modifiers (such as Ctrl and Alt) can be provided. Mouse speed can be specified by profile settings (Citrix / Simulation / Mouse) or by an appropriate call to the CitrixSetOption function. The position can be specified absolutely, or relatively to a window (by providing a window handle) or the last mouse position (by setting the bRelative parameter to true).

The top left corner (of the screen or window) has the coordinates 0 / 0.

Include file

CitrixAPI.bdh

Syntax

CitrixMouseMove( in nX        : number,
                 in nY        : number,
                 in bRelative : boolean optional,
                 in nWindow   : number optional,
                 in nModifier : number optional ) : boolean;

Return value

  • true if successful

  • false otherwise

Parameter | Description
nX | X coordinate of the new mouse position (relative to the provided window or the entire desktop). When the bRelative parameter is set to true, the new mouse position is calculated by adding the specified X value to the current mouse position.
nY | Y coordinate of the new mouse position (relative to the provided window or the entire desktop). When the bRelative parameter is set to true, the new mouse position is calculated by adding the specified Y value to the current mouse position.
bRelative | Specify this parameter to calculate the new mouse position by adding the provided vector (nX, nY) to the current mouse position (optional). When this parameter is omitted, the nWindow parameter dictates how the new mouse position is calculated.
nWindow Window handle returned by a call to CitrixWaitForWindowCreation (optional). When this parameter is omitted or DESKTOP is specified, the provided coordinates must be relative to the desktop. When a window handle is specified, the nX and nY parameters state a position relative to the top left corner of the window (wherever the window is on the desktop).

When the bRelative parameter is set to true, this parameter is ignored.

nModifier

Specify one of the following values (optional):

  • MOD_None (default): No modifier

  • MOD_Shift: Shift key pressed in combination with the mouse button

  • MOD_Ctrl: Ctrl key pressed in combination with the mouse button

  • MOD_Alt: Alt key pressed in combination with the mouse button

Example:

transaction TMain
  var
  begin
    CitrixInit(640, 480);
    CitrixConnect("myserver", "myusername", "mypass", "mydomain", COLOR_16bit);
    CitrixWaitForLogon();
    hWnd6 := CitrixWaitForWindowCreation("ICA Seamless Host Agent", MATCH_Exact, 0x94C800C4, 0, 0, 390, 223);
    CitrixWaitForWindow(hWnd6, EVENT_Activate);
    CitrixWaitForWindowCreation("Program Manager");
    CitrixMouseClick(211, 197, hWnd6, MOUSE_ButtonLeft);
    CitrixWaitForWindow(hWnd6, EVENT_Destroy);
    ThinkTime(4.48);
    CitrixMouseClick(41, 13, hWnd4, MOUSE_ButtonLeft);
    hWnd8 := CitrixWaitForWindowCreation("", MATCH_Exact, 0x96400000, 2, 193, 163, 263);
    CitrixMouseMove(76, 117, false, hWnd8);
    hWnd8 := CitrixWaitForWindowCreation("My Documents", MATCH_Exact, 0x16CF0000, 171, 98, 328, 235);
    CitrixWaitForWindow(hWnd8, EVENT_Activate);
    CitrixMouseButtonDown(82, 13, hWnd8, MOUSE_ButtonLeft);
    CitrixMouseButtonUp(367, 44, false, DESKTOP, MOUSE_ButtonLeft);
    CitrixWaitForWindowPos(hWnd8, 285, 31);
    ThinkTime(5.41);
    CitrixMouseClick(317, 13, hWnd8, MOUSE_ButtonLeft);
    CitrixWaitForWindow(hWnd8, EVENT_Destroy);
    CitrixDisconnect();
  end TMain;
Parent topic: Mouse Functions
Related reference
CitrixMouseButtonDown Function
CitrixMouseButtonUp Function
CitrixMouseClick Function
CitrixMouseDblClick Function


Keyboard Functions

  • CitrixKey Function
    Types a specified key.
  • CitrixKeyDown Function
    Presses a specified key.
  • CitrixKeyString Function
    Types the specified string into the window that has keyboard focus.
  • CitrixKeyUp Function
    Releases a specified key that was pressed by a prior CitrixKeyDown call.
Parent topic: Citrix Functions Overview


CitrixKey Function

Action

Types a specified key. The window that has keyboard focus receives the key-stroke event. Key modifiers (such as Shift and Alt) can be provided. The third parameter specifies how often the key is to be pressed. Timing parameters (such as key down-time and repeat-delay) can be specified in profile settings (Citrix / Simulation / Keyboard) or by an appropriate call to the CitrixSetOption function.

Include file

CitrixAPI.bdh

Syntax

CitrixKey( in nKey      : number,
           in nModifier : number optional,
           in nRepeat   : number optional ) : boolean;

Return value

  • true if successful

  • false otherwise

Parameter | Description
nKey

The key to type. Use a key number (ASCII code) or one of these predefined values:

  • KEY_Backspace

  • KEY_Tab

  • KEY_Enter

  • KEY_Shift

  • KEY_Ctrl

  • KEY_Alt

  • KEY_PageUp

  • KEY_PageDown

  • KEY_End

  • KEY_Home

  • KEY_LeftArrow

  • KEY_UpArrow

  • KEY_RightArrow

  • KEY_DownArrow

  • KEY_Insert

  • KEY_Delete

  • KEY_NumLock

See the CitrixApi.bdh for additional predefined values.

nModifier

Specify one of the following values (optional):

  • MOD_None (default): No modifier

  • MOD_Shift: Shift key pressed in combination with the mouse button

  • MOD_Ctrl: Ctrl key pressed in combination with the mouse button

  • MOD_Alt: Alt key pressed in combination with the mouse button

To use more than one key modifier, combine the modifiers with the "|" symbol, For example, to type the key "Ctrl-Shift-X", use the following syntax:

CitrixKey(88, MOD_Ctrl | MOD_Shift);
nRepeat | Repeat count of key strokes (optional). When this parameter is omitted the key is pressed once.

Example:

  transaction TMain
  var
  begin
    CitrixInit(640, 480);
    CitrixConnect("myserver", "myusername", "mypass", "mydomain", COLOR_16bit);
    CitrixWaitForLogon();
    hWnd6 := CitrixWaitForWindowCreation("ICA Seamless Host Agent", MATCH_Exact, 0x94C800C4, 0, 0, 390, 223);
    CitrixWaitForWindow(hWnd6, EVENT_Activate);
    CitrixWaitForWindowCreation("Program Manager");
    ThinkTime(8.25);
    CitrixMouseClick(219, 195, hWnd6, MOUSE_ButtonLeft);
    CitrixWaitForWindow(hWnd6, EVENT_Destroy);
    CitrixMouseDblClick(113, 20, DESKTOP, MOUSE_ButtonLeft);
    hWnd10 := CitrixWaitForWindowCreation("Microsoft Excel", MATCH_Exact, 0x15CF0000, -4, -4, 648, 460);
    CitrixWaitForWindow(hWnd10, EVENT_Activate);
    CitrixWaitForWindow(hWnd10, EVENT_CaptionChange, "Microsoft Excel - Book1", MATCH_Exact);
    CitrixKeyString("field1");
    CitrixKey(KEY_Enter);
    CitrixKeyString("field2");
    CitrixKey(KEY_Enter, MOD_None, 3);
    CitrixKeyString("a");
    CitrixKey(KEY_Enter);
    CitrixKey(65, MOD_Ctrl); // 'a'
    CitrixMouseClick(630, 13, hWnd10, MOUSE_ButtonLeft);
    hWnd11 := CitrixWaitForWindowCreation("Microsoft Excel", MATCH_Exact, 0x94C801C5, 149, 206, 350, 108);
    CitrixWaitForWindow(hWnd11, EVENT_Activate);
    CitrixMouseClick(186, 85, hWnd11, MOUSE_ButtonLeft);
    CitrixWaitForWindow(hWnd11, EVENT_Destroy);
    CitrixWaitForWindow(hWnd10, EVENT_Destroy);
    CitrixDisconnect();
  end TMain;

Parent topic: Keyboard Functions
Related reference
CitrixKeyDown Function
CitrixKeyString Function
CitrixKeyUp Function


CitrixKeyDown Function

Action

Presses a specified key. To release the key, call the CitrixKeyUp function. The window that has keyboard focus receives the key event.

Include file

CitrixAPI.bdh

Syntax

CitrixKeyDown( in nKey : number ) : boolean;

Return value

  • true if successful

  • false otherwise

Parameter Description
nKey

The key to type. Use a key number (ASCII code) or one of these predefined values:

  • KEY_Backspace

  • KEY_Tab

  • KEY_Enter

  • KEY_Shift

  • KEY_Ctrl

  • KEY_Alt

  • KEY_PageUp

  • KEY_PageDown

  • KEY_End

  • KEY_Home

  • KEY_LeftArrow

  • KEY_UpArrow

  • KEY_RightArrow

  • KEY_DownArrow

  • KEY_Insert

  • KEY_Delete

  • KEY_NumLock

See the CitrixApi.bdh for additional predefined values.

Example:

  transaction TMain
  var
  begin
    CitrixInit(640, 480);
    CitrixConnect("myserver", "myusername", "mypass", "mydomain", COLOR_16bit);
    CitrixWaitForLogon();
    hWnd6 := CitrixWaitForWindowCreation("ICA Seamless Host Agent", MATCH_Exact, 0x94C800C4, 0, 0, 390, 223);
    CitrixWaitForWindow(hWnd6, EVENT_Activate);
    CitrixWaitForWindowCreation("Program Manager");
    ThinkTime(8.25);
    CitrixMouseClick(219, 195, hWnd6, MOUSE_ButtonLeft);
    CitrixWaitForWindow(hWnd6, EVENT_Destroy);
    CitrixMouseDblClick(113, 20, DESKTOP, MOUSE_ButtonLeft);
    hWnd10 := CitrixWaitForWindowCreation("Microsoft Excel", MATCH_Exact, 0x15CF0000, -4, -4, 648, 460);
    CitrixWaitForWindow(hWnd10, EVENT_Activate);
    CitrixKeyDown(KEY_Enter);
    CitrixMouseClick(208, 268, hWnd10, MOUSE_ButtonLeft);
    CitrixKeyUp(KEY_Enter);
    CitrixMouseClick(630, 13, hWnd10, MOUSE_ButtonLeft);
    hWnd11 := CitrixWaitForWindowCreation("Microsoft Excel", MATCH_Exact, 0x94C801C5, 149, 206, 350, 108);
    CitrixWaitForWindow(hWnd11, EVENT_Activate);
    CitrixMouseClick(186, 85, hWnd11, MOUSE_ButtonLeft);
    CitrixWaitForWindow(hWnd11, EVENT_Destroy);
    CitrixWaitForWindow(hWnd10, EVENT_Destroy);
    CitrixDisconnect();
  end TMain;
Parent topic: Keyboard Functions
Related reference
CitrixKey Function
CitrixKeyString Function
CitrixKeyUp Function


CitrixKeyString Function

Action

Types the specified string into the window that has keyboard focus.

Include file

CitrixAPI.bdh

Syntax

CitrixKeyString( in sInput : string ) : boolean;

Return value

  • true if successful

  • false otherwise

Parameter | Description
sInput | String to type.

Example:

  transaction TMain
  var
  begin
    CitrixInit(640, 480);
    CitrixConnect("myserver", "myusername", "mypass", "mydomain", COLOR_16bit);
    CitrixWaitForLogon();
    hWnd6 := CitrixWaitForWindowCreation("ICA Seamless Host Agent", MATCH_Exact, 0x94C800C4, 0, 0, 390, 223);
    CitrixWaitForWindow(hWnd6, EVENT_Activate);
    CitrixWaitForWindowCreation("Program Manager");
    ThinkTime(8.25);
    CitrixMouseClick(219, 195, hWnd6, MOUSE_ButtonLeft);
    CitrixWaitForWindow(hWnd6, EVENT_Destroy);
    CitrixMouseDblClick(113, 20, DESKTOP, MOUSE_ButtonLeft);
    hWnd10 := CitrixWaitForWindowCreation("Microsoft Excel", MATCH_Exact, 0x15CF0000, -4, -4, 648, 460);
    CitrixWaitForWindow(hWnd10, EVENT_Activate);
    CitrixWaitForWindow(hWnd10, EVENT_CaptionChange, "Microsoft Excel - Book1", MATCH_Exact);
    CitrixKeyString("field1");
    CitrixKey(KEY_Enter);
    CitrixKeyString("field2");
    CitrixKey(KEY_Enter, MOD_None, 3);
    CitrixKeyString("a");
    CitrixKey(KEY_Enter);
    CitrixKey(65, MOD_Ctrl); // 'a'
    CitrixMouseClick(630, 13, hWnd10, MOUSE_ButtonLeft);
    hWnd11 := CitrixWaitForWindowCreation("Microsoft Excel", MATCH_Exact, 0x94C801C5, 149, 206, 350, 108);
    CitrixWaitForWindow(hWnd11, EVENT_Activate);
    CitrixMouseClick(186, 85, hWnd11, MOUSE_ButtonLeft);
    CitrixWaitForWindow(hWnd11, EVENT_Destroy);
    CitrixWaitForWindow(hWnd10, EVENT_Destroy);
    CitrixDisconnect();
  end TMain;
Parent topic: Keyboard Functions
Related reference
CitrixKey Function
CitrixKeyDown Function
CitrixKeyUp Function


CitrixKeyUp Function

Action

Releases a specified key that was pressed by a prior CitrixKeyDown call. If the key has not been pressed, an error will be raised.

Include file

CitrixAPI.bdh

Syntax

CitrixKeyUp( in nKey :  number ) : boolean;

Return value

  • true if successful

  • false otherwise

Parameter Description
nKey

The key to type. Use a key number (ASCII code) or one of these predefined values:

  • KEY_Backspace

  • KEY_Tab

  • KEY_Enter

  • KEY_Shift

  • KEY_Ctrl

  • KEY_Alt

  • KEY_PageUp

  • KEY_PageDown

  • KEY_End

  • KEY_Home

  • KEY_LeftArrow

  • KEY_UpArrow

  • KEY_RightArrow

  • KEY_DownArrow

  • KEY_Insert

  • KEY_Delete

  • KEY_NumLock

See the CitrixApi.bdh for additional predefined values.

Example:

  transaction TMain
  var
  begin
    CitrixInit(640, 480);
    CitrixConnect("myserver", "myusername", "mypass", "mydomain", COLOR_16bit);
    CitrixWaitForLogon();
    hWnd6 := CitrixWaitForWindowCreation("ICA Seamless Host Agent", MATCH_Exact, 0x94C800C4, 0, 0, 390, 223);
    CitrixWaitForWindow(hWnd6, EVENT_Activate);
    CitrixWaitForWindowCreation("Program Manager");
    ThinkTime(8.25);
    CitrixMouseClick(219, 195, hWnd6, MOUSE_ButtonLeft);
    CitrixWaitForWindow(hWnd6, EVENT_Destroy);
    CitrixMouseDblClick(113, 20, DESKTOP, MOUSE_ButtonLeft);
    hWnd10 := CitrixWaitForWindowCreation("Microsoft Excel", MATCH_Exact, 0x15CF0000, -4, -4, 648, 460);
    CitrixWaitForWindow(hWnd10, EVENT_Activate);
    CitrixKeyDown(KEY_Enter);
    CitrixMouseClick(208, 268, hWnd10, MOUSE_ButtonLeft);
    CitrixKeyUp(KEY_Enter);
    CitrixMouseClick(630, 13, hWnd10, MOUSE_ButtonLeft);
    hWnd11 := CitrixWaitForWindowCreation("Microsoft Excel", MATCH_Exact, 0x94C801C5, 149, 206, 350, 108);
    CitrixWaitForWindow(hWnd11, EVENT_Activate);
    CitrixMouseClick(186, 85, hWnd11, MOUSE_ButtonLeft);
    CitrixWaitForWindow(hWnd11, EVENT_Destroy);
    CitrixWaitForWindow(hWnd10, EVENT_Destroy);
    CitrixDisconnect();
  end TMain;
Parent topic: Keyboard Functions
Related reference
CitrixKey Function
CitrixKeyDown Function
CitrixKeyString Function


Window Functions

  • CitrixGetWindow Function
    Returns the specified window of the currently tracked window stack.
  • CitrixGetWindowCaption Function
    Returns the caption of the specified window.
  • CitrixGetWindowId Function
    Returns the window-id (MS Windows) of the specified window.
  • CitrixGetWindowParentId Function
    Returns the window-id (MS Windows) of the parent window of the specified window.
  • CitrixGetWindowPos Function
    Returns the position of the specified window.
  • CitrixGetWindowSize Function
    Returns the size of the specified window.
  • CitrixGetWindowStyle Function
    Returns the style and the extended style of the specified window.
  • CitrixWindowBringToTop Function
    Brings the specified window to the top-most position.
  • CitrixWindowMove function
    Moves the specified window.
  • CitrixWindowResize Function
    Resizes the specified window.
  • CitrixSearchWindow Function
    Searches all tracked windows for a suitable window. The opposite of the CitrixWaitForWindowCreation function, this function does not wait until a specified window appears.
  • CitrixSearchWindowById Function
    Uses window-id (MS Windows) to search for a window.
Parent topic: Citrix Functions Overview


CitrixGetWindow Function

Action

This function returns the specified window of the currently tracked window stack. The nOrder parameter specifies which window is to be returned. If the function succeeds, a window handle that can be used as the nWindow parameter in Citrix functions is returned.

Include file

CitrixAPI.bdh

Syntax

CitrixGetWindow( in nOrder : number ): number;

Return value

  • > 0 if the function succeeds

  • 0 otherwise

Parameter Description
nOrder

Specifies one of the following values:

  • 0 For the top-most window.

  • >0 Specifies the position of the window in relation to the top-most window (e.g., “2” is the 3rd position).

  • -1 Specifies the active window (the top-most window may be a different window).

  • -2 Specifies the bottom-most window.

Example:

  transaction TMain
  var
    sWindowCaption : string;
    nWindowHandle  : number;
    i              : number;
  begin
    CitrixInit(640, 480);
    CitrixConnect("myserver", "myusername", "mypass", "mydomain", COLOR_16bit);
    CitrixWaitForLogon();
    hWnd6 := CitrixWaitForWindowCreation("ICA Seamless Host Agent", MATCH_Exact, 0x94C800C4, 0, 0, 390, 223);
    CitrixWaitForWindow(hWnd6, EVENT_Activate);
    CitrixWaitForWindowCreation("Program Manager");
    CitrixMouseClick(182, 195, hWnd6, MOUSE_ButtonLeft);
    CitrixWaitForWindow(hWnd6, EVENT_Destroy);
    ThinkTime(2.78);
    CitrixMouseDblClick(38, 22, DESKTOP, MOUSE_ButtonLeft);
    hWnd8 := CitrixWaitForWindowCreation("My Documents", MATCH_Exact, 0x16CF0000, 285, 31, 268, 205);
    CitrixWaitForWindow(hWnd8, EVENT_Activate);
    i := 0;
    nWindowHandle := CitrixGetWindow(i);
    while (nWindowHandle > 0) do
      CitrixGetWindowCaption(nWindowHandle, sWindowCaption);
      print("window " + string(nWindowHandle) + ": " + sWindowCaption);
      i := i + 1;
      nWindowHandle := CitrixGetWindow(i);
    end;
    CitrixMouseClick(258, 13, hWnd8, MOUSE_ButtonLeft);
    CitrixWaitForWindow(hWnd8, EVENT_Destroy);
    CitrixDisconnect();
  end TMain;
Parent topic: Window Functions
Related reference
CitrixGetWindowCaption Function
CitrixGetWindowId Function
CitrixGetWindowParentId Function
CitrixGetWindowPos Function
CitrixGetWindowSize Function
CitrixGetWindowStyle Function
CitrixWindowBringToTop Function
CitrixWindowMove function
CitrixWindowResize Function
CitrixSearchWindow Function
CitrixSearchWindowById Function


CitrixGetWindowCaption Function

Action

Returns the caption of the specified window.

Include file

CitrixAPI.bdh

Syntax

CitrixGetWindowCaption( in  nWindow  : number,
                        out sCaption : string ): boolean;

Return value

  • true if the function succeeds

  • false otherwise

Parameter | Description
nWindow | Window handle returned by a call to CitrixWaitForWindowCreation or the SearchWindow functions.
sCaption | Retrieves the caption of the specified window.

Example:

  transaction TMain
  var
    sWindowCaption : string;
    nWindowHandle  : number;
    i              : number;
  begin
    CitrixInit(640, 480);
    CitrixConnect("myserver", "myusername", "mypass", "mydomain", COLOR_16bit);
    CitrixWaitForLogon();
    hWnd6 := CitrixWaitForWindowCreation("ICA Seamless Host Agent", MATCH_Exact, 0x94C800C4, 0, 0, 390, 223);
    CitrixWaitForWindow(hWnd6, EVENT_Activate);
    CitrixWaitForWindowCreation("Program Manager");
    CitrixMouseClick(182, 195, hWnd6, MOUSE_ButtonLeft);
    CitrixWaitForWindow(hWnd6, EVENT_Destroy);
    ThinkTime(2.78);
    CitrixMouseDblClick(38, 22, DESKTOP, MOUSE_ButtonLeft);
    hWnd8 := CitrixWaitForWindowCreation("My Documents", MATCH_Exact, 0x16CF0000, 285, 31, 268, 205);
    CitrixWaitForWindow(hWnd8, EVENT_Activate);
    i := 0;
    nWindowHandle := CitrixGetWindow(i);
    while (nWindowHandle > 0) do
      CitrixGetWindowCaption(nWindowHandle, sWindowCaption);
      print("window " + string(nWindowHandle) + ": " + sWindowCaption);
      i := i + 1;
      nWindowHandle := CitrixGetWindow(i);
    end;
    CitrixMouseClick(258, 13, hWnd8, MOUSE_ButtonLeft);
    CitrixWaitForWindow(hWnd8, EVENT_Destroy);
    CitrixDisconnect();
  end TMain;
Parent topic: Window Functions
Related reference
CitrixGetWindow Function
CitrixGetWindowId Function
CitrixGetWindowParentId Function
CitrixGetWindowPos Function
CitrixGetWindowSize Function
CitrixGetWindowStyle Function
CitrixWindowBringToTop Function
CitrixWindowMove function
CitrixWindowResize Function
CitrixSearchWindow Function
CitrixSearchWindowById Function


CitrixGetWindowId Function

Action

Returns the window-id (MS Windows) of the specified window.

Include file

CitrixAPI.bdh

Syntax

CitrixGetWindowId( in  nWindow   : number,
                   out ParamName : number ): boolean;

Return value

  • true if the function succeeds

  • false otherwise

Parameter | Description
nWindow | Window handle returned by a call to CitrixWaitForWindowCreation or the SearchWindow functions.
nId | Retrieves the window-id of the specified window.

Example:

  transaction TMain
  var
    sWindowCaption : string;
    nWindowHandle  : number;
    nWindowID      : number;
    nWindowParentID: number;
    i              : number;
  begin
    CitrixInit(640, 480);
    CitrixConnect("myserver", "myusername", "mypass", "mydomain", COLOR_16bit);
    CitrixWaitForLogon();
    hWnd6 := CitrixWaitForWindowCreation("ICA Seamless Host Agent", MATCH_Exact, 0x94C800C4, 0, 0, 390, 223);
    CitrixWaitForWindow(hWnd6, EVENT_Activate);
    CitrixWaitForWindowCreation("Program Manager");
    CitrixMouseClick(182, 195, hWnd6, MOUSE_ButtonLeft);
    CitrixWaitForWindow(hWnd6, EVENT_Destroy);
    ThinkTime(2.78);
    CitrixMouseDblClick(38, 22, DESKTOP, MOUSE_ButtonLeft);
    hWnd8 := CitrixWaitForWindowCreation("My Documents", MATCH_Exact, 0x16CF0000, 285, 31, 268, 205);
    CitrixWaitForWindow(hWnd8, EVENT_Activate);
    i := 0;
    nWindowHandle := CitrixGetWindow(i);
    while (nWindowHandle > 0) do
      CitrixGetWindowId(nWindowHandle, nWindowID);
      CitrixGetWindowParentId(nWindowHandle, nWindowParentID);
      CitrixGetWindowCaption(nWindowHandle, sWindowCaption);
      print("window " + string(nWindowHandle)
                      + "; id: " + string(nWindowID)
                      + "; parentid: "
                      + string(nWindowHandle) + "; name: "
                      + sWindowCaption);
      i := i + 1;
      nWindowHandle := CitrixGetWindow(i);
    end;
    CitrixMouseClick(258, 13, hWnd8, MOUSE_ButtonLeft);
    CitrixWaitForWindow(hWnd8, EVENT_Destroy);
    CitrixDisconnect();
  end TMain;
Parent topic: Window Functions
Related reference
CitrixGetWindow Function
CitrixGetWindowCaption Function
CitrixGetWindowParentId Function
CitrixGetWindowPos Function
CitrixGetWindowSize Function
CitrixGetWindowStyle Function
CitrixWindowBringToTop Function
CitrixWindowMove function
CitrixWindowResize Function
CitrixSearchWindow Function
CitrixSearchWindowById Function


CitrixGetWindowParentId Function

Action

Returns the window-id (MS Windows) of the parent window of the specified window.

Include file

CitrixAPI.bdh

Syntax

CitrixGetWindowParentId( in  nWindow : number,
                         out nId     : number ): boolean;

Return value

  • true if the function succeeds

  • false otherwise

Parameter | Description
nWindow | Window handle returned by a call to CitrixWaitForWindowCreation or the SearchWindow functions.
nId | Retrieves the window-id of the parent window of the specified window.

Example:

  transaction TMain
  var
    sWindowCaption : string;
    nWindowHandle  : number;
    nWindowID      : number;
    nWindowParentID: number;
    i              : number;
  begin
    CitrixInit(640, 480);
    CitrixConnect("myserver", "myusername", "mypass", "mydomain", COLOR_16bit);
    CitrixWaitForLogon();
    hWnd6 := CitrixWaitForWindowCreation("ICA Seamless Host Agent", MATCH_Exact, 0x94C800C4, 0, 0, 390, 223);
    CitrixWaitForWindow(hWnd6, EVENT_Activate);
    CitrixWaitForWindowCreation("Program Manager");
    CitrixMouseClick(182, 195, hWnd6, MOUSE_ButtonLeft);
    CitrixWaitForWindow(hWnd6, EVENT_Destroy);
    ThinkTime(2.78);
    CitrixMouseDblClick(38, 22, DESKTOP, MOUSE_ButtonLeft);
    hWnd8 := CitrixWaitForWindowCreation("My Documents", MATCH_Exact, 0x16CF0000, 285, 31, 268, 205);
    CitrixWaitForWindow(hWnd8, EVENT_Activate);
    i := 0;
    nWindowHandle := CitrixGetWindow(i);
    while (nWindowHandle > 0) do
      CitrixGetWindowId(nWindowHandle, nWindowID);
      CitrixGetWindowParentId(nWindowHandle, nWindowParentID);
      CitrixGetWindowCaption(nWindowHandle, sWindowCaption);
      print("window " + string(nWindowHandle)
                      + "; id: " + string(nWindowID)
                      + "; parentid: "
                      + string(nWindowHandle) + "; name: "
                      + sWindowCaption);
      i := i + 1;
      nWindowHandle := CitrixGetWindow(i);
    end;
    CitrixMouseClick(258, 13, hWnd8, MOUSE_ButtonLeft);
    CitrixWaitForWindow(hWnd8, EVENT_Destroy);
    CitrixDisconnect();
  end TMain;
Parent topic: Window Functions
Related reference
CitrixGetWindow Function
CitrixGetWindowCaption Function
CitrixGetWindowId Function
CitrixGetWindowPos Function
CitrixGetWindowSize Function
CitrixGetWindowStyle Function
CitrixWindowBringToTop Function
CitrixWindowMove function
CitrixWindowResize Function
CitrixSearchWindow Function
CitrixSearchWindowById Function


CitrixGetWindowPos Function

Action

Returns the position of the specified window.

Include file

CitrixAPI.bdh

Syntax

CitrixGetWindowPos( in  nWindow : number,
                    out nX      : number allownull,
                    out nY      : number optional ): boolean;

Return value

  • true if the function succeeds

  • false otherwise

Parameter | Description
nWindow | Window handle returned by a call to CitrixWaitForWindowCreation or the SearchWindow functions.
nX | Retrieves the X-coordinate of the top-left corner of the specified window. When only the Y-coordinate is of interest, null may be specified.
nY | Retrieves the Y-coordinate of the top-left corner of the specified window (optional).

Example:

  transaction TMain
  var
    nWindowHandle  : number;
    i              : number;
    iWindowPosX    : number;
    iWindowPosY    : number;
  begin
    CitrixInit(640, 480);
    CitrixConnect("myserver", "myusername", "mypass", "mydomain", COLOR_16bit);
    CitrixWaitForLogon();
    hWnd6 := CitrixWaitForWindowCreation("ICA Seamless Host Agent", MATCH_Exact, 0x94C800C4, 0, 0, 390, 223);
    CitrixWaitForWindow(hWnd6, EVENT_Activate);
    CitrixWaitForWindowCreation("Program Manager");
    CitrixMouseClick(182, 195, hWnd6, MOUSE_ButtonLeft);
    CitrixWaitForWindow(hWnd6, EVENT_Destroy);
    ThinkTime(2.78);
    CitrixMouseDblClick(38, 22, DESKTOP, MOUSE_ButtonLeft);
    hWnd8 := CitrixWaitForWindowCreation("My Documents", MATCH_Exact, 0x16CF0000, 285, 31, 268, 205);
    CitrixWaitForWindow(hWnd8, EVENT_Activate);
    i := 0;
    nWindowHandle := CitrixGetWindow(i);
    while (nWindowHandle > 0) do
      CitrixGetWindowPos(nWIndowHandle, iWindowPosX, iWindowPosY);
      print("window " + string(nWindowHandle)
                      + "; pos x: " + string(iWindowPosX)
                      + "; pos y: " + string(iWindowPosY));
      i := i + 1;
      nWindowHandle := CitrixGetWindow(i);
    end;
    CitrixMouseClick(258, 13, hWnd8, MOUSE_ButtonLeft);
    CitrixWaitForWindow(hWnd8, EVENT_Destroy);
    CitrixDisconnect();
  end TMain;
Parent topic: Window Functions
Related reference
CitrixGetWindow Function
CitrixGetWindowCaption Function
CitrixGetWindowId Function
CitrixGetWindowParentId Function
CitrixGetWindowSize Function
CitrixGetWindowStyle Function
CitrixWindowBringToTop Function
CitrixWindowMove function
CitrixWindowResize Function
CitrixSearchWindow Function
CitrixSearchWindowById Function


CitrixGetWindowSize Function

Action

Returns the size of the specified window.

Include file

CitrixAPI.bdh

Syntax

CitrixGetWindowSize( in  nWindow : number,
                     out nWidth  : number allownull,
                     out nHeight : number optional ): boolean;

Return value

  • true if the function succeeds

  • false otherwise

Parameter | Description
nWindow | Window handle returned by a call to CitrixWaitForWindowCreation or the SearchWindow functions.
nWidth | Retrieves the width of the specified window. When only the height is of interest, null may be specified.
nHeight | Retrieves the height of the specified window (optional).

Example:

  transaction TMain
  var
    nWindowHandle  : number;
    i              : number;
    iWindowWidth   : number;
    iWindowHeight  : number;
  begin
    CitrixInit(640, 480);
    CitrixConnect("myserver", "myusername", "mypass", "mydomain", COLOR_16bit);
    CitrixWaitForLogon();
    hWnd6 := CitrixWaitForWindowCreation("ICA Seamless Host Agent", MATCH_Exact, 0x94C800C4, 0, 0, 390, 223);
    CitrixWaitForWindow(hWnd6, EVENT_Activate);
    CitrixWaitForWindowCreation("Program Manager");
    CitrixMouseClick(182, 195, hWnd6, MOUSE_ButtonLeft);
    CitrixWaitForWindow(hWnd6, EVENT_Destroy);
    ThinkTime(2.78);
    CitrixMouseDblClick(38, 22, DESKTOP, MOUSE_ButtonLeft);
    hWnd8 := CitrixWaitForWindowCreation("My Documents", MATCH_Exact, 0x16CF0000, 285, 31, 268, 205);
    CitrixWaitForWindow(hWnd8, EVENT_Activate);
    i := 0;
    nWindowHandle := CitrixGetWindow(i);
    while (nWindowHandle > 0) do
      CitrixGetWindowSize(nWIndowHandle, iWindowWidth, iWindowHeight);
      print("window " + string(nWindowHandle)
                      + "; width: " + string(iWindowWidth)
                      + "; height: " + string(iWindowHeight));
      i := i + 1;
      nWindowHandle := CitrixGetWindow(i);
    end;
    CitrixMouseClick(258, 13, hWnd8, MOUSE_ButtonLeft);
    CitrixWaitForWindow(hWnd8, EVENT_Destroy);
    CitrixDisconnect();
  end TMain;
Parent topic: Window Functions
Related reference
CitrixGetWindow Function
CitrixGetWindowCaption Function
CitrixGetWindowId Function
CitrixGetWindowParentId Function
CitrixGetWindowPos Function
CitrixGetWindowStyle Function
CitrixWindowBringToTop Function
CitrixWindowMove function
CitrixWindowResize Function
CitrixSearchWindow Function
CitrixSearchWindowById Function


CitrixGetWindowStyle Function

Action

Returns the style and the extended style of the specified window.

Include file

CitrixAPI.bdh

Syntax

CitrixGetWindowStyle( in  nWindow   : number,
                      out nStyle    : number allownull,
                      out nExtStyle : number optional ): boolean;

Return value

  • true if the function succeeds

  • false otherwise

Parameter | Description
nWindow | Window handle returned by a call to CitrixWaitForWindowCreation or the SearchWindow functions.
nStyle | Retrieves the style of the specified window. When only the extended style is of interest, null may be specified.
nExtStyle | Retrieves the extended style of the specified window (optional).

Example:

  transaction TMain
  var
    nWindowHandle  : number;
    i              : number;
    iStyle         : number;
    iExtStyle      : number;
  begin
    CitrixInit(640, 480);
    CitrixConnect("myserver", "myusername", "mypass", "mydomain", COLOR_16bit);
    CitrixWaitForLogon();
    hWnd6 := CitrixWaitForWindowCreation("ICA Seamless Host Agent", MATCH_Exact, 0x94C800C4, 0, 0, 390, 223);
    CitrixWaitForWindow(hWnd6, EVENT_Activate);
    CitrixWaitForWindowCreation("Program Manager");
    CitrixMouseClick(182, 195, hWnd6, MOUSE_ButtonLeft);
    CitrixWaitForWindow(hWnd6, EVENT_Destroy);
    ThinkTime(2.78);
    CitrixMouseDblClick(38, 22, DESKTOP, MOUSE_ButtonLeft);
    hWnd8 := CitrixWaitForWindowCreation("My Documents", MATCH_Exact, 0x16CF0000, 285, 31, 268, 205);
    CitrixWaitForWindow(hWnd8, EVENT_Activate);
    i := 0;
    nWindowHandle := CitrixGetWindow(i);
    while (nWindowHandle > 0) do
      CitrixGetWindowStyle(nWIndowHandle, iStyle, iExtStyle);
      print("window " + string(nWindowHandle)
                      + "; style: " + string(iStyle)
                      + "; ext style: " + string(iExtStyle));
      i := i + 1;
      nWindowHandle := CitrixGetWindow(i);
    end;
    CitrixMouseClick(258, 13, hWnd8, MOUSE_ButtonLeft);
    CitrixWaitForWindow(hWnd8, EVENT_Destroy);
    CitrixDisconnect();
  end TMain;
Parent topic: Window Functions
Related reference
CitrixGetWindow Function
CitrixGetWindowCaption Function
CitrixGetWindowId Function
CitrixGetWindowParentId Function
CitrixGetWindowPos Function
CitrixGetWindowSize Function
CitrixWindowBringToTop Function
CitrixWindowMove function
CitrixWindowResize Function
CitrixSearchWindow Function
CitrixSearchWindowById Function


CitrixWindowBringToTop Function

Action

Brings the specified window to the top-most position. Note that a normal application window may not appear in front of the task-bar while the “Always on top” setting is enabled.

Include file

CitrixAPI.bdh

Syntax

CitrixWindowBringToTop( in nWindow : number ): boolean;

Return value

  • true if the function succeeds

  • false otherwise

Parameter | Description
nWindow | Window handle returned by a call to CitrixWaitForWindowCreation or the SearchWindow functions.

Example:

  transaction Tmain
  var
  begin
    CitrixInit(640, 480);
    CitrixConnect("myserver", "myusername", "mypass", "mydomain", COLOR_16bit);
    CitrixWaitForLogon();
    hWnd4 := CitrixWaitForWindowCreation("", MATCH_Exact, 0x96840000, -2, 452, 644, 30);
    hWnd5 := CitrixWaitForWindowCreation("ICA Seamless Host Agent", MATCH_Exact, 0x94C800C4, 0, 0, 390, 223);
    CitrixWaitForWindow(hWnd5, EVENT_Activate);
    CitrixWaitForWindowCreation("Program Manager");
    CitrixMouseClick(212, 194, hWnd5, MOUSE_ButtonLeft);
    CitrixWaitForWindow(hWnd5, EVENT_Destroy);
    ThinkTime(3.86);
    CitrixMouseDblClick(34, 21, DESKTOP, MOUSE_ButtonLeft);
    hWnd7 := CitrixWaitForWindowCreation("My Documents", MATCH_Exact, 0x16CF0000, 285, 31, 200, 100);
    CitrixWaitForWindow(hWnd7, EVENT_Activate);
    CitrixMouseDblClick(112, 20, DESKTOP, MOUSE_ButtonLeft);
    hWnd9 := CitrixWaitForWindowCreation("Microsoft Excel – Book4", MATCH_Exact, 0x15CF0000, -4, -4, 648, 460);
    CitrixMouseClick(179, 16, hWnd4, MOUSE_ButtonLeft);
    hWnd10 := CitrixWaitForWindowCreation("UltraEdit-32 – [Edit1]", MATCH_Exact, 0x15CF8000, -4, -4, 648, 460);
    CitrixWindowBringToTop(hWnd7); // bring "My Documents" to top
    wait 2.0;
    CitrixMouseClick(633, 15, hWnd10, MOUSE_ButtonLeft);
    CitrixWaitForWindow(hWnd10, EVENT_Destroy);
    CitrixMouseClick(633, 12, hWnd9, MOUSE_ButtonLeft);
    CitrixWaitForWindow(hWnd9, EVENT_Destroy);
    CitrixMouseClick(189, 9, hWnd7, MOUSE_ButtonLeft);
    CitrixWaitForWindow(hWnd7, EVENT_Destroy);
    CitrixDisconnect();
  end TMain;
Parent topic: Window Functions
Related reference
CitrixGetWindow Function
CitrixGetWindowCaption Function
CitrixGetWindowId Function
CitrixGetWindowParentId Function
CitrixGetWindowPos Function
CitrixGetWindowSize Function
CitrixGetWindowStyle Function
CitrixWindowMove function
CitrixWindowResize Function
CitrixSearchWindow Function
CitrixSearchWindowById Function


CitrixWindowMove function

Action

Moves the specified window. The target position can either be specified absolutely or relative to the current position.

Include file

CitrixAPI.bdh

Syntax

CitrixWindowMove( in nWindow   : number,
            in nX        : number,
            in nY        : number,
            in bRelative : boolean optional ): boolean;

Return value

  • true if the function succeeds

  • false otherwise

Parameter | Description
nWindow | Window handle returned by a call to CitrixWaitForWindowCreation or the SearchWindow functions.
nX | When bRelative is omitted or set to false, the left margin of the window is moved to this X-coordinate. When bRelative is set to true, the window is moved horizontally nX pixels (may be a negative value).
nY | When bRelative is omitted or set to false, the top margin of the window is moved to this Y-coordinate. When bRelative is set to true, the window is moved vertically nY pixels (may be a negative value).
bRelative | Specifies whether the nX and nY parameters are interpreted as absolute coordinates or as a move vector (optional).

Example:

  transaction TMain
  var
  begin
    CitrixInit(640, 480);
    CitrixConnect("myserver", "myusername", "mypass", "mydomain", COLOR_16bit);
    CitrixWaitForLogon();
    hWnd6 := CitrixWaitForWindowCreation("ICA Seamless Host Agent", MATCH_Exact, 0x94C800C4, 0, 0, 390, 223);
    CitrixWaitForWindow(hWnd6, EVENT_Activate);
    CitrixWaitForWindowCreation("Program Manager");
    CitrixMouseClick(182, 195, hWnd6, MOUSE_ButtonLeft);
    CitrixWaitForWindow(hWnd6, EVENT_Destroy);
    ThinkTime(2.78);
    CitrixMouseDblClick(38, 22, DESKTOP, MOUSE_ButtonLeft);
    hWnd8 := CitrixWaitForWindowCreation("My Documents", MATCH_Exact, 0x16CF0000, 285, 31, 268, 205);
    CitrixWaitForWindow(hWnd8, EVENT_Activate);
    CitrixWindowMove(hWnd8, 10, 10, true);
    wait
            1.0;
    CitrixMouseClick(258, 13, hWnd8, MOUSE_ButtonLeft);
    CitrixWaitForWindow(hWnd8, EVENT_Destroy);
    CitrixDisconnect();
  end TMain;
Parent topic: Window Functions
Related reference
CitrixGetWindow Function
CitrixGetWindowCaption Function
CitrixGetWindowId Function
CitrixGetWindowParentId Function
CitrixGetWindowPos Function
CitrixGetWindowSize Function
CitrixGetWindowStyle Function
CitrixWindowBringToTop Function
CitrixWindowResize Function
CitrixSearchWindow Function
CitrixSearchWindowById Function


CitrixWindowResize Function

Action

Resizes the specified window.

Include file

CitrixAPI.bdh

Syntax

CitrixWindowResize( in nWindow : number,
                    in nWidth  : number,
                    in nHeight : number ): boolean;

Return value

  • true if the function succeeds

  • false otherwise

Parameter | Description
nWindow | Window handle returned by a call to CitrixWaitForWindowCreation or the SearchWindow functions.
nWidth | Specifies the new width of the window.
nHeight | Specifies the new height of the window.

Example:

  transaction TMain
  var
  begin
    CitrixInit(640, 480);
    CitrixConnect("myserver", "myusername", "mypass", "mydomain", COLOR_16bit);
    CitrixWaitForLogon();
    hWnd6 := CitrixWaitForWindowCreation("ICA Seamless Host Agent", MATCH_Exact, 0x94C800C4, 0, 0, 390, 223);
    CitrixWaitForWindow(hWnd6, EVENT_Activate);
    CitrixWaitForWindowCreation("Program Manager");
    CitrixMouseClick(182, 195, hWnd6, MOUSE_ButtonLeft);
    CitrixWaitForWindow(hWnd6, EVENT_Destroy);
    ThinkTime(2.78);
    CitrixMouseDblClick(38, 22, DESKTOP, MOUSE_ButtonLeft);
    hWnd8 := CitrixWaitForWindowCreation("My Documents", MATCH_Exact, 0x16CF0000, 285, 31, 268, 205);
    CitrixWaitForWindow(hWnd8, EVENT_Activate);
    CitrixWindowResize(hWnd8, 200, 100);
    wait 3.0;
    CitrixMouseClick(190, 13, hWnd8, MOUSE_ButtonLeft);
    CitrixWaitForWindow(hWnd8, EVENT_Destroy);
    CitrixDisconnect();
  end TMain;
Parent topic: Window Functions
Related reference
CitrixGetWindow Function
CitrixGetWindowCaption Function
CitrixGetWindowId Function
CitrixGetWindowParentId Function
CitrixGetWindowPos Function
CitrixGetWindowSize Function
CitrixGetWindowStyle Function
CitrixWindowBringToTop Function
CitrixWindowMove function
CitrixSearchWindow Function
CitrixSearchWindowById Function


CitrixSearchWindow Function

Action

The opposite of the CitrixWaitForWindowCreation function, this function does not wait until a specified window appears; this function searches all tracked windows for a suitable window. A window may be specified by its caption, whereas five different search options may be provided with the nMatch parameter. If the function succeeds it returns a window handle that can be used as the nWindow parameter in Citrix functions.

Include file

CitrixAPI.bdh

Syntax

CitrixSearchWindow( in sCaption : string,
                    in nMatch   : number optional ): number;

Return value

  • >0 if the function succeeds

  • 0 otherwise

Parameter | Description
sCaption | Caption of the window to search for.
nMatch

Specify one of the following values (optional):

  • MATCH_Exact (default): Case-sensitive comparison.
  • MATCH_ExactNoCase: Case-insensitive comparison.
  • MATCH_Wildcard: The search string must either begin or end with a '*' character, which matches everything. The rest of the string is compared case sensitively.
  • MATCH_WildcardNoCase: The search string must either begin or end with a '*' character, which matches everything. The rest of the string is compared case insensitively.
  • MATCH_RegExp: The search string is a regular expression. See the regular expression chapter for a description of Silk Performer's regular expression capability.

Example:

  transaction TMain
  var
    nWindowSearchHandle : number;
    sWindowName         : string;
  begin
    CitrixInit(640, 480);
    CitrixConnect("myserver", "myusername", "mypass", "mydomain", COLOR_16bit);
    CitrixWaitForLogon();
    hWnd6 := CitrixWaitForWindowCreation("ICA Seamless Host Agent", MATCH_Exact, 0x94C800C4, 0, 0, 390, 223);
    CitrixWaitForWindow(hWnd6, EVENT_Activate);
    CitrixWaitForWindowCreation("Program Manager");
    CitrixMouseClick(182, 195, hWnd6, MOUSE_ButtonLeft);
    CitrixWaitForWindow(hWnd6, EVENT_Destroy);
    ThinkTime(2.78);
    CitrixMouseDblClick(38, 22, DESKTOP, MOUSE_ButtonLeft);
    hWnd8 := CitrixWaitForWindowCreation("My Documents", MATCH_Exact, 0x16CF0000, 285, 31, 268, 205);
    CitrixWaitForWindow(hWnd8, EVENT_Activate);
    nWindowSearchHandle := CitrixSearchWindow("My D*", MATCH_Wildcard);
    CitrixGetWindowCaption(nWindowSearchHandle, sWindowName);
    print("window " + string(nWindowSearchHandle)
                      + "; name: " + sWindowName);
    CitrixMouseClick(258, 13, hWnd8, MOUSE_ButtonLeft);
    CitrixWaitForWindow(hWnd8, EVENT_Destroy);
    CitrixDisconnect();
  end TMain;
Parent topic: Window Functions
Related reference
CitrixGetWindow Function
CitrixGetWindowCaption Function
CitrixGetWindowId Function
CitrixGetWindowParentId Function
CitrixGetWindowPos Function
CitrixGetWindowSize Function
CitrixGetWindowStyle Function
CitrixWindowBringToTop Function
CitrixWindowMove function
CitrixWindowResize Function
CitrixSearchWindowById Function


CitrixSearchWindowById Function

Action

This function uses window-id (MS Windows) to search for a window. If the function succeeds it returns a window handle that can be used as the nWindow parameter in Citrix functions.

Include file

CitrixAPI.bdh

Syntax

CitrixSearchWindowById( in nId : number ): number;

Return value

  • >0 if the function succeeds

  • 0 otherwise

Parameter | Description
nId | Retrieves the window-id of the specified window.

Example:

  transaction TMain
  var
    nWindowHandle       : number;
    nWindowSearchHandle : number;
    nWindowID           : number;
    i                   : number;
  begin
    CitrixInit(640, 480);
    CitrixConnect("myserver", "myusername", "mypass", "mydomain", COLOR_16bit);
    CitrixWaitForLogon();
    hWnd6 := CitrixWaitForWindowCreation("ICA Seamless Host Agent", MATCH_Exact, 0x94C800C4, 0, 0, 390, 223);
    CitrixWaitForWindow(hWnd6, EVENT_Activate);
    CitrixWaitForWindowCreation("Program Manager");
    CitrixMouseClick(182, 195, hWnd6, MOUSE_ButtonLeft);
    CitrixWaitForWindow(hWnd6, EVENT_Destroy);
    ThinkTime(2.78);
    CitrixMouseDblClick(38, 22, DESKTOP, MOUSE_ButtonLeft);
    hWnd8 := CitrixWaitForWindowCreation("My Documents", MATCH_Exact, 0x16CF0000, 285, 31, 268, 205);
    CitrixWaitForWindow(hWnd8, EVENT_Activate);
    i := 0;
    nWindowHandle := CitrixGetWindow(i);
    while (nWindowHandle > 0) do
      CitrixGetWindowId(nWindowHandle, nWindowID);
      nWindowSearchHandle := CitrixSearchWIndowById(nWindowID);
      print("window " + string(nWindowHandle)
                      + "; ID: " + string(nWindowID)
                      + "; found handle ID:" + string(nWindowSearchHandle));
      i := i + 1;
      nWindowHandle := CitrixGetWindow(i);
    end;
    CitrixMouseClick(258, 13, hWnd8, MOUSE_ButtonLeft);
    CitrixWaitForWindow(hWnd8, EVENT_Destroy);
    CitrixDisconnect();
  end TMain;
Parent topic: Window Functions
Related reference
CitrixGetWindow Function
CitrixGetWindowCaption Function
CitrixGetWindowId Function
CitrixGetWindowParentId Function
CitrixGetWindowPos Function
CitrixGetWindowSize Function
CitrixGetWindowStyle Function
CitrixWindowBringToTop Function
CitrixWindowMove function
CitrixWindowResize Function
CitrixSearchWindow Function


Synchronization Functions

  • CitrixWaitForDisconnect Function
    Waits for the Citrix client to be disconnected from the Citrix server.
  • CitrixWaitForLogon Function
    Waits until a Citrix client logs on successfully or a specified timeout period expires.
  • CitrixWaitForScreen Function
    Uses screen appearance to synchronize subsequent user actions.
  • CitrixWaitForText Function
    Uses optical character recognition (OCR) to synchronize subsequent user actions.
  • CitrixWaitForTextFuzzy Function
    Uses optical character recognition (OCR) to synchronize subsequent user actions. CitrixWaitForTextFuzzy performs OCR more exactly than CitrixWaitForText but requires more resources.
  • CitrixWaitForWindow Function
    Waits until a specified window event (specified with the nEvent parameter) occurs.
  • CitrixWaitForWindowCreation Function
    Waits until a specified window appears or a specified timeout period expires.
  • CitrixWaitForWindowPos Function
    Waits until a window has a specified position.
  • CitrixWaitForWindowRestore Function
    Waits until a window is restored (having previously been maximized).
  • CitrixWaitForWindowSize Function
    Waits until a window has a specified size.
Parent topic: Citrix Functions Overview


CitrixWaitForDisconnect Function

Action

Waits for the ICA client to be disconnected from the Citrix server. This function must be used when a simulated user ends a session with a mouse click or key stroke (e.g. by closing a published application or selecting Log Off from the Start menu). When a session is to be actively closed (e.g. by closing the Citrix client), CitrixDisconnect must be called.

CitrixWaitForDisconnect waits until the disconnection takes place or the specified timeout period expires. In the case of a timeout, error reporting can be prohibited with the bNoError parameter.

Include file

CitrixAPI.bdh

Syntax

CitrixWaitForDisconnect( in nTimeout : number optional,
                         in bNoError : boolean optional ) : boolean;

Return value

  • true if successful

  • false otherwise

Parameter | Description
nTimeout | Specifies the time in milliseconds to wait for the disconnection (optional). When this parameter is omitted or set to 0, the default timeout is used. The default value can be adjusted by profile settings ( Settings > Active Profile > Citrix > General > Synchronization timeout ) or an appropriate call to the CitrixSetOption function.
bNoError | Set this parameter to true to prevent a timeout from raising an error. This is especially useful for controlling variable user reactions.

Example:

  transaction TMain
  var
  begin
    CitrixInit(640, 480);
    CitrixConnect("myserver", "myusername", "mypass", "mydomain", COLOR_16bit);
    CitrixWaitForLogon();
    hWnd4 := CitrixWaitForWindowCreation("", MATCH_Exact, 0x96840000, -2, 452, 644, 30);
    hWnd5 := CitrixWaitForWindowCreation("ICA Seamless Host Agent", MATCH_Exact, 0x94C800C4, 0, 0, 390, 223);
    CitrixWaitForWindow(hWnd5, EVENT_Activate);
    CitrixWaitForWindowCreation("Program Manager");
    ThinkTime(3.33);
    CitrixMouseClick(208, 193, hWnd5, MOUSE_ButtonLeft);
    CitrixWaitForWindow(hWnd5, EVENT_Destroy);
    ThinkTime(2.45);
    CitrixMouseClick(41, 7, hWnd4, MOUSE_ButtonLeft);
    hWnd7 := CitrixWaitForWindowCreation("", MATCH_Exact, 0x96400000, 2, 193, 163, 263);
    CitrixMouseClick(48, 250, hWnd7, MOUSE_ButtonLeft);
    CitrixWaitForWindow(hWnd7, EVENT_Destroy);
    hWnd9 := CitrixWaitForWindowCreation("Shut Down Windows", MATCH_Exact, 0x94C808CC, 111, 96, 417, 192);
    CitrixWaitForWindow(hWnd9, EVENT_Activate);
    CitrixMouseClick(184, 165, hWnd9, MOUSE_ButtonLeft);
    CitrixWaitForDisconnect();
  end TMain;
Parent topic: Synchronization Functions
Related reference
CitrixWaitForLogon Function
CitrixWaitForScreen Function
CitrixWaitForText Function
CitrixWaitForTextFuzzy Function
CitrixWaitForWindow Function
CitrixWaitForWindowCreation Function
CitrixWaitForWindowPos Function
CitrixWaitForWindowRestore Function
CitrixWaitForWindowSize Function


CitrixWaitForLogon Function

Action

This function waits until a Citrix client logs on successfully or a specified timeout period expires.

Include file

CitrixAPI.bdh

Syntax

CitrixWaitForLogon( in nTimeout  : number optional ) : boolean;

Return value

  • true if successful

  • false otherwise

Parameter | Description
nTimeout | Specifies the time in milliseconds to wait for the Citrix client to log on (optional). When this parameter is omitted or set to 0, the default timeout is used. The default value can be adjusted by profile settings ( Settings > Active Profile > Citrix > General > Synchronization timeout ) or an appropriate call to the CitrixSetOption function.

Example:

dcltrans
  transaction TMain
  var
  begin
    CitrixInit(640, 480);
    CitrixConnect("server1", "username", "password", "companydomain", COLOR_16bit);
    CitrixWaitForLogon();
    hWnd4 := CitrixWaitForWindowCreation("", MATCH_Exact, 0x96840000, -2, 452, 644, 30);
    hWnd5 := CitrixWaitForWindowCreation("ICA Seamless Host Agent", MATCH_Exact, 0x94C800C4, 0, 0, 390, 223);
    CitrixWaitForWindow(hWnd5, EVENT_Activate);
    CitrixWaitForWindowCreation("Program Manager");
    ThinkTime(31.50);
    CitrixMouseClick(217, 192, hWnd5, MOUSE_ButtonLeft);
    CitrixWaitForWindow(hWnd5, EVENT_Destroy);
    CitrixDisconnect();
  end TMain;
Parent topic: Synchronization Functions
Related reference
CitrixWaitForDisconnect Function
CitrixWaitForScreen Function
CitrixWaitForText Function
CitrixWaitForTextFuzzy Function
CitrixWaitForWindow Function
CitrixWaitForWindowCreation Function
CitrixWaitForWindowPos Function
CitrixWaitForWindowRestore Function
CitrixWaitForWindowSize Function


CitrixWaitForScreen Function

Action

This function uses screen appearance to synchronize subsequent user actions. Based on provided parameters, this function waits until the image in the specified screen region changes, matches the captured hash value(s), or does not match the hash value(s). To compare the actual screen region with the provided hash value(s), it is necessary that the color depth used during recording be identical to that used during replay.

The screen region can be specified absolutely or relatively to a window (by specifying a window handle). When only a window handle, and no position or size, is provided, the region specified by the window outline is used.

Note: Screen synchronization is only possible in Normal Mode (see CitrixInit). When used in Fast Mode this function waits a specified period of time (configurable through a call to CitrixSetOption). In the case of a timeout, error reporting can be prohibited with the bNoError parameter.

Include file

CitrixAPI.bdh

Syntax

CitrixWaitForScreen( in nWindow  : number,
                     in nX       : number,
                     in nY       : number,
                     in nWidth   : number,
                     in nHeight  : number,
                     in sHash    : string optional,
                     in bUnequal : boolean optional,
                     in nTimeout : number optional,
                     in bNoError : boolean optional,
                     in nPolling : number optional ) : boolean;

Return value

  • true if successful

  • false otherwise

Parameter | Description
nWindow | Window handle returned by a call to CitrixWaitForWindowCreation. Use DESKTOP to specify a region relative to the desktop.
nX | X coordinate of the left margin of the screen region.
nY | Y coordinate of the top margin of the screen region.
nWidth | Width of the region.
nHeight | Height of the region.
sHash | Captured hash value, to which the specified region should be compared (optional). This can also be a list of hash values separated by one of the following characters: , ; | / Omit this parameter to synchronize on any change in the region.
bUnequal | Set this parameter to true to wait for the specified region to mismatch the provided hash value.
nTimeout | Specify the time in milliseconds to wait for the screen region to reach the correct appearance (optional). When this parameter is omitted or set to 0, the default timeout is used. The default value can be adjusted by profile settings ( Settings > Active Profile > Citrix > General > Synchronization timeout ) or an appropriate call to the CitrixSetOption function.
bNoError | Set this parameter to true to prevent a timeout from raising an error. This is especially useful for controlling variable user reactions.
nPolling | Specify the polling period in milliseconds that the Citrix Replay engine will wait to poll a screen for an update (0 means no polling). If omitted, the parameter is set to 1000. This parameter needs to be set to wait for any change in the specified region, rather than waiting for a specific change as defined by the sHash parameter. This setting overrides the CitrixSetOption(CITRIX_OPT_ScreenTextPolling) polling interval.

Example:

  transaction TMain
  var
  begin
    CitrixInit(640, 480);
    CitrixConnect("citserver", "user", "password", "companydomain", COLOR_16bit);
    CitrixWaitForLogon();
    hWnd6 := CitrixWaitForWindowCreation("ICA Seamless Host Agent", MATCH_Exact, 0x94C800C4, 0, 0, 390, 223);
    CitrixWaitForWindow(hWnd6, EVENT_Activate);
    CitrixWaitForWindowCreation("Program Manager");
    ThinkTime(3.31);
    CitrixMouseClick(214, 197, hWnd6, MOUSE_ButtonLeft);
    CitrixWaitForWindow(hWnd6, EVENT_Destroy);
    CitrixMouseDblClick(112, 16, DESKTOP, MOUSE_ButtonLeft);
    hWnd9 := CitrixWaitForWindowCreation("Microsoft Excel – Book*", MATCH_Wildcard, 0x15CF0000, -4, -4, 648, 460);
    CitrixWaitForScreen(hWnd9, 172, 137, 250, 148, "f100c8b71521fd895c23825b7f73a3a5|56a4337ff1aaf9ea477f0c5a2073dd2d", false);
    CitrixMouseClick(634, 9, hWnd9, MOUSE_ButtonLeft);
    CitrixWaitForWindow(hWnd9, EVENT_Destroy);
    ThinkTime(3.02);
    CitrixDisconnect();
  end TMain;
Parent topic: Synchronization Functions
Related reference
CitrixWaitForDisconnect Function
CitrixWaitForLogon Function
CitrixWaitForText Function
CitrixWaitForTextFuzzy Function
CitrixWaitForWindow Function
CitrixWaitForWindowCreation Function
CitrixWaitForWindowPos Function
CitrixWaitForWindowRestore Function
CitrixWaitForWindowSize Function


CitrixWaitForText Function

Action

This function uses optical character recognition (OCR) to synchronize subsequent user actions. Based on provided parameters, this function waits until the provided text pattern appears on the specified location.

Use TrueLog Explorer to insert this synchronization call.

The screen region can be specified absolutely or relatively to a window (by specifying a window handle). When only a window handle, and no position or size, is provided, the region specified by the window outline is used.

Note: Text synchronization is only possible in Normal Mode (see CitrixInit). When used in Fast Mode this function waits a specified period of time (configurable through a call to CitrixSetOption).

When optional font parameters are present, the pattern file is checked to see if the selected font is available. When font parameters are omitted font checking is not performed.

For successful text conversion it is necessary to use the perfOcrFonts.dat and perfOcrPattern.pat configuration files, which contain used fonts in the correct size and format. These files must be added to the Data Files section of the project (both files are located at <public user documents>\Silk Performer 21.0\Data). If the files are not available, or do not contain the correct specifications, they can be generated or updated using the OCR dialog in the Citrix System Settings.

In the case of a timeout, error reporting can be prohibited with the bNoError parameter.

Include file

CitrixAPI.bdh

Return value

  • true if successful

  • false otherwise

Syntax

CitrixWaitForText(  in  sText        : string,
                    in  nWindow      : number,
                    in  nX           : number,
                    in  nY           : number,
                    in  nWidth       : number,
                    in  nHeight      : number,
                    in  nMatch       : number,
                    in  sFont        : string  optional,
                    in  nFontSize    : number  optional,
                    in  nFontFlags   : number  optional,
                    in  nTimeout     : number  optional,
                    in  bNoError     : boolean optional,
                    out sResult      : string  optional,
                    in  nPolling     : number  optional ): boolean;
Parameter | Description
sText | String or string pattern to wait for.
nWindow | Window handle returned by a call to CitrixWaitForWindowCreation. Use DESKTOP to specify a region relative to the desktop.
nX | X coordinate of the left margin of the screen region.
nY | Y coordinate of the top margin of the screen region.
nWidth | Width of the region.
nHeight | Height of the region.
nMatch

Specify one of the following values (optional):

  • MATCH_Exact (default): Case-sensitive comparison.
  • MATCH_ExactNoCase: Case-insensitive comparison.
  • MATCH_Wildcard: The search string must either begin or end with a '*' character, which matches everything. The rest of the string is compared case sensitively.
  • MATCH_WildcardNoCase: The search string must either begin or end with a '*' character, which matches everything. The rest of the string is compared case insensitively.
  • MATCH_RegExp: The search string is a regular expression. See the regular expression chapter for a description of Silk Performer's regular expression capability.

In the optional flag MATCH_IfDifferent is added to the value the function waits until the OCR result does not match the provided string or string pattern any more.

sFont | Font that should be checked for on the system and in the provided configuration files (optional). This parameter does not affect the conversion; it enables rapid fault detection when using remote agents and moving projects to different hosts. If a specified font is not on the operating system, then it must be installed. If the provided configuration files do not contain the font, use the OCR configuration dialog (System Settings / Citrix) to adjust them. When this parameter is omitted font checking is not performed.
nFontSize | The font size that should be checked for in the provided configuration files (optional). This parameter does not affect the conversion; it enables rapid fault detection when using remote agents and moving projects to different hosts. If the provided configuration files do not contain the font size, use the OCR configuration dialog (System Settings / Citrix) to adjust them. When this parameter is omitted, font-size checking is not performed.
nFontFlags

Specifies the font shape (bold, italic, or underlined) that should be checked for in the provided configuration files (optional). This parameter does not affect the conversion; it enables rapid fault detection when using remote agents and moving projects to different hosts. If the provided configuration files do not contain the specified font shapes, use the OCR configuration dialog (System Settings / Citrix) to adjust them. When this parameter is omitted, font-shape checking is not performed.

Specify any combination of the following values:
  • FONT_FLAG_Italic
  • FONT_FLAG_Bold
  • FONT_FLAG_Underlined
nTimeout | Specify the time in milliseconds to wait for the screen region to reach the correct appearance (optional). When this parameter is omitted or set to 0, the default timeout is used. The default value can be adjusted by profile settings ( Settings > Active Profile > Citrix > General > Synchronization timeout ) or an appropriate call to the CitrixSetOption function.
bNoError | Set this parameter to true to prevent a timeout from raising an error. This is especially useful for controlling variable user reactions.
sResult | Retrieves the result of the OCR conversion.
nPolling | Specify the polling period in milliseconds that the Citrix Replay engine will wait to poll a screen for an update (0 means no polling). If omitted, the parameter is set to 1000. This setting overrides the CitrixSetOption(CITRIX_OPT_ScreenTextPolling) polling interval.

Example:

transaction TMain
var
  sResult  : string;
begin
  CitrixInit(800,600); // do not change the resolution
  CitrixConnect("server","John",Decrypt("8V6F"),"",COLOR_256);
  CitrixWaitForLogon();
  CitrixWaitForText("St*",DESKTOP,20,579,35,16,MATCH_Wildcard,null,0,0,0,false,sResult);
  print(sResult);
  CitrixDisconnect();
end TMain;
Parent topic: Synchronization Functions
Related reference
CitrixWaitForDisconnect Function
CitrixWaitForLogon Function
CitrixWaitForScreen Function
CitrixWaitForTextFuzzy Function
CitrixWaitForWindow Function
CitrixWaitForWindowCreation Function
CitrixWaitForWindowPos Function
CitrixWaitForWindowRestore Function
CitrixWaitForWindowSize Function


CitrixWaitForTextFuzzy Function

Action

This function uses optical character recognition (OCR) to synchronize subsequent user actions. Based on provided parameters, this function waits until the provided text pattern appears on the specified location.

Use TrueLog Explorer to insert this synchronization call.

The screen region can be specified absolutely or relatively to a window (by specifying a window handle). When only a window handle, and no position or size, is provided, the region specified by the window outline is used.

Note: Text synchronization is only possible in Normal Mode (see CitrixInit). When used in Fast Mode this function waits a specified period of time (configurable through a call to CitrixSetOption).

In the case of a timeout, error reporting can be prohibited with the bNoError parameter.

CitrixWaitForTextFuzzy performs OCR more exactly than CitrixWaitForText but requires more resources.

Include file

CitrixAPI.bdh

Return value

  • true if successful

  • false otherwise

Syntax

CitrixWaitForTextFuzzy( in  sText        : string,
                        in  nWindow      : number,
                        in  nX           : number,
                        in  nY           : number,
                        in  nWidth       : number,
                        in  nHeight      : number,
                        in  sLanguage    : string,
                        in  nMatch       : number,
                        in  nTimeout     : number  optional,
                        in  bNoError     : boolean optional,
                        out sResult      : string  optional,
                        in  nPolling     : number  optional ): boolean;
Parameter | Description
sText | String or string pattern to wait for.
nWindow | Window handle returned by a call to CitrixWaitForWindowCreation. Use DESKTOP to specify a region relative to the desktop.
nX | X coordinate of the left margin of the screen region.
nY | Y coordinate of the top margin of the screen region.
nWidth | Width of the region.
nHeight | Height of the region.
sLanguage | The language of the text to be verified. Possible language codes are chi_sim, dan, deu, eng, fin, fra, ita, jpn, nld, nor, pol, spa and swe.
nMatch

Specify one of the following values (optional):

  • MATCH_Exact (default): Case-sensitive comparison.
  • MATCH_ExactNoCase: Case-insensitive comparison.
  • MATCH_Wildcard: The search string must either begin or end with a '*' character, which matches everything. The rest of the string is compared case sensitively.
  • MATCH_WildcardNoCase: The search string must either begin or end with a '*' character, which matches everything. The rest of the string is compared case insensitively.
  • MATCH_RegExp: The search string is a regular expression. See the regular expression chapter for a description of Silk Performer's regular expression capability.

In the optional flag MATCH_IfDifferent is added to the value the function waits until the OCR result does not match the provided string or string pattern any more.

nTimeout | Specify the time in milliseconds to wait for the screen region to reach the correct appearance (optional). When this parameter is omitted or set to 0, the default timeout is used. The default value can be adjusted by profile settings ( Settings > Active Profile > Citrix > General > Synchronization timeout ) or an appropriate call to the CitrixSetOption function.
bNoError | Set this parameter to true to prevent a timeout from raising an error. This is especially useful for controlling variable user reactions.
sResult | Retrieves the result of the OCR conversion.
nPolling | Specify the polling period in milliseconds that the Citrix Replay engine will wait to poll a screen for an update (0 means no polling). If omitted, the parameter is set to 1000. This setting overrides the CitrixSetOption(CITRIX_OPT_ScreenTextPolling) polling interval.

Example:

transaction TMain
var
  sResult  : string;
begin
  CitrixInit(800,600); // do not change the resolution
  CitrixConnect("server","John",Decrypt("8V6F"),"",COLOR_256);
  CitrixWaitForLogon();
  CitrixWaitForTextFuzzy("St*",DESKTOP,20,579,35,16,MATCH_Wildcard, "eng",0,false,sResult);
  print(sResult);
  CitrixDisconnect();
end TMain;
Parent topic: Synchronization Functions
Related reference
CitrixWaitForDisconnect Function
CitrixWaitForLogon Function
CitrixWaitForScreen Function
CitrixWaitForText Function
CitrixWaitForWindow Function
CitrixWaitForWindowCreation Function
CitrixWaitForWindowPos Function
CitrixWaitForWindowRestore Function
CitrixWaitForWindowSize Function


CitrixWaitForWindow Function

Action

This function waits until a specified window event (specified with the nEvent parameter) occurs. Such events may be an activation, destruction or caption change of a specified window. If a selected event is a caption change, any caption change of the specified window will satisfy the function. Additionally a caption can be specified explicitly using the sCaption and nMatch parameters. See CitrixWaitForWindowCreation for a detailed description of these two parameters.

In the case of a timeout, error reporting can be prohibited with the bNoError parameter.

Include file

CitrixAPI.bdh

Syntax

CitrixWaitForWindow( in nWindow  : number,
                     in nEvent   : number optional,
                     in sCaption : number optional,
                     in nMatch   : number optional,
                     in nTimeout : number optional,
                     in bNoError : boolean optional ) : boolean;

Return value

  • true if successful

  • false otherwise

Parameter | Description
nWindow | Window handle returned by a call to CitrixWaitForWindowCreation. Use DESKTOP to specify a region relative to the desktop.
nEvent

Specify one of the following values (optional):

  • EVENT_Activate (default): Waits for the activation of the specified window.

  • EVENT_Destroy: Waits for the destruction (close) of the specified window.

  • EVENT_CaptionChange: Waits for the caption change of the specified window. When this option is specified, the next two parameters can be used to explicitly specify a caption.

sCaption | Window caption to wait for. When the nEvent parameter is not EVENT_CaptionChange, this parameter is ignored. When this parameter is omitted (or “” is used), this function waits for the next caption change of the window.
nMatch

When the nEvent parameter is not EVENT_CaptionChange, this parameter is ignored (optional).Specify one of the following values:

  • MATCH_Exact (default): Case-sensitive comparison.
  • MATCH_ExactNoCase: Case-insensitive comparison.
  • MATCH_Wildcard: The search string must either begin or end with a '*' character, which matches everything. The rest of the string is compared case sensitively.
  • MATCH_WildcardNoCase: The search string must either begin or end with a '*' character, which matches everything. The rest of the string is compared case insensitively.
  • MATCH_RegExp: The search string is a regular expression. See the regular expression chapter for a description of Silk Performer's regular expression capability.
nTimeout | Specifies the time in milliseconds to wait for the specified event (optional). When this parameter is omitted or set to 0, the default timeout is used. The default value can be adjusted by profile settings ( Settings > Active Profile > Citrix > General > Synchronization timeout ) or an appropriate call to the CitrixSetOption function.
bNoError | Set this parameter to true to prevent a timeout from raising an error. This is especially useful for controlling variable user reactions.

Example:

  transaction TMain
  var
  begin
    CitrixInit(640, 480);
    CitrixConnect("myserver", "myusername", "mypass", "mydomain", COLOR_16bit);
    CitrixWaitForLogon();
    hWnd4 := CitrixWaitForWindowCreation("", MATCH_Exact, 0x96840000, -2, 452, 644, 30);
    hWnd5 := CitrixWaitForWindowCreation("ICA Seamless Host Agent", MATCH_Exact, 0x94C800C4, 0, 0, 390, 223);
    CitrixWaitForWindow(hWnd5, EVENT_Activate);
    CitrixWaitForWindowCreation("Program Manager");
    ThinkTime(3.33);
    CitrixMouseClick(208, 193, hWnd5, MOUSE_ButtonLeft);
    CitrixWaitForWindow(hWnd5, EVENT_Destroy);
    ThinkTime(2.45);
    CitrixMouseClick(41, 7, hWnd4, MOUSE_ButtonLeft);
    hWnd7 := CitrixWaitForWindowCreation("", MATCH_Exact, 0x96400000, 2, 193, 163, 263);
    CitrixMouseClick(48, 250, hWnd7, MOUSE_ButtonLeft);
    CitrixWaitForWindow(hWnd7, EVENT_Destroy);
    hWnd9 := CitrixWaitForWindowCreation("Shut Down Windows", MATCH_Exact, 0x94C808CC, 111, 96, 417, 192);
    CitrixWaitForWindow(hWnd9, EVENT_Activate);
    CitrixMouseClick(184, 165, hWnd9, MOUSE_ButtonLeft);
    CitrixWaitForDisconnect();
  end TMain;
Parent topic: Synchronization Functions
Related reference
CitrixWaitForDisconnect Function
CitrixWaitForLogon Function
CitrixWaitForScreen Function
CitrixWaitForText Function
CitrixWaitForTextFuzzy Function
CitrixWaitForWindowCreation Function
CitrixWaitForWindowPos Function
CitrixWaitForWindowRestore Function
CitrixWaitForWindowSize Function


CitrixWaitForWindowCreation Function

Action

This function waits until a specified window appears or a specified timeout period expires. A window can be specified by its caption, whereas five different search options can be provided by the nMatch parameter. When the window to wait for does not have a caption, the style of the window is used to identify the correct window (nStyle).

When this function succeeds, it returns a (positive) window handle that must be used as the nWindow parameter throughout the Citrix functions.

When the newly created window has a different size than is specified by the nWidth and nHeight parameters (size of the window during recording), the window is resized to the specified size (otherwise recorded user actions wouldn’t work). When the position of the newly created window is different than that specified by the nX and nY parameters (position of the window during recording) and the bForcePos parameter is set to true, the window is moved to the correct position. When the bForcePos parameter is omitted or set to false, profile settings (Citrix / General/ Force window position) specify whether or not the window is moved.

This function is not only triggered by the creation of a window, but also by a (matching) caption change of an existing window.

In the case of a timeout error, reporting can be prohibited with the bNoError parameter.

Include file

CitrixAPI.bdh

Syntax

CitrixWaitForWindowCreation( in sCaption  : string,
                             in nMatch    : number optional,
                             in nStyle    : number optional,
                             in nX        : number optional,
                             in nY        : number optional,
                             in nWidth    : number optional,
                             in nHeight   : number optional,
                             in bForcePos : boolean optional,
                             in nTimeout  : number optional,
                             in bNoError  : boolean optional ) : number;

Return value

  • >= 0 if the function succeeds (0 for the desktop)

  • < 0 otherwise

Parameter | Description
sCaption | Caption of the window to wait for. It does not matter if the caption appears due to the creation of a new window or because of a caption change of an existing window.
nMatch

Specify one of the following values (optional):

  • MATCH_Exact (default): Case-sensitive comparison.
  • MATCH_ExactNoCase: Case-insensitive comparison.
  • MATCH_Wildcard: The search string must either begin or end with a '*' character, which matches everything. The rest of the string is compared case sensitively.
  • MATCH_WildcardNoCase: The search string must either begin or end with a '*' character, which matches everything. The rest of the string is compared case insensitively.
  • MATCH_RegExp: The search string is a regular expression. See the regular expression chapter for a description of Silk Performer's regular expression capability.
nStyle | When a window doesn’t have a caption, the style parameter is used to identify the correct window (optional).
nX | X coordinate of the left margin of the window at recording (optional). When this parameter is provided and either the bForcePos parameter or the global setting (profile setting / Citrix / General/ Force window position) is set to true, the window is moved to this position.
nY | Y coordinate of the top margin of the window at recording (optional). When this parameter is provided and either the bForcePos parameter or the global setting (profile setting / Citrix / General/ Force window position) is set to true, the window is moved to this position
nWidth | The width of the window at recording (optional). When this parameter is provided, the window is resized to this width.
nHeight | The height of the window at recording (optional). When this parameter is provided, the window is resized to this height.
bForcePos | See description of nX / nY.
nTimeout | Specifies the time in milliseconds to wait for the appearance of the window (optional). When this parameter is omitted or set to 0, the default timeout is used. The default value can be adjusted by profile settings ( Settings > Active Profile > Citrix > General > Synchronization timeout ) or an appropriate call to the CitrixSetOption function.
bNoError | Set this parameter to true to prevent a timeout from raising an error. This is especially useful for controlling variable user reactions.

Example:

  transaction TMain
  var
  begin
    CitrixInit(640, 480);
    CitrixConnect("myserver", "myusername", "mypass", "mydomain", COLOR_16bit);
    CitrixWaitForLogon();
    hWnd4 := CitrixWaitForWindowCreation("", MATCH_Exact, 0x96840000, -2, 452, 644, 30);
    hWnd5 := CitrixWaitForWindowCreation("ICA Seamless Host Agent", MATCH_Exact, 0x94C800C4, 0, 0, 390, 223);
    CitrixWaitForWindow(hWnd5, EVENT_Activate);
    CitrixWaitForWindowCreation("Program Manager");
    ThinkTime(3.33);
    CitrixMouseClick(208, 193, hWnd5, MOUSE_ButtonLeft);
    CitrixWaitForWindow(hWnd5, EVENT_Destroy);
    ThinkTime(2.45);
    CitrixMouseClick(41, 7, hWnd4, MOUSE_ButtonLeft);
    hWnd7 := CitrixWaitForWindowCreation("", MATCH_Exact, 0x96400000, 2, 193, 163, 263);
    CitrixMouseClick(48, 250, hWnd7, MOUSE_ButtonLeft);
    CitrixWaitForWindow(hWnd7, EVENT_Destroy);
    hWnd9 := CitrixWaitForWindowCreation("Shut Down Windows", MATCH_Exact, 0x94C808CC, 111, 96, 417, 192);
    CitrixWaitForWindow(hWnd9, EVENT_Activate);
    CitrixMouseClick(184, 165, hWnd9, MOUSE_ButtonLeft);
    CitrixWaitForDisconnect();
  end TMain;
Parent topic: Synchronization Functions
Related reference
CitrixWaitForDisconnect Function
CitrixWaitForLogon Function
CitrixWaitForScreen Function
CitrixWaitForText Function
CitrixWaitForTextFuzzy Function
CitrixWaitForWindow Function
CitrixWaitForWindowPos Function
CitrixWaitForWindowRestore Function
CitrixWaitForWindowSize Function


CitrixWaitForWindowPos Function

Action

This function waits until a window has a specified position. This function is used to synchronize subsequent user input after a window has been moved through a user action (e.g. a mouse drag).

In the case of a timeout, error reporting can be prohibited with the bNoError parameter.

Include file

CitrixAPI.bdh

Syntax

CitrixWaitForWindowPos( in nWindow  : number,
                        in nX       : number,
                        in nY       : number,
                        in nTimeout : number optional,
                        in bNoError : boolean optional ) : boolean

Return value

  • true if successful

  • false otherwise

Parameter | Description
nWindow | Window handle returned by a call to CitrixWaitForWindowCreation. Use DESKTOP to specify a region relative to the desktop.
nX | X coordinate to which the left margin of the window must be moved to satisfy the function.
nY | Y coordinate to which the left top margin of the window must be moved to satisfy the function.
nTimeout | Specifies the time in milliseconds to wait for the window to move to the correct position (optional). When this parameter is omitted or set to 0, the default timeout is used. The default value can be adjusted by profile settings ( Settings > Active Profile > Citrix > General > Synchronization timeout ) or an appropriate call to the CitrixSetOption function.
bNoError | Set this parameter to true to prevent a timeout from raising an error. This is especially useful for controlling variable user reactions.

Example:

  transaction TMain
  var
  begin
    CitrixInit(640, 480);
    CitrixConnect("myserver", "myusername", "mypass", "mydomain", COLOR_16bit);
    CitrixWaitForLogon();
    hWnd6 := CitrixWaitForWindowCreation("ICA Seamless Host Agent", MATCH_Exact, 0x94C800C4, 0, 0, 390, 223);
    CitrixWaitForWindow(hWnd6, EVENT_Activate);
    CitrixWaitForWindowCreation("Program Manager");
    CitrixMouseButtonDown(163, 12, hWnd6, MOUSE_ButtonLeft);
    CitrixMouseButtonUp(289, 54, false, DESKTOP, MOUSE_ButtonLeft);
    CitrixWaitForWindow(hWnd6,EVENT_Activate);
    CitrixWaitForWindowPos(hWnd6, 126, 42);
    CitrixMouseClick(187, 203, hWnd6, MOUSE_ButtonLeft);
    CitrixWaitForWindow(hWnd6, EVENT_Destroy);
    ThinkTime(2.63);
    CitrixDisconnect();
  end TMain;
Parent topic: Synchronization Functions
Related reference
CitrixWaitForDisconnect Function
CitrixWaitForLogon Function
CitrixWaitForScreen Function
CitrixWaitForText Function
CitrixWaitForTextFuzzy Function
CitrixWaitForWindow Function
CitrixWaitForWindowCreation Function
CitrixWaitForWindowRestore Function
CitrixWaitForWindowSize Function


CitrixWaitForWindowRestore Function

Action

This function waits until a window is restored (having previously been maximized). This function is used to synchronize subsequent user input after a window is restored through a user action (e.g. a mouse click).

When a restored window has a different size than is specified by the nWidth and nHeight parameters (size of the window during recording) the window is resized to the specified size (otherwise recorded user actions wouldn’t work). When the position of the newly created window is different than that specified by the nX and nY parameters (position of the window during recording) and the bForcePos parameter is set to true, the window is moved to the correct position. When the bForcePos parameter is omitted or set to false, profile settings (Citrix / General/ Force window position) dictate whether or not the window is moved.

In the case of a timeout, error reporting can be prohibited with the bNoError parameter.

Include file

CitrixAPI.bdh

Syntax

CitrixWaitForWindowRestore( in nWindow   : number,
                            in nX        : number optional,
                            in nY        : number optional,
                            in nWidth    : number optional,
                            in nHeight   : number optional,
                            in bForcePos : boolean optional,
                            in nTimeout  : number optional,
                            in bNoError  : boolean optional ) : boolean;

Return value

  • true if successful

  • false otherwise

Parameter | Description
nWindow | Window handle returned by a call to CitrixWaitForWindowCreation. Use DESKTOP to specify a region relative to the desktop.
nX | X coordinate of the left margin of the window at recording (optional). When this parameter is provided and either the bForcePos parameter or the global setting (profile setting / Citrix / General/ Force window position) is set to true, the window is moved to this position.
nY | Y coordinate of the top margin of the window at recording (optional). When this parameter is provided and either the bForcePos parameter or the global setting (profile setting / Citrix / General/ Force window position) is set to true, the window is moved to this position.
nWidth | The width of the window at recording (optional). When this parameter is provided the window is resized to this width.
nHeight | The height of the window at recording (optional). When this parameter is provided, the window is resized to this height.
bForcePos | See description of nX / nY (optional).
nTimeout | Specifies the time in milliseconds to wait for the window to move to the correct position (optional). When this parameter is omitted or set to 0, the default timeout is used. The default value can be adjusted by profile settings ( Settings > Active Profile > Citrix > General > Synchronization timeout ) or an appropriate call to the CitrixSetOption function.
bNoError | Set this parameter to true to prevent a timeout from raising an error. This is especially useful for controlling variable user reactions.

Example:

  transaction TMain
  var
  begin
    CitrixInit(640, 480);
    CitrixConnect("myserver", "myusername", "mypass", "mydomain", COLOR_16bit);
    CitrixWaitForLogon();
    hWnd6 := CitrixWaitForWindowCreation("ICA Seamless Host Agent", MATCH_Exact, 0x94C800C4, 0, 0, 390, 223);
    CitrixWaitForWindow(hWnd6, EVENT_Activate);
    CitrixWaitForWindowCreation("Program Manager");
    CitrixMouseClick(182, 195, hWnd6, MOUSE_ButtonLeft);
    CitrixWaitForWindow(hWnd6, EVENT_Destroy);
    ThinkTime(2.78);
    CitrixMouseDblClick(38, 22, DESKTOP, MOUSE_ButtonLeft);
    hWnd8 := CitrixWaitForWindowCreation("My Documents", MATCH_Exact, 0x16CF0000, 285, 31, 268, 205);
    CitrixWaitForWindow(hWnd8, EVENT_Activate);
    CitrixMouseClick(234, 11, hWnd8, MOUSE_ButtonLeft);
    CitrixWaitForWindowPos(hWnd8, -4, -4);
    CitrixWaitForWindowSize(hWnd8, 648, 460);
    CitrixMouseClick(614, 12, hWnd8, MOUSE_ButtonLeft);
    CitrixWaitForWindowRestore(hWnd8, -4, -4, 648, 460);
    CitrixWaitForWindowPos(hWnd8, 285, 31);
    CitrixWaitForWindowSize(hWnd8, 268, 205);
    CitrixMouseClick(258, 13, hWnd8, MOUSE_ButtonLeft);
    CitrixWaitForWindow(hWnd8, EVENT_Destroy);
    CitrixDisconnect();
  end TMain;
Parent topic: Synchronization Functions
Related reference
CitrixWaitForDisconnect Function
CitrixWaitForLogon Function
CitrixWaitForScreen Function
CitrixWaitForText Function
CitrixWaitForTextFuzzy Function
CitrixWaitForWindow Function
CitrixWaitForWindowCreation Function
CitrixWaitForWindowPos Function
CitrixWaitForWindowSize Function


CitrixWaitForWindowSize Function

Action

This function waits until a window has a specified size. This function is used to synchronize subsequent user input after a window has been resized through a user action (e.g. a mouse drag). In the case of a timeout, error reporting can be prohibited with the bNoError parameter.

Include file

CitrixAPI.bdh

Syntax

CitrixWaitForWindowSize( in nWindow  : number,
                         in nWidth   : number,
                         in nHeight  : number,
                         in nTimeout : number optional,
                         in bNoError : boolean optional ) : boolean;

Return value

  • true if successful

  • false otherwise

Parameter | Description
nWindow | Window handle returned by a call to CitrixWaitForWindowCreation. Use DESKTOP to specify a region relative to the desktop.
nWidth | The window must have this width to satisfy the function.
nHeight | The window must have this height to satisfy the function.
nTimeout | Specifies the time in milliseconds to wait for the window to reach the correct size (optional). When this parameter is omitted or set to 0, the default timeout is used. The default value can be adjusted by profile settings ( Settings > Active Profile > Citrix > General > Synchronization timeout ) or an appropriate call to the CitrixSetOption function.
bNoError | Set this parameter to true to prevent a timeout from raising an error. This is especially useful for controlling variable user reactions.

Example:

  transaction TMain
  var
  begin
    CitrixInit(640, 480);
    CitrixConnect("myserver", "myusername", "mypass", "mydomain", COLOR_16bit);
    CitrixWaitForLogon();
    hWnd6 := CitrixWaitForWindowCreation("ICA Seamless Host Agent", MATCH_Exact, 0x94C800C4, 0, 0, 390, 223);
    CitrixWaitForWindow(hWnd6, EVENT_Activate);
    CitrixWaitForWindowCreation("Program Manager");
    CitrixMouseClick(182, 195, hWnd6, MOUSE_ButtonLeft);
    CitrixWaitForWindow(hWnd6, EVENT_Destroy);
    ThinkTime(2.78);
    CitrixMouseDblClick(38, 22, DESKTOP, MOUSE_ButtonLeft);
    hWnd8 := CitrixWaitForWindowCreation("My Documents", MATCH_Exact, 0x16CF0000, 285, 31, 268, 205);
    CitrixWaitForWindow(hWnd8, EVENT_Activate);
    CitrixMouseClick(234, 11, hWnd8, MOUSE_ButtonLeft);
    CitrixWaitForWindowPos(hWnd8, -4, -4);
    CitrixWaitForWindowSize(hWnd8, 648, 460);
    CitrixMouseClick(614, 12, hWnd8, MOUSE_ButtonLeft);
    CitrixWaitForWindowRestore(hWnd8, -4, -4, 648, 460);
    CitrixWaitForWindowPos(hWnd8, 285, 31);
    CitrixWaitForWindowSize(hWnd8, 268, 205);
    CitrixMouseClick(258, 13, hWnd8, MOUSE_ButtonLeft);
    CitrixWaitForWindow(hWnd8, EVENT_Destroy);
    CitrixDisconnect();
  end TMain;
Parent topic: Synchronization Functions
Related reference
CitrixWaitForDisconnect Function
CitrixWaitForLogon Function
CitrixWaitForScreen Function
CitrixWaitForText Function
CitrixWaitForTextFuzzy Function
CitrixWaitForWindow Function
CitrixWaitForWindowCreation Function
CitrixWaitForWindowPos Function
CitrixWaitForWindowRestore Function


General Functions

  • CitrixSetClientName Function
    When a Citrix client connects to a Citrix server it uses a name to identify itself.
  • CitrixSetOption Function
    Sets a particular option.
  • CitrixPing Function
    Sends a ping synchronization request to the currently connected Citrix server, with sPingData as payload.
  • CitrixSetProperty Function
    Sets a property of a Citrix client.
  • CitrixSetRamDisk Function
    Specifies a directory that is to be used for the temporary storage of images.
  • CitrixSetSocksProxy Function
    Specifies a socks proxy to be used for Citrix replay.
  • CitrixGetSessionString Function
    Returns the session string of the current ICA session from the server.
  • CitrixAddInterrupt Function
    Adds an interrupt specification.
  • CitrixGetActInterrupt Function
    To be used only within an event handler.
  • CitrixRemoveInterrupt Function
    Removes the interrupt specification that is added by a call to CitrixAddInterrupt.
  • CitrixGetMeasures Function
    Retrieves measures collected by a Citrix client for an actual session.
  • CitrixGetScreen Function
    Takes a screenshot of the selected region and writes the screenshot to a file in the result directory.
  • CitrixGetScreenHash Function
    Retrieves the hash value of the selected screen.
  • CitrixParseText Function
    Performs optical character recognition (OCR) on a selected screen region and stores the result in a sResult parameter.
  • CitrixParseTextFuzzy Function
    Performs optical character recognition (OCR) on a selected screen region and stores the result in a sResult parameter. CitrixParseTextFuzzy performs OCR more exactly than CitrixParseText but requires more resources.
  • CitrixVerifyText Function
    Performs optical character recognition (OCR) on a selected screen region and compares the result with a provided string.
  • CitrixVerifyTextFuzzy Function
    Performs optical character recognition (OCR) on a selected screen region and compares the result with a provided string. CitrixVerifyTextFuzzy performs OCR more exactly than CitrixVerifyText but requires more resources.
Parent topic: Citrix Functions Overview


CitrixSetClientName Function

Action

When a Citrix client connects to a MetaFrame server it uses a name to identify itself. This name is automatically generated during replay. The name looks like “SP_User_x,” where x numerates the virtual users. Call this function when a custom name is to be used.

Include file

CitrixAPI.bdh

Syntax

CitrixSetClientName( in sClientName : string ) : boolean;

Return value

  • true if successful

  • false otherwise

Parameter | Description
sClientName | Custom client name.

Example:

  transaction TMain
  var
  begin
    CitrixInit(640, 480);
    CitrixSetClientName("MyClient");
    CitrixSetApplication("Excel");
    CitrixConnect("myserver", "myusername", "mypass", "mydomain", COLOR_16bit);
    CitrixWaitForLogon();
    hWnd4 := CitrixWaitForWindowCreation("Microsoft Excel – Book*", MATCH_Wildcard, 0x15CF0000, -4, -4, 648, 488);
    CitrixMouseClick(636, 14, hWnd4, MOUSE_ButtonLeft);
    CitrixWaitForWindow(hWnd4, EVENT_Destroy);
    ThinkTime(2.63);
    CitrixDisconnect();
  end TMain;
Parent topic: General Functions
Related reference
CitrixSetOption Function
CitrixPing Function
CitrixSetProperty Function
CitrixSetRamDisk Function
CitrixSetSocksProxy Function
CitrixGetSessionString Function
CitrixAddInterrupt Function
CitrixGetActInterrupt Function
CitrixRemoveInterrupt Function
CitrixGetMeasures Function
CitrixGetScreen Function
CitrixGetScreenHash Function
CitrixParseText Function
CitrixParseTextFuzzy Function
CitrixVerifyText Function
CitrixVerifyTextFuzzy Function


CitrixSetOption Function

Action

Sets a particular option.

Include file

CitrixAPI.bdh

Syntax

CitrixSetOption( in nOption : number,
                 in nValue  : number ) : boolean;

Return value

  • true if successful

  • false otherwise

Parameter | Description
nOption

Specify one of the following values:

  • CITRIX_OPT_UseHttp:

    Set to 1 to use TCP/IP + HTTP as network protocols.

    Set to 0 to use only TCP/IP.

  • CITRIX_OPT_SpeedScreenLatRed:

    Speed Screen Latency Reduction.

    0 .. Off.

    1 .. On

  • CITRIX_OPT_EncryptLevel:

    Use one of the following values:

    0 .. Server Default.

    1 .. Basic encryption.

    2 .. RC5 128 bit encryption for login only.

    3 .. RC5 40 bit encryption.

    4 .. RC5 56 bit encryption.

    5 .. RC5 128 bit encryption

  • CITRIX_OPT_Compress:

    Select this option to compress all transferred data. Reduces the size of data, but requires additional processor resources.

    0 .. Off.

    1 .. On

  • CITRIX_OPT_ImgCache:

    Select this option to store commonly -used graphical objects, such as bitmaps, in a local disk cache.

    0 .. Off.

    1 .. On

  • CITRIX_OPT_QueueMouse:

    Select this option to queue mouse updates. Reduces the number of network packets sent from the Citrix client to the Citrix server. Specify the time to queue input in milliseconds.

  • CITRIX_OPT_QueueKeyboard:

    Select this option to queue keyboard updates. Reduces the number of network packets sent from the Citrix client to the Citrix server. Specify the time to queue input in milliseconds.

  • CITRIX_OPT_DisconnectOnTransEnd:

    Select this option to disconnect the Citrix client at the end of each transaction (this includes the TInit transaction).

    0 .. Off.

    1 .. On

  • CITRIX_OPT_SyncTimeout:

    Specify the default synchronization timeout (in milliseconds) to be used by all CitrixWaitForXXX functions, that do not specify a timeout value.

  • CITRIX_OPT_PostActionThinkTime:

    Specify the time (in milliseconds) that the virtual user is to remain inactive between actions.

  • CITRIX_OPT_PostSyncThinkTime:

    Specify the time (in milliseconds) that the virtual user is to remain inactive after passing a successful synchronization point (CitrixWaitForXXX).

  • CITRIX_OPT_LogBmpOnUserAction:

    When TrueLog is enabled a screenshot is made and written to the TrueLog at the end of each synchronization function. Select this option to additionally capture and write a screenshot at the beginning of each user -action.

    0 .. Off.

    1 .. On

  • CITRIX_OPT_DumpRgnOnSyncFailure:

    The CitrixWaitForScreen function captures a screen region and checks it against a specified condition (normally it is compared against a hash value that’s captured at recording). If the function call fails (the condition does not match and the timeout period expires) when this option is selected, the caught screen region is dumped to a file in the result directory. The file can then be examined or compared to what was written during recording for root cause analysis.

    0 .. Off.

    1 .. On

  • CITRIX_OPT_ForcePos:

    Select this option to have calls to CitrixWaitForWindowCreation and CitrixWaitForWindowRestore move the window to the coordinates that were captured during recording. When this box is not checked, both functions provide a parameter (bForcePos) that enables this option for each individual call.

    0 .. Off.

    1 .. On

  • CITRIX_OPT_MouseTimeDown:

    Specify the length of time that the virtual user is to hold the mouse button in the pressed state. Used for CitrixMouseClick and CitrixMouseDblClick.

  • CITRIX_OPT_MouseDblClickDelay:

    Specify the length of time that is to pass between the two clicks of a double click. Used for CitrixMouseDblClick.

  • CITRIX_OPT_MouseSpeed:

    Specify the speed at which the mouse is to move across the screen (pixels per second).

  • CITRIX_OPT_KeyTimeDown:

    Specify the length of time that the virtual user is to hold a keyboard key in the down state. Used for CitrixKey and CitrixKeyString.

  • CITRIX_OPT_KeyTimeIdle:

    Specify the length of time that is to pass between the individual key-strokes specified by the CitrixKeyString function.

  • CITRIX_OPT_KeyTimeRepeat:

    Specify the time required for a complete key stroke when simulating repeat functionality (a value of 50 means 20 keys per second).

  • CITRIX_OPT_ScreenTextPolling

    Specify the polling period in milliseconds that the Citrix Replay engine will wait to poll a screen for an update (0 means no polling). If omitted, the parameter is set to 1000.
nValue | Value of the selected option.

Example:

  transaction TMain
  var
  begin
    CitrixInit(640, 480);
    CitrixSetOption(CITRIX_OPT_SyncTimeout, 60000); // sync timeout = 60 sec.
    CitrixSetApplication("Excel");
    CitrixConnect("myserver", "myusername", "mypass", "mydomain", COLOR_16bit);
    CitrixWaitForLogon();
    hWnd4 := CitrixWaitForWindowCreation("Microsoft Excel – Book*", MATCH_Wildcard, 0x15CF0000, -4, -4, 648, 488);
    CitrixMouseClick(636, 14, hWnd4, MOUSE_ButtonLeft);
    CitrixWaitForWindow(hWnd4, EVENT_Destroy);
    ThinkTime(2.63);
    CitrixDisconnect();
  end TMain;
Parent topic: General Functions
Related reference
CitrixSetClientName Function
CitrixPing Function
CitrixSetProperty Function
CitrixSetRamDisk Function
CitrixSetSocksProxy Function
CitrixGetSessionString Function
CitrixAddInterrupt Function
CitrixGetActInterrupt Function
CitrixRemoveInterrupt Function
CitrixGetMeasures Function
CitrixGetScreen Function
CitrixGetScreenHash Function
CitrixParseText Function
CitrixParseTextFuzzy Function
CitrixVerifyText Function
CitrixVerifyTextFuzzy Function


CitrixPing Function

Action

Sends a ping synchronization request to the currently connected Citrix server, with sPingData as payload. This function waits until either the server responds or the timeout expires.

Include file

CitrixAPI.bdh

Syntax

CitrixPing( in  sPingData : string,
            out nRTT      : number,
            in  nTimeout  : number optional ): boolean;

Return value

  • true if the function succeeds

  • false otherwise

Parameter | Description
sPingData | Payload sent to the server.
nRTT | Retrieves the round-trip time of the sent ping request.
nTimeout | Specifies the time to wait for the server to respond (optional). When this parameter is omitted or set to 0, the default timeout is used. The default value can be adjusted by profile settings ( Settings > Active Profile > Citrix > General > Synchronization timeout ) or an appropriate call to the CitrixSetOption function.

Example:

  transaction TMain
  var
    nRTT : number;
  begin
    CitrixInit(640, 480);
    CitrixSetApplication("Excel");
    CitrixConnect("myserver", "myusername", "mypass", "mydomain", COLOR_16bit);
    CitrixWaitForLogon();
    hWnd4 := CitrixWaitForWindowCreation("Microsoft Excel - Book*", MATCH_Wildcard, 0x15CF0000, -4, -4, 648, 488);
    CitrixKeyString("test");
    CitrixMouseClick(636, 14, hWnd4, MOUSE_ButtonLeft);
    ThinkTime(2.63);
    CitrixMouseClick(306, 289, hWnd4, MOUSE_ButtonLeft);
    CitrixWaitForWindow(hWnd4, EVENT_Destroy);
    CitrixPing("payload", nRTT);
    print("CitrixPing round trip time: " + string(nRTT));
    CitrixDisconnect();
  end TMain;
Parent topic: General Functions
Related reference
CitrixSetClientName Function
CitrixSetOption Function
CitrixSetProperty Function
CitrixSetRamDisk Function
CitrixSetSocksProxy Function
CitrixGetSessionString Function
CitrixAddInterrupt Function
CitrixGetActInterrupt Function
CitrixRemoveInterrupt Function
CitrixGetMeasures Function
CitrixGetScreen Function
CitrixGetScreenHash Function
CitrixParseText Function
CitrixParseTextFuzzy Function
CitrixVerifyText Function
CitrixVerifyTextFuzzy Function


CitrixSetProperty Function

Action

Sets a property of a Citrix client. See Citrix client documentation for possible property/value pairs.

Include file

CitrixAPI.bdh

Syntax

CitrixSetProperty( in sProp  : string,
                   in sValue : string ) : boolean;

Return value

  • true if successful

  • false otherwise

Parameter | Description
sProp | Property name.
sValue | Property value

Example:

  transaction TMain
  var
  begin
    CitrixInit(640, 480);
    CitrixSetApplication("Excel");
    CitrixSetProperty("Border", "20");
    CitrixConnect("myserver", "myusername", "mypass", "mydomain", COLOR_16bit);
    CitrixWaitForLogon();
    hWnd4 := CitrixWaitForWindowCreation("Microsoft Excel - Book*", MATCH_Wildcard, 0x15CF0000, -4, -4, 648, 488);
    CitrixKeyString("test");
    CitrixMouseClick(636, 14, hWnd4, MOUSE_ButtonLeft);
    ThinkTime(2.63);
    CitrixMouseClick(306, 289, hWnd4, MOUSE_ButtonLeft);
    CitrixWaitForWindow(hWnd4, EVENT_Destroy);
    ThinkTime(2.63);
    CitrixDisconnect();
  end TMain;
Parent topic: General Functions
Related reference
CitrixSetClientName Function
CitrixSetOption Function
CitrixPing Function
CitrixSetRamDisk Function
CitrixSetSocksProxy Function
CitrixGetSessionString Function
CitrixAddInterrupt Function
CitrixGetActInterrupt Function
CitrixRemoveInterrupt Function
CitrixGetMeasures Function
CitrixGetScreen Function
CitrixGetScreenHash Function
CitrixParseText Function
CitrixParseTextFuzzy Function
CitrixVerifyText Function
CitrixVerifyTextFuzzy Function


CitrixSetRamDisk Function

Action

Specifies a directory that is to be used for the temporary storage of images. TrueLog-generation performance improves when the specified drive is a RAM disk. Used for both record and replay.

Include file

CitrixAPI.bdh

Syntax

CitrixSetRamDisk( in sPath : string ): boolean;

Return value

  • true if the function succeeds

  • false otherwise

Parameter | Description
sPath | Path of a directory that is to be used for the temporary storage of images for TrueLog generation.

Example:

  transaction TMain
  var
  begin
    CitrixInit(640, 480);
    CitrixSetRamDisk("z:"); //use ramdisk drive "z:"
    CitrixSetApplication("Excel");
    CitrixConnect("myserver", "myusername", "mypass", "mydomain", COLOR_16bit);
    CitrixWaitForLogon();
    hWnd4 := CitrixWaitForWindowCreation("Microsoft Excel - Book*", MATCH_Wildcard, 0x15CF0000, -4, -4, 648, 488);
    CitrixKeyString("test");
    CitrixMouseClick(636, 14, hWnd4, MOUSE_ButtonLeft);
    ThinkTime(2.63);
    CitrixMouseClick(306, 289, hWnd4, MOUSE_ButtonLeft);
    CitrixWaitForWindow(hWnd4, EVENT_Destroy);
    ThinkTime(2.63);
    CitrixDisconnect();
  end TMain;
Parent topic: General Functions
Related reference
CitrixSetClientName Function
CitrixSetOption Function
CitrixPing Function
CitrixSetProperty Function
CitrixSetSocksProxy Function
CitrixGetSessionString Function
CitrixAddInterrupt Function
CitrixGetActInterrupt Function
CitrixRemoveInterrupt Function
CitrixGetMeasures Function
CitrixGetScreen Function
CitrixGetScreenHash Function
CitrixParseText Function
CitrixParseTextFuzzy Function
CitrixVerifyText Function
CitrixVerifyTextFuzzy Function


CitrixSetSocksProxy Function

Action

Specifies a socks proxy to be used for Citrix replay.

Include file

CitrixAPI.bdh

Syntax

CitrixSetSocksProxy( in sProxy : string,
                     in nPort : number,
                     in nVersion : number ): boolean;

Return value

  • true if the function succeeds

  • false otherwise

Parameter | Description
sProxy | Host name or IP address of the socks proxy to be used for Citrix replay.
nPort | Port of the socks proxy.
nVersion | Socks protocol version to be used (v4 or v5).

Example:

  transaction TMain
  var
  begin
    CitrixSetSocksProxy("lab13", 1080, 5);
    CitrixInit(640, 480);
    CitrixSetApplication("Excel");
    CitrixConnect("myserver", "myusername", "mypass", "mydomain", COLOR_16bit);
    CitrixWaitForLogon();
    hWnd4 := CitrixWaitForWindowCreation("Microsoft Excel - Book*", MATCH_Wildcard, 0x15CF0000, -4, -4, 648, 488);
    CitrixKeyString("test");
    CitrixMouseClick(636, 14, hWnd4, MOUSE_ButtonLeft);
    ThinkTime(2.63);
    CitrixMouseClick(306, 289, hWnd4, MOUSE_ButtonLeft);
    CitrixWaitForWindow(hWnd4, EVENT_Destroy);
    CitrixDisconnect();
  end TMain;

Parent topic: General Functions
Related reference
CitrixSetClientName Function
CitrixSetOption Function
CitrixPing Function
CitrixSetProperty Function
CitrixSetRamDisk Function
CitrixGetSessionString Function
CitrixAddInterrupt Function
CitrixGetActInterrupt Function
CitrixRemoveInterrupt Function
CitrixGetMeasures Function
CitrixGetScreen Function
CitrixGetScreenHash Function
CitrixParseText Function
CitrixParseTextFuzzy Function
CitrixVerifyText Function
CitrixVerifyTextFuzzy Function


CitrixGetSessionString Function

Action

Returns the session string of the current ICA session from the server. The string that is returned is specified by the nIndex value.

Include file

CitrixAPI.bdh

Syntax

CitrixGetSessionString( in  nIndex  : number,
                        out sString : string ): boolean;

Return value

  • true if successful

  • false otherwise

Parameter | Description
nIndex

Specifies one of the following values:

  • 0: Returns the server name.

  • 1: Returns the user name

  • 2: Returns the domain
sString | Retrieves the specified value.

Example:

  transaction TMain
  var
    sSession   : string;
  begin
    CitrixInit(640, 480);
    CitrixSetApplication("Excel");
    CitrixConnect("myserver", "myusername", "mypass", "mydomain", COLOR_16bit);
    CitrixWaitForLogon();
    hWnd4 := CitrixWaitForWindowCreation("Microsoft Excel - Book*", MATCH_Wildcard, 0x15CF0000, -4, -4, 648, 488);
    CitrixKeyString("test");
    CitrixMouseClick(636, 14, hWnd4, MOUSE_ButtonLeft);
    ThinkTime(2.63);
    CitrixMouseClick(306, 289, hWnd4, MOUSE_ButtonLeft);
    CitrixWaitForWindow(hWnd4, EVENT_Destroy);
    CitrixGetSessionString(0, sSession);
    print("Citrix host name: " + sSession);
    CitrixGetSessionString(1, sSession);
    print("Citrix user name: " + sSession);
    CitrixGetSessionString(2, sSession);
    print("Citrix domain: " + sSession);
    CitrixDisconnect();
  end TMain;
Parent topic: General Functions
Related reference
CitrixSetClientName Function
CitrixSetOption Function
CitrixPing Function
CitrixSetProperty Function
CitrixSetRamDisk Function
CitrixSetSocksProxy Function
CitrixAddInterrupt Function
CitrixGetActInterrupt Function
CitrixRemoveInterrupt Function
CitrixGetMeasures Function
CitrixGetScreen Function
CitrixGetScreenHash Function
CitrixParseText Function
CitrixParseTextFuzzy Function
CitrixVerifyText Function
CitrixVerifyTextFuzzy Function


CitrixAddInterrupt Function

Action

Adds an interrupt specification. On certain window events (creations, activations, destructions, and caption changes) all stored interrupt specifications are checked; when an interrupt specification matches an occurred event, then an interrupt is thrown. Interrupts may be handled by a Citrix event handler. For further information see the event-handler section.

Include file

CitrixAPI.bdh

Syntax

CitrixAddInterrupt( in nReason  : number,
                    in sCaption : string allownull,
                    in nMatch   : number,
                    in nWindow  : number optional): boolean;

Return value

  • true if the function succeeds

  • false otherwise

Parameter | Description
nReason

  • INTERRUPT_WindowCreate: An interrupt is triggered if a created window matches the specified conditions.

  • INTERRUPT_WindowActivate: An interrupt is triggered if an activated window matches the specified conditions.

  • INTERRUPT_WindowDestroy: An interrupt is triggered if a destroyed window matches the specified conditions.

  • INTERRUPT_CaptionChange: An interrupt is triggered if a changed window caption matches the specified window caption (specified in the nMatch parameter) or the window with the nWindow ID changes its caption.

sCaption | The caption that triggers an interrupt if it matches the window caption (which is specified in the nMatch parameter). If this parameter is provided (and not null or “”) then the nWindow parameter will be ignored.
nMatch

Specifies one of the following values:

  • MATCH_Exact (default): Case-sensitive comparison.
  • MATCH_ExactNoCase: Case-insensitive comparison.
  • MATCH_Wildcard: The search string must either begin or end with a '*' character, which matches everything. The rest of the string is compared case sensitively.
  • MATCH_WildcardNoCase: The search string must either begin or end with a '*' character, which matches everything. The rest of the string is compared case insensitively.
  • MATCH_RegExp: The search string is a regular expression. See the regular expression chapter for a description of Silk Performer's regular expression capability.
nWindow | If the sCaption parameter is not provided, then windows will be examined by comparing their ID’s against the nWindow parameter (optional).

Example

transaction TMain
  var
  begin
    CitrixInit(800, 600);
    CitrixAddInterrupt(INTERRUPT_WindowCreate, "ICA Seamless Host Agent", MATCH_Exact);
    CitrixConnect("lab74", "labadmin", "labpass", "testlab1", COLOR_16bit);
    CitrixWaitForLogon();
    hWnd4 := CitrixWaitForWindowCreation("", MATCH_Exact, 0x96840000, -2, 572, 804, 30);
    CitrixWaitForWindowCreation("Program Manager");
    CitrixMouseClick(36, 17, hWnd4, MOUSE_ButtonLeft, MOD_None, -1, 0);
    hWnd11 := CitrixWaitForWindowCreation("", MATCH_Exact, 0x96400000, 2, 313, 163, 263);
    CitrixMouseClick(62, 247, hWnd11, MOUSE_ButtonLeft);
    CitrixWaitForWindow(hWnd11, EVENT_Destroy);
    hWnd12 := CitrixWaitForWindowCreation("Shut Down Windows", MATCH_Exact, 0x94C808CC, 191, 136, 417, 192);
    CitrixWaitForWindow(hWnd12, EVENT_Activate);
    CitrixMouseClick(203, 170, hWnd12, MOUSE_ButtonLeft);
    CitrixWaitForDisconnect();
  end TMain;
dclevent
  handler Handler1 <EVENT_CITRIXINTERRUPT>
  var
    nInterrupt, nWindow : number;
    nStyle              : number;
  begin
    CitrixGetActInterrupt(nInterrupt, nWindow);

    ErrorAdd(FACILITY_CITRIXENGINE, 47, SEVERITY_INFORMATIONAL);
    print(string(nWindow));
    if CitrixGetWindowStyle(nWindow, nStyle) and (nStyle <> 0xB4000000) then
      CitrixWaitForWindow(nWindow, EVENT_Activate);
      CitrixMouseClick(201, 202, nWindow, MOUSE_ButtonLeft);
      CitrixWaitForWindow(nWindow, EVENT_Destroy);
    end;
    ErrorRemove(FACILITY_CITRIXENGINE, 47);

  end Handler1;
Parent topic: General Functions
Related reference
CitrixSetClientName Function
CitrixSetOption Function
CitrixPing Function
CitrixSetProperty Function
CitrixSetRamDisk Function
CitrixSetSocksProxy Function
CitrixGetSessionString Function
CitrixGetActInterrupt Function
CitrixRemoveInterrupt Function
CitrixGetMeasures Function
CitrixGetScreen Function
CitrixGetScreenHash Function
CitrixParseText Function
CitrixParseTextFuzzy Function
CitrixVerifyText Function
CitrixVerifyTextFuzzy Function


CitrixGetActInterrupt Function

Action

To be used only within an event handler. This function returns the actual Citrix interrupt reason as well as the window that triggered it.

Include file

CitrixAPI.bdh

Syntax

CitrixGetActInterrupt( out nReason : number allownull ,
                       out nWindow : number optional ): boolean;

Return value

  • true if the function succeeds

  • false otherwise

Parameter | Description
nReason

Returns one of the following values:

  • INTERRUPT_WindowCreate

  • INTERRUPT_WindowActivate

  • INTERRUPT_WindowDestroy

  • INTERRUPT_CaptionChange
nWindow | Retrieves the window handle that triggered the interrupt.

Example

transaction TMain
  var
  begin
    CitrixInit(800, 600);
    CitrixAddInterrupt(INTERRUPT_WindowCreate, "ICA Seamless Host Agent", MATCH_Exact);
    CitrixConnect("lab74", "labadmin", "labpass", "testlab1", COLOR_16bit);
    CitrixWaitForLogon();
    hWnd4 := CitrixWaitForWindowCreation("", MATCH_Exact, 0x96840000, -2, 572, 804, 30);
    CitrixWaitForWindowCreation("Program Manager");
    CitrixMouseClick(36, 17, hWnd4, MOUSE_ButtonLeft, MOD_None, -1, 0);
    hWnd11 := CitrixWaitForWindowCreation("", MATCH_Exact, 0x96400000, 2, 313, 163, 263);
    CitrixMouseClick(62, 247, hWnd11, MOUSE_ButtonLeft);
    CitrixWaitForWindow(hWnd11, EVENT_Destroy);
    hWnd12 := CitrixWaitForWindowCreation("Shut Down Windows", MATCH_Exact, 0x94C808CC, 191, 136, 417, 192);
    CitrixWaitForWindow(hWnd12, EVENT_Activate);
    CitrixMouseClick(203, 170, hWnd12, MOUSE_ButtonLeft);
    CitrixWaitForDisconnect();
  end TMain;
dclevent
  handler Handler1 <EVENT_CITRIXINTERRUPT>
  var
    nInterrupt, nWindow : number;
    nStyle              : number;
  begin
    CitrixGetActInterrupt(nInterrupt, nWindow);

    ErrorAdd(FACILITY_CITRIXENGINE, 47, SEVERITY_INFORMATIONAL);
    print(string(nWindow));
    if CitrixGetWindowStyle(nWindow, nStyle) and (nStyle <> 0xB4000000) then
      CitrixWaitForWindow(nWindow, EVENT_Activate);
      CitrixMouseClick(201, 202, nWindow, MOUSE_ButtonLeft);
      CitrixWaitForWindow(nWindow, EVENT_Destroy);
    end;
    ErrorRemove(FACILITY_CITRIXENGINE, 47);

  end Handler1;
Parent topic: General Functions
Related reference
CitrixSetClientName Function
CitrixSetOption Function
CitrixPing Function
CitrixSetProperty Function
CitrixSetRamDisk Function
CitrixSetSocksProxy Function
CitrixGetSessionString Function
CitrixAddInterrupt Function
CitrixRemoveInterrupt Function
CitrixGetMeasures Function
CitrixGetScreen Function
CitrixGetScreenHash Function
CitrixParseText Function
CitrixParseTextFuzzy Function
CitrixVerifyText Function
CitrixVerifyTextFuzzy Function


CitrixRemoveInterrupt Function

Action

Removes the interrupt specification that is added by a call to CitrixAddInterrupt. Specifies exactly the same parameters that are provided by the call to CitrixAddInterrupt.

Include file

CitrixAPI.bdh

Syntax

CitrixRemoveInterrupt( in nReason  : number,
                       in sCaption : string allownull,
                       in nMatch   : number,
                       in nWindow  : number optional ): boolean;

Return value

  • true if the function succeeds

  • false otherwise

Parameter | Description
nReason

  • INTERRUPT_WindowCreate: An interrupt is triggered if a created window matches the specified conditions.

  • INTERRUPT_WindowActivate: An interrupt is triggered if an activated window matches the specified conditions.

  • INTERRUPT_WindowDestroy: An interrupt is triggered if a destroyed window matches the specified conditions.

  • INTERRUPT_CaptionChange: An interrupt is triggered if a changed window caption matches the specified window caption (specified in the nMatch parameter) or the window with the nWindow ID changes its caption.

sCaption | The caption that triggers an interrupt if it matches the window caption (which is specified in the nMatch parameter). If this parameter is provided (and not null or “”) then the nWindow parameter will be ignored.
nMatch

Specify one of the following values (optional):

  • MATCH_Exact (default): Case-sensitive comparison.
  • MATCH_ExactNoCase: Case-insensitive comparison.
  • MATCH_Wildcard: The search string must either begin or end with a '*' character, which matches everything. The rest of the string is compared case sensitively.
  • MATCH_WildcardNoCase: The search string must either begin or end with a '*' character, which matches everything. The rest of the string is compared case insensitively.
  • MATCH_RegExp: The search string is a regular expression. See the regular expression chapter for a description of Silk Performer's regular expression capability.
nWindow | If the sCaption parameter is not provided, then windows will be examined by comparing their ID’s against the nWindow parameter.

Parent topic: General Functions
Related reference
CitrixSetClientName Function
CitrixSetOption Function
CitrixPing Function
CitrixSetProperty Function
CitrixSetRamDisk Function
CitrixSetSocksProxy Function
CitrixGetSessionString Function
CitrixAddInterrupt Function
CitrixGetActInterrupt Function
CitrixGetMeasures Function
CitrixGetScreen Function
CitrixGetScreenHash Function
CitrixParseText Function
CitrixParseTextFuzzy Function
CitrixVerifyText Function
CitrixVerifyTextFuzzy Function


CitrixGetMeasures Function

Action

Retrieves measures collected by a Citrix client for an actual session. Null may be specified for measures that are not of interest.

Include file

CitrixAPI.bdh

Syntax

CitrixGetMeasures( out nBytesIn   : number optional,
                   out nBytesOut  : number optional,
                   out nFramesIn  : number optional,
                   out nFramesOut : number optional,
                   out nErrorsIn  : number optional,
                   out nErrorsOut : number optional,
                   out nLastLat   : number optional,
                   out nAvgLat    : number optional,
                   out nLatDev    : number optional ): boolean;

Return value

  • true if successful

  • false otherwise

Parameter | Description
nBytesIn | Received bytes
nBytesOut | Sent bytes
nFramesIn | Received frames
nFramesOut | Sent frames
nErrorsIn | Received errors
nErrorsOut | Sent errors
nLastLat | Last latency
nAvgLat | Average latency
nLatDev | Current latency deviation

Example:

  transaction TMain
  var
    nBytesIn   : number;
    nBytesOut  : number;
    nFramesIn  : number;
    nFramesOut : number;
    nErrorsIn  : number;
    nErrorsOut : number;
    nLastLat   : number;
    nAvgLat    : number;
    nLatDev    : number;
  begin
    CitrixInit(640, 480);
    CitrixSetApplication("Excel");
    CitrixConnect("myserver", "myusername", "mypass", "mydomain", COLOR_16bit);
    CitrixWaitForLogon();
    hWnd4 := CitrixWaitForWindowCreation("Microsoft Excel - Book*", MATCH_Wildcard, 0x15CF0000, -4, -4, 648, 488);
    CitrixKeyString("test");
    CitrixMouseClick(636, 14, hWnd4, MOUSE_ButtonLeft);
    ThinkTime(2.63);
    CitrixMouseClick(306, 289, hWnd4, MOUSE_ButtonLeft);
    CitrixWaitForWindow(hWnd4, EVENT_Destroy);
    CitrixGetMeasures(nBytesIn, nBytesOut, nFramesIn, nFramesOut, nErrorsIn, nErrorsOut, nLastLat, nAvgLat, nLatDev);
    print("Citrix measures: ");
    print(" bytes in: " + string(nBytesIn));
    print(" bytes out: " + string(nBytesOut));
    print(" frames in: " + string(nFramesIn));
    print(" frames out: " + string(nFramesOut));
    print(" errors in: " + string(nErrorsIn));
    print(" errors out: " + string(nErrorsOut));
    print(" last latency: " + string(nLastLat));
    print("  avg. latency:" + string(nAvgLat));
    print(" current latency deviation: " + string(nLatDev));
    CitrixDisconnect();
  end TMain;
Parent topic: General Functions
Related reference
CitrixSetClientName Function
CitrixSetOption Function
CitrixPing Function
CitrixSetProperty Function
CitrixSetRamDisk Function
CitrixSetSocksProxy Function
CitrixGetSessionString Function
CitrixAddInterrupt Function
CitrixGetActInterrupt Function
CitrixRemoveInterrupt Function
CitrixGetScreen Function
CitrixGetScreenHash Function
CitrixParseText Function
CitrixParseTextFuzzy Function
CitrixVerifyText Function
CitrixVerifyTextFuzzy Function


CitrixGetScreen Function

Action

Takes a screenshot of the selected region and writes the screenshot to a file in the result directory. The file name can be provided by the first parameter. If the file name is omitted, it will be automatically generated by the user ID and hash value of the image. Use the optional sOutFile parameter to get the generated file name.

The screen region can be specified absolutely or relatively to a window (by specifying a window handle). When only a window handle and no position or size is provided, the region specified by the window outline is used. CitrixGetScreen without any parameter takes a screenshot of the entire screen and saves it to a file that’s name is a concatenation of the calling user and the hash value of the current screen.

Note: CitrixGetScreen can only be called in Normal Mode (see CitrixInit). If used in Fast Mode, an error will be raised.

Include file

CitrixAPI.bdh

Syntax

CitrixGetScreen( in  sFile    : string optional,
                 in  nWindow  : number optional,
                 in  nX       : number optional,
                 in  nY       : number optional,
                 in  nWidth   : number optional,
                 in  nHeight  : number optional,
                 out sOutFile : string optional ) : boolean;

Return value

  • true if successful

  • false otherwise

Parameter | Description
sFile | Name of the file, which is stored in the result directory (optional). When this parameter is omitted the filename is generated automatically using the hash value of the image.
nWindow | Window handle returned by a call to CitrixWaitForWindowCreation. Use DESKTOP or omit this parameter to specify a region relative to the desktop (or the entire desktop).
nX | X coordinate of the left margin of the screen region (optional).
nY | Y coordinate of the top margin of the screen region (optional).
nWidth | Width of the region (optional). Omit this parameter to take a screen shot of the entire window.
nHeight | Height of the region (optional). Omit this parameter to take a screenshot of the entire window.
sOutFile | Returns the name of the written file (optional).

Example:

  transaction TMain
  var
  begin
    CitrixInit(640, 480);
    CitrixConnect("citserver", "user", "password", "companydomain", COLOR_16bit);
    CitrixWaitForLogon();
    hWnd6 := CitrixWaitForWindowCreation("ICA Seamless Host Agent", MATCH_Exact, 0x94C800C4, 0, 0, 390, 223);
    CitrixWaitForWindow(hWnd6, EVENT_Activate);
    CitrixWaitForWindowCreation("Program Manager");
    ThinkTime(3.31);
    CitrixMouseClick(214, 197, hWnd6, MOUSE_ButtonLeft);
    CitrixWaitForWindow(hWnd6, EVENT_Destroy);
    CitrixMouseDblClick(112, 16, DESKTOP, MOUSE_ButtonLeft);
    hWnd9 := CitrixWaitForWindowCreation("Microsoft Excel – Book*", MATCH_Wildcard, 0x15CF0000, -4, -4, 648, 460);
    CitrixGetScreen("screenshot01.bmp", hWnd9, 10, 20, 100, 100);
    CitrixMouseClick(634, 9, hWnd9, MOUSE_ButtonLeft);    CitrixWaitForWindow(hWnd9, EVENT_Destroy);
    ThinkTime(3.02);
    CitrixDisconnect();
  end TMain;
Parent topic: General Functions
Related reference
CitrixSetClientName Function
CitrixSetOption Function
CitrixPing Function
CitrixSetProperty Function
CitrixSetRamDisk Function
CitrixSetSocksProxy Function
CitrixGetSessionString Function
CitrixAddInterrupt Function
CitrixGetActInterrupt Function
CitrixRemoveInterrupt Function
CitrixGetMeasures Function
CitrixGetScreenHash Function
CitrixParseText Function
CitrixParseTextFuzzy Function
CitrixVerifyText Function
CitrixVerifyTextFuzzy Function


CitrixGetScreenHash Function

Action

Retrieves the hash value of the selected screen.

The screen region can be specified absolutely or relatively to a window (by specifying a window handle). When a window handle is provided without position or size, the region specified by the window outline is used.

Note: CitrixGetScreenHash can only be called in Normal Mode (see CitrixInit). If used in Fast Mode, an error will be raised.

Include file

CitrixAPI.bdh

Syntax

CitrixGetScreenHash( out sHash   : string,
                     in  nWindow : number optional,
                     in  nX      : number optional,
                     in  nY      : number optional,
                     in  nWidth  : number optional,
                     in  nHeight : number optional ) : boolean;

Return value

  • true if successful

  • false otherwise

Parameter | Description
sHash | Hash value of the selected screen region.
nWindow | Window handle returned by a call to CitrixWaitForWindowCreation. Use DESKTOP or omit this parameter to specify a region relative to the desktop (or the entire desktop).
nX | X coordinate of the left margin of the screen region (optional).
nY | Y coordinate of the top margin of the screen region (optional).
nWidth | Width of the region (optional). Omit this parameter to get a screenshot of the entire window.
nHeight | Height of the region (optional). Omit this parameter to get a screenshot of the entire window.

Example:

  transaction TMain
  var
    sHash : string;
  begin
    CitrixInit(640, 480);
    CitrixConnect("citserver", "user", "password", "companydomain", COLOR_16bit);
    CitrixWaitForLogon();
    hWnd6 := CitrixWaitForWindowCreation("ICA Seamless Host Agent", MATCH_Exact, 0x94C800C4, 0, 0, 390, 223);
    CitrixWaitForWindow(hWnd6, EVENT_Activate);
    CitrixWaitForWindowCreation("Program Manager");
    ThinkTime(3.31);
    CitrixMouseClick(214, 197, hWnd6, MOUSE_ButtonLeft);
    CitrixWaitForWindow(hWnd6, EVENT_Destroy);
    CitrixMouseDblClick(112, 16, DESKTOP, MOUSE_ButtonLeft);
    hWnd9 := CitrixWaitForWindowCreation("Microsoft Excel - Book*", MATCH_Wildcard, 0x15CF0000, -4, -4, 648, 460);
    CitrixGetScreenHash(sHash, hWnd9, 10, 20, 100, 100);
    print(sHash);
    CitrixMouseClick(634, 9, hWnd9, MOUSE_ButtonLeft);
    CitrixWaitForWindow(hWnd9, EVENT_Destroy);
    ThinkTime(3.02);
    CitrixDisconnect();
  end TMain;
Parent topic: General Functions
Related reference
CitrixSetClientName Function
CitrixSetOption Function
CitrixPing Function
CitrixSetProperty Function
CitrixSetRamDisk Function
CitrixSetSocksProxy Function
CitrixGetSessionString Function
CitrixAddInterrupt Function
CitrixGetActInterrupt Function
CitrixRemoveInterrupt Function
CitrixGetMeasures Function
CitrixGetScreen Function
CitrixParseText Function
CitrixParseTextFuzzy Function
CitrixVerifyText Function
CitrixVerifyTextFuzzy Function


CitrixParseText Function

Action

This function performs optical character recognition (OCR) on a selected screen region and stores the result in a sResult parameter. Screen regions can be specified absolutely or relative to a window (by specifying a window handle).

Note: OCR operations are only possible in Normal Mode (see CitrixInit). This function fails when used in Fast Mode. When the optional font parameters are present, the pattern file is checked for the used font’s availability. When the parameters are omitted font checking is not performed.

For successful text conversion it is necessary to use the perfOcrFonts.dat and perfOcrPattern.pat configuration files, which contain the used fonts in the correct size and format. These two files must be added to the Data Files section of the project (both files are located at <public user documents>\Silk Performer 21.0\Data). If the files do not exist, or they do not contain the right specifications, they can be generated or updated using the OCR dialog in the Citrix System Settings.

Include file

CitrixAPI.bdh

Syntax

CitrixParseText( out sResult    : string,
                 in  nWindow    : number,
                 in  nX         : number,
                 in  nY         : number,
                 in  nWidth     : number,
                 in  nHeight    : number,
                 in  sFont      : string optional,
                 in  nFontSize  : number optional,
                 in  nFontFlags : number optional ) : boolean;

Return value

  • true if successful

  • false otherwise

Parameter | Description
sResult | String variable that receives the converted text.
nWindow | Window handle returned by a call to CitrixWaitForWindowCreation. Use DESKTOP to specify a region relative to the desktop.
nX | X coordinate of the left margin of the screen region.
nY | Y coordinate of the top margin of the screen region.
nWidth | Width of the region.
nHeight | Height of the region
sFont | Font that should be checked for on the system and in the provided configuration files (optional). This parameter does not affect the conversion; it enables rapid fault detection when using remote agents and moving projects to different hosts. When a specified font is not on the operating system, it must be installed. If the provided configuration files do not contain the font, use the OCR configuration dialog (System Settings / Citrix) to adjust them. When this parameter is omitted font checking is not performed.
nFontSize | The font size that should be checked for in the provided configuration files (optional). This parameter does not affect the conversion; it enables rapid fault detection when using remote agents and moving projects to different hosts. If the provided configuration files do not contain the font-size, use the OCR configuration dialog (System Settings / Citrix) to adjust them. When this parameter is omitted font-size checking is not performed.
nFontFlags

Specifies the font shape (bold, italic, or underlined) that should be checked for in the provided configuration files (optional). This parameter does not affect the conversion; it enables rapid fault detection when using remote agents and moving projects to different hosts. If the provided configuration files do not contain the specified font shapes, use the OCR configuration dialog (System Settings / Citrix) to adjust them. When this parameter is omitted font-shape checking is not performed.

Specify any combination of the following values:

  • FONT_FLAG_Italic

  • FONT_FLAG_Bold

  • FONT_FLAG_Underlined

Example

  transaction TMain
  var
    sParam1 : string;
  begin
    CitrixInit(640, 480); // do not change the resolution
    CitrixConnect("lab1", "user", "password", "domain", COLOR_16bit);
    CitrixWaitForLogon();
    CitrixParseText(sParam1, DESKTOP, 73, 109, 74, 23, "Tahoma", 8);
    Print("sParam1: " + sParam1);
    CitrixDisconnect();
  end TMain;
Parent topic: General Functions
Related reference
CitrixSetClientName Function
CitrixSetOption Function
CitrixPing Function
CitrixSetProperty Function
CitrixSetRamDisk Function
CitrixSetSocksProxy Function
CitrixGetSessionString Function
CitrixAddInterrupt Function
CitrixGetActInterrupt Function
CitrixRemoveInterrupt Function
CitrixGetMeasures Function
CitrixGetScreen Function
CitrixGetScreenHash Function
CitrixParseTextFuzzy Function
CitrixVerifyText Function
CitrixVerifyTextFuzzy Function


CitrixParseTextFuzzy Function

Action

This function performs optical character recognition (OCR) on a selected screen region and stores the result in a sResult parameter. Screen regions can be specified absolutely or relative to a window (by specifying a window handle).

Note: OCR operations are only possible in Normal Mode (see CitrixInit). This function fails when used in Fast Mode. When the optional font parameters are present, the pattern file is checked for the used font’s availability. When the parameters are omitted font checking is not performed.

CitrixParseTextFuzzy performs OCR more exactly than CitrixParseText but requires more resources.

Include file

CitrixAPI.bdh

Syntax

CitrixParseTextFuzzy( out sResult    : string,
                      in  nWindow    : number,
                      in  nX         : number,
                      in  nY         : number,
                      in  nWidth     : number,
                      in  nHeight    : number,
                      in  sLanguage  : string ): boolean;

Return value

  • true if successful

  • false otherwise

Parameter | Description
sResult | String variable that receives the converted text.
nWindow | Window handle returned by a call to CitrixWaitForWindowCreation. Use DESKTOP to specify a region relative to the desktop.
nX | X coordinate of the left margin of the screen region.
nY | Y coordinate of the top margin of the screen region.
nWidth | Width of the region.
nHeight | Height of the region
sLanguage | The language of the text to be verified. Possible language codes are chi_sim, dan, deu, eng, fin, fra, it, jpn, nld, nor, pol, spa and swe.

Example

  transaction TMain
  var
    sParam1 : string;
  begin
    CitrixInit(640, 480); // do not change the resolution
    CitrixConnect("lab1", "user", "password", "domain", COLOR_16bit);
    CitrixWaitForLogon();
    CitrixParseTextFuzzy(sParam1, DESKTOP, 73, 109, 74, 23, "eng");
    Print("sParam1: " + sParam1);
    CitrixDisconnect();
  end TMain;
Parent topic: General Functions
Related reference
CitrixSetClientName Function
CitrixSetOption Function
CitrixPing Function
CitrixSetProperty Function
CitrixSetRamDisk Function
CitrixSetSocksProxy Function
CitrixGetSessionString Function
CitrixAddInterrupt Function
CitrixGetActInterrupt Function
CitrixRemoveInterrupt Function
CitrixGetMeasures Function
CitrixGetScreen Function
CitrixGetScreenHash Function
CitrixParseText Function
CitrixVerifyText Function
CitrixVerifyTextFuzzy Function


CitrixVerifyText Function

Action

This function performs optical character recognition (OCR) on a selected screen region and compares the result with a provided string. When the verification condition is not met, an error is raised. You can specify the severity of the error. Screen regions can be specified absolutely or relative to a window (by specifying a window handle).

Note: OCR operations are only possible in Normal Mode (see CitrixInit). This function will fail when used in Fast Mode.

When optional font parameters are present, the pattern file is checked to see if the selected font is available. When font parameters are omitted font checking is not performed.

For successful text conversion it is necessary to use the perfOcrFonts.dat and perfOcrPattern.pat configuration files, which contain used fonts in the correct size and format. These files must be added to the Data Files section of the project (both files are located at <public user documents>\Silk Performer 21.0\Data). If the files are not available, or do not contain the correct specifications, they can be generated or updated using the OCR dialog in the Citrix System Settings.

Include file

CitrixAPI.bdh

Syntax

CitrixVerifyText( in sVerify    : string,
                  in nWindow    : number,
                  in nX         : number,
                  in nY         : number,
                  in nWidth     : number,
                  in nHeight    : number,
                  in nOptions   : number optional,
                  in nSeverity  : number optional := SEVERITY_ERROR,
                  in sFont      : string optional,
                  in nFontSize  : number optional,
                  in nFontFlags : number optional ): boolean;

Return value

  • true if the function succeeds

  • false otherwise

Parameter | Description
sVerify | String to compare with the parsed data.
nWindow | Window handle returned by a call to CitrixWaitForWindowCreation. Use DESKTOP to specify a region relative to the desktop.
nX | X coordinate of the left margin of the screen region.
nY | Y coordinate of the top margin of the screen region.
nWidth | Width of the region.
nHeight | Height of the region
nOptions

Specify any combination of the following flags (optional):

  • CITRIX_FLAG_Equal When this flag is set the verification succeeds if the comparison succeeds (default).

  • CITRIX_FLAG_NotEqual When this flag is set the verification succeeds if the comparison fails.

  • CITRIX_FLAG_CaseSensitive When this flag is set the string compare operation is case sensitive.

  • CITRIX_FLAG_IgnoreWhitespace When this flag is set all white spaces are ignored.

nSeverity Optional: Severity of the error that is raised if the verification fails. Can be one of the following values:
  • SEVERITY_SUCCESS: Success; no error (numerical value: 0)
  • SEVERITY_INFORMATIONAL: Informational; no error (numerical value: 1)
  • SEVERITY_WARNING: Warning; no error (numerical value: 2)
  • SEVERITY_ERROR: (Default) Error; simulation continues (numerical value: 3)
  • SEVERITY_TRANS_EXIT: Error; the active transaction is aborted (numerical value: 4)
  • SEVERITY_PROCESS_EXIT: Error; the simulation is aborted (numerical value: 5)
sFont | Font that should be checked for on the system and in the provided configuration files (optional). This parameter does not affect the conversion; it enables rapid fault detection when using remote agents and moving projects to different hosts. If a specified font is not on the operating system, then it must be installed. If the provided configuration files do not contain the font, use the OCR configuration dialog (System Settings / Citrix) to adjust them. When this parameter is omitted font checking is not performed.
nFontSize | The font size that should be checked for in the provided configuration files (optional). This parameter does not affect the conversion; it enables rapid fault detection when using remote agents and moving projects to different hosts. If the provided configuration files do not contain the font size, use the OCR configuration dialog (System Settings / Citrix) to adjust them. When this parameter is omitted, font-size checking is not performed.
nFontFlags

Specifies the font shape (bold, italic, or underlined) that should be checked for in the provided configuration files (optional). This parameter does not affect the conversion; it enables rapid fault detection when using remote agents and moving projects to different hosts. If the provided configuration files do not contain the specified font shapes, use the OCR configuration dialog (System Settings / Citrix) to adjust them. When this parameter is omitted, font-shape checking is not performed.

Specify any combination of the following values:

  • FONT_FLAG_Italic

  • FONT_FLAG_Bold

  • FONT_FLAG_Underlined

Example

  transaction TMain
  begin
    CitrixInit(640, 480); // do not change the resolution
    CitrixConnect("lab1", "user", "password", "domain", COLOR_16bit);
    CitrixWaitForLogon();
    CitrixVerifyText("Joe", DESKTOP, 73, 109, 74, 23, CITRIX_FLAG_IgnoreWhitespace, SEVERITY_WARNING,"Tahoma", 8);
    CitrixDisconnect();
  end TMain;
Parent topic: General Functions
Related reference
CitrixSetClientName Function
CitrixSetOption Function
CitrixPing Function
CitrixSetProperty Function
CitrixSetRamDisk Function
CitrixSetSocksProxy Function
CitrixGetSessionString Function
CitrixAddInterrupt Function
CitrixGetActInterrupt Function
CitrixRemoveInterrupt Function
CitrixGetMeasures Function
CitrixGetScreen Function
CitrixGetScreenHash Function
CitrixParseText Function
CitrixParseTextFuzzy Function
CitrixVerifyTextFuzzy Function


CitrixVerifyTextFuzzy Function

Action

This function performs optical character recognition (OCR) on a selected screen region and compares the result with a provided string. When the verification condition is not met, an error is raised. You can specify the severity of the error. Screen regions can be specified absolutely or relative to a window (by specifying a window handle).

Note: OCR operations are only possible in Normal Mode (see CitrixInit). This function will fail when used in Fast Mode.

CitrixVerifyTextFuzzy performs OCR more exactly than CitrixVerifyText but requires more resources.

Include file

CitrixAPI.bdh

Syntax

CitrixVerifyTextFuzzy( in sVerify    : string,
                       in nWindow    : number,
                       in nX         : number,
                       in nY         : number,
                       in nWidth     : number,
                       in nHeight    : number,
                       in sLanguage  : string,
                       in nOptions   : number optional,
                       in nSeverity  : number optional := SEVERITY_ERROR ): boolean;

Return value

  • true if successful

  • false otherwise

Parameter | Description
sVerify | String to compare with the parsed data.
nWindow | Window handle returned by a call to CitrixWaitForWindowCreation. Use DESKTOP to specify a region relative to the desktop.
nX | X coordinate of the left margin of the screen region.
nY | Y coordinate of the top margin of the screen region.
nWidth | Width of the region.
nHeight | Height of the region
sLanguage | The language of the text to be verified. Possible language codes are chi_sim, dan, deu, eng, fin, fra, ita, jpn, nld, nor, pol, spa and swe.
nOptions

Specify any combination of the following flags (optional):

  • CITRIX_FLAG_Equal When this flag is set the verification succeeds if the comparison succeeds (default).

  • CITRIX_FLAG_NotEqual When this flag is set the verification succeeds if the comparison fails.

  • CITRIX_FLAG_CaseSensitive When this flag is set the string compare operation is case sensitive.

  • CITRIX_FLAG_IgnoreWhitespace When this flag is set all white spaces are ignored.

nSeverity Optional: Severity of the error that is raised if the verification fails. Can be one of the following values:
  • SEVERITY_SUCCESS: Success; no error (numerical value: 0)
  • SEVERITY_INFORMATIONAL: Informational; no error (numerical value: 1)
  • SEVERITY_WARNING: Warning; no error (numerical value: 2)
  • SEVERITY_ERROR: (Default) Error; simulation continues (numerical value: 3)
  • SEVERITY_TRANS_EXIT: Error; the active transaction is aborted (numerical value: 4)
  • SEVERITY_PROCESS_EXIT: Error; the simulation is aborted (numerical value: 5)

Example

  transaction TMain
  begin
    CitrixInit(640, 480); // do not change the resolution
    CitrixConnect("lab1", "user", "password", "domain", COLOR_16bit);
    CitrixWaitForLogon();
    CitrixVerifyTextFuzzy("Joe", DESKTOP, 73, 109, 74, 23, CITRIX_FLAG_IgnoreWhitespace, SEVERITY_WARNING, "eng");
    CitrixDisconnect();
  end TMain;
Parent topic: General Functions
Related reference
CitrixSetClientName Function
CitrixSetOption Function
CitrixPing Function
CitrixSetProperty Function
CitrixSetRamDisk Function
CitrixSetSocksProxy Function
CitrixGetSessionString Function
CitrixAddInterrupt Function
CitrixGetActInterrupt Function
CitrixRemoveInterrupt Function
CitrixGetMeasures Function
CitrixGetScreen Function
CitrixGetScreenHash Function
CitrixParseText Function
CitrixParseTextFuzzy Function
CitrixVerifyText Function


.NET Testing Support

This section includes complete instructions for testing Microsoft .NET with the Silk Performer .NET Framework and .NET Explorer.

  • .NET Explorer Help
    Includes complete instructions for testing Microsoft .NET with .NET Explorer.
  • .NET Framework Developer Guide
    Includes complete instructions for testing Microsoft .NET with the Silk Performer .NET Framework.
  • Testing SOAP Web Services for .NET
    Explains the basics of SOAP-based Web services and details how you can test them in .NET.


.NET Explorer Help

  • Tools and Samples
    Explains the tools, sample applications and test projects that Silk Performer provides for testing Java and .NET.
  • Silk Performer .NET Framework
    Silk Performer’s .NET Framework enables developers and QA personnel to coordinate their development and testing efforts while allowing them to work entirely within their specialized environments.
  • Tour of the UI
    Introduces the main elements of the .NET Explorer interface, including the Loaded Components, Method Call, and Test Scenario panes, and the workflow bar.
  • Setting Up .NET Explorer Projects
    Explains how to set up projects and define tests with .NET Explorer.
  • Setting Up Tests
    Includes an introduction to .NET Explorer GUI elements, customization of input parameters, definition of output value verifications, and generation of random variables. The section concludes with an explanation of how to use .NET Explorer to test .NET Remoting.
  • Animated Runs
    Explains that animated runs execute the test methods that are assigned to your test cases. Several output logs and reports are available.
  • Analyzing Results
    Lists the four file types that are available for analyzing Web Service and .NET Remoting test results.
  • Configuring Option Settings
    Explains the application setting options that are available in .NET Explorer.
  • Exporting Projects
    Explains that .NET Explorer enables you to export projects to Silk Performer and Visual Studio .NET.
  • Command Line Execution
    For automated execution of .NET Explorer test cases, use the command line interface.
Parent topic: .NET Testing Support


Tools and Samples

Explains the tools, sample applications and test projects that Silk Performer provides for testing Java and .NET.
  • Introduction
    Serves as a high-level overview of the different test approaches and tools, including Java Explorer, Java Framework, .NET Explorer, and .NET Framework, that are offered by Silk Performer Service Oriented Architecture (SOA) Edition.
  • Provided Tools
    Offers an overview of each of the tools provided with Silk Performer for testing Java and .NET.
  • Sample Applications for testing Java and .NET
    Explains that the sample applications provided with Silk Performer enable you to experiment with Silk Performer's component-testing functionality.
  • Sample Test Projects
    Explains the sample projects that are included with Silk Performer.
Parent topic: .NET Explorer Help
Parent topic: .NET Framework Developer Guide
Parent topic: Java Explorer Help
Parent topic: Java Framework Developer Guide


Introduction

This introduction serves as a high-level overview of the different test approaches and tools, including Java Explorer, Java Framework, .NET Explorer, and .NET Framework, that are offered by Silk Performer Service Oriented Architecture (SOA) Edition.

Silk Performer SOA Edition Licensing

Each Silk Performer installation offers the functionality required to test .NET and Java components. Access to Java and .NET component testing functionality is however only enabled through Silk Performer licensing options. A Silk Performer SOA Edition license is required to enable access to component testing functionality. Users may or may not additionally have a full Silk Performer license.

What You Can Test With Silk Performer SOA Edition

With Silk Performer SOA Edition you can thoroughly test various remote component models, including:

  • Web Services
  • .NET Remoting Objects
  • Enterprise JavaBeans (EJB)
  • Java RMI Objects
  • General GUI-less Java and .NET components

Unlike standard unit testing tools, which can only evaluate the functionality of a remote component when a single user accesses it, Silk Performer SOA Edition can test components under concurrent access by up to five virtual users, thereby emulating realistic server conditions. With a full Silk Performer license, the number of virtual users can be scaled even higher. In addition to testing the functionality of remote components, Silk Performer SOA Edition also verifies the performance and interoperability of components.

Silk Performer SOA Edition assists you in automating your remote components by:

  • Facilitating the development of test drivers for your remote components
  • Supporting the automated execution of test drivers under various conditions, including functional test scenarios and concurrency test scenarios
  • Delivering quality and performance measures for tested components

Silk Performer offers the following approaches to creating test clients for remote components:

  • Visually, without programming, through Java Explorer and .NET Explorer
  • Using an IDE (Microsoft Visual Studio)
  • Writing Java code
  • Recording an existing client
  • Importing JUnit or NUnit testing frameworks
  • Importing Java classes
  • Importing .NET classes
Parent topic: Tools and Samples


Provided Tools

Offers an overview of each of the tools provided with Silk Performer for testing Java and .NET.
  • Silk Performer .NET Explorer
    Enables you to test Web Services, .NET Remoting objects, and other GUI-less .NET objects.
  • Silk Performer Visual Studio Extension
    Allows you to implement test drivers in Microsoft Visual Studio that are compatible with Silk Performer.
  • Silk Performer Java Explorer
    Enables you to test Web Services, Enterprise JavaBeans (EJB), RMI objects, and other GUI-less Java objects.
  • Silk Performer Workbench
    Explains that remote component tests that are developed and executed using Java Explorer or .NET Explorer can be executed within Silk Performer Workbench.
Parent topic: Tools and Samples


Silk Performer .NET Explorer

Silk Performer .NET Explorer, which was developed using .NET, enables you to test Web Services, .NET Remoting objects, and other GUI-less .NET objects. .NET Explorer allows you to define and execute complete test scenarios with different test cases without requiring manual programming; everything is done visually through point and click operations. Test scripts are visual and easy to understand, even for staff members who are not familiar with .NET programming languages.

Test scenarios created with .NET Explorer can be exported to Silk Performer for immediate reuse in concurrency and load testing, and to Microsoft Visual Studio for further customization.

Parent topic: Provided Tools


Silk Performer Visual Studio Extension

The Silk Performer Visual Studio extension allows you to implement test drivers in Microsoft Visual Studio that are compatible with Silk Performer. Such test drivers can be augmented with Silk Performer features that facilitate test organization, verification, performance measurement, test data generation, and reporting.

Tests created with the extension can be run either within Microsoft Visual Studio, with full access to Silk Performer's functionality, or within Silk Performer, for concurrency and load testing scenarios.

The extension offers the following features:
  • Writing test code in any of the main .NET languages (C# or VB.NET).
  • Testing Web services / .NET Remoting objects and redirecting HTTP traffic over the Silk Performer Web engine to take advantage of features such as modem simulation and IP-address multiplexing. SOAP envelopes can also be explored using TrueLog Explorer.
  • Defining virtual users and their transactions through .NET custom attributes. A BDL script is generated automatically based on the custom attributes that have been applied to classes/methods.
  • Running TryScript tests from within Microsoft Visual Studio with the ability to watch virtual user output in a tool window within Microsoft Visual Studio.
  • Exploring the results of Try Scripts.

.NET Resources

  • http://msdn.microsoft.com/net
  • Installing the Visual Studio Extension
    Install the Visual Studio Extension to use Silk Performer with Visual Studio.
  • Starting the Visual Studio Extension
    Start the Visual Studio extension to run .NET tests created with Microsoft Visual Studio.
Parent topic: Provided Tools
Parent topic: Understanding the .NET Framework Platform


Silk Performer Java Explorer

Silk Performer Java Explorer, which was developed using Java, enables you to test Web Services, Enterprise JavaBeans (EJB), RMI objects, and other GUI-less Java objects. Java Explorer allows you to define and execute complete test scenarios with multiple test cases without requiring manual programming. Everything can be done visually via point and click operations. Test scripts are visual and easy to understand, even for personnel who are not familiar with Java programming.

Test scenarios created with Java Explorer can be exported to Silk Performer for immediate reuse in concurrency and load testing.

Note: Java Explorer is only compatible with JDK versions 1.2 and later (v1.4 or later recommended).

Java Resources

  • http://java.sun.com
  • http://www.javaworld.com
Parent topic: Provided Tools


Silk Performer Workbench

Remote component tests that are developed and executed using Java Explorer or .NET Explorer can be executed within Silk Performer Workbench. Silk Performer is an integrated test environment that serves as a central console for creating, executing, controlling and analyzing complex testing scenarios. Java Explorer and .NET Explorer visual test scripts can be exported to Silk Performer by creating Silk Performer Java Framework and .NET Framework projects. While Java Explorer and .NET Explorer serve as test-beds for functional test scenarios, Silk Performer can be used to run the same test scripts in more complex scenarios for concurrency and load testing.

In the same way that Silk Performer is integrated with Java Explorer and .NET Explorer, Silk Performer is also integrated with Silk Performer's Visual Studio .NET Add-On. Test clients created in Microsoft Visual Studio using Silk Performer's Visual Studio .NET Add-On functionality can easily be exported to Silk Performer for concurrency and load testing.

Note: Because there is such a variety of Java development tools available, a Java tool plug-in is not feasible. Instead, Silk Performer offers features that assist Java developers, such as syntax highlighting for Java and the ability to run the Java complier from Silk Performer Workbench.

In addition to the integration of Silk Performer with .NET Explorer, Java Explorer, and Microsoft Visual Studio, you can use Silk Performer to write custom Java and .NET based test clients using Silk Performer's powerful Java and .NET Framework integrations.

The tight integration of Java and .NET as scripting environments for Silk Performer test clients allows you to reuse existing unit tests developed with JUnit and NUnit by embedding them into Silk Performer's framework architecture. To begin, launch Silk Performer and create a new Java or .NET Framework-based project.

In addition to creating test clients visually and manually, Silk Performer also allows you to create test clients by recording the interactions of existing clients, or by importing JUnit test frameworks or existing Java/.NET classes. A recorded test client precisely mimics the interactions of a real client.

Note: The recording of test clients is only supported for Web Services clients.

To create a Web Service test client based on the recording of an existing Web Service client, launch Silk Performer and create a new project of application type Web Services/XML/SOAP.

Parent topic: Provided Tools


Sample Applications for testing Java and .NET

The sample applications provided with Silk Performer enable you to experiment with Silk Performer's component-testing functionality.

Sample applications for the following component models are provided:

  • Web Services
  • .NET Remoting
  • Java RMI
  • Public Web Services
    Lists Web Services that are hosted on publicly accessible servers:
  • .NET Message Sample
    Explains the .NET Message Sample, which provides a .NET sample application that utilizes various .NET technologies.
  • .NET Explorer Remoting Sample
    Explains how the .NET Remoting sample application can be used for the testing of .NET Remoting.
  • Java RMI Samples
    Explains the Java RMI sample applications that are included.
Parent topic: Tools and Samples


Public Web Services

Several Web Services are hosted on publicly accessible demonstration servers:

  • http://demo.borland.com/BorlandSampleService/BorlandSampleService.asmx
  • http://demo.borland.com/OrderWebServiceEx/OrderService.asmx
  • http://demo.borland.com/OrderWebService/OrderService.asmx
  • http://demo.borland.com/AspNetDataTypes/DataTypes.asmx
Note: OrderWebService provides the same functionality as OrderWebServiceEx, however it makes use of SOAP headers in transporting session information, which is not recommended as a starting point for Java Explorer.
Parent topic: Sample Applications for testing Java and .NET


.NET Message Sample

The .NET Message Sample provides a .NET sample application that utilizes various .NET technologies:

  • Web Services
  • ASP.NET applications communicating with Web Services
  • WinForms applications communicating with Web Services and directly with .NET Remoting objects.

To access the .NET Message Sample:

If you have Silk Performer SOA Edition: Go to Start > Programs > Silk > Silk Performer SOA Edition 21.0 > Sample Applications > .NET Framework Samples .

If you have Silk Performer Enterprise Edition: Go to Start > Programs > Silk > Silk Performer 21.0 > Sample Applications > .NET Framework Samples .

Parent topic: Sample Applications for testing Java and .NET
Related concepts
Using the .NET Message Sample


.NET Explorer Remoting Sample

The .NET Remoting sample application can be used in .NET Explorer for the testing of .NET Remoting.

To access the .NET Explorer Remoting Sample:

If you have Silk Performer SOA Edition: Go to Start > Programs > Silk > Silk Performer SOA Edition 21.0 > Sample Applications > .NET Explorer Samples > .NET Explorer Remoting Sample .

If you have Silk Performer Enterprise Edition: Go to Start > Programs > Silk > Silk Performer 21.0 > Sample Applications > .NET Explorer Samples > .NET Explorer Remoting Sample .

DLL reference for .NET Explorer: <public user documents>\Silk Performer 21.0\SampleApps\DOTNET\RemotingSamples\RemotingLib\bin\debug\RemotingLib.dll.

Parent topic: Sample Applications for testing Java and .NET


Java RMI Samples

Two Java RMI sample applications are included:

  • A simple RMI sample application that is used in conjunction with the sample Java Framework project (<public user documents>\Silk Performer 21.0\Samples\JavaFramework\RMI).

    To start the ServiceHello RMI Server, go to: Start > Programs > Silk > Silk Performer 21.0 > Sample Applications > Java Samples > RMI Sample - SayHello.

  • A more complex RMI sample that uses RMI over IIOP is also available. For details on setting up this sample, go to: Start > Programs > Silk > Silk Performer 21.0 > Sample Applications > Java Samples > Product Manager. This sample can be used with the sample test project that is available at <public user documents>\Silk Performer 21.0\SampleApps\RMILdap.

Java RMI can be achieved using two different protocols, both of which are supported by Java Explorer:

  • Java Remote Method Protocol (JRMP)
  • RMI over IIOP

Java Remote Method Protocol (JRMP)

A simple example server can be found at <public user documents>\Silk Performer 21.0\SampleApps\Java.

Launch the batch file LaunchRemoteServer.cmd to start the sample server. Then use the Java Explorer Start Here Wizard to begin testing RMI objects. Select RMI and click Next.

The next dialog asks for the RMI registry settings and a classpath where the RMI interfaces for the client can be found. Here are the settings to be used for this example:

Host: localhost

Port: 1099

Client Stub Class: <public user documents>\Silk Performer 21.0\SampleApps\Java\Lib\sampleRmi.jar.

RMI over IIOP

A simple example server can be found at: <public user documents>\Silk Performer 21.0\SampleApps\Java.

Launch the batch file LaunchRemoteServerRmiOverIiop.cmd to start the sample server.

Use the Java Explorer Start Here Wizard to begin testing RMI objects. Select Enterprise JavaBeans/RMI over IIOP and click Next.

The next step asks for the JNDI settings and a classpath where the RMI interfaces for the client can be found. Here are the settings to be provided for this example:

Server: Sun J2EE Server

Factory: com.sun.jndi.cosnaming.CNCtxFactory

Provider URL: iiop://localhost:1050

Stub Class: Click Browse and add the following jar file: <public user documents>\Silk Performer 21.0\SampleApps\Java\Lib\sampleRmiOverIiop.jar.

Parent topic: Sample Applications for testing Java and .NET


Sample Test Projects

The following sample projects are included with Silk Performer. To open a sample test project, open Silk Performer and create a new project. The Workflow - Outline Project dialog opens. Select the application type Samples.

  • .NET Sample Projects
    Lists the .NET sample projects that are included.
  • Java Sample Projects
    Lists the sample Java projects that are included.
Parent topic: Tools and Samples


.NET Sample Projects

.NET Remoting

This sample project implements a simple .NET Remoting client using the Silk Performer .NET Framework. The .NET Remoting test client, written in C#, comes with a complete sample .NET Remoting server.

Web Services

This sample shows you how to test SOAP Web Services with the Silk Performer .NET Framework. The sample project implements a simple Web Services client. The Web Services test client, written in C#, accesses the publicly available demo Web Service at: http://demo.borland.com/BorlandSampleService/BorlandSampleService.asmx
Parent topic: Sample Test Projects


Java Sample Projects

JDBC

This sample project implements a simple JDBC client using the Silk Performer Java Framework. The JDBC test client connects to the Oracle demo user scott using Oracle's "thin" JDBC driver. You must configure connection settings in the databaseUser.bdf BDL script to run the script in your environment. The sample accesses the EMP Oracle demo table.

RMI/IIOP

This sample project implements a Java RMI client using the Silk Performer Java Framework. The test client uses IIOP as the transport protocol and connects to a RMI server provided as a sample application. For detailed instructions on setting up this sample project, see <public user documents>\Silk Performer 21.0\SampleApps\RMILdap\Readme.html.

The Java RMI server can be found at: <public user documents>\Silk Performer 21.0\SampleApps\RMILdap.

RMI

This sample project implements a Java RMI client using the Silk Performer Java Framework. The test client connects to a RMI server provided as a sample application. For detailed instructions on setting up this sample project, see <public user documents>\Silk Performer 21.0\SampleApps\RMILdap\Readme.html.

To access the Java RMI server:

If you have Silk Performer SOA Edition: Go to Start > Programs > Silk > Silk Performer SOA Edition 21.0 > Sample Applications > Java Samples > RMI Sample - SayHello .

If you have Silk Performer Enterprise Edition: Go to Start > Programs > Silk > Silk Performer 21.0 > Sample Applications > Java Samples > RMI Sample - SayHello.

Parent topic: Sample Test Projects


Testing .NET Components

Silk Performer’s Visual Studio .NET Add-On provides functionality to developers working in .NET-enabled languages for generating Silk Performer projects and test scripts entirely from within Visual Studio.0

  • The .NET Framework Approach
    With Silk Performer’s Visual Studio .NET Add-On, developers can generate Silk Performer projects and test scripts entirely from within Visual Studio.
  • The .NET Explorer Approach
    Explains how .NET Explorer integrates with Silk Performer and the .NET Framework.
Parent topic: Silk Performer .NET Framework


The .NET Framework Approach

The .NET Framework approach to testing is ideal for developers and advanced QA personnel who are not familiar with coding BDL (Silk Performer’s Benchmark Description Language) scripting language, but are comfortable using Visual Studio to code .NET-enabled languages such as C#, COBOL.NET, C++ .NET, and Visual Basic.NET. With Silk Performer’s Visual Studio .NET Add-On, developers can generate Silk Performer projects and test scripts entirely from within Visual Studio by simply adding marking attributes to the methods they write in Visual Studio. The Add-On subsequently creates all BDL scripting that is required to enable the QA department to invoke newly created methods from Silk Performer.

Parent topic: Testing .NET Components
Related concepts
Understanding the .NET Framework Platform


The .NET Explorer Approach

.NET Explorer is a GUI-driven tool that is well suited to QA personnel who are proficient with Silk Performer in facilitating analysis of .NET components and thereby creating Silk Performer projects, test case specifications, and scripts from which load tests can be run.

Developers who are proficient with Microsoft Visual Studio may also find .NET Explorer helpful for quickly generating basic test scripts that can subsequently be brought into Visual Studio for advanced modification.

Parent topic: Testing .NET Components


Understanding the .NET Framework Platform

.NET Framework is a powerful programming platform that enables developers to create Windows-based applications. The .NET Framework is comprised of CLR (Common Language Runtime, a language-neutral development environment) and FCL (Framework Class Libraries, an object-oriented functionality library).

Visit the .NET Framework Developer Center for full details regarding the .NET Framework.

  • Working with Silk Performer .NET Framework
    Describes how you can use the Silk Performer .NET Framework to test Web services and .NET components.
  • Silk Performer .NET Framework Overview
    Provides an overview of how the Silk Performer .NET Framework works.
  • Intermediate Code
    Intermediate code is descriptive language that delivers instructions to functions that are available in libraries or within remote components.
  • Silk Performer Helper Classes
    Explains how helper classes serve as an interface between Silk Performer’s BDL language and the .NET language.
  • Silk Performer Visual Studio Extension
    Allows you to implement test drivers in Microsoft Visual Studio that are compatible with Silk Performer.
Parent topic: Silk Performer .NET Framework


Working with Silk Performer .NET Framework

The Silk Performer .NET Framework allows you to test Web services and .NET components. The framework includes a set of the Benchmark Description Language (BDL) API functions of Silk Performer and an add-on for Microsoft Visual Studio.

Note: For additional details regarding the available BDL API functions, refer to the Benchmark Description Language (BDL) Reference.

The framework allows you to either code your BDL calls to .NET objects manually in Silk Performer or use generated BDL code from the Visual Studio .NET Add-On. One benefit of the latter approach is that the developer of the .NET test driver doesn't require BDL skills, because BDL script generation is handled "behind the scenes" by the Visual Studio .NET Add-On. BDL Scripts can be launched for testing purposes from within Microsoft Visual Studio through the Add-On. All user output and generated output files, like TrueLogs, logs, output, and others, can be viewed from within Microsoft Visual Studio.

The .NET Framework allows you to route all HTTP/HTTPS traffic that is generated by a .NET component over the Silk Performer Web engine. This feature logs TrueLog nodes for each SOAP or .NET Remoting Web request, that is made by a .NET component.

This architecture provides good separation between test driver code and the test environment. There are also mechanisms for defining interaction between BDL and .NET, so you can design a fully customizable .NET test driver from a generated Silk Performer BDL script.

Parent topic: Understanding the .NET Framework Platform
Related concepts
Benchmark Description Language (BDL) Reference


Silk Performer .NET Framework Overview

.NET Framework Overview

The Silk Performer .NET Framework integration allows you to instantiate .NET objects and then call methods on them.

The Microsoft .NET Common Language Runtime (CLR) is hosted by the Silk Performer virtual user process when BDF scripts contain DotNet BDL functions.

HTTP/HTTPS traffic that is generated by instantiated .NET objects can be routed over the Silk Performer Web engine. Each WebRequest/WebResponse is logged in a TrueLog, allowing you to see what is sent over the wire when executing Web service and .NET Remoting calls.

Depending on the active profile setting, which is a .NET application domain setting, either each virtual user has its own .NET application domain where .NET objects are loaded, or alternately all virtual users in the process can share an application domain.

A .NET application domain isolates its running objects from other application domains. An application domain is like a virtual process where the objects running in the process are safe from interruption by other processes. The advantage of having one application domain for each virtual user is that the objects that are loaded for each user don't interrupt objects from other users, since they are isolated in their own domains.

The disadvantage is that additional application domains require additional administrative overhead of the CLR. This overhead results in longer object-loading and method-invocation times.

Parent topic: Understanding the .NET Framework Platform


Intermediate Code

.NET code is not compiled into binary “machine” code. .NET code is intermediate code. Intermediate code is descriptive language that delivers instructions, for example “call this method” or “add these numbers”, to functions that are available in libraries or within remote components.

.NET code runs within a machine-independent runtime, or “execution engine,” which can be run on any platform—Windows, Unix, Linux, or Macintosh. So, regardless of the platform you’re running, you can run the same intermediate code. The drawback of this cross-platform compatibility is that, because intermediate code must be integrated with a runtime, it’s slower than compiled machine code.

.NET code calls basic Microsoft functionality that is available in .NET class libraries. These are the “base” classes. “Specific” classes, for creating Web applications, Windows applications, and Web Services are also available. In the runtime itself you also have some classes that are offered by Microsoft for building applications—all of this comprises the .NET Framework upon which intermediate code can be written using one of a number of available .NET-enabled programming languages.

It doesn’t matter which language is used to create the intermediate code that delivers instructions to the available classes through the .NET runtime—the resulting functionality is the same.

Parent topic: Understanding the .NET Framework Platform


Silk Performer Helper Classes

.NET helper classes serve as an interface between Silk Performer’s BDL language and the .NET language. Although Silk Performer is able to call the .NET Framework through the basic functions that it offers, helper classes are required to enable .NET to call back to Silk Performer. With helper classes, which are generated automatically with .NET Explorer and the Visual Studio .NET Add-On, .NET developers can take full advantage of developing test code in .NET and don’t need to learn BDL. The test code that developers deliver to QA, by making use of helper classes, can be called from Silk Performer or scheduled in load tests using Silk Central.

Parent topic: Understanding the .NET Framework Platform


Starting the Visual Studio Extension

Perform one of the following steps to start the Visual Studio extension:
  • Click Start > All Programs > Microsoft Visual Studio > Microsoft Visual Studio and create a new Silk Performer Visual Studio project.
  • Click Start > All Programs > Silk > Silk Performer 21.0 > Silk Performer Workbench and create a new project with the application type .NET > .NET Framework using Visual Studio .NET Add-On.
Parent topic: Silk Performer Visual Studio Extension


Tour of the UI

Explains the view tabs that are offered by .NET Explorer.

  • Overview
    Introduces the main elements of the .NET Explorer interface, including the Loaded Components, Method Call, and Test Scenario panes, and the workflow bar.
  • Design Tab
    Explains that the Design tab offers the display of loaded components, invocation of methods, customization of input/output data, and the design of test scenarios.
  • Code Tab
    Explains that the Code tab displays generated code files for the current test scenario and that various code types are available.
  • Output Tab
    Explains that the Output tab displays log output during test runs.
Parent topic: .NET Explorer Help


Overview

The main sections of the .NET Explorer interface are highlighted below.

Workflow Bar

The .NET Explorer workflow bar assists you in configuring and running your tests. The buttons on the workflow bar enable you to perform the following commands:

  • Start Here: Opens the Load File Wizard, which guides you through selecting the type of testing that you want to perform and loading the required components.
  • Test Class: Allows you to create a new test case for a class, or to add methods to an existing test case. This button is enabled when you select a class in the Loaded Components menu tree.
  • Invoke: Invokes the selected method in the Loaded Components menu tree and adds it to the selected test case in the Test Scenario menu tree.
  • Customize: Lets you store data as variables. This button is enabled when you select an input parameter in the Input Data menu tree, or an output parameter in the Output Data menu tree.
  • Verification: Allows you to define verifications for variables. This button is enabled when you select an output parameter in the Output Data menu tree that has been stored as a variable.
  • Run Test: Performs an animated run of your test cases.
  • Results: Lets you explore the results of your last test run through user report, TrueLog, error report, or log file analysis.
  • Net Traffic: Displays the request and response network traffic of the method call that is selected in the Test Scenario menu tree.

WSDL/DLL Address Field

The WSDL/DLL address field allows for the loading of either WSDLs or .NET assemblies.

Loaded Components Pane

The Loaded Components pane includes three tabs:
  • Classes: A list of loaded Web services, remotable classes/interfaces and other .NET classes. Allows you to instantiate objects, connect to remote objects, or call static methods.
  • Objects: A list of instantiated objects, global and random variables. Allows you to call methods on those kind of objects.
  • References: A list of loaded files (assemblies, WSDL‘s).

Method Call Pane

  • The Input Data menu tree shows input parameters (both headers and bodies) for the selected method call.
  • The Input Data Properties field shows the properties of the input parameters (value, type, pass, null, etc).
  • The Output Data menu tree shows the output parameters (header and body) of the last/selected method call.
  • The Output Data Properties field shows the properties of the output parameters (value, type, pass, null, etc).

Test Scenario Pane

The Test Scenario pane lists the current test cases along with all added method calls.

Parent topic: Tour of the UI


Design Tab

The Design tab is the primary mode used to access the majority of .NET Explorer functionality. The Design tab offers the display of loaded components, invocation of methods, customization of input/output data, and the design of test scenarios.

  • Loaded Components Pane
    Explains that the Loaded Components pane, on the Design tab, distinguishes between classes and objects and displays these components within different tree menus.
  • Classes Tab
    Explains that all loaded classes and Web services are listed in the .NET ExplorerLoaded Components pane on the Classes tab.
  • Objects Tab
    Explains that when an object is instantiated through a constructor or returned by a method and stored in a variable, the object is listed in the Loaded Components pane on the Objects tab.
  • References Tab
    Explains that the References tab offers a list of loaded files (for example, assemblies and WSDLs).
Parent topic: Tour of the UI


Loaded Components Pane

The Loaded Components pane, on the Design tab, distinguishes between classes and objects and displays these components within different tree menus.

On the Classes tab you see all loaded classes with their members (methods, fields, and properties) that can be accessed without the need of an object context. Normally these are static members and constructors.

When you instantiate a class, the created object is shown on the Objects tab with all instance members (methods, fields, and properties).

The two exceptions are Web services and interfaces. As an object instance is not required for Web Services (which are objects that expose static methods), all methods offered by Web services are shown on the Classes tab.

Interfaces are displayed in the Remotable Interfaces menu node. .NET Remoting allows for WellKnown remotable objects, which implement interfaces. Therefore it is not necessary to instantiate objects that work with WellKnowns (only one instance exists on the server). This is why .NET Explorer treats remotable interfaces like Web services. All members of interfaces are shown on the Classes tab. When you first attempt to invoke a method you must supply the endpoint of the remotable interface (as you must provide endpoints for Web services).

Parent topic: Design Tab


Classes Tab

All loaded classes and Web services are listed in the .NET Explorer Loaded Components pane on the Classes tab.

Only constructors, static methods, and members are displayed, as there is no object context required to call them.

Web services and remotable interfaces are treated as if they only have static methods.

The following folders are available in Classes view:

Web Services

Classes that are derived from SoapHttpClientProtocol are included in this folder. Asynchronous method calls are not allowed and therefore are not shown.

Remotable Classes

Classes that are derived from MarshalByRefObjects are included in this folder. Activation information (type and URL) can be set at the class node.

To create a remote object, call one of the constructors or use the context menu.

Remotable Interfaces

Interfaces are included in this folder. Interfaces are treated like Web services.

An activation URL to a WellKnown object can be defined for each interface. If an interface is configured for remote access to a WellKnown object, simply call a method.

COM Classes

COM classes are COM wrapper classes that have been imported to be callable from .NET.

Other Classes

Other classes that do not fit in the above listed categories are included in this folder.

Parent topic: Design Tab


Objects Tab

When an object is instantiated through a constructor or returned by a method and stored in a variable, the object is listed in the Loaded Components pane on the Objects tab. Instance members and methods that can then be invoked by the user are displayed.

The Objects tab shows objects stored in variables that have global scope and those that have a local scope of the currently selected test case.

Objects

By default, unless changed in the Options dialog box, only objects that differ from the basic types (for example, strings and integers) are listed here as objects. Instance methods and members are displayed to allow for easy invokation.

Members and properties have get/set accessors to enable the getting and setting of values.

Local test case objects are included in the Local Test Case Objects folder. Global test case objects are included in the Global Test Case Objects folder.

Variables

By default variables that store simple datatypes such as strings and integers are listed in the Global Random Variables folder, not as objects but as simple variables.

To work with variables of simple data types like objects, select Show Primitive Types as Objects on the Options dialog box.

Parent topic: Design Tab


References Tab

The References tab offers a list of loaded files (for example, assemblies and WSDLs).

Parent topic: Design Tab


Code Tab

Code view displays generated code files for the current test scenario. The following code types are available:

Client Proxy Code

The Client Proxy tab displays generated WebClient proxy code. When loading a WSDL file to access a Web Service, a WebClient proxy class is created. Proxy classes are created on method and type information in WSDL files. When Web Service methods return complex types, additional classes are declared. These additional classes are used to represent the complex types in the method calls that take complex parameters. For detailed information about WebClient Proxy generation, consult the MSDN for details regarding WSDL.EXE, a tool that creates proxy classes in the same way.

Test Driver Code

The test driver Test Code tab displays code generated for the test driver. This code can be compiled to a standalone console application. The main method for the application contains the calls to the test cases that are defined in your current test scenario. The test case methods contain all the calls that you have defined in your scenario for the respective test case.

When you export a standalone console application (via the Export menu) and then run the application, you will see output information regarding successful/failed methods in the console window.

Silk Performer .NET Framework Code

The Silk Performer .NET Framework tab displays test code for Silk Performer .NET Framework. For each test case in your current test scenario you will find a method with the [Transaction] attribute applied to it. These transaction methods contain all the calls that you have defined in your test scenario for the respective test case.

This code can either be exported to Microsoft Visual Studio as a Silk Performer .NET Project, or it can be exported directly to Silk Performer. In either case, results will be reported to Silk Performer and can be viewed in the log files or virtual user output.

Native BDL Script

The BDL Native tab displays native BDL script for Web Service calls. When testing Web Services, .NET Explorer can create BDL scripts with WebPagePost API calls for each Web Service method call in the current test scenario. WebPagePost methods are called with posted HTTP traffic from .NET Explorer during the last execution of the current test scenario.

Exporting to a native BDL script allows you to test a Web Service by sending its HTTP traffic without using the .NET Framework to generate the HTTP traffic.

BDL for .NET Framework

Th BDL FW tab displays BDL script for Silk Performer .NET Framework. When exporting a project as a Silk Performer .NET Framework project, .NET Explorer uses the code in the Silk Performer .NET Framework code pane, compiles the code to a .NET Assembly (DLL), and creates a BDL script that loads the DLL and calls the methods that have been marked with the [Transaction] attribute. The BDL script is shown here, but it is not shown in the final state that will be generated upon export. Only a skeletal BDL script is displayed.

Parent topic: Tour of the UI


Output Tab

The Output tab displays log output during test runs. The Output tab shows details about each call of the most recent animated run. Statistics regarding execution time and executed methods are also shown.

Example Animated Log Output

Test started: 08.10.2004 08:01:50
Test stopped: 08.10.2004 08:01:53
Method calls: 1
Success calls: 1
Error calls: 0
TestWebProxies.Service1.echoStringArray
Parameters : System.String[](string)
Return Value: System.String[](string)
Note: The Output tab can also be accessed by clicking Results on the Workflow Bar.
Parent topic: Tour of the UI


Setting Up .NET Explorer Projects

This section shows you how to set up projects and define tests with .NET Explorer. A sample Web service is used for demonstration purposes.

.NET Explorer requires that Microsoft .NET Framework 4.0 or later is installed. Microsoft .NET Framework is available on Microsoft's .NET Framework Downloads page.

  • Creating .NET Explorer Projects
    Create a new .NET Explorer project to test Web services, .NET remoting, imported COM wrappers, and other .NET classes.
  • Test Case Definition
    Explains the available approaches for defining test cases with .NET Explorer.
  • Using the Load File Wizard
    Use the Load File Wizard to define where the information for the object you wish to test is located.
  • Viewing and Comparing WSDL Files
    If a WSDL file has changed, update individual Web Service Proxy classes with a new WSDL file.
  • Defining Client Certificates for a Web Service
    Define client certificates for Web services that require client certificates for authentication.
  • Test Case Characteristics
    Explains the characteristics of test cases as they relate to .NET Explorer.
Parent topic: .NET Explorer Help
Related concepts
Testing .NET Remoting


Creating .NET Explorer Projects

Upon opening .NET Explorer you are prompted to either open an existing project or create a new project.
  1. Click the Create a new project option button.
  2. Enter a name for your project in the text box.
  3. Click OK.
Your new project is created and the .NET Explorer GUI displays.
Parent topic: Setting Up .NET Explorer Projects


Test Case Definition

Three approaches are available for defining tests with .NET Explorer:
  • Use the Load File Wizard to define where the information for the object you wish to test is located. The wizard then displays the available classes, automatically instantiates the available objects, and calls methods on those objects. This approach is more involved, but it offers more control.
  • Enter the location of the Web services’ WSDL file directly into .NET Explorer’s WSDL/DLL field and click Load. Information about the methods and objects is then displayed, however objects are not instantiated and methods are not called. This approach offers a quick, simple approach to analyzing remote service functionality.

  • Import a COM wrapper via the Load COM Type Libraries dialog (Model > Test COM Classes).

For demonstration purposes this Help uses the Load File Wizard to instantiate the objects available on the sample Web service, which is available at http://demo.borland.com/BorlandSampleService/BorlandSampleService.asmx?WSDL.

Parent topic: Setting Up .NET Explorer Projects
Related tasks
Using the Load File Wizard


Using the Load File Wizard

  1. Click Start Here on the workflow bar.

    The Load File Wizard dialog box displays.

  2. To test a Web service, you must provide a Web Services Description Language (WSDL) document. Click the Web Services option button and specify a path or URL to the WSDL document using the browse (...) button.
    Note: To test .NET Remoting or other .NET classes, click the corresponding option button (.NET Remoting or Other .NET Classes) and then specify a .NET Assembly (DLL or EXE) that defines the class.
  3. Click Next. The WSDL file now loads and finds out what is available on the Web service. A WSDL file is an XML description of the functionality that is offered by the Web service.
    Note: The sample Web service offers a minimum of functionality. It simply echoes back some values.
  4. Select the Web service class you wish to test from the Class list box. Normally there will be only one class, but it is possible that the loaded WSDL will define multiple Web services.
  5. Using the URL (Endpoint) text box, you can change the endpoint of the service. The default endpoint is the one defined in the WSDL document. If required, you can change Web service proxy and authentication settings for the Web server by clicking browse (...) and entering information into the Web Proxy Settings Wizard dialog box.
  6. Click Next. The Method invocation page displays.
  7. Check the check boxes beside the methods that you want to have tested, for example echoFloat(Single) and echoString(String). Methods are called using the default parameters.
    Note: To see the member functions of the base classes, click Inherited. This feature is generally only applicable to the testing of .NET Remoting and other .NET classes.
  8. To adjust the sequence in which the methods are called, use the up and down arrow buttons. This way, you can move methods up and down the invocation list. The button between the up and down arrow buttons enables you to invert the selection of methods, meaning that all unmarked methods become marked, and vice versa.
    Note: Login and logout methods must be in first and last positions, respectively.
  9. Click Next. The Select a test case page displays.
  10. Select the test case to which the testing methods should be added. You can select from the following:
    • Init Test Case: This is the first test case that is called in test runs. Select this test case if your method calls are related to initialization, logging in, or start-up.
    • Existing Test Case: You can add to an existing test case. Choose the test case from the list box to the right of this selection.
    • New Test Case: A new test case is created and the methods are added to the new test case. Using the text box to the right of this selection, give the new test case a unique name.
    • End Test Case: This is the last test case that is called in test runs. Select this test case if your method calls are related to clean-up, for example logging off.
  11. Click Finish.
    Note: A message displays if you have selected a method that takes parameters, letting you know that default parameters will be used for the method, which may result in an exception being thrown. Methods that throw exceptions will be excluded from your test scenario. If you do not want to proceed, click No, then go back, deselect the method in question, and add it later manually with a more meaningful parameter value.
The Web Service has been loaded in the Loaded Components menu tree and the selected methods have been called and added to the selected test case.
Parent topic: Setting Up .NET Explorer Projects


Viewing and Comparing WSDL Files

WSDL files are stored in project files. For older projects, you must update Web Service Proxy classes to store WSDL documents. This is done by updating individual Web Service Proxy classes with a new WSDL file.
  1. Select a Web Service Proxy class in the Loaded Components menu tree. A property called WSDL is displayed in the Input Data Properties field.
  2. Select the WSDL parameter and click browse (...). The WSDL View dialog box opens, which includes the original URL, the date the WSDL file was downloaded, and the contents of the WSDL file.
  3. Enter a URL in the Compare With text box and click Compare. The content check functionality compares the string contents of both files.
You are informed whether or not there is a difference between the files’ contents, but not what the specific difference is.
Parent topic: Setting Up .NET Explorer Projects


Defining Client Certificates for a Web Service

For Web services that require client certificates for authentication, client certificates must be defined in Web service properties.
  1. Select a Web service class in the Loaded Components menu tree. A property called ClientCertificates is displayed in the Input Data Properties field.
  2. Select the ClientCertificates parameter and click browse (...). The Client Certificate dialog box opens, where certificates can be added or removed.
  3. Click browse (...) next to the File text box to locate and select a certificate (.cer) file. The selected client certificate is listed in the File text box.
  4. Add a certificate file to the list of certificates by clicking the + button. Multiple certificates can be defined. Certificates can be removed by clicking the - button.
  5. Click OK.
Once client certificates have been added, the ClientCertificates property description is updated with the number of assigned certificates.

Generated Code

The following code is generated for the test framework and standalone code:
mWebProxy1 = new TestWebProxies.Service1();
mWebProxy1.ClientCertificates.Add(System.Security.Cryptography.X509Certificates.
X509Certificate.CreateFromCertFile("C:\\TestX509.cer"));
When exporting to a native BDL script, the following comment appears:
// You have to add the following certificate(s) to your profile!
// C:\TestX509.cer
Parent topic: Setting Up .NET Explorer Projects


Test Case Characteristics

Following is an overview of the characteristics of test cases as they relate to .NET Explorer:
  • Each test scenario includes an Init test case and an End test case. Multiple Main test cases may also be defined. An Init test case is the first test case that is called during a test run. Init test cases often include method calls that are related to initialization, logging in, or start-up. An End test case is the last test case that is called during a test run. End test cases often include method calls that are related to clean-up, for example logging off.
  • Main test cases are executed between Init and End test cases and may include any sort of method call.
  • A local variable is only valid within a single test case and cannot be passed to another test case. Only global variables can be used to pass values between test cases.
  • Each test case must have a unique name.
  • Test case properties can be edited by selecting a test case in the Test Scenario menu tree and defining field values in the Output Data Properties field:
    • StopAtError is the attribute that defines the number of errors that can occur during an animated run. If this number is reached, the animated run aborts. Setting this attribute to 0 specifies that errors will be ignored.
    • CallCount is the attribute that defines the number of times that a test case will be called during an animated run.
  • You can create, copy, and remove test cases by right-clicking a test case in the Test Scenario menu tree and selecting the respective menu item.
Parent topic: Setting Up .NET Explorer Projects


Setting Up Tests

This section explains how to set up and customize your tests with .NET Explorer. Topics include an introduction to GUI elements, customization of input parameters, definition of output value verifications, and generation of random variables. The section concludes with an explanation of how to use .NET Explorer to test .NET Remoting.

  • Customizing Input Parameters
    Explains how to customize method parameters using the Input Value Wizard.
  • Storing Output Values in Variables
  • Defining Global Variables
    Explains how to create a global variable to be used as an input parameter. Also explains how to initialize parameters from a data file.
  • Defining Output Value Verifications
    Explains that once you have stored an output parameter value in a variable you can specify a verification rule for the variable.
  • Adding Method Calls
    Explains how to invoke a method and add it to the currently selected test case.
  • Updating Method Calls
    Explains how to update a method that has already been added to a test case.
  • Complex Input/Output Data
    Explains that .NET Explorer supports complex data types such as arrays and objects as both input data and output data.
  • Testing .NET Remoting
    Explains that .NET Explorer supports both Client Activated Objects (CAO) remote objects and Server Activated Objects (SAO) remote objects.
  • Negative Testing
    Explains that negative testing is testing in which test methods are designed to throw exceptions. Such methods are only considered successfully executed when the anticipated exception type is thrown.
Parent topic: .NET Explorer Help


Customizing Input Parameters

When a method has input headers or parameters, its values are displayed in the Input Data pane with their default values. Select the method you want to invoke in the Loaded Components pane. Parameters are displayed with their default values in the Input Data pane, and you can configure the option settings through Tools > Options .

To change a value, select a parameter. If a parameter is a simple data type, which means a string, float, or integer, you can enter the value directly into the InputValue text box in the Input Data Properties pane. If the parameter is a complex type, which means an object or array, or you want to use a random value or a value from a stored variable, click (...) to open the Input Value Wizard.

  1. Select an InputValue row in the Input Data Properties pane to display the Input Value Wizard (...) button.
  2. Click (...). The Input Value Wizard opens.
  3. Define the input value for the parameter of the method. You can pass a null value, a value from a variable, or a constant value.
    • Click Is Null to pass a null value. This value is only valid for strings, objects, and arrays.
    • If you have already stored a variable that holds values of the parameter’s type, click Use Variable and select the variable from the list box.

      If the parameter is an array, type the index into the Index Array text box.

    • If the parameter is not an object or array, you can specify a constant value such as a string, integer, or double value. Click the Constant value option button.
    • If you do not want to use a constant value and would rather use a random value for types such as string, integer, or float, you can create a new random value by clicking New random variable. If a random value of the parameter type has already been created, click Random variable and select the variable from the list box.
  4. Click OK.
Once input parameters have been defined, you can invoke a method to have that method automatically added it to the selected test case in the Test Scenario pane. From there, corresponding output values can either be stored as variables or verifications can be set up for them.
Parent topic: Setting Up Tests
Related concepts
Creating Parameters with the Parameter Wizard
Complex Input/Output Data


Storing Output Values in Variables

Using the Output Data and Output Data Properties panes, you can store output values as variables for later use or you can define verifications for the values.

  1. Invoke a method by clicking Invoke on the Workflow bar (or by right-clicking a method in the Input Data pane and selecting Invoke/Add to Test Case) and explore the output data.
  2. Select an output value node in the Output Data pane. You can store such values in variables that can be used as input values for other method calls.
  3. Select an OutputValue row in the Output Data Properties pane to display the (...) button. Click (...) to invoke the Output Value Wizard and store the value.
    Note: The Output Value Wizard can also be launched by clicking Customize on the Workflow bar, or by right-clicking an output parameter in the Output Data pane.
  4. In the Output Value Wizard, type a name for the output value variable in the Variable name text box.
  5. Define the scope of the variable. The default is Local, which means that the variable can only be used within the test case within which it has been created. Global scope means that the variable can be used within any test case. Global scope enables you to pass information between test cases.
  6. Click OK. Verifications can be executed against variables. The Verification Wizard dialog box offers two text boxes for this purpose: Variable and Array Index (which defines the array index when a variable is an array).
Parent topic: Setting Up Tests
Related concepts
Verifications


Defining Global Variables

Global variables can be shared between test cases. These vary from local variables, which are only available to specific test cases.

Global variables can be used as input parameters for function calls and can also be used to store return values. Global variables are configured with an initial value, which makes them useful when you need to have the same value used for multiple function calls. Each time a test run begins, global variables are initialized with the defined initial value. The initial value can be changed if the variable is used to store result values.

When exporting global variables to Silk Performer, the global attribute can be retained as a Silk Performer project attribute, enabling you to also configure the initial values of global variables. To be able to modify the project attribute value in Silk Performer, you must set the UseAttribute value of the External Access property in the Input Data Properties pane to True before exporting the project.

Note: Global variables of type string and byte[] can be initialized from data files (.txt files). This is useful when a lot of content must be passed to a method call. Rather than manually typing the content into the edit control, you can initialize a variable from a specified file. The From File text box is only enabled when the variable type is System.String or System.Byte[].
  1. Select the Objects tab. Right-click an object in the Objects tree menu and select New Global Variable. The Global Variable dialog box displays.
  2. Type a name for the variable in the Variable Name text box.
  3. Select a Variable type. The following types are available:
    • string
    • integer
    • boolean
    • double
    • single
    • byte
    • byte array
    • date/time
  4. Each variable has an initial value and a current value. When tests are run, all global variables are initialized to their initial values. Specify an intial value for the variable in the Initialize Value text box. You can also take the initial value from a file by clicking the from File option button and then specifying the file location by clicking (...).
  5. Click OK.
Parent topic: Setting Up Tests


Defining Output Value Verifications

  1. Select Verification in the Output Data Properties pane to display the (...) button.
  2. Click (...) to open the Verification Wizard.
    • Select No Verification if you do not want the value to be verified.
    • Select NULL verification to verify that the value is either null, by checking the Should be null check box, or not null. This option verifies whether or not a value is present.
    • Select Constant string to verify that the value exactly matches a constant string.
    • Select Reg. expression to verify a string value.
    • Select Range if you are verifying integers or doubles. Then specify a range for the value using the From and To text boxes.
    • Select Variable to verify that the value exactly matches the value of the variable. If the variable is an array you can also define the Array index for the element that should be used for the verification.
  3. Select the Severity of error that should be thrown if the verification fails. The following severity options are available:
    Severity Option
    Description
    Success, no error
    No error is thrown.
    Informational
    An informational message is logged.
    Warning
    A warning is thrown.
    Error, simulation continues
    An error is thrown, but the simulation continues.
    Error, the active test case is aborted
    An error is thrown, the simulation continues, however the active test case is aborted.
    Error, the simulation is aborted
    An error is thrown and the simulation is aborted.
    Custom
    A section is inserted into the .NET code where special error handling code can be inserted.
  4. Click OK.
Parent topic: Setting Up Tests


Adding Method Calls

  1. Within the Loaded Components or Method Call pane, select the method to be added.
  2. Invoke the method by clicking Invoke. The invoked method is added automatically to the currently selected test case.
Parent topic: Setting Up Tests


Updating Method Calls

  1. From the Test Scenario pane, select the method that is to be changed.
  2. Make modifications to the input/output parameters of the method in the Input Data or Output Data panes. Updates are automatically accepted when you exit the Input Data or Output Data panes.
Parent topic: Setting Up Tests


Complex Input/Output Data

.NET Explorer supports complex data types such as arrays and objects as both input data and output data. The Output Value Wizard assists you in using such data as variables.

  • Storing Array or Object Output Data as Variable
    Explains that when a method returns an array or an object as output data, you can store the value in a variable of either local or global scope.
  • Taking Array Object Data From a Variable
    Explains that when using an array from a variable as input data, the entire array can be taken from the variable.
  • Defining Each Member of a Variable Individually
    When using an object as input data, you can take the entire object from a variable or define each member individually.
  • Defining Array Elements
    Explains that when a method requires an array as an input parameter, you can define the number of array elements.
  • Defining a Column-Bound Variable
    Explains that in addition to standard random variables, random values bound to multi-column data files can also be defined.
Parent topic: Setting Up Tests


Storing Array or Object Output Data as Variable

  1. Select the complex output parameter in the Output Data pane.
  2. Click (...) to open the Output Value Wizard.
  3. Specify the variable’s name and scope.
Parent topic: Complex Input/Output Data
Related tasks
Storing Output Values in Variables


Taking Array Object Data From a Variable

  1. Select a complex input parameter in the Input Data pane.
  2. Click (...) to open the Input Value Wizard.
  3. Define the input value.
Parent topic: Complex Input/Output Data


Defining Each Member of a Variable Individually

  1. Select individual members of an object in the Input Data pane.
  2. Define input values in the InputValue text box. For example, you can specify a random value from a value list as one input value and specify a constant value as another input value.
Parent topic: Complex Input/Output Data
Parent topic: Complex Input/Output Data
Related tasks
Customizing Input Parameters
Customizing Input Parameters


Defining Array Elements

  1. The default length for arrays is 1. To change the number of elements in an array, select the array node in the Input Data pane.
  2. In the Length text box, enter the number of elements in the array. .NET Explorer than automatically adds or removes the required elements.
  3. To specify an element’s value, select the element in the array and specify the value in the InputValue text box.
  4. Array members or an entire array can be assigned input parameters from a variable. To specify input parameters from a variable, click (...) to open the Input Value Wizard.
  5. Click Use variable on the Input Value Wizard and select a preconfigured variable from the list box. All variables of the current parameter type are listed.
  6. Click OK.
Parent topic: Complex Input/Output Data


Defining a Column-Bound Variable

  1. Right-click the Global Random Variables tree menu node (Loaded Components pane, Objects tab) and select New Multi-Column Variable.
  2. On the Multi Column Parameter Wizard, select a file that contains multi-column data. The files that are displayed in the combo box control are the CSV files that are available in the Data directory.
  3. When a CSV file uses a specific column separator, select the Separator so that .NET Explorer can accurately populate the grid displaying the contents of the file.
  4. Specify a name for the Handle name variable. A file handle variable is a handle that is assigned a row in a multi-column file.
  5. Select the column that should be bound to the new variable by clicking within one of the column’s cells. The currently selected column is marked with an (*) at the end of the column name. Handle name and Parameter name are automatically generated when you change the file or select a different column if the user has not already changed the name manually.
  6. Specify a File name for the new bound variable.
  7. Click Finish to open the CSV file in the registered client application (for example, Microsoft Excel). Changing the file in the client application and re-selecting it in the combo box will reload the file with the revised content.
You will see the new file handle and the new column variable in the Global Random Variables tree menu node. To bind another variable to another column in the file, right-click another file handle element in the tree menu and select New Multi-Column Variable. The wizard will reappear with read-only file properties (File name, Handle name, and Separator).

These variables can now be used as input parameters for method calls. They will appear in the Input Parameter page variable list.

  • Defining How Column Variables are Bound
    Explains how to change the sequence or row access and define the test case in which each new row should be selected.
Parent topic: Complex Input/Output Data
Related tasks
Inserting Parameters with Values from Multi-Column Data Files


Defining How Column Variables are Bound

Before proceeding with this task you must have defined a column-bound variable.

  1. Double-click a multi-column file handle in the Global Random Variables tree menu node (Loaded Components pane, Objects tab). The Input Data Properties table allows you to change the sequence of row access and the amount of time that passes before each subsequent row is selected. When a new row is selected, the bound column variables are set to the values defined in the file.
  2. Specify if rows should be selected randomly or sequentially by selecting an option from the RowSelection list box.
  3. Click within the InitTestCase list box and select the test case in which each new row should be selected (for example, If you select a main test case that runs multiple times during each animated run, a new row will be accessed with each run).
Parent topic: Defining a Column-Bound Variable
Related tasks
Inserting Parameters with Values from Multi-Column Data Files


Testing .NET Remoting

.NET Explorer supports both Client Activated Objects (CAO), which are remote objects in which clients create new instances of objects on remoting servers, and Server Activated Objects (SAO), or WellKnown remote objects, in which a server offers one instance of a special type (class) and clients access the same object on the remoting server.

Both CAOs and SAOs are accessed through URLs. For CAOs, the Activation URL is the URL where a new CAO can be created, for example http://localhost. For SAOs, the URL is the location where the SAO object can be accessed, for example http://localhost/RemoteObject.rem.

CAO classes can only be derived from the base class MarshalByRefObject. SAOs can be derived from MarshalByRefObject or by implementing an interface.

To create a CAO or activated object, right-click a MarshalByRef object and select Create Remote Object. You will be prompted for the Activation URL and for the variable name that will be associated with the created object.

To call methods on a SAO or WellKnown object, simply call the method. You will then be prompted for the Activation URL.

For full details regarding .NET Remoting, refer to the MSDN Online Library at http://msdn.microsoft.com.

Parent topic: Setting Up Tests


Negative Testing

Negative testing is testing in which test methods are designed to throw exceptions. Such methods are only considered successfully executed when the anticipated exception type is thrown.

Silk Performer offers an attribute that can be applied to test methods to indicate that a specific exception type is expected. If the specified exception is not thrown during execution, then the test method fails.

The Handle Exception dialog box opens whenever a method throws an exception. The dialog box enables you to specify what to do with the method:

  • Do not add this method to the test case
  • Add to test case

    The method is added. If the method throws the exception again during the animated run, it is considered an error.

  • Add to test case and expect this exception during test run

    The method is added. If the method throws the exception again during the animated run, it is considered a success. If the exception is not thrown, it is considered an error.

Click Details to view detailed exception information. The Explorer Exception dialog box displays the thrown exception and all inner exceptions. The exception detail grid shows all properties of the exception object. Place your cursor over the value column to display a tool-tip that includes complete content. This is especially useful for the StackTrace property as it is a multi-line property.

Expected Exceptions

Each method call that is added to a test case has a property called Expected Exceptions. This property holds a list of exception types that are expected to be thrown during an animated run. If you selected Add to test case and expect this exception during test run on the Handle Exception dialog box, the thrown exception type will automatically be added to this list.

Click (...) in the Output Data Properties pane to display the Expected Exceptions dialog box. This dialog box enables you to add/remove expected exception types.

The Possible Exceptions list is populated with the system exceptions. You can enter an exception type that is not of the system types, though to proceed you must click OK on a confirmation dialog box informing you of potential impact.

The following code is generated for method calls when the exception SoapException is expected:

public void TestWebProxies_Service1__GetRandomNumber1() {
try {
Bdl.MeasureStart("Service1::GetRandomNumber");
              mWebProxy1.GetRandomNumber(5, 1);
              Bdl.MeasureStop("Service1::GetRandomNumber");
              Bdl.LogVerification(
               "Expected exception of the type(s): System.Web.Services.Protocols.SoapException "+
               "has not been thrown!", Bdl.Severity.SEVERITY_ERROR);
} catch (System.Web.Services.Protocols.SoapException expected_0) {
               Bdl.MeasureStop("Service1::GetRandomNumber");
              Bdl.LogException(expected_0, Bdl.Severity.SEVERITY_SUCCESS);
} catch (SilkPerformer.StopException stopExcp) {
              Bdl.MeasureStop("Service1::GetRandomNumber");
              Bdl.LogException(stopExcp);
              throw stopExcp;
} catch (System.Exception e) {
              Bdl.MeasureStop("Service1::GetRandomNumber");
              Bdl.LogException(e);
}
}

If an exception is not thrown, a verification of severity Error will be logged. The log will contain the exception types that were expected but not thrown.

Parent topic: Setting Up Tests


Animated Runs

Animated runs or test runs execute all test methods that are assigned to your test cases, with corresponding input and output data displayed in the Input Data and Output Data windows as they are submitted/received. Status symbols indicate the success/failure status of method calls after they have run.

Output of animated runs includes several logs and reports that help you to identify problems with tested components.

To configure settings for animated runs go to Tools > Options > Options tab. The following settings are available:

  • Always run Init test case
  • Always run End test case
  • Run all test cases during animated run
  • Invoke Delay (time delay between method calls, in ms)
Note: By default, there is a 2-second (2000 ms) delay between the invocation of method calls. This is because .NET Explorer is designed to test the functionality of components, but not to overtax them with excessive load. Invocation delay settings can be configured on the Options tab.
  • Executing an Animated Run
    Animated runs or test runs, execute all test methods that are assigned to your test cases, with corresponding input and output data displayed in the Input Data and Output Data windows as they are submitted/received.
  • Viewing Status of Animated Runs
    Explains that depending on the number of times a test case is called (CallCount property) you can see which iteration is currently executing in the Test Scenario window. You can also see the status of each test case and method.
Parent topic: .NET Explorer Help


Executing an Animated Run

  1. Click Run Test. The Animated Run dialog box displays.
  2. Select the test cases that are to be executed during the test run (InitTestCase, TestCase, or EndTestCase). The default selections vary based on your option settings.
    Note: When test cases depend on each other for accessing global objects, ensure that you do not exclude test cases that define objects that are used by other test cases.
  3. Check the Do verifications check box to specify that verifications that have been defined for output parameters should be performed.
  4. Click OK to begin the animated run. All global variables are initialized to their initial values. All random variables are reset.

    If you have specified a different calling count for your test cases than the default (1), the test cases will be executed the number of times defined in this property.

    If the number of method calls reporting an error exceeds the number of allowed errors defined in the test case properties, the test case will be aborted.

    Note: Animated runs can be aborted manually by either hitting Esc on your keyboard or by selecting Stop Run from the Run menu. Animated runs are aborted automatically when a verification with severity Error, the simulation is aborted fails.
Parent topic: Animated Runs


Viewing Status of Animated Runs

Depending on the number of times a test case is called (CallCount property) you can see which iteration is currently executing in the Test Scenario window. Each test case and test method has one of the following status icons:

  • OK - Green checkmark
  • Verified - Blue V icon
  • Warning - Yellow triangle with exclamation mark
  • Error - Red X

Methods that fail due to thrown exceptions or failed verifications display failed or warning method call icons next to them. If a method call fails you can view a description of the failure by holding your cursor over the method.

Parent topic: Animated Runs


Analyzing Results

.NET Explorer enables developers and testers to explore the TCP/HTTP network traffic that is sent and received with each Web Service and .NET Remoting call.

Once you have completed a test run, you can view four files to assist you in analyzing test results:

  • User report - View the user report generated during the last animated run. The report contains statistical information about each test case and each test method call.
  • TrueLog for Web Service calls - View the TrueLog generated during the last animated run. The TrueLog contains detailed information about Web Service calls.
  • Error report - View the error report generated during the last animated run. The report contains a description for every error that occurred.
  • Animated log - This file contains information about every method that has been called with their parameters and errors that occurred.
  • Viewing Result Files
    Explains how to open the Explore Results dialog box and select a result type.
  • User Report
    Explains that the user report offers information regarding time elapsed for each test case and test-method call.
  • TrueLog for Web Service Calls
    Explains that when testing Web Services, TrueLogs that contain HTTP traffic for each tested Web Service method are generated.
  • Error Report
    Explains that the error report delivers an overview of all errors that occur during test runs.
  • Animated Log
    Explains that the animated log on the Output tab displays real-time information about the methods that were called in the most recent test run.
  • Analyzing Request/Response Network Traffic
    Explains that .NET Explorer enables developers and testers to explore the TCP/HTTP network traffic that is sent and received with each Web service and .NET Remoting call.
Parent topic: .NET Explorer Help


Viewing Result Files

Before proceeding with this task you must execute a test.

  1. Click Results on the Workflow bar to display the Explore Results dialog box.
  2. Select the result type you want to generate. Alternately, result files can be selected from the .NET Explorer Results menu.
Parent topic: Analyzing Results


User Report

The user report is based on the Silk Performer virtual user report. This report offers information regarding time elapsed for each test case and test-method call.

User reports are comprised of four sections:

  • Test case summary
  • Test case details
  • Test method summary
  • Errors

The Test case summary section offers information about the number of executed test cases and the number of errors that occurred during the test run.

The Test case details table gives you information about each test case:

  • Number of executions per test case
  • Execution time of each test case

The Test method summary table offers information about each test method that has been called. You receive information about execution times, number of errors that occurred, and when testing Web Services or .NET Remoting, the number of bytes that were transmitted.

The Errors table gives you information about each error that occurred during the test run. You receive information regarding when each error occurred, which test methods caused the errors, and short descriptions of the errors.

Parent topic: Analyzing Results


TrueLog for Web Service Calls

When testing Web Services, TrueLogs that contain all HTTP traffic for each tested Web Service method are generated.

For each Web Service call there is a TrueLog node that contains request and response HTTP header and body information. The TrueLog contains a transaction node for each test case and a Web document node for each Web Service / .NET Remoting request.

Parent topic: Analyzing Results
Related concepts
TrueLog Overview


Error Report

The error report delivers an overview of all errors that occur during test runs. They include details regarding error time, in which test case and which test method each error occurred, severity types, and error messages.

Parent topic: Analyzing Results


Animated Log

The animated log on the Output tab displays real-time information about the methods that were called in the most recent test run. Additional information about passed parameters is also included. When exceptions are encountered, the animated log offers detailed stack traces for the exceptions.

The animated log can be accessed at any time by selecting the Output tab.

Parent topic: Analyzing Results


Analyzing Request/Response Network Traffic

.NET Explorer enables developers and testers to explore the TCP/HTTP network traffic that is sent and received with each Web service and .NET Remoting call. Such information can be helpful to developers in seeing how large objects are serialized in XML when they are sent. It is also helpful to testers in load-testing scenarios.

With Web service calls, which are generally XML over HTTP, the actual content of HTTP headers from the requests and responses is displayed.

  1. Right-click an invoked Web service call or .NET Remoting method in the Input Data, Output Data, or Test Scenario pane and select Show Traffic. The Request/Response data of method call dialog box opens. Alternative: Select a method call and click Net Traffic on the Workflow bar. The upper left pane of the dialog box shows you the request header information of the call. The upper-right pane shows the reponse header information of the call. The lower-left window shows the request body, which is a SOAP envelope in the case of Web service calls. The lower-right pane displays the response body, which is also a SOAP envelope in the case of Web service calls.
  2. Select view tabs to view data in the request body and response body panes:

    • Hex View - Displays traffic data in binary (hexadecimal) view. This is useful when exploring the .NET Remoting binary protocol.

    • XML View - Displays SOAP traffic in an XML tree view. This view makes it easier to analyze the XML content of SOAP messages.
    • Text - Displays traffic data in a textual representation without formatting.
  3. Click OK.
Parent topic: Analyzing Results


Configuring Option Settings

Several application setting options are available in .NET Explorer:

  • Default values
  • Code
  • Verifications
  • Animated runs
  • Loaded file drop list
  • Default proxy connection
  • Configuring Project-Wide Default Values
    You can define the default values that are available for each data type across your .NET Explorer project.
  • Application Settings
    Explains that the Microsoft .NET Framework allows you to specify settings in an application-specific configuration file.
  • Code Settings
    Explains that multiple options are available for defining the behavior of code when working with .NET Explorer.
  • Verification Settings
    Explains the setting options that are available for verifications.
  • Animated Run Settings
    Explains the setting options that are available for animated runs.
  • Editing the Loaded File Drop List
    Explains how to edit the list of files that is available from the WSDL/DLL list box.
  • Configuring Proxy Connection Settings
    Explains how to configure a default proxy connection to be used when loading WSDL documents and Web Service calls.
Parent topic: .NET Explorer Help


Configuring Project-Wide Default Values

The Default Values options tab enables you to change the default input parameter values for method calls. You can set default values for the following value types:

  • Boolean
  • Double
  • Integer
  • String

Boolean can either be True or False. The other data type values must be selected from available variables, random variables, or constant values.

  1. Navigate to Tools > Options . The Default Values tab of the Options dialog box opens by default.
  2. Select a default value row to display that data type's browse (...) button.
  3. For Boolean, select either True or False from the list box. For all other value types, click (...) to launch the Input Value Wizard.
  4. Click OK.
Parent topic: Configuring Option Settings


Application Settings

The Microsoft .NET Framework allows you to specify settings in an application-specific configuration file. The configuration file must have the same name as the application and carry the .config extension (for example, myapplication.exe.config). For ASP.NET Web applications, the extension is web.config.

The configuration file is an XML file with the following schema:

<configuration>
  <startup />
  <runtime />
  <appSettings>
    <add key=”mykey” value=”myvalue />
  </appSettings>
  <system.runtime.remoting />
  …
</configuration>

When such a file is present, the .NET runtime reads the settings and configures the internal runtime. With the key appSettings you can specify key/value pairs that can be read during runtime. A useful application for this is connection strings or other configuration properties. By changing the settings in the XML file, the behavior of the application can be adjusted without changing the code.

The App Settings options tab facilitates the testing of .NET components by enabling you to specify key/value pairs. The option page not only allows you to define settings, it also enables you to initialize settings from an existing .config file. This saves time when you already have a .config file that contains all settings and meaningful values.

You can browse (...) to and Load a .config file, in which case all appSettings are used to initialize the grid control, or you can add the entries manually. Changes take effect when you click OK.

When a project is exported as a standalone application, an app.exe.config file that includes the appSettings is exported.

When exporting to either a Microsoft Visual Studio project or a Silk Performer .NET project, a app.config file with only the appsettings entries is created. The app.config file is read by the perfrun when a virtual user is executed. Perfrun takes those settings and uses them to write a perfrun.exe.config file, which contains other settings as well.

Parent topic: Configuring Option Settings


Code Settings

Multiple options are available for defining the behavior of code when working with .NET Explorer. These settings are available on the Options dialog box, Code tab.

.NET Code Generation

These project-level options define the behavior of .NET code generation in .NET Explorer:

  • Try-Catch block in every method - A try-catch block is scripted in each test method. Caught exceptions are forwarded to Silk Performer .NET Framework. It is recommended that you select this option.
  • Verifications - Verifications will be scripted in test methods. It is recommended that you select this option to make use of verification settings.
  • Test logic in BDL - Each test method call becomes a TestMethod in the Silk Performer .NET Framework and therefore becomes a separate method call in the resulting BDL script. It is recommended that you not select this option because test logic should remain in test case methods in the .NET Code.
  • Language - Select your preferred .NET language for code generation.

Source View

These user-level options define the behavior of the .NET Explorer source tree menu:

  • Show primitive types as objects - Primitive (simple) types that are stored in global variables are normally displayed as variables, not as objects. When this option is selected, types such as int and string are displayed as objects and you are able to call the methods that are defined for those types, for example String.Compare.
  • Show base type information - When this option is selected, members of the base types of displayed objects are displayed. Otherwise only the members that are declared by the object types themselves are displayed.
  • Use namespaces - When selected, the full namespace names of loaded classes are displayed in the class tree.
  • Switch to object view when storing a variable
Parent topic: Configuring Option Settings


Verification Settings

Setting options for verifications are available on the Options dialog box, Options tab.

  • Automatically define a verification for stored values - When selected, default verifications are defined whenever you store an output value in a variable.
  • Ignore case (default value) - This is the default value of the Ignore Case check box when verifying a string value in the Verification Wizard.
  • Check verifications during animated run - This is the default value for the Do Verifications check box on the Selecting Test Cases dialog box.
Parent topic: Configuring Option Settings


Animated Run Settings

Setting options for animated runs are available on the Options dialog box, Options tab.

  • Always run init test case - The init test case is checked by default on the Selecting Test Cases dialog box.
  • Always run end test case - The end test case is checked by default on the Selecting Test Cases dialog box.
  • Run all test cases during animated run - All test cases are checked by default on the Selecting Test Cases dialog box.
  • Invoke delay - Defines the delay between the invokation of method calls in animated runs. The lower the setting, the more frequently methods are called and consequently more load is placed on execution servers.
Parent topic: Configuring Option Settings


Editing the Loaded File Drop List

  1. Navigate to Tools > Options . The Options dialog box displays.
  2. Click the Layout tab. The Load file entries text box lists all recently loaded WSDL and DLL files.
  3. Select a file entry and click Delete (X) to remove it from the WSDL/DLL list box.
  4. Click Yes on the confirmation dialog box.
  5. Click OK.
Parent topic: Configuring Option Settings


Configuring Proxy Connection Settings

  1. Navigate to Tools > Options . The Options dialog box displays.
  2. Click the Connection tab.
  3. Type the Address of the default proxy server.
  4. Type the Port number of the default proxy server.
  5. Type the User who has access to the default proxy server.
  6. Type the user password into the Password text box.
  7. Click OK.
Parent topic: Configuring Option Settings


Exporting Projects

.NET Explorer enables you to export projects to Silk Performer and Microsoft Visual Studio.

Exporting to Silk Performer from .NET Explorer is helpful for QA personnel who are proficient with Silk Performer in facilitating analysis of .NET components and want to create Silk Performer projects, test case specifications, and scripts from which load tests can be run.

Exporting to Microsoft Visual Studio from .NET Explorer is helpful for developers who want to use .NET Explorer to quickly generate basic test scripts that can be modified in Microsoft Visual Studio.

When a developer opens an exported .NET Explorer project in Visual Studio, the virtual user classes, test methods, and all code are generated automatically. From here a developer can add more methods, perform modifications, or execute Try Script runs to confirm the accuracy of scripts. Once a script is ready, it can be passed along to QA in BDL form for use in Silk Performer.

The other approach available to developers is to export projects directly to Silk Performer as .NET projects.

  • Exporting a .NET Explorer Project
    Export a .NET Explorer project to create Silk Performer projects, test case specifications, and scripts.
  • Exporting a Project to Silk Performer
    Explains that two options are available for exporting Silk Performer projects: Web projects and .NET projects.
  • Exporting a Project to Microsoft Visual Studio
    Describes how you can export a project to Microsoft Visual Studio to run tests.
  • Exporting a BDL Script
    .NET Explorer enables you to export test scenarios in BDL format independent of project files, assemblies, and source files.
  • Exporting a Standalone Console Application
    .NET Explorer can compile test cases into standalone console applications that call all test case methods in their main methods.
Parent topic: .NET Explorer Help


Exporting a .NET Explorer Project

  1. Open the .NET Explorer Export menu and select the required export type:
    • Silk Performer Web project
    • Silk Performer .NET project
    The Export Project dialog box opens.
  2. Type a Project name, Project description, and destination Directory for the exported file. By default, projects are saved to <my documents>\Silk Performer 21.0\Projects.
  3. Optionally check the Open exported project after export check box.
  4. Click OK.

If you will be calling a Web service on the Internet, be sure to set the correct proxy in your Silk Performer project settings.

Parent topic: Exporting Projects


Exporting a Project to Silk Performer

Two options are available for exporting projects to Silk Performer:

Silk Performer Web Projects

When testing Web Services, .NET Explorer enables you to export Silk Performer Web projects with native BDL scripts (no .NET code is included) that include WebPagePost statements for each Web service call, enabling you to run tests in Silk Performer to test the Web services while making use of the powerful Silk Performer Web engine and features such as TrueLog, statistical reporting, modem simulation, and IP spoofing. All random variables, output variables, and verifications are included in exported scripts.

Note: .NET Framework is not required.
  • Silk Performer project file
  • BDL Web script
  • Random files

Silk Performer .NET Projects

Your test scenario can be compiled into a .NET assembly that uses the Silk Performer .NET Framework. Silk Performer .NET projects are then created with the compiled assembly and a BDF file that contains the calls to the assembly. In other words, .NET test code is compiled into a .NET intermediate language and then executed through Silk Performer. The value of this is that you can utilize Silk Performer runtime and scripting to make Web calls even though you are running .NET code and not a Web script.

Note: Microsoft Visual Studio is not required.

With this intermediate code, when a test case contains Web service calls, the calls are routed over the Silk Performer Web engine so that you can obtain detailed information about each Web service call and make use of features such as TrueLog, statistical reporting, modem simulation, and IP spoofing.

  • Silk Performer project file
  • BDL .NET script
  • Random files
  • Referenced assemblies
Parent topic: Exporting Projects


Exporting a Project to Microsoft Visual Studio

Test scenarios can be exported to C# or VB.NET files and then added to newly created Silk Performer .NET projects, which can subsequently be used in Microsoft Visual Studio to run tests. Further code customization in Visual Studio is also possible.

When you export a test scenario to a Silk Performer Microsoft Visual Studio project, .NET Explorer creates a Silk Performer .NET project and a corresponding Microsoft Visual Studio project. The test code that you define in your test scenario is added to your project and you can continue to work in Microsoft Visual Studio to make changes to the script. The exported test code makes use of the Silk Performer .NET Framework.

Once you have finished modifying test code, you can either continue to work in Silk Performer or you can run a test from within Microsoft Visual Studio.

When a test case contains Web service calls, the calls are routed over the Silk Performer Web engine so that you can obtain detailed information about each Web service call and make use of features such as modem simulation and IP spoofing.

  • Silk Performer .NET project
  • Visual Studio project (C# or VB)
  • Source files (test driver and proxies for Web services)
Parent topic: Exporting Projects


Exporting a BDL Script

  1. Open the .NET Explorer Export menu and select the required export type (BDL Web script or BDL .NET Framework script).
  2. On the Save as dialog box, type a name and destination for the exported BDF file. By default, projects are saved to the Silk Performer Projects directory at <my documents>\Silk Performer 21.0\Projects.
Parent topic: Exporting Projects


Exporting a Standalone Console Application

.NET Explorer can compile test cases into standalone console applications that call all test case methods in their main methods.

Console applications can be used to either run test scenarios independently of .NET Explorer, or to generate network traffic that can be recorded by Silk Performer. Silk Performer can consequently generate Web BDL scripts based on the network traffic.

  1. Open the .NET Explorer Export menu and select Standalone Console Application.
  2. On the Export Standalone Console Application to File dialog box specify a name and destination for the exported EXE file. By default, projects are saved to the Silk Performer project's Projects directory at <my documents>\Silk Performer 21.0\Projects.
  • Recording a Console Application With Silk Performer
    By recording a console application you get a Web BDL script that contains all the HTTP/TCP calls to a Web Service or .NET Remoting component.
Parent topic: Exporting Projects


Recording a Console Application With Silk Performer

  1. Launch Silk Performer and create a new Web project.
  2. Create a new recording profile for the console application.
  3. Specify a name for the profile.
  4. Specify the path to the executable.
  5. Select Custom Application as the application type.
  6. Select Winsock.
  7. Begin recording the application.
After recording you have a Web BDL script that contains all the HTTP/TCP calls of the console application to a Web service or .NET Remoting component.
Parent topic: Exporting a Standalone Console Application


Command Line Execution

Overview

It makes sense to run some functions from the command line, particularly those that are run numerous times on a daily basis.

The following .NET Explorer functions can be called from the command line:

Launch .NET Explorer
As with most applications, .NET Explorer can be launched from the command line. If you installed Silk Performer in the default directory, the command is C:\Program Files\Silk\Silk Performer 21.0\netexplorer.exe.
Execute animated runs for one or all test cases
You can launch .NET Explorer and have animated runs start immediately for one or all test cases in a project using a command line parameter:
  • To execute all test cases in a project, enter for example netexplorer.exe myproject.nef * at the command line.

  • To execute only the main test case in a project, enter for example netexplorer.exe myproject.nef TMain at the command line.

Write log files

When executing projects, result files (log, html, and error) are stored in project directories (.nef file directories). These files receive the same name as the .nef file, for example myproject.err, myproject.log, and myproject.html.

To define a different base name for these files, specify the log filename as an additional parameter in the command line, for example netexplorer myproject.nef * mylogfilename.

Usage

netexplorer netfile testcase | * [output]
Parameter | Description
netfile | .NET Explorer file (.nef)
testcase | The name of the test case to execute, or * to execute all
output | The directory to write reports to. If no path information is passed, the files are written to the project directory. The following result files are written: .log, .html, and .err
Parent topic: .NET Explorer Help


.NET Framework Developer Guide

  • Tools and Samples
    Explains the tools, sample applications and test projects that Silk Performer provides for testing Java and .NET.
  • Silk Performer .NET Framework
    Silk Performer’s .NET Framework enables developers and QA personnel to coordinate their development and testing efforts while allowing them to work entirely within their specialized environments.
  • Load Testing .NET Components
    Explains how to use the Silk Performer Visual Studio .NET Add-On for the testing of .NET components and Web services.
  • Testing .NET Services
    Offers an overview of the the Silk Performer .NET Framework can route Web traffic generated by .NET components through the Silk Performer Web engine. .NET Framework and the Silk Performer .NET Add-On for Microsoft Visual Studio .NET.
Parent topic: .NET Testing Support


Load Testing .NET Components

This section explains how to use the Silk Performer Visual Studio .NET Add-On for the testing of .NET components and Web services.

  • Setting Up Silk Performer .NET Projects
    Set up a Silk Performer .NET project to generate a Microsoft Visual Studio project that supports the features offered by the Visual Studio .NET Add-On.
  • Creating a Web Service Client Proxy
    Microsoft Visual Studio includes a wizard that generates a Web Service client proxy that you can use to call Web Service methods.
  • Instantiating Client Proxy Objects
    To instantiate a client proxy object you can declare a variable of the client proxy class as a public member variable of the .NET test driver.
  • Try Script Runs From Microsoft Visual Studio
    Explains that once you have implemented your .NET test code, you can execute a Try Script run from Microsoft Visual Studio.
  • Web Service Calls
    Explains how the Silk Performer .NET Framework routes Web traffic generated by .NET components over the Silk Performer Web engine.
  • Dependencies
    Explains how to specify files for addition to your Silk Performer project’s data files section.
  • Configuring .NET Add-In Option Settings
    Option settings for the .NET Add-In enable you to configure TrueLog Explorer, virtual user output, and BDF script settings.
  • Continuing Your Work in Silk Performer
  • Custom Attributes
    Explains the VirtualUser attribute and how to apply it to clases.
Parent topic: .NET Framework Developer Guide


Creating a Web Service Client Proxy

Microsoft Visual Studio includes a wizard that generates a Web Service client proxy that you can use to call Web Service methods. The wizard is launched via Project > Add Web Reference.
  1. Type the URL of your Web Service into the top text box, for example, http://demo.borland.com/BorlandSampleService/BorlandSampleService.asmx?WSDL, and click Enter. The Add Web Reference button is enabled when the wizard loads the WSDL document from the specified URL.
  2. Click Add Web Reference. The wizard generates a proxy class in a namespace that is the reverse of the name of the Web server that hosts the service (for example, demo.host.com becomes com.host.demo).
  3. Explore objects to see which classes have been generated. Each Web Service, and all complex data types used by the Web Service methods, are represented as classes. In the generated proxy code, the proxy class takes its name from the Web Service. The namespace of the class is the reverse of the name of the Web server that hosts the service. All files that are generated by the Add Web Reference wizard are displayed on the Solution Explorer tab.
    Note: The Show All Files option must be activated to display all generated files.
Parent topic: Load Testing .NET Components


Instantiating Client Proxy Objects

To instantiate a client proxy object you can declare a variable of the client proxy class as a public member variable of the .NET test driver. The variable should be instantiated either in the constructor or in the Init transaction. The first part of the namespace where the proxy class is generated is the name of your project, as this is the default namespace.
  1. Once you have instantiated a proxy class object, make calls to the service by inserting Web Service invocation code into a main transaction. Call the Web Service methods using simple parameters.
  2. Use MeasureStart and MeasureStop to measure the time required for the methods to execute.
  3. Print the result of the echoString method.
You can also call a Web Service method that takes an object as a parameter. To do this, instantiate the object, set the member values, and pass the object to the Web Service.
Note: You can catch exceptions and log them in the TrueLog.
Parent topic: Load Testing .NET Components


Try Script Runs From Microsoft Visual Studio

Once you have implemented your .NET test code, you can execute a Try Script run from Microsoft Visual Studio by calling Run > Try Script from the Silk Performer menu. Try Script runs are trial test runs that you can use to evaluate if your tests have been set up correctly.

The steps that are then performed by the Add-In are as follows:

  • The .NET code is compiled into a .NET assembly.
  • A BDF script is generated based on the meta information of the custom attributes and the settings in the Options dialog box.
  • The most recent BDF script is overwritten if there have been changes to the meta data of your assembly (for example, changed custom attributes, method order, or generation options).
  • If the meta data has changed, but you have altered the latest BDF file manually, you will be prompted to confirm that you want to have the file overwritten. This detection is achieved by comparing the last modified date of the BDF file with the timestamp scripted in the BDF file.
  • If you have multiple virtual user classes (classes that have the VirtualUser attribute applied) you will be prompted to specify which of the users is to be started.
  • Executing a Try Script Run
Parent topic: Load Testing .NET Components


Executing a Try Script Run

  1. Select Run > Try Script from the Silk Performer menu.
    Note: If you are accessing a Web Service on the Internet, ensure that you have configured proxy settings for the active profile.
  2. If you have multiple virtual user classes, select the virtual user that you want to execute from the Select Virtual User dialog box.
    Note: If there are multiple test classes, you must select the test class that you want to execute.
  3. Click Run to begin the test.
    Note: If the Automatic Start when running a Try Script option has been selected in Silk Performer options, TrueLog Explorer will launch showing the TrueLog that was generated by the test.
    Virtual user return-value output can be viewed in the Virtual User output tool window within Microsoft Visual Studio via the Bdl.Print method. The output window can be docked to other windows. Test controller output is displayed in a separate pane of the output tool window.
    Note: WebDotNetRequest entries are Web Service calls that are routed over the Silk Performer Web engine.
    TrueLog Explorer launches automatically during Try Script runs. Each Web Service call has a node in the displayed TrueLog. The nodes in the main transaction represent the SOAP HTTP traffic that was responsible for the Web Service calls. By default, all HTTP traffic is redirected over the Silk Performer Web engine, enabling TrueLog output. You can turn off redirection or enable it for specific Web Service client proxy classes via the Silk Performer Web Settings dialog box.
  4. Using the TrueLog Explorer XML control, explore the SOAP envelope that was returned by each Web Service call.
Once the test is complete you can explore other result files (log, output, report, and error) by selecting them from the Silk Performer Results menu.
Parent topic: Try Script Runs From Microsoft Visual Studio


Web Service Calls

The Silk Performer .NET Framework can route Web traffic generated by .NET components over the Silk Performer Web engine. This means that the Silk Performer Web engine executes the actual Web requests, allowing you to see exactly what is sent over the wire. This enables you to make use of Silk Performer Web engine features such as modem simulation, IP multiplexing, network statistics, and TrueLog.

By default, all network traffic is routed over the Web engine. You can however enable routing only for specific Web Service client proxy classes. To enable this feature only for specific Web Service proxy classes, change the base class of a proxy class from SoapHttpClientProtocol to SilkPerformer.SPSoapHttpClientProtocol.

This base class exchange allows the Silk Performer .NET Framework to generate more detailed statistical information for each Web Service call. It is recommended that you enable this feature for all of your Web Service proxy classes. This can be done using Visual Studio’s Web Service dialog box, which is accessible via the Silk Performer menu.

When this feature is disabled, the .NET HTTP classes process all requests.

For each Web Service call, a node is created in the TrueLog with the SOAP envelope that was passed to the Web Service and returned to the client.

When all or some classes are instrumented by Silk Performer, the HTTP traffic responsible for Web Service calls is routed over the Silk Performer Web engine. Network traffic and statistics are then written to the TrueLog. Modem simulation and IP multiplexing are also available.

  • Routing Web Service Calls
    Configure routing settings for your Web calls and select the Web Service proxy classes that should be instrumented by Silk Performer.
Parent topic: Load Testing .NET Components


Routing Web Service Calls

  1. Open the Web Services dialog box (select Web settings from the Silk Performer menu).
  2. Select the Web Service proxy classes that should be instrumented by Silk Performer. These are the classes that will be routed over the Silk Performer Web engine. Select Instrument all HTTP/HTTPS traffic to have all calls routed or select specific proxy classes for routing.
Parent topic: Web Service Calls


Dependencies

You can specify the files upon which your .NET code depends using the Add Dependencies dialog box (select Add Dependencies from the Silk Performer menu).

The files you specify will be added to your Silk Performer project’s data files section. This ensures that those files will be available on agents when you run tests that use multiple agents. To get the path to a file you have added to the data files section, use the GetDataFilePath function of the BDL object. This function returns the absolute path to the file. If you run a Try Script on localhost, the path will be to your original file. If you run a test it will return the path in the agent’s data directory.

  • Adding Dependencies
    You can specify the files that will be added to your Silk Performer project’s data files section.
Parent topic: Load Testing .NET Components


Adding Dependencies

  1. Select Add Dependencies from the Silk Performer menu to open the Add Dependencies dialog box.
  2. Click Add file to browse to and select a file that you want to add. To remove a selected file, click Remove.
  3. Click OK to accept the dependent file list.
    Note: All files in the Silk Performer project’s data files section will be copied to the agent that executes the test. To get the full path to a file, use the Bdl.GetDataFilePath function with the filename as a parameter. This function ensures that you receive the correct path to your file, regardless of whether or not the file was executed locally or remotely.
Parent topic: Dependencies


Configuring .NET Add-In Option Settings

  1. From the Silk Performer menu, select Options to open the Options dialog box.
  2. Check the Automatic Start when running a Try Script check box to have TrueLog Explorer launch automatically and display the TrueLog of the current Try Script.
  3. In the Virtual User Output group box, define which types of information you want to have displayed in the Virtual User Output window.
    • Errors
    • Transactions
    • Functions
    • Information
    • User Data
    • All Errors of all Users
  4. In the BDL Script Generation group box, specify BDF script-generation settings.
    Option | Description
    DotNetCallMethod | When checked, MeasureStart and MeasureStop statements are scripted around each DotNetCallMethod call.
    Generate BDH for .NET Method Calls | When checked, a BDH file that contains BDL functions for each .NET call is generated. This makes the main BDF file slim as it only includes the BDL function calls in the transactions.
    Generate BDL functions for .NET Methods | When checked, a BDL function is scripted for each .NET call. The transactions then call the functions.
  5. Click OK to confirm the settings.
Parent topic: Load Testing .NET Components


Continuing Your Work in Silk Performer

Once you have finished implementing your .NET test driver you can continue running tests with Silk Performer. You can open your .NET project in Silk Performer by selecting the Open in Silk Performer command from the Silk Performer menu.

In Silk Performer, you can run tests with multiple users distributed over multiple agents. Take advantage of the Silk Performer Web engine features (modem simulation and IP-address multiplexing) by testing how Web Service calls perform when they are called over a slow modem and how the Web server performs when numerous users make simultaneous service calls.

Parent topic: Load Testing .NET Components


Attributes for Unit Test Standards

Unit-testing frameworks such as NUnit and Microsoft Unit Test Framework introduce attributes for methods that are to be called before and after test methods. These methods are called Setup/Initialize and TearDown/Cleanup.

To comply with these standards, four attributes are offered:

Attribute Class | Applicable to | Parameters | Description
VirtualUserInitialize | method |  | This method is called before a normal test method/transaction is called. It can be used for the global initialization of variables that all test methods use. Only one method with this attribute is allowed per virtual user.
VirtualUserCleanup | method |  | This method is called after each test method is called. It can be used for global clean-up. Only one method with this attribute is allowed per virtual user.
TestInitialize | method |  | This method is called before each test method/transaction. It can be used to initialize variables that are utilized by the subsequent test method.
TestCleanup | method |  | This method is called after each test method/transaction. It can be used for clean-up after a test method call
Parent topic: Custom Attributes


Negative Testing

Negative testing is testing in which test methods are designed to throw exceptions. Such methods should only be considered successful when a specific anticipated exception type is thrown.

Silk Performer offers an attribute that can be applied to test methods to indicate that a specific exception type is expected. If the specified exception is not thrown during execution, then the test method has failed.

Attribute Class | Applicable to | Parameters | Descriptions
TestException | method | - Exception type - Log text if the anticipated exception is not thrown (optional) | Test method/transactions can be declared with one or more TestException attributes. During execution, the runtime checks to see if the defined exception type was thrown. If the anticipated exception type was thrown, then the method call is considered successful. If not, the method call is considered a failure and exception details are written to the log file.
Parent topic: Custom Attributes


Testing .NET Services

This section offers an overview of the Silk Performer .NET Framework and the Silk Performer .NET Add-On for Microsoft Visual Studio .NET. It also serves as an in-depth demonstration of how to execute .NET methods with BDL, how to write complete test drivers in .NET, and how to test drivers in Visual Studio .NET. It explains how to write test code in .NET and customize test code in BDL. Because SOAP (Web services) has become widely accepted, this chapter also explores how Web services can easily be tested using Silk Performer and the .NET Framework.

  • Development Workflow
    Lines out the development workflow for .NET.
  • Writing a .NET Test Driver
    Describes how you can write a .NET test driver.
  • BDL Code Generation Engine
    Describes the BDL Code Generation Engine that generates a BDL script based on the meta data information of the compiled .NET assembly.
  • Testing Your .NET Test Driver
    Describes how you can test the .NET test driver.
  • Testing Web Services With Microsoft Visual Studio
    Explains that the Silk Performer .NET Framework and .NET add-on allow easy access to Web services from within .NET.
  • Testing with .NET Explorer
    Describes how you can use .NET Explorer to generate .NET test drivers.
  • Available BDL Functions for .NET Interoperability
    Describes the BDL functions that the Silk Performer .NET Framework and .NET add-on allow easy access to Web services from within .NET. provides for .NET interoperability.
Parent topic: .NET Framework Developer Guide
Related concepts
Silk Performer .NET Framework
Silk Performer Visual Studio Extension


Development Workflow

.NET Development Workflow
Parent topic: Testing .NET Services


Writing a .NET Test Driver

This section describes how you can write a .NET test driver.

  • Creating a .NET Project
    Describes how you can create a new .NET project.
  • Defining a Virtual User in .NET
  • Defining a Transaction in .NET
    Describes how you can define a transaction in .NET.
  • Defining Additional Test Methods
    Describes how you can define test methods in .NET.
  • Passing Data Between BDL and .NET
    Describes the two means to exchange values between the generated BDL script and the .NET test driver
  • Calling BDL Functions from .NET
    Describes how you can call BDL functions from .NET.
  • Random Variables
    Describes how you can define random variables for your test user.
  • Exception Handling
    Describes how the Silk Performer .NET Framework handles exceptions in your test code.
  • Debugging
    Describes a workaround to enforce debugging for TryScript runs.
  • Configuration Files
    Describes how you can handle runtime-specific configurations with .NET.
Parent topic: Testing .NET Services


Creating a .NET Project

Silk Performer ships with an add-on and a project wizard for Microsoft Visual Studio .NET. Microsoft Visual Studio .NET must be installed on your machine prior to the installation of the add-on. The project wizard creates a .NET project in one of the supported .NET languages, which are C# or VB.NET, and generates a sample test driver into which you only have to add your test code into the test methods. You can insert calls to .NET components, Web services and BDL functions, like MeasureStart, MeasureStop, and others.

This wizard can be invoked either by creating a new .NET project with Silk Performer or by creating a new Silk Performer project in Visual Studio .NET. In either case you start with a new Silk Performer .NET project in Microsoft Visual Studio .NET with the sample test code file open.

PerfDotNetFW.dll is a .NET assembly that ships with Silk Performer. It implements all classes, custom attributes, and enums that can be used to define meta information for automatic Silk Performer BDL script generation and calls BDL functions from within the .NET test driver. PerfDotNetFW.dll is discussed in great detail later in this chapter. The assembly is automatically referenced by the generated project.

Parent topic: Writing a .NET Test Driver


Defining a Virtual User in .NET

A virtual user in .NET is a public .NET class with the SilkPerformer.VirtualUser attribute applied. This attribute tells the add-on to generate a virtual user definition in the BDL script.

The VirtualUser attribute has one parameter - the name of the virtual user that is to be generated in the BDL script when running a try script.

You can have multiple VirtualUser classes in your .NET assembly but the names of the virtual users must be unique.

Defining a Virtual User in .NET

C# Code BDL Script
[VirtualUser("Vuser1")]
public class MyTestUser1
{
  ...
}
[VirtualUser("Vuser2")]
public class MyTestUser2
{
  ...
}

dcluser
  user
    Vuser1
    ...
  user
    Vuser2
Parent topic: Writing a .NET Test Driver


Defining a Transaction in .NET

A transaction in .NET is a public (non virtual) .NET method of your virtual user class that has the SilkPerformer.Transaction attribute applied to it. There are three types of transactions, init, main, and end. There can only be one init and one end transaction for each virtual user class, but there can be multiple main transaction methods.

The transaction type is passed as the first parameter. ETransactionType is an enum that defines the possible types.

SilkPerformer.ETransactionType:
  • TRANSTYPE_INIT
  • TRANSTYPE_MAIN
  • TRANSTYPE_END

Transactions of type main have an optional second parameter that defines the number of transaction calls - the default value is 1.

Example

C# Code BDL Script
[VirtualUser("Vuser1")]
public class MyTestUser1
{
  [Transaction(
    Etranstype.TRANSTYPE_INIT)]
  public void TInit()
  {
  }
  [Transaction(
    Etranstype.TRANSTYPE_MAIN)]
  public void TMain()
  {
  }
  [Transaction(
    Etranstype.TRANSTYPE_MAIN, 5)]
  public void TMain2()
  {
  }
  [Transaction(
    Etranstype.TRANSTYPE_END)]
  public void TEnd()
  {
  }
}

dcluser
  user
    Vuser1
  transactions
    TInit : begin;
    TMain : 1;
    TMain2 : 5;
    TEnd : end;

var hVuser1 : number;

dcltrans
  transaction TInit
  begin
    hVuser1:=
    DotNetLoadObject("..","MyTestUser1");
    DotNetCallMethod(hVuser1,"TInit");
  end;

  transaction TMain
  begin
    DotNetCallMethod(hVuser1,"TMain");
  end;
  transaction TMain2
  begin
    DotNetCallMethod(hVuser1,"TMain2");
  end;

  transaction TEnd
  begin
    DotNetCallMethod(hVuser1,"TEnd");
    DotNetFreeObject(hVuser1);
  end;

The add-on script generator scripts an init and an end transaction even if there are no corresponding .NET methods. These are used to load the .NET object in the init transaction and free it in the end transaction.

As you can see from the sample above, the transactions contain a DotNetCallMethod to call the .NET test driver method.

Parent topic: Writing a .NET Test Driver


Defining Additional Test Methods

A test method in .NET is a public (non virtual) method that has the SilkPerformer.TestMethod attribute applied to it. Each call to a test method is scripted as a DotNetCallMethod function in the current transaction. It's possible to have multiple test methods in a single transaction.

Defining a Test Method

C# Code BDL Script
[VirtualUser("Vuser1")]
[Transaction(Etranstype.TRANSTYPE_MAIN)]
  public void TMain()
  {
  }

  [TestMethod]
  public void Method1()
  {
  }

  [TestMethod]
  public void Method2()
  {
  }

dcluser
  transaction TMain
  begin
    DotNetCallMethod(hVuser1,"TMain");
    DotNetCallMethod(hVuser1,"Method1");
    DotNetCallMethod(hVuser1,"Method2");
  end;

The two test methods, Method1 and Method2, will be called in the current transaction. The current transaction is the transaction method that is declared previous to these test methods in the .NET code.

Parent topic: Writing a .NET Test Driver


Passing Data Between BDL and .NET

There are two means of exchanging values between the generated BDL script and the .NET test driver:
  • Attributes
  • Parameters
  • Declaring Attributes
    Explains how attributes are declared as project attributes, making them customizable without the need to change the .NET code.
  • Defining Parameters
    Describes how you can define input parameters and return values for .NET methods.
Parent topic: Writing a .NET Test Driver


Declaring Attributes

A method can have multiple SilkPerformer.TestAttribute attributes applied to it. Attributes are not scripted, but created as project attributes. This makes it easier for engineers to customize BDL scripts to change values for different attributes, as all attributes can be found in the project attributes dialog box. Therefore the .NET test driver can access attributes with Bdl.AttributeGet.

The TestAttribute attribute has two parameters. The first parameter is the name of the attribute and the second is the default value of the project attribute.

A comment is scripted prior to the function call to indicate what specific attributes the function call requires.

// Requires attribute "Attrib1" with the default value: "Value1"
DotNetCallMethod(hVuser1, "TMain");

Declaring Attributes

C# Code BDL Script
[Transaction(Etranstype.TRANSTYPE_MAIN)]
[TestAttribute("Attrib1","Value1")]
public void TMain()
{
  string s = Bdl.AttributeGet("Attrib1");
}

dcltrans
  transaction TMain
  begin
    // Requires attribute "Attrib1"
    // with the default value: "Value1"
    DotNetCallMethod(hVuser1,"TMain");
  end;

By customizing the attribute value in the project attributes dialog box, you can customize the runtime behavior of the .NET test driver without changing the .NET code.

Parent topic: Passing Data Between BDL and .NET
Related reference
Primary BDL Functions


Defining Parameters

If a method has input parameters and a return value, the Code Generation Engine appropriately creates the BDL calls for passing those parameters in and getting the return parameter. Therefore a method can have any combination of parameters and return values that can be accessed by the DotNet API functions (DotNetGetXX).

Defining Parameters

C# Code BDL Script
[Transaction(Etranstype.TRANSTYPE_MAIN)]
public string TMain(string s, int n)
{
  return s + n.ToString();
}

dcltrans
  transaction Tmain
  var
    sReturn : string;
  begin
    DotNetSetString(hVuser1,"stringvalue");
    DotNetSetInt(hVuser1, 123);
    DotNetCallMethod(hVuser1,"TMain");
    DotNetGetString(hVuser1, sReturn, sizeof(sReturn));
  end;
As you can see in the above example, DotNetSetXX functions are scripted for each method parameter. The values are default values that are suggested by the Add-On. The Code Generation Engine also scripts a DotNetGetXX function for the return value of the method. The following .NET parameter types are supported:
  • String
  • Byte
  • SByte
  • UIntPtr
  • UInt16
  • UInt32
  • UInt64
  • Int16
  • Int32
  • Int64
  • IntPtr
  • Decimal
  • Double
  • Single
  • Boolean
  • Object

Return Parameter

By default the return parameter is stored in a variable with the name xReturn, or sReturn for strings. You can give the variable a meaningful name by applying the SilkPerformer.BdlParameter attribute to your return type and passing the variable name as the first parameter (sConcatParam in the following example).

Example for Return Parameter

C# Code BDL Script
[Transaction(Etranstype.TRANSTYPE_MAIN)]
[return:BdlParameter("sConcatParam")]
public string TMain(string s, int n)
{
  return s + n.ToString();
}

dcltrans
  transaction Tmain
  var
    sConcatParam : string;
  begin
    DotNetSetString(hVuser1,"stringvalue");
    DotNetSetInt(hVuser1, 123);
    DotNetCallMethod(hVuser1,"TMain");
    DotNetGetString(hVuser1, sConcatParam,
      sizeof(sConcatParam));
  end;

The ability to define a different name for the return variable is necessary for the Code Generation Engine to generate BDL code that passes values between function calls.

Parent topic: Passing Data Between BDL and .NET


Calling BDL Functions from .NET

Most of the functions exposed by the kernel.bdh of Silk Performer are implemented in PerfDotNetFW.DLL, which is a .NET assembly that comes with Silk Performer. The methods are static methods in the SilkPerformer.Bdl class. As Silk Performer is an imported namespace you can call the methods with Bdl.<MethodName>. PerfDotNetFW.dll is referenced by default when you create a Silk Performer .NET project.

  • Primary BDL Functions
    Lists the primary functions that are implemented by the SilkPerformer.Bdl class.
  • Constant Values
    Lists the constant values that certain BDL functions take as parameters.
Parent topic: Writing a .NET Test Driver


Primary BDL Functions

The following table lists the primary functions that are implemented by the SilkPerformer.Bdl class. For a complete list of all functions, open the class in Microsoft Visual Studio .NET.
Function | Description
  • AttributeSet
  • AttributeGet
Setting and getting attribute values.
  • MeasureStart
  • MeasureStop
  • MeasurePause
  • MeasureResume
  • MeasureInc
  • MeasureIncFloat
  • MeasureGet
  • MeasureSetBound
  • MeasureTimeseries
  • MeasureOnOff
Measure functions.
  • GetUser
  • GetUserId
  • GetUserIdOnAgent
  • GetUserGroup
  • GetProfile
  • GetAgentId
  • GetRuntimes
  • GetAgent
  • GetController
  • GetProject
  • GetLoadTest
  • GetMemUsage
  • GetBdfFileName
  • GetBuildNo
Information about the current test.
Print | Printing messages to the virtual user output.
RepMessage Write a message to the following files:
  • .ERR
  • .LOG
  • .RPT
  • WriteErr
  • WriteLog
  • WriteData
  • WriteWrt
  • Write
  • Writeln
Write data to output files.
GetDataFilePath | Gets the absolute path to a file in the data files section.
RndUniN, and others | Random functions.
Parent topic: Calling BDL Functions from .NET


Constant Values

Some functions in the BDL take constant values as parameters. These constant values are defined as public enums in the SilkPerformer.Bdl namespace. The following list lists some of the defined enums:
  • PrintDisplay (OPT_DISPLAY_ERRORS, OPT_DISPLAY_TRANSACTIONS, ...)
  • PrintColor (TEXT_GRAY, TEXT_BLACK, ...)
  • Severity (SEVERITY_SUCCESS, SEVERITY_INFORMATIONAL, ...)
  • MeasureKind (MEASURE_KIND_SUM, MEASURE_KIND_COUNT, ...)
  • MeasureUsage (MEASURE_USAGE_TIMER, ...)
  • MeasureClass (MEASURE_IIOP, MEASURE_TIMER, ...)
  • ThinkTimeOption (OPT_THINKTIME_RANDOMWAIT, ...)

Example

[Transaction(EtransactionType.TRANSTYPE_MAIN)]
[TestAttribute("Attribute1", "TestValue")]
public void Tmain()
{
  string sValue = Bdl.AttributeGet("Attribute1");
  Bdl.MeasureStart("My Testmeasure");
  string sReturn = SomeMethod(sValue);
  Bdl.Print(sReturn);
  Bdl.MeasureStop("My Testmeasure");
}
Parent topic: Calling BDL Functions from .NET


Random Variables

You can define random variables for your test user that can be accessed within .NET test code. There is a wizard in Visual Studio .NET that helps you define these random variables. The wizard has the same look & feel as the random variable wizard of Silk Performer.

Depending on the type of random variable you choose, the wizard adds the appropriate random custom attribute to the virtual user class. You can use the following random custom attributes:
  • RndBin
  • RndExpF
  • RndFile
  • RndInd
  • RndPerN
  • RndSno
  • RndStr
  • RndStream
  • RndUniF
  • RndUniN

The first parameter is the name of the random variable. This is followed by the parameters that must be defined in BDL to define the random variable. For additional information, refer to the Benchmark Description Language (BDL) Reference or check Visual Studio .NET's Code Completion.

You can access random variables with the following three new functions that are declared in the BDL class as static methods:
  • GetRandomFloat
  • GetRandomNumber
  • GetRandomString
Those methods take the name of the random variable as an input parameter and then return random values.
Parent topic: Writing a .NET Test Driver
Related concepts
Benchmark Description Language (BDL) Reference


Exception Handling

The goal in exception handling is to catch all exceptions in your test code. That is why after creating a project, the default code has try/catch blocks in each test method.

The Silk Performer .NET Framework throws one exception, the SilkPerformer.StopException. The framework throws this exception when a run is aborted or stopped by the user. You can utilize this exception for clean up.

Other exceptions are handled normally. For detailed exception information in your TrueLogs, use Bdl.LogException to log exceptions, including message and stack trace, to TrueLog. This is particularly useful when running tests while TrueLog On Error is activate, because you can see which exceptions are thrown and you get a complete stack trace.

Parent topic: Writing a .NET Test Driver


Debugging

Running TryScripts in debugging mode is not directly supported from within Visual Studio .NET. We recommend an approach to enforce debugging through a work-around.

Place a System.Diagnostics.Debug.Assert (false) statement in the constructor of your test driver or at any other position in your code. Compile your code and initiate a TryScript run from Silk Performer. You can also initiate a TryScript run from Visual Studio .NET, however we do not recommend this approach, as a new instance of Microsoft Visual Studio .NET is required for debugging and the new instance will not obtain information regarding it's impact on the instance that is running the TryScript run.

If you subsequently initiate a TryScript run from Silk Performer, a debug assertion dialog box opens, allowing you to debug the code.

Parent topic: Writing a .NET Test Driver


Configuration Files

Microsoft .NET Framework allows to store a configuration file in the directory of the .NET executable or ASP.NET application that contains runtime-specific configurations. These configurations are loaded when the application is launched. For .NET executables the configuration file needs to be named with both the .exe file extension and the .config file extension. For example myprogramm.exe.config.

When running a test, the executable that hosts your .NET test driver code is perfrun.exe. Therefore it's possible to have a perfrun.exe.config that contains configuration settings that are loaded at startup. However this approach is not possible because Silk Performer generates the perfrun.exe.config file automatically before starting a test and would therefore overwrite such a configuration file. The perfrun.exe.config file contains settings based on the profile settings of the project profile.

With Silk Performer, you can have an app.config file in your project directory to specify your own configuration file settings. Silk Performer checks for this configuration file and merges the content into an automatically generated perfrun.exe.config file. To make the settings in the app.config file available to all agent machines, you need to add this file to the Data Files folder in the Project menu tree.

A perfrun.exe.config file has the following structure:
<configuration>
  <system.net>
    ...
  </system.net>
  <runtime>
    ...
  </runtime>
</configuration>

For backward compatiblity, when Silk Performer locates an app.config file, the content is added after the runtime tag. That means that your app.config file can contain any configuration nodes that are allowed below the root configuration node, except the system.net and runtime nodes, because Silk Performer generates those nodes.

With Silk Performer you can provide a fully-configured app.config file with all possible configuration sections. Silk Performer adds the necessary entries for web-traffic routing in the generated perfrun.exe.config file.

Configuring .NET Remoting Components

If you wish to configure .NET Remoting components, you need an app.config file such as the following:
<system.runtime.remoting>
  <application>
    <channels>
      <channel ref="http" port="2000" />
    </channels>
    <client url="http://remoteserver:2000">
      <activated type="RemoteDll.RemoteClass1, RemoteDll" />
      <activated type="RemoteDll.RemoteClass2, RemoteDll" />
    </client>
  </application>
</system.runtime.remoting>
Parent topic: Writing a .NET Test Driver
Related tasks
Adding Data Files


BDL Code Generation Engine

The Silk Performer .NET Add-On has a BDL Code Generation Engine that generates a BDL script based on the meta data information of the compiled .NET assembly (.NET test driver). The engine is invoked when a TryScript run is started in Microsoft Visual Studio .NET. The compiled .NET assembly is scanned for classes that have the VirtualUser attribute applied. Those classes are then scanned for methods that have either a Transaction or TestMethod attribute applied to them. The sequence of methods is important because calls to test methods, which are methods with the TestMethod attribute, are scripted in the transaction, which is a method with the Transaction attribute, that is declared prior to the test method.

  • Virtual User
    Describes how the Virtual User name is used to prevent method-name duplication.
  • Transactions - Virtual User Classes
    Describes how the virtual user class of a transaction is handled.
  • Test Methods
    Describes how the Code Generation Engine handles test methods.
  • Test Attributes
    Describes how the Code Generation Engine handles the test attributes of transactions and test methods.
  • Methods with Parameters
    Describes how the Code Generation Engine handles the input parameters and the return value of a method.
  • BDL Parameters
    Describes how you can apply a BdlParameter attribute to the return type of a method.
  • Intelligent Parameter Passing
    Describes how the Code Generation Engine passes the return value of a function to an input parameter with the same name in another function.
  • Options
    Describes the options that you can set in the Visual Studio .NET add-on to change the BDL code generation.
Parent topic: Testing .NET Services


Virtual User

The Virtual User name is used as a prefix for all transactions and methods scripted in BDL. This is necessary to prevent method-name duplication, since the same method name may exist in two different .NET classes.

The engine checks for duplicate Virtual User names. If the assembly contains more than one Virtual User class, the names passed as parameters to the VirtualUser attribute must be unique. If there are duplicate names, an error is thrown and shown in the task list.

Note: You should avoid using multiple methods with the same name in one .NET class. .NET allows using multiple methods with the same name if the methods have different parameters, but the Code Generation Engine of Silk Performer does not support this feature.
  • Random Variables - Virtual User Classes
    Describes how the virtual user class of a random variable is handled.
Parent topic: BDL Code Generation Engine


Random Variables - Virtual User Classes

The Silk Performer code-generation engine also checks the virtual user class of all defined random-variable custom attributes. For each random variable, the corresponding random-variable definition is declared in the BDL script.

Currently these variables are of no real use, neither on the BDL side or the .NET side. If you use one of the Bdl.GetRandom functions, the definition of the random variable is read from the metadata information of the .NET code, not from the BDL file. That means that if you change the random variable definition in BDL it will not have any effect on the .NET code as it still must have the definition from the custom attributes. This behavior will be adjusted in future versions so that you will be able to change settings in the BDL script and have the executing .NET code receive those random values based on the BDL settings.

Parent topic: Virtual User


Transactions - Virtual User Classes

The Code Generation Engine checks all methods that have the transaction attribute applied. There are three types of transactions, init, main, and end. A Virtual User class can only have one init and one end transaction. Even if there is no init or end transaction within the .NET code, transactions are still scripted because they are required for loading and freeing the .NET objects.

The first call in the init transaction in BDL is a DotNetLoadObject method call. After this call the actual call to the .NET method is made. Thereafter all methods with the TestMethod attribute that are defined between this transaction method and the next are called.

The last call in the end transaction in BDL is a DotNetFreeObject method call.

The main transactions call the actual transaction method in .NET and then the appropriate test method calls.

Parent topic: BDL Code Generation Engine


Test Methods

When the Code Generation Engine scans the .NET assembly and finds a method with a TestMethod attribute, the engine scripts a call to the method in the current transaction. The current transaction is the transaction method that was declared before the test method. As a result, declaring a test method without a transaction method results in an error. Declaration means that the transaction method has been declared previously in the code.

Test Method

C# Code BDL Script
[Transaction(Etranstype.TRANSTYPE_MAIN)]
public void TMain1()
{
}

[TestMethod]
public void TestMeth1()
{
}

[Transaction(Etranstype.TRANSTYPE_MAIN)]
public void TMain2()
{
}

[TestMethod]
public void TestMeth2()
{
}

[TestMethod]
public void TestMeth3()
{
}

dcltrans
  transaction TMain1
  begin
    DotNetCallMethod(hVuser1, "TMain1");
    DotNetCallMethod(hVuser1, "TestMeth1");
  end;
  transaction TMain2
  begin
    DotNetCallMethod(hVuser1, "TMain2");
    DotNetCallMethod(hVuser1, "TestMeth2");
    DotNetCallMethod(hVuser1, "TestMeth3");
  end;

Erroneous Test Method Declaration

The following test method declaration would cause an error with the Code Generation Engine as there is no current transaction for the TestMeth1 method:
[TestMethod]
public void TestMeth1()
{}

[Transaction(Etranstype.TRANSTYPE_MAIN)]
public void TMain1()
{}
Parent topic: BDL Code Generation Engine


Test Attributes

When the Code Generation Engine processes a transaction or test method it checks whether the method has TestAttribute attributes applied to it. A project attribute is generated for each test attribute. The name and default values are used to generate project attributes with the same names and default values. To make it easier for engineers who customize BDL script, comments are scripted before the DotNetCallMethod.
// Requires attribute "Attr1" with the default value: "Value1" DotNetCallMethod(hVuser1, "TMain1");
// Requires attribute "Attr2" with the default value: "Value2"
// Requires attribute "Attr3" with the default value: "Value3" DotNetCallMethod(hVuser1, "TestMeth1");

Test Attributes

C# Code BDL Script
[Transaction(Etranstype.TRANSTYPE_MAIN)]
[TestAttribute("Attr", "Value1")]
public void TMain1()
{
}

[TestMethod]
[TestAttribute("Attr2", "Value2")]
[TestAttribute("Attr3", "Value3")]
public void TestMeth1()
{
}

dcltrans
  transaction TMain1
  begin
    // Requires attribute "Attr1"
    // with the default value: "Value1"
    DotNetCallMethod(hVuser1, "TMain1");
    // Requires attribute "Attr2"
    // with the default value: "Value2"
    // Requires attribute "Attr3"
    // with the default value: "Value3"
    DotNetCallMethod(hVuser1, "TestMeth1");
  end;
Parent topic: BDL Code Generation Engine


Methods with Parameters

If a method, whether it is a transaction or a test method, has input parameters or a return value, the engine scripts DotNetSetXX functions to pass the input parameters and a DotNetGetXX function to retrieve the return value.

The following DotNetGetXX and DotNetSetXX functions are available:
  • DotNetSetString
  • DotNetSetInt
  • DotNetSetFloat
  • DotNetSetBoolean
  • DotNetSetObject
  • DotNetGetString
  • DotNetGetInt
  • DotNetGetFloat
  • DotNetGetBoolean
  • DotNetGetObject

Therefore you can exchange strings, integers, floats, Booleans, and objects. Objects are object handles to other .NET objects.

The Code Generation Engine scripts a DotNetSetXX function for each parameter in the same sequence as the parameter definition. If there is a return value, it scripts the corresponding DotNetGetXX function.

The Code Generation Engine creates appropriate values for input parameters such as 123 for the int in the example below. Silk Performer does not support arrays.

Methods with Parameters

C# Code BDL Script
[Transaction(Etranstype.TRANSTYPE_MAIN)]
public object TMain1(string s, int n)
{
}

dcltrans
  transaction TMain1
  var
    hReturn : number;
  begin
    DotNetSetString("stringvalue");
    DotNetSetInt(123);
    DotNetCallMethod(hVuser1, "TMain1");
    DotNetGetObject(hReturn);
  end;
The following .NET data types are supported:
  • String
  • Byte
  • SByte
  • UIntPtr
  • UInt16
  • UInt32
  • UInt64
  • Int16
  • Int32
  • Int64
  • IntPtr
  • Decimal
  • Double
  • Single
  • Boolean
  • Object
Parent topic: BDL Code Generation Engine


BDL Parameters

If a method, whether it is a transaction or a test method, has a return parameter, the Code Generation Engine stores the value by default in a variable with the name xResult, where x depends on the return type. To change this behavior, apply a BdlParameter attribute to the return type of the method and pass the variable name as the first parameter.

BDL Parameters

C# Code BDL Script
[Transaction(Etranstype.TRANSTYPE_MAIN)]
[return:BdlParameter("sConcatParam")]
public string TMain(string s, int n)
{
  return s + n.ToString();
}

dcltrans
  transaction Tmain
  var
    sConcatParam : string;
  begin
    DotNetSetString(hVuser1, "stringvalue");
    DotNetSetInt(hVuser1, 123);
    DotNetCallMethod(hVuser1, "TMain");
    DotNetGetString(hVuser1, sConcatParam,
      sizeof(sConcatParam));
  end;
Parent topic: BDL Code Generation Engine


Intelligent Parameter Passing

The Code Generation Engine checks methods for their return values and input parameters. If a method has an input parameter that has the same name as a previously returned value, the return value will be passed to the function. Normally return parameters do not have names assigned to them - but you can assign a name by applying a BdlParameter attribute.

As a result, you can pass values between method calls by giving the parameters and return values the same names. When you declare the parameters, ensure that you do not assign the same name to different parameter types. In Silk Performer the Code Generation Engine does not check if the return value and input parameter types are the same.

Intelligent Parameter Passing

C# Code BDL Script
[Transaction(Etranstype.TRANSTYPE_MAIN)]
[return:BdlParameter("sName")]
public string TMain()
{
  return "Andi";
}
[TestMethod]
public void Hello(string sName)
{
  Bdl.Print("Hello " + sName);
}

dcltrans
  transaction Tmain
  var sName : string;
  begin
    DotNetCallMethod(hVuser1, "TMain");
    DotNetGetString(hVuser1, sName, sizeof(sName));
    DotNetSetString(hVuser1, sName);
    DotNetCallMethod(hVuser1, "Hello");
  end;
Parent topic: BDL Code Generation Engine


Options

This section describes the options that you can set in the Options dialog box of the Visual Studio .NET add-on. These options change the BDL code generation.

  • Generating Timers for DotNetCallMethod
    If this option is enabled, the time for each method to execute becomes available in the overview report.
  • Generating BDL Functions for .NET Method Calls
    If this option is enabled, the engine scripts a BDL function for each call to a .NET method.
  • Generating BDH for .NET Method Calls
    If this option is enabled, the engine scripts a BDL function for each .NET method and stores them in a BDH file in the main BDF file.
  • Generating Project Attributes
    When this option is enabled (by default), project attributes are created for each TestAttribute custom attribute on a method.
Parent topic: BDL Code Generation Engine


Generating Timers for DotNetCallMethod

If this option is enabled, the engine scripts a MeasureStart and MeasureStop for each DotNetCallMethod that uses the name of the method. This gives you the time taken for the method to execute and the information becomes available in the overview report.

Generating Timers for DotNetCallMethod

C# Code BDL Script
[Transaction(Etranstype.TRANSTYPE_MAIN)]
public void TMain()
{
}

[TestMethod]
public void Test1()
{
}

dcltrans
  transaction Tmain
  begin
    MeasureStart("TMain");
    DotNetCallMethod(hVuser1, "TMain");
    MeasureStop("TMain");
    MeasureStart("Test1");
    DotNetCallMethod(hVuser1, "Test1");
    MeasureStop("Test1");
  end;
Parent topic: Options


Generating BDL Functions for .NET Method Calls

If this option is enabled, the engine scripts a BDL function for each call to a .NET method. The transaction calls the generated function. This makes the transactions shorter and easy to read. Input parameters to the .NET method become input parameters for the BDL function. If the .NET method returns a value, the value will be the return value of the function.

BDL Functions for .NET Method Calls

C# Code BDL Script
[Transaction(Etranstype.TRANSTYPE_MAIN)]
public void TMain()
{
}

[TestMethod]
public string Test1(int nParam)
{
}

dclfunc
  function Vuser_Tmain(hObject:number)
  begin
    DotNetCallMethod(hObject, "TMain");
  end;

  function Vuser_Test1(hObject:number;nParam:number): string;
    var sReturn : string;
  begin
    DotNetSetInt(hObject, nParam);
    DotNetCallMethod(hObject, "TMain");
    DotNetGetString(hObject, sReturn, sizeof(sReturn));
    Vuser_Test1 := sReturn;
  end;
  dcltrans
  transaction Tmain
    var sReturn : string;
  begin
    Vuser_Tmain(hVuser);
    SReturn := Vuser_Test1(hVuser, "stringparam");
  end;
Parent topic: Options


Generating BDH for .NET Method Calls

If this option is enabled, the engine scripts a BDL function for each .NET method and stores them in a BDH file in the main BDF file. This option implies the Generating BDL Functions for .NET Method Calls option.

Parent topic: Options


Generating Project Attributes

When this option is enabled (by default), project attributes are created for each TestAttribute custom attribute on a method and a comment is scripted before the DotNetCallMethod call to help engineers determine which attributes are required by which methods.

If the Generating Project Attributes option is disabled, you need to script AttributeSetString calls before the call to define the attributes and default values.

We recommend that you enable the option because you can then manage all your attributes using the project attributes dialog and you do not need to browse through the script.

Parent topic: Options


Testing Your .NET Test Driver

You can test the .NET test driver within Visual Studio .NET without even opening Silk Performer. The add-on can run a Try Script, making the results and output visible in Microsoft Visual Studio .NET. This feature enables .NET developers to concentrate on developing their .NET test drivers. They do not need Silk Performer or BDL skills because script generation is done by the add-on. QA departments can take the final versions of .NET test drivers and customize the generated scripts to their needs.

  • Preparations
    Describes what you need to do before you can test your .NET test driver.
  • Try Script Runs
    Describes how you can launch a Try Script run.
  • Exploring Results
    Describes where you can find the results of the load tests that you have performed.
  • Running Tests in Silk Performer
    Describes the tasks you can perform in Silk Performer when you have completed the implementation of the .NET test driver.
Parent topic: Testing .NET Services


Preparations

If you have created a .NET test driver, and you do not need any special data files or profile changes, you are ready to execute a TryScript run to test your .NET test driver.

  • Data Files
    Describes how you can add files in your .NET methods to the data files section of the Silk Performer project.
  • Profile and System Settings
    Describes the profile settings that are specific to .NET.
  • Web Settings
    Describes the Web settings that are specific to .NET.
  • Testing Options
    Describes the options that are relevant to running tests.
Parent topic: Testing Your .NET Test Driver
Related concepts
Writing a .NET Test Driver


Data Files

If you access any files in your .NET methods you should add those files to the data files section of the Silk Performer project. You can do this through the Add Dependencies dialog box of the Silk Performer menu. If you are running a test on a remote agent, the files will be copied to the data directory of the agent. To ensure you have the right file path to your files, use the Bdl.GetDataFilePath method. This method returns the path to each data file using the filenames as parameters.

Adding the C:\myfiles\file1.txt File to the Data Files

[Transaction(Etranstype.TRANSTYPE_MAIN)]
public void TMain()
{
  string sFilename = Bdl.GetDataFilePath("file1.txt");
  System.IO.FileStream fs = System.IO.File.Open(sFilename,
  System.IO.FileMode.Open);
  ...
  fs.Close();
}

The .NET test driver DLL is automatically added to the data files of the project so that the DLL is available to remote agents.

Parent topic: Preparations


Profile and System Settings

You can edit your profile and system settings within Microsoft Visual Studio .NET using the familiar Silk Performer dialog boxes. Open the dialog boxes through the Profile Settings and System Settings menu entries of the Silk Performer menu.

The following profile settings are specific to .NET:
  • Traffic redirection
    Option
    Description
    Route HTTP .NET through Silk Performer web engine

    If this option is enabled, all HTTP/HTTPS network traffic that is generated by .NET components is routed over the Silk Performer Web engine. This allows you to make use of Web engine features such as modem simulation, IP multiplexing, and others.

    This also creates TrueLog nodes for each Web request, along with statistical information about the traffic.

    Routed Web Service proxy classes
    This read-only class is filled by the .NET add-on with the Web service proxy classes you are using in your .NET test driver.
  • Application domain setting
    Option
    Description
    One application domain for each virtual user container process

    If this option is checked, there is only one application domain for all virtual users in the container process. This option improves performance because there is less overhead for the .NET Common Language Runtime to administrate multiple application domains for each process.

    The disadvantage is that all objects that are loaded from all virtual sers in the container process share a single application domain and therefore may conflict with one another in terms of, for example, global variables/resources.

    One application domain for each virtual user

    If this option is checked, each virtual user has its own application domain. The objects loaded by each virtual user are isolated in their application domains from other objects in other application domains.

    The disadvantage of this is that there is additional overhead for the .NET Common Language Runtime to administer multiple application domains in one process - therefore there is some performance loss.

  • Framework version
    Option
    Description
    Version

    Select the Microsoft .NET Framework version for your script replay. Silk Performer automatically populates this list with the framework version that you have installed on your computer.

Parent topic: Preparations


Web Settings

You can change the Web settings in the Web Settings dialog box from the Silk Performer menu.

In this dialog box you can set the option Route HTTP .NET through Silk Performer web engine.

If you are testing Web services through a generated Web-service proxy class, you can route the generated network traffic over the Silk Performer Web engine to get information about sent and received data and use features such as modem simulation.

In the checklist of the dialog box you find all the Web Service proxy classes of your project. You can check or uncheck the proxy classes that should be routed over the Web engine. When you check Route HTTP .NET through Silk Performer Web engine, all proxy classes are routed since all network traffic is routed. Alternately, you can route individual Web-service calls by selecting them from the list.

The list of Web-service proxy classes is written to your project file and you can view the list in the .NET options of the profile settings dialog box.

Parent topic: Preparations


Testing Options

Select the Options dialog box from the Silk Performer menu. The dialog box includes options that affect output during tests and behavior of the Code Generation Engine.

The options that are relevant for running tests are:
  • TrueLog Explorer
    Option
    Description
    Automatically Start when running a TryScript
    If this option is checked, TrueLog Explorer will launch automatically when a TryScript is run.
  • Virtual User Output

    These options define what output will be printed to the Virtual User Output window during TryScript runs. For additional information on the options, refer to Silk Performer Help.

Parent topic: Preparations
Related concepts
Options


Try Script Runs

You can launch a Try Script run from the Silk Performer menu or by pressing F8. This is only possible if you did not assign a different command to F8 when the add-on was installed.

  • Steps Performed by the Add-On before Try Script Runs
    The .NET add-on performs a series of steps before it runs a Try Script run.
Parent topic: Testing Your .NET Test Driver


Steps Performed by the Add-On before Try Script Runs

The .NET add-on performs the following steps before it begins with the execution of a Try Script run:
  1. The add-on compiles the .NET Assembly. If the compilation fails the add-on does not execute the Try Script.
  2. The Code Generation Engine generates the BDF/BDH files.
    The engine checks if it has to overwrite old BDF/BDH files. Old files are overwritten only if there has been one of the following changes made to the structure of the .NET test driver:
    • Changes to VirtualUser, Transaction, TestMethod, TestAttribute, or BdlParameter attributes.
    • Changes to the sequence of a method definition.
    • Changes to the parameter definition of the methods.
    • Changes to code generation options.
    If significant changes have been made, the engine checks whether the BDF has been changed manually since it was last generated. If it has been changed, you must specify whether the file can be overwritten. If you select No, the Try Script is not executed.
  3. The add-on prompts you to execute the VirtualUser. If there is more than one VirtualUser class in the .NET test driver, you must choose which virtual user is to be executed.
  4. A temporary project file is generated and configured to run the Try Script.
  5. The Virtual User Output window is activated.
  6. The test begins.
  7. If the Automatically Start TrueLog Explorer option setting has been enabled, TrueLog Explorer will launch with the TrueLog of the active Try Script.
  8. All virtual user output, contingent on options, is printed to the Virtual User Output window.
Parent topic: Try Script Runs


Running Tests in Silk Performer

Once you have completed the implementation of the .NET test driver, you can run tests from within Silk Performer. To do this, open Silk Performer from the Silk Performer menu. The project file is opened in Silk Performer with all the generated scripts and data files.

You can customize the .NET test driver by changing the input values of the .NET functions in the BDL script. The separation of .NET code and BDL code is a great benefit for companies with testing departments in which not all employees are familiar with .NET. One employee with .NET skills can implement .NET test drivers and pass a generated Silk Performer project along to other employees who are more familiar with Silk Performer. Those employees can then customize the BDL script by changing input parameters and configuring real tests.

Running Tests on Remote Agents

If you want to run a .NET test on remote agents you must make sure that the Microsoft .NET Framework is installed on each of the agents. You can download the Microsoft .NET Framework from http://msdn.microsoft.com.

Parent topic: Testing Your .NET Test Driver


Testing Web Services With Microsoft Visual Studio

The Silk Performer .NET Framework and .NET add-on allow easy access to Web services from within .NET. Microsoft Visual Studio .NET has wizards that allow you to specify the URLs of Web services. It can also create Web-service client proxies to invoke the methods of Web services.

  • Creating a Web Service Client Proxy
  • Instantiating a Client Proxy Object
    Describes how you can instantiate a client-proxy object.
  • Calling a Web Service Method
    Describes how you can call a Web-service method.
  • Routing Web-Service Traffic
    Explains that the Silk Performer .NET Framework can route Web traffic generated by .NET components through the Silk Performer Web engine.
  • Exploring Results in Visual Studio
    Enter a short description of your concept here (optional).
Parent topic: Testing .NET Services
Related concepts
Testing .NET Components


Exploring Results in Visual Studio

A TrueLog node is logged for each Web-service call that is executed by the .NET test driver, if routing Web-service traffic is enabled. Click the Response tab of the node in TrueLog Explorer for the Response SOAP Envelope, or click the Request tab for the Request SOAP Envelope.

The overview report for each Web-service method that is called contains the statistical information, like the round-trip time, the server busy time, and others.

Parent topic: Testing Web Services With Microsoft Visual Studio


Testing with .NET Explorer

.NET Explorer is a tool that allows you to generate .NET test drivers through a point & click approach. .NET Explorer supports the following technologies:
  • SOAP Web Services
  • .NET Remoting
  • .NET Components
For additional information, refer to the .NET Explorer Help.
Parent topic: Testing .NET Services
Related concepts
.NET Explorer Help


Available BDL Functions for .NET Interoperability

This section describes the BDL functions that The Silk Performer .NET Framework and .NET add-on allow easy access to Web services from within .NET. provides for .NET interoperability. For detailed descriptions of these functions and all other BDL API functions, refer to the Benchmark Description Language (BDL) Reference. BDL reference details are also available in Silk Performer Help.

  • DotNetLoadObject Function
    Loads a .NET Assembly and creates an instance of a .NET type.
  • DotNetFreeObject Function
    Releases the object handle, so that the garbage collector will free the object.
  • DotNetCallMethod Function
    Calls a public method on the .NET object or a static method of a .NET type.
  • DotNetSetString Function
    Sets a string parameter for the next DotNetCallMethod or DotNetLoadObject call in an internal parameter array.
  • DotNetSetFloat Function
    Sets a float parameter for the next DotNetCallMethod or DotNetLoadObject call in an internal parameter array.
  • DotNetSetBool Function
    Sets a boolean parameter for the next DotNetCallMethod or DotNetLoadObject call in an internal parameter array.
  • DotNetSetInt Function
    Sets an integer parameter for the next DotNetCallMethod or DotNetLoadObject call in an internal parameter array.
  • DotNetSetObject Function
    Sets an object as parameter for the next DotNetCallMethod or DotNetLoadObject call in an internal parameter array.
  • DotNetGetString Function
    Gets the string return value of the last DotNetCallMethod call in sReturn.
  • DotNetGetFloat Function
    Gets the float return value of the last DotNetCallMethod call in fReturn.
  • DotNetGetBool Function
    Gets the boolean return value of the last DotNetCallMethod call in bReturn.
  • DotNetGetInt Function
    Gets the integer return value of the last DotNetCallMethod call in nReturn.
  • DotNetGetObject Function
    Gets the handle to the object returned by the last DotNetCallMethod call.
Parent topic: Testing .NET Services


Java Testing Support

This section offers complete instructions for testing Java with the Silk Performer Java Framework and Java Explorer.

  • Java Explorer Help
    Includes complete instructions for testing Java with Java Explorer.
  • Java Framework Developer Guide
    Includes complete instructions for testing Java with the Silk Performer Java Framework.
  • Testing SOAP Web Services for Java
    Explains the basics of SOAP-based Web Services and details how they can be tested in Java.


Java Explorer Help

  • Tools and Samples
    Explains the tools, sample applications and test projects that Silk Performer provides for testing Java and .NET.
  • Testing Java Components
    Explains that the Java Framework encourages efficiency and tighter integration between QA and development by enabling developers and QA personnel to coordinate their development and testing efforts while working entirely within their specialized environments.
  • Tour of the UI
    Introduces the main elements of the Java Explorer interface, including the Loaded Components, Method Call, and Test Scenario panes, and the workflow bar.
  • Setting Up Java Explorer
    Describes how to set up a project and define tests in Java Explorer.
  • Setting Up Tests
    Includes an introduction to Java Explorer GUI elements, customization of input parameters, definition of output value verifications, and generation of random variables. The section concludes with an explanation of how to use Java Explorer to test EJBs and RMI over IIOP.
  • Animated Runs
    Explains that animated runs execute the test methods that are assigned to your test cases. Several output logs and reports are available.
  • Analyzing Results
    Lists the four file types that are available for analyzing Java test results.
  • System and Project Settings
    Describes the system and project setting options that Java Explorer provides.
  • Exporting Projects
    Describes the environments to which you can export a test scenario.
Parent topic: Java Testing Support


Testing Java Components

The Java Framework encourages efficiency and tighter integration between QA and development by enabling developers and QA personnel to coordinate their development and testing efforts while working entirely within their specialized environments.

  • Testing Java Components Overview
    Explains that with the Java Framework developers work exclusively in their Java programming environments while QA staff work exclusively in Silk Performer.
  • Working With JDK Versions
    Explains that you need to test components against all JDK versions.
  • Java Framework Approach
    Explains that the Java Framework approach to component testing is ideal for developers and advanced QA personnel who are not familiar with BDL, but are familiar with Java programming.
  • Plug-In for Eclipse
    Explains the plug-in for Eclipse developers that automatically generates all required BDL code from within the Eclipse SDK.
  • Java Explorer Overview
    Explains Java Explorer
Parent topic: Java Explorer Help
Parent topic: Java Framework Developer Guide


Testing Java Components Overview

With the Java Framework developers work exclusively in their Java programming environments while QA staff work exclusively in Silk Performer. There is no need for staff to learn new tools.

Java developers typically build applications and then hand them off to QA for testing. QA personnel are then tasked with testing Java applications end-to-end and component-by-component. Typically QA personnel are not given clients (test drivers) to test applications and they typically are not able to code such test clients themselves. This is where Java Explorer and the Java Framework are effective. Java Explorer offers a means of visually scripting test clients. In effect Java Explorer acts like a test client and can be used to interact with the application under test.

All Java components can be tested with Java Explorer, but the focus lies on the following three Java components: Enterprise JavaBeans (EJBs), Web Services, and Remote Method Invocation (RMI).

The Java Framework enables users to run stand-alone Java test code, to use other tools to invoke Java test code, or to execute test code from an exported standalone console.

Parent topic: Testing Java Components


Working With JDK Versions

Because multiple Java Developer Kit (JDK) versions are available, you need to test components against all versions. Both Silk Performer's Java Explorer and Java Framework support testing components of various vendors and of different JDK versions.

Parent topic: Testing Java Components


Java Framework Approach

The Java Framework approach to component testing is ideal for developers and advanced QA personnel who are not familiar with BDL (Benchmark Description Language), but are comfortable working with a Java development tool. With this approach, Java code is used by the QA department to invoke newly created methods from Silk Performer.

You can generate Java Framework BDL code using the Silk Performer JUnit import tool. The import tool produces BDL code that can invoke customer test code or customer JUnit testcode. It can also be used to directly invoke a client API.

Parent topic: Testing Java Components
Related concepts
JUnit Integration


Plug-In for Eclipse

Silk Performer offers a plug-in for Eclipse developers that automatically generates all required BDL code from within the Eclipse SDK. Developers simply write their code in Eclipse and implement certain methods for integrating with the Silk Performer Java Framework. The plug-in then creates all required BDL scripting that the QA department needs to invoke newly created methods from Silk Performer. The plug-in for Eclipse enables developers and QA personnel to better coordinate their efforts, consolidating test assets and enabling both testers and developers to work within the environments with which they are most comfortable.

Parent topic: Testing Java Components


Java Explorer Overview

Java Explorer is a GUI-driven tool that is well suited for QA personnel who are proficient with Silk Performer in facilitating analysis of Java components and thereby creating Silk Performer projects, test case specifications, and scripts from which tests can be run.

Developers who are proficient with Java may also find Java Explorer helpful for quickly generating basic test scripts that can subsequently be brought into a development tool for advanced modification.

Java Explorer emulates Java clients. When working with Web services, Java Explorer achieves this through the use of proxies, which are conversion encoding/decoding modules between the network and client. Proxies communicate with servers by converting function calls into SOAP (XML) traffic, which is transferred through HTTP. Requests are decoded on the remote computer where the component resides. The XML request is then decoded into a real function call, and the function call is executed on the remote server. The results are encoded into XML and sent back to Java Explorer through SOAP, where they are decoded and presented to the user. What you see as the return result of the method call is exactly what the server has sent over the wire through XML.

Parent topic: Testing Java Components


Tour of the UI

Explains the view tabs that are offered by Java Explorer.

  • Overview
    Introduces the main elements of the Java Explorer interface, including the Loaded Components, Method Call, and Test Scenario panes, and the workflow bar.
  • Design Tab
    Explains that the Design tab offers the display of loaded components, invocation of methods, customization of input/output data, and the design of test scenarios.
  • Code Tab
    Explains that the Code tab displays generated code files for the current test scenario and that various code types are available.
  • Output Tab
    Explains that the Output tab displays log output during test runs.
Parent topic: Java Explorer Help


Overview

The main sections of the Java Explorer interface are highlighted below.

Workflow Bar

The Java Explorer workflow bar assists you in configuring and running your tests. The buttons on the workflow bar enable you to perform the following commands:

  • Start Here: Opens the Load File Wizard, which guides you through selecting the type of testing that you want to perform and loading the required components.
  • Test Class: Allows you to create a new test case for a class, or to add methods to an existing test case. This button is enabled when you select a class in the Loaded Components menu tree.
  • Invoke: Invokes the selected method in the Loaded Components menu tree and adds it to the selected test case in the Test Scenario menu tree.
  • Customize: Lets you store data as variables. This button is enabled when you select an input parameter in the Input Data menu tree, or an output parameter in the Output Data menu tree.
  • Verification: Allows you to define verifications for variables. This button is enabled when you select an output parameter in the Output Data menu tree that has been stored as a variable.
  • Run Test: Performs an animated run of your test cases.
  • Results: Lets you explore the results of your last test run through user report, TrueLog, error report, or log file analysis.

WSDL/JAR Address Field

The WSDL/JAR address field allows for the loading of either WSDLs or Java classes and packages.

Loaded Components Pane

The Loaded Components pane includes three tabs:
  • Classes: A list of loaded Web services, remotable classes or interfaces, and other Java classes. Allows you to instantiate objects, connect to remote objects, or call static methods.
  • Objects: A list of instantiated objects, global variables, and random variables. Allows you to call methods on those kind of objects.

Method Call Pane

  • The Input Data menu tree shows input parameters (both headers and bodies) for the selected method call.
  • The Input Data Properties field shows the properties of the input parameters (value, type, pass, null, etc).
  • The Output Data menu tree shows the output parameters (header and body) of the last/selected method call.
  • The Output Data Properties field shows the properties of the output parameters (value, type, pass, null, etc).

Test Scenario Pane

The Test Scenario pane lists the current test cases along with all added method calls.

Parent topic: Tour of the UI


Design Tab

The Design tab is the primary mode used to access the majority of Java Explorer functionality. The Design tab offers the display of loaded components, invocation of methods, customization of input/output data, and the design of test scenarios.

  • Loaded Components Pane
    Explains that the Loaded Components pane, on the Design tab, distinguishes between classes and objects and displays these components within different tree menus.
  • Classes Tab
    Explains that all loaded classes and Web services are listed in the Java Explorer Loaded Components pane on the Classes tab.
  • Objects Tab
    Explains that when an object is instantiated through a constructor or returned by a method and stored in a variable, the object is listed in the Loaded Components pane on the Objects tab.
Parent topic: Tour of the UI


Loaded Components Pane

The Loaded Components pane, on the Design tab, distinguishes between classes and objects and displays these components within different tree menus.

On the Classes tab you see all loaded classes with their members (methods, fields, and properties) that can be accessed without the need of an object context. Normally these are static members and constructors.

When you instantiate a class, the created object is shown on the Objects tab with all instance members (methods, fields, and properties).

The two exceptions are Web services and Remote Objects. As an object instance is not required for Web Services (which are objects that expose static methods), all methods offered by Web services are shown on the Classes tab. Remote Objects, for example EJB home objects, which are used to create an EJB object, are also listed in the Classes tab, although they are in fact objects.

Parent topic: Design Tab


Classes Tab

All loaded classes and Web services are listed in the Java Explorer Loaded Components pane on the Classes tab.

Only constructors, static methods, and members are displayed, as there is no object context required to call them.

Web services and remotable interfaces are treated as if they only have static methods.

The following folders are available in Classes view:

Remote Objects

Home interfaces of EJBs on remote servers. The home interfaces are looked up on a naming service through JNDI. Invoking a create method on EJB home objects instantiates EJB objects on servers.

Web Services

Stub classes, which are helper classes that encapsulate network communications. Axis classes are derived from org.apache.axis.client.Stub or org.apache.axis2.client.Stub, depending on the selected Web service plugin in Tools > Project Settings > Web Service Plugin. When you use the Metro client stub, classes are derived from javax.xml.ws.Service. Asynchronous method calls are not allowed and therefore are not shown.

Other Classes

Other Java classes, that do not fit in the above listed categories, and the application under test (AUT) are included in this folder.

Parent topic: Design Tab


Objects Tab

When an object is instantiated through a constructor or returned by a method and stored in a variable, the object is listed in the Loaded Components pane on the Objects tab. Instance members and methods that can then be invoked by the user are displayed.

The Objects tab shows objects stored in variables that have global scope and those that have a local scope of the currently selected test case.

Objects

Objects contain logic and data. For example, the data of an object might consist of a string. In this case, the logic of the object would consist of functions that can be used to manipulate the string.

Note: You can create new objects by invoking a method more than once using different input parameters.

Instance methods and members are displayed to allow for easy invokation.

Members have get/set accessors to enable the getting and setting of values.

Local test case objects are included in the Local Test Case Objects folder. A local object is only displayed while the test case that is associated with it is selected. Global test case objects are included in the Global Test Case Objects folder.

Note: To create a new test case, right-click a test case and choose New Test Case.

Variables

By default variables that store simple data types such as strings and integers are listed in the Global Random Variables folder, not as objects but as simple variables. Depending on the variable type - either simple value type or complex object - variables are either displayed as simple types, with no actions allowed, or as objects for which you can invoke all methods on the variable object, for example methods on java.lang.String.

String values are represented as complex objects that allow you to call all methods of the java.lang.String class.

Parent topic: Design Tab


Code Tab

Displays generated code files for the current test scenario. The following code types are available:

Test Driver Test Code

This tab displays the Java code generated for the test driver. This code can be compiled to a standalone console application. The main method for the application contains the calls to the test cases that are defined in your current test scenario. The test case methods contain all the calls that you have defined in your scenario for the respective test case.

When you export a standalone console application through the Export menu and then run the application, you see output information regarding successful/failed methods in the console window.

Silk Performer Java Framework Test Code

When you export a Silk Performer Java Framework project, the following files are generated:
  • Silk Performer project file (.lpt)
  • Silk Performer script file (.bdf)
  • Java test script (.java)

This tab displays the Java test script code for Silk Performer Java Framework. Java framework code run by Silk Performer enables you to execute Java scripts through BDL. For each test case in your current test scenario, Java Explorer generates a separate BDL transaction in the test script.

BDL Script

This tab displays the BDL script code for Silk Performer Java Framework. The generated BDL executes the Java test script with the settings stored in the Silk Performer project file.

JUnit Code

This tab displays the JUnit test script code. this code can be executed with any JUnit TestRunner. For more information about JUnit testing, refer to the Silk Performer Help.

Client Proxy

This tab displays generated Web Service Client proxy code. When you load a WSDL file to access a Web service, a Client proxy class is created. Proxy classes are created on method and type information in WSDL files. When Web-service methods return complex types, additional classes are declared. These additional classes are used to represent complex types in the method calls that take complex parameters.

Parent topic: Tour of the UI


Output Tab

The Output tab displays log output during test runs. The tab shows details about each call of the most recent animated run. Statistics regarding execution time and executed methods are also shown.

Note: The Output tab can also be accessed by clicking Results on the Workflow Bar.

The following items are available:

Animation Log

Displays detailed information about test duration, method calls, and errors. It also lists each method, including input parameters and output values.

Java Explorer automatically saves this file to <my documents>\Silk Performer 21.0\Projects\<projectname>\RecentTestRun\<projectname>.log.

Error Log

The Error Log delivers detailed information about errors that occurred during the last test run.

Java Explorer automatically saves this file to <my documents>\Silk Performer 21.0\Projects\<projectname>\RecentTestRun\<projectname>.err.

User Report

An overview report in HTML format that displays the consolidated information from the animation log and the error log, in a report format that you can use for distribution or printing.

Java Explorer automatically saves this file to <my documents>\Silk Performer 21.0\Projects\<projectname>\RecentTestRun\<projectname>.html.

Example Animated Log Output

Test started: 08.10.2004 08:01:50
Test stopped: 08.10.2004 08:01:53
Method calls: 1
Success calls: 1
Error calls: 0
TestWebProxies.Service1.echoStringArray
Parameters : System.String[](string)
Return Value: System.String[](string)
Parent topic: Tour of the UI


Setting Up Java Explorer

This section describes how you can set up a project in Java Explorer and how you can define tests for the project. A sample Web Service host is used for demonstration purposes. For additional information on how to use Java Explorer to test Enterprise JavaBeans and RMI over IIOP, see Enterprise JavaBeansand RMI over IIOP.

  • Java Explorer Prerequisites
    Describes the prerequisites that are needed before you can create a project in Java Explorer.
  • Creating a New Project
    Create a new Java Explorer project to run tests with Java Explorer.
  • Test Case Definition
    Explains the available approaches to define a test for a Java Explorer project.
  • Setting Up a Test Using the Load File Wizard
    Set up a Java Explorer test with the Load File Wizard to get enhanced control over the test.
  • Test Case Characteristics
    Explains the characteristics of test cases as they relate to Java Explorer.
Parent topic: Java Explorer Help


Java Explorer Prerequisites

To work with Java Explorer you need to have a Java Development Kit 7, 8, downloadable from the Java SE Downloads page, or a IBM Java Development Kit installed on your system.

If you are using Microsoft Windows Vista or Microsoft Windows 7 as your operating system, you must have administrator priviledges to launch Java Explorer from the Start menu. If you do not have administrator priviledges, Java Explorer is not able to create files or folders or to run Silk Performer.

Some Web Services only work with specific SOAP stacks, depending on the server-side implementation of the Web Service. In this case, use trial and error to find the appropriate SOAP stacks, because the reported error messages are not clear.

Parent topic: Setting Up Java Explorer


Creating a New Project

To create a new Java Explorer project:

  1. Start Java Explorer. The Create or open a project dialog box opens.
  2. Click the Create a New Project option button.
  3. Type a name for the project into the text box.
    Note: The project name cannot be longer than 19 characters and cannot contain certain special characters, for example *, ., or !.
  4. Click OK. The new project is created and the Java Explorer Web GUI opens. A new folder, which contains all the files required by the project for operation, is created in the project directory. The default project directory is <my documents>\Silk Performer 21.0\Projects.
  5. Navigate to Tools > Project Settings > Web Service Plugin .
  6. Select the Web service plug-in (SOAP stack) that is required for your tests. Because of incompatibilities between different SOAP stacks, you cannot change the SOAP stack once it is used by Java Explorer. Web Service plug-ins that are used, are grayed out in the list box.
Parent topic: Setting Up Java Explorer


Test Case Definition

Use one of the following two approaches to define a test with Java Explorer:
  • Use the Load File Wizard to define where the information for an object you want to test is located. The wizard displays the available classes, automatically instantiates the available objects, and calls methods on those objects. This approach requires more involvement, but provides more control.
  • Enter the location of the Web services' WSDL file into the WSDR/JAR text box in Java Explorer and click Load. Information about the methods and objects is then displayed. This approach provides a quick and simple way to analyze remote service functionality.
    Note: Objects are not instantiated and methods are not called.

For demonstration purposes this Help uses the Load File Wizard to instantiate the objects available on the sample Web service, which is available at http://demo.borland.com/BorlandSampleService/BorlandSampleService.asmx?WSDL.

Parent topic: Setting Up Java Explorer
Related tasks
Setting Up a Test Using the Load File Wizard


Setting Up a Test Using the Load File Wizard

To set up a Java Explorer test using the Load File Wizard:
  1. Click Start Here on the workflow bar. The Load File Wizard dialog box opens.
  2. Click the option button that corresponds to the class type that you want to test.
    • Web Services
    • Enterprise JavaBeans
    • RMI
    • Java Archive
    • Java Class
  3. To test a Web service, you must provide a Web Services Description Language (WSDL) document. Click the Web Services option button and specify a path or URL to the WSDL document using the browse (...) button.
    Note: To test Enterprise JavaBeans, click the corresponding option button and then specify the EJB-specific connection settings. To test other class types, click the appropriate option button and then specify the path to a Java archive or class file.
  4. Click Next. The WSDL file now loads and finds out what is available on the Web service. A WSDL file is an XML description of the functionality that is offered by the Web Service.
    Note: The sample Web service offers a minimum of functionality-it simply echoes back some values.
  5. Select the Web service class you wish to test from the Class list box. Normally there will be only one class, but it is possible that the loaded WSDL will define multiple Web services.
  6. Use the URL (Endpoint) text box to change the endpoint of the service. The default endpoint is the one defined in the WSDL document.
  7. Optional: To change the Web service proxy and authentication settings for the Web server, click browse (...) to open the Connection Settings dialog box.
    1. Type the endpoint of the Web service in the URL text box.
    2. If user credentials are required for authentication, type the information in the Username and Password text boxes.
    3. Click OK.
  8. Click Next. The Method Invocation dialog box opens.
  9. Check the check boxes beside the methods that you want to test. For example echoFloat and echoString. Methods are called using the default parameters.
    Note: The checked Inherited check box indicates that the member functions of the base classes are visible. You cannot change the state of the check box manually.
  10. To adjust the sequence in which the methods are called, use the up and down arrow buttons. This way, you can move methods up and down the invocation list. The button between the up and down arrow buttons enables you to invert the selection of methods, meaning that all unmarked methods become marked, and vice versa.
    Note: Login and logout methods must be in first and last positions, respectively.
  11. Click Next. The Select a test case dialog box opens.
  12. Select the test case to which the testing methods should be added. You can select from the following:
    • Init Test Case: This is the first test case that is called in test runs. Select this test case if your method calls are related to initialization, logging in, or start-up.
    • Existing Test Case: You can add to an existing test case. Choose the test case from the list box to the right of this selection.
    • New Test Case: A new test case is created and the methods are added to the new test case. Using the text box to the right of this selection, give the new test case a unique name.
    • End Test Case: This is the last test case that is called in test runs. Select this test case if your method calls are related to clean-up, for example logging off.
  13. Click Finish.
    Note: A message displays if you have selected a method that takes parameters, letting you know that default parameters will be used for the method, which may result in an exception being thrown. Methods that throw exceptions will be excluded from your test scenario. If you don’t want to proceed, click No, then go back, deselect the method in question, and add it later manually with a more meaningful parameter value.
The Web service has been loaded in the class tree list and the selected methods have been called and added to the selected test case.
Parent topic: Setting Up Java Explorer


Test Case Characteristics

Following is an overview of the characteristics of test cases as they relate to Java Explorer:
  • Each test scenario includes an Init test case and an End test case. Multiple Main test cases may also be defined. An Init test case is the first test case that is called during a test run. Init test cases often include method calls that are related to initialization, logging in, or start-up. An End test case is the last test case that is called during a test run. End test cases often include method calls that are related to clean-up, for example logging off.
  • Main test cases are executed between Init and End test cases and may include any sort of method call.
  • A local variable is only valid within a single test case and cannot be passed to another test case. Only global variables can be used to pass values between test cases.
  • Each test case must have a unique name.
  • Names of test cases are restricted. The names are mapped to Java methods and Silk Performer transactions, so they are subject to the restrictions of Java method and Silk Performer transaction names. Code exported to Silk Performer cannot use keywords that are defined by BDL or Java. You cannot use the names of the following variables because they are scripted by Java Explorer scripts when exporting to Silk Performer Java Framework Projects:
    all | allownull | and | array | aux
    begin | benchmark | bin | boolean | by
    char chr clock$ commit con const create com1 ... com9 cursor
    database | dclevent | dclform | dclfunc | dclparam | dclrand | dclsql | dcltrans | dcluser | delete | dll | do | double | drop | dstring
    else | elseif | end | eos | exit | explicit
    false | fetch | float | for | form | from | function
    group
    halt | handler
    if | in | init | inout | insert | into
    last lenspec long loop lpt1 ... lpt9
    mod
    next | not | nul | number
    of | optional | or | ord | order | out
    prn | proc | ptr
    rc | reset | result | return | rndbin | rndefxp | rndexpn | rndfile | rndind | rndpern | rndsno | rndstr | rndstream | rndunif | rndunii
    rndunin | rollback | row | rows
    select | set | short | sizeof | sizespec | sql | stored | string
    then | throw | to | transaction | transactions | true
    union | unique | unsigned | update | use | user
    values | var | void
    wait | where | while | write | writeln
  • Test case properties can be edited by selecting a test case in the Test Scenario menu tree and defining field values in the Output Data Properties field:
    • StopAtError is the attribute that defines the number of errors that can occur during an animated run. If this number is reached, the animated run aborts. Setting this attribute to 0 specifies that errors will be ignored.
    • CallCount is the attribute that defines the number of times that a test case will be called during an animated run.
    • The Name attribute of the test case must be unique among all test cases.
  • You can create, copy, and remove test cases by right-clicking a teste case in the Test Scenario menu tree and selecting the respective menu item.
Parent topic: Setting Up Java Explorer


Setting Up Tests

This section explains how to set up and customize your tests with Java Explorer. Topics include an introduction to GUI elements, customization of input parameters, definition of output value verifications, and generation of random variables. The section concludes with an explanation of how to use Java Explorer to test EJBs and RMI over IIOP.

  • Customizing Input Parameters
    Use the Input Value Wizard to customize input parameters of a complex type.
  • Storing Output Values in Variables
    Use the Output Data and Output Data Properties panes to store output data as variables for later use.
  • Manually Adding Global Variables
    Explains how to create a global variable to be used as an input parameter. Also explains how to initialize parameters from a data file.
  • Capturing an HTTP Response
    Describes how to use Silk Performer to record and capture the server response when running a test against a Web service.
  • Defining Output Value Verifications
    Store an output parameter value in a variable to specify a verification rule for the variable.
  • Adding Method Calls
    Invoke a method to add it to the currently selected test case.
  • Updating Method Calls
    Update a method that has already been added to a test case.
  • Complex Input/Output Data
    Explains that Java Explorer supports complex data types such as arrays and objects as both input data and output data.
  • Random Value Types
    Describes the random value types that you can apply to an input value type.
  • Configuring Random Variables
    Use the Random Variable Wizard to configure random variables for entire input parameters or individual members of complex input parameters.
  • Enterprise JavaBeans and RMI over IIOP
    Describes how you can use EJBs with RMI or RMI over IIOP.
  • Java RMI
    Describes how you can test Java RMI.
  • Testing Java Archives
    Describes how you can test Java archives.
  • Test Class Wizard
    Describes how you can use the Test Class Wizard to create a test for a class or an instantiated object.
  • Secure Web Services
    Describes how you can test secure Web services.
  • Negative Testing
    Describes how you can ignore expected exceptions when you perform negative testing.
Parent topic: Java Explorer Help


Customizing Input Parameters

You should customize the input parameters before you execute a method. If you want to customize a method call after it is executed, for example if the method call was generated using the Load File Wizard, you need to execute an Animated Run after you have customized the method call to make the changes effective.

When a method has input headers or parameters, its values are displayed in the Default Input Parameter Values pane with their default values. Select the method you want to invoke in the Loaded Components pane. Parameters are displayed with their default values in the Default Input Parameter Values pane. To configure default values in the System Settings, click Tools > System Settings > Default Values.

To change a value, select a parameter in the Default Input Parameter Values pane. If a parameter is a simple data type, like string, float, or integer, you can enter the value directly into the text boxes in the pane. If the parameter is a complex type, like an object or array, or you want to use a random value or a value from a stored variable, click (...) to open the Input Value Wizard.

To use the Input Value Wizard to customize an input parameter:

  1. Select the InputValue row in the Input Data Properties pane.
  2. Click (...). The Input Value Wizard opens.
  3. Define the input value for the parameter of the method. You can pass a null value, a value from a variable, or a constant value.
    • ClickIs Null to pass a null value. This value is only valid for strings, objects, and arrays.
    • If you have already stored a variable that holds values of the parameter’s type, click Use Variable and select the variable from the list box.

      If the parameter is an array, type the index into the Index Array text box.

    • If the parameter is not an object or array, you can specify a constant value such as a string, integer, or double value. Select the Constant value option button.
    • If you do not want to use a constant value and would rather use a random value for types such as string, integer, or float, you can create a new random value by clicking New random variable. If a random value of the parameter type has already been created, click Random variable and select the variable from the list box.
  4. Click OK.
Once input parameters have been defined, you can invoke a method to have that method automatically added it to the selected test case in the Test Scenario pane. From there, corresponding output values can either be stored as variables or verifications can be set up for them.
Parent topic: Setting Up Tests
Related concepts
Animated Runs


Storing Output Values in Variables

Using the Output Data and Output Data Properties panes, you can store output values as variables for later use or you can define verifications for the values.

  1. Click Invoke on the Workflow bar or by right-click a method in the Input Data pane and choose Invoke/Add to Test Case to invoke the method. The Output Value Wizard opens.
    Note: You can also open the Output Value Wizard by clicking Customize in the Workflow bar, or by right-clicking an output parameter in the Output Data pane.
  2. In the Output Value Wizard, type a name for the output value variable in the Variable name text box.
  3. Click the option button that corresponds to the scope of the variable. The default is Local, which means that the variable can only be used within the test case within which it has been created. Global scope means that the variable can be used within any test case. Global scope enables you to pass information between test cases.
  4. Click OK.
Parent topic: Setting Up Tests


Manually Adding Global Variables

Global variables can be shared between test cases. They vary from local variables, which are only available to specific test cases.

Note: You can also create global variables by clicking the Global scope option button in the Output Value Wizard.

Global variables can be used as input parameters for function calls. Global variables are configured with an initial value, which makes them useful when you need to have the same value used for multiple function calls. Each time a test run begins, global variables are initialized with the defined initial value.

To create a global variable:

  1. Click the Objects tab.
  2. Right-click an object in the Objects tree menu and choose New Global Variable. The Define a Global Variable dialog box displays.
  3. Enter a name for the variable in the Variable Name text box.
  4. Select a Variable type. The following variable types are available:
    • boolean
    • byte
    • short
    • int
    • long
    • char
    • float
    • double
    • java.lang.String
  5. Each variable has an initial value and a current value. When tests are run, all global variables are initialized to their initial values. Specify an intial value for the variable in the Initialize Value text box.
  6. Click OK.
Parent topic: Setting Up Tests


Capturing an HTTP Response

By default, Java Explorer does not allow you to view the HTTP response when running a test against a Web service. As an alternative, you can use Silk Performer to record and capture the server response.

  1. Launch Silk Performer.
  2. In the Silk Performer menu, click Settings > System .
  3. Click the Recorder icon. The Recording Profiles page opens.
  4. Click Add to add a new recording profile for Java. The Recording Profile dialog box opens.
  5. In the Profile name text box, type a unique name for the Java recording profile. The profile name is required to identify the application in the Silk Performer Recorder window.
  6. In the Application path text box, type the name of the Java application's executable and the directory in which it resides. To locate the executable, click Browse.
    Note: There may be multiple Java executables. Therefore, it is important that the Recording Profile should match the Java executable used in the Java Explorer runtime settings.
  7. In the Working directory text box, type the working directory of the Java application. The working directory is the folder that contains the application or related files. Some applications need files located in other directories, so you might have to specify the folder in which these files reside.
  8. In the Application type list box, make sure that Custom Application is selected.
  9. In the Protocol selection area, select the Web check box, which identifies that the Silk Performer Recorder hooks into a Web application, intercepts all function calls, and displays the results.
  10. Click OK to add the new Java profile to the list.
  11. Ensure that you record the script in Silk Performer with the newly created recording profile before invoking and running the test in Java Explorer.
  12. After you save the recording, you can view the HTTP response in TrueLog Explorer by selecting the In Body tab of the recorded TrueLog file (.xlg).
Parent topic: Setting Up Tests


Defining Output Value Verifications

  1. Select Verification in the Output Data Properties pane to display the (...) button.
  2. Click (...) to open the Verification Wizard.
    1. Select Range if you are verifying integers or doubles. Then specify a range for the value using the From and To text boxes.
  3. Select one of the following:
    • Click No Verification if you do not want the value to be verified.
    • Click Verification with NULL or variable to verify one of the following:
      • Check the Should be null check box, to verify that the value is NULL.
      • The value is not NULL. This option verifies whether or not a value is present.
      • Verify that the value exactly matches the value of an existing variable, a public member of a variable, or an element of an array.If the variable is an array you can also define the Array index for the element that should be used for the verification.
    • Click Constant Value to verify that the value exactly matches a constant string.
    • Click Regular expression to verify against a string value.
    • Click Range if you are verifying that a numeric value is within a specified range. Then specify a range for the value using the From and To text boxes.
  4. Select the Severity of error that should be thrown if the verification fails. The following severity options are available:

    • Success, no error

      No error is thrown

    • Informational

      An informational message is logged

    • Warning

      A warning is thrown

    • Error, simulation continues

      An error is thrown, but the simulation continues

    • Error, the active test case is aborted

      An error is thrown, the simulation continues, however the active test case is aborted. This is a transaction exit severity in Silk Performer

    • Error, the simulation is aborted

      An error is thrown and the simulation is aborted

    • Custom

      A section is inserted into the .NET code where special error handling code can be inserted

  5. Click OK.
  • Verification with NULL or Variable
    Describes how you can verify against NULL or a variable.
Parent topic: Setting Up Tests


Verification with NULL or Variable

The Verification with NULL or variable selection inludes a list box that contains the entries < is Null > and < is not Null > and a list of variables that match the return value of the method call.

The list box additionally contains arrays for which the element type matches the return value of the method call. For example, the array myStringArray has a return value of type java.lang.String. You can select variables that represent a string array from the list box. In such cases, an array index list box is enabled.

The list box also contains public fields of complex objects of matching type. For example, the test class PublicMember has a public field called mStr of type string, which can be selected. The notation of public fields is <variable name>.<member name>, which for the example is PublicMember.mStr.

Parent topic: Defining Output Value Verifications


Adding Method Calls

  1. Within the Loaded Components or Method Call pane, select the method to be added.
  2. Invoke the method by clicking Invoke. The invoked method is added automatically to the currently selected test case. If the method call returns a value, the Output Value Wizard opens automatically, and prompts you to store the value.
Parent topic: Setting Up Tests


Updating Method Calls

  1. From the Test Scenario pane, select the method that is to be changed.
  2. Make modifications to the input/output parameters of the method in the Input Data or Output Data panes. Updates are automatically accepted when you exit the Input Data or Output Data panes.
  3. Perform an Animated Run to apply the changes.
Parent topic: Setting Up Tests
Related concepts
Animated Runs


Complex Input/Output Data

Java Explorer supports complex data types such as arrays and objects as both input data and output data. The Output Value Wizard assists you in using such data as variables.

  • Verification of Variables
    Describes how Java Explorer supports the verification of variables.
  • Storing Array or Object Output Data as Variable
    When a method returns an array or an object as output data, you can store the value in a variable of either local or global scope.
  • Taking Array Object Data From a Variable
    When you use an array from a variable as input data, you can take the entire array from the variable.
  • Defining Each Member of a Variable Individually
    When using an object as input data, you can take the entire object from a variable or define each member individually.
  • Defining Array Elements
    When a method requires an array as an input parameter, you can define the number of array elements and all elements in the array.
  • Using Complex Input Data
    Use complex input data as described in this example.
Parent topic: Setting Up Tests


Verification of Variables

Java Explorer fully supports the verification of complex data types. When the return value of a method, including array elements and public fields of complex type, is complex, you can select an existing variable, an array element of an existing variable, or a public field of an existing varible to verify against. Java Explorer also supports the verification of variables with primitive data types.

Parent topic: Complex Input/Output Data


Storing Array or Object Output Data as Variable

When a method returns an array or an object as output data, you can store the value in a variable of either local or global scope.

  1. Select the complex output parameter in the Output Data pane.
  2. Click (...). The Output Value Wizard opens.
  3. Specify the name and scope of the variable.
Parent topic: Complex Input/Output Data
Related tasks
Storing Array or Object Output Data as Variable


Taking Array Object Data From a Variable

  1. Select a complex input parameter in the Input Data pane.
  2. Click (...). The Input Value Wizard opens.
  3. Define the input value.
Parent topic: Complex Input/Output Data
Related tasks
Customizing Input Parameters


Defining Array Elements

  1. The default length for arrays is 1. To change the number of elements in an array, select the array node in the Input Data pane.
  2. In the Length text box, enter the number of elements in the array. Java Explorer automatically adds or removes the required elements.
  3. To specify the value of an element, select the element in the array and specify the value in the Value text box.
  4. Array members or an entire array can be assigned input parameters from a variable. To specify input parameters from a variable, click (...). The Input Value Wizard opens.
  5. Click Use variable on the Input Value Wizard and select a preconfigured variable from the list box. All variables of the current parameter type are listed.
  6. Click OK.
Parent topic: Complex Input/Output Data


Using Complex Input Data

The following example task describes how you can use complex input data:
  1. Call the method echoStringArray of the sample Web service. The sample Web service is available from http://demo.borland.com/BorlandSampleService/BorlandSampleService.asmx?WSDL. This service requires an object of the generated class ArrayOfString as a parameter.
  2. Right click init() and choose Invoke in the Design pane to instantiate the ArrayOfString object. The Output Value Wizard opens.
  3. Check the Store as variable check box.
  4. Type myArrayOfString into the Variable name text box.
  5. Click OK. The Output Value Wizard closes.
  6. Right click setString(String[]) and choose Invoke in the Design pane to call the setString method and define the array elements.
  7. Use the Input Value Wizard to pass myArrayOfString to the echoStringArray method.
Parent topic: Complex Input/Output Data
Related tasks
Setting Up a Test Using the Load File Wizard


Random Value Types

When you define a random variable for an input value you can only choose one of the random types that are applicable for that input value type.

Random variables return one of the following value types:
  • String
  • Number
  • Float

String Random Values

You can define random variables that return strings with the Random Variable Wizard.

Individual Strings

An individual string declares a random variable of type RndInd. With each access, such a variable contains a random value with type string. You must declare all possible values for the random variable, along with their probabilities. For each string value you must define a weighted number that indicates the probability that the string value will be selected. Weighted numbers are integer numbers.

Strings from a Pattern

A string from a pattern declares a random variable of type RndStr. Such a variable contains a random string value with each access. The characters of the string and the length of the string are randomly generated following a uniform distribution.

The pattern string defines the characters that you must use to construct random strings. The length of calculated strings is selected randomly with a uniform distribution based on defined minimum and maximum lengths, including boundaries.

Number Random Values

You can define random variables that return integers with the Random Variable Wizard. The values can either be calculated based on a weighted number list or by specifying a number range.

Integer Numbers

Declares a random variable of type RndUniN. With each access, such a variable contains a value that is generated following a uniform distribution. The parameters of the RndUniN function specify the minimum value and the maximum value of the uniform distribution. Within these boundaries all integer values have the same probability, including the boundaries.

Weighted Integer Numbers

Declares a random variable of type RndInd. With each access, such a variable contains a random value whose type is either string or integer, depending on the syntax of the declaration. You must declare all possible values for the random variable, along with their probabilities. You cannot mix integer and string values. For each integer value you must define a weighted number that indicates the probability that the integer value will be selected.

Float Random Values

You can define random variables that return floats with the Random Variable Wizard. There is only one possible definition for generating float values currently.

Floating Point Numbers

Declares a random variable of type RndUniF. With each access, such a variable contains a value that is generated following a uniform distribution. The parameters of the RndUniF function specify the minimum value and the maximum value of the uniform distribution.

Parent topic: Setting Up Tests


Configuring Random Variables

With the Random Variable Wizard, you can configure random variables for entire input parameters or individual members of complex input parameters. You can also reuse existing random variables by using the Input Value Wizard.

To configure a random variable:

  1. On the Input Value Wizard, click the New random variable option button. Alternative: If you have already configured a random variable that you would like to apply, click the Use random variable option button.
  2. Alternative: If you have already configured a random variable that you would like to apply, perform the following:
    1. Click the Use random variable option button.
    2. Select the variable that you wish to apply from the list box.
    3. Click OK.
  3. Click OK. The Random Variable Wizard opens.
  4. From the Random type list box, select the type of random variable that you wish to insert to your script. A short type description and a variable declaration preview for each type is displayed.
    Note: Random variables always have global scope, and so are available to all test cases in your project.
  5. Click Next.
  6. In the Parameter pane, edit the existing valyues or insert new values. Weight numbers define the fraquency at which values are displayed. The weight numbers are more flexible than using percentages to define frequency.
  7. Click Finish.
Parent topic: Setting Up Tests


Enterprise JavaBeans and RMI over IIOP

Enterprise JavaBeans (EJB) is a specification for developing scalable, server-side, multi-user enterprise applications. When you test components like EJBs or other remote components, you cannot use HTTP traffic when the application expects RMI or RMI over IIOP traffic. To communicate with the application, Silk Performer must invoke a Java client that generates the appropriate protocols that can be used to approach the interface of the application.

Java Remote Method Invocation (RMI) technology is developed jointly by Sun Microsystems and IBM. RMI delivers CORBA-distributed computing functionality to the Java 2 platform, when the technology is run over Internet Inter-Orb Protocol (RMI-IIOP).

  • Working with Enterprise JavaBeans
    Create an EJB on the application server to test the EJB with Java Explorer.
  • Vendor-Specific JNDI Settings
    Describes the vendor-specific JNDI settings of the application server.
  • Working with RMI Over IIOP
    Test RMI over IIOP to use CORBA-distributed computing functionality.
  • Testing the RMI Sample
    Test the Silk Performer RMI sample to get additional knowledge of RMI testing.
Parent topic: Setting Up Tests
Related concepts
Java RMI Samples


Working with Enterprise JavaBeans

Testing an EJB with Java Explorer involves the following three main steps:
  • Connecting to the Java Name Service (JNDI)
  • Selecting an EJB Home object that is registered at the Naming Service and can be used as the factory object
  • Creating an EJB on the application server

To test an EJB:

  1. In the Workflow bar, click Start Here. The Load File Wizard opens.
  2. Alternative: In the Classes pane, right-click Remote Objects and choose New EJB to start the EJB Wizard directly. In this approach, skip the next two steps.
  3. Click the Enterprise JavaBeans / RMI over IIOP option button.
  4. Click Next. The Connect to Naming Server dialog box opens.
  5. If available, select the application server vendor from the Server list box.
    Note: The entries in the list work as a template that pre-configures other settings, like initial context factory, protocol, and port, with default values. For additional information regarding the configuration of specific application server types, see Vendor-Specific JNDI Settings.
  6. In the Factory text box, specify the context factory of the naming service.
  7. In the Host/Port text boxes, type the URL where the naming service provider is to be hosted. The naming server provider URL is comprised by protocol, host, and port. You can also type the URL directly into the Provider URL text box.
  8. If required by the provider, type the credentials in the User and Password text boxes.
  9. Click Edit Classpath .... The Classpath Configuration dialog box opens.
  10. Choose Static and click Add entries to classpath to specify the archives that are necessary to connect to the naming service of the application server.
  11. Choose Dynamic and click Add entries to classpath to specify the archives that contain the client stubs of the application. For vendor-specific details, refer to the application server documentation. For additional information on classpaths, see Classpath Settings.
  12. Click OK.
  13. Back on the EJB Wizard, click Next to connect to the naming service. The Look up and narrow a Home Interface or Remote Object dialog box opens.
  14. In the naming service sub-folders, select the EJB Home interface, represented by a "hand holding a coffee bean" icon, or the remote object, represented by a satellite dish icon, for which Java Explorer should obtain a reference. The corresponding client stubs must have been added to the classpath of the project.
  15. Click Finish. You can now use the Load File Wizard to browse for the methods of the remote object and to specify which test case the methods are to be called from.
    Note: EJBs which implement the EJBLocalObject interface instead of the EJBHome interface are not displayed correctly in the JNDI tree.
  16. Alternative: If you invoke the EJB Wizard directly by right-clicking Remote Objects in the Classes pane, you must perform the following two steps:
    1. Select the create() method of the EJB Home object to instantiate an EJB object. Store the EJB object to a variable.
    2. Invoke one or more methods on the EJB object.
Parent topic: Enterprise JavaBeans and RMI over IIOP
Related concepts
Vendor-Specific JNDI Settings


Vendor-Specific JNDI Settings

The application server vendor-specific default values are inserted automatically when you select the aproperiate server name in the Connect to Naming Service dialog box. The following vendor-specific default values exist:
  • initial context factory
  • protocol
  • port
Note: The naming service provider URL is comprised by protocol, host, and port.
  • Connecting to BEA WebLogic
    Use a BEA WebLogic server as the application server.
  • Connecting to IBM WebSphere
    Use an IBM WebSphere server as the application server.
  • Connecting to Sun
    Use a Sun server as the application server.
  • Connecting to JBoss
    Use a JBoss server as the application server.
Parent topic: Enterprise JavaBeans and RMI over IIOP


Connecting to BEA WebLogic

To connect to a BEA WebLogic server:
  1. In the Connect to Naming Service dialog box, choose WebLogic Application Server from the Server list box.
  2. From the Factory list box, choose weblogic.jndi.WLInitialContextFactory
  3. In the Provider Url text box, type t3://red:7001. The port may vary depending on the configuration of the server.
  4. Click Edit Classpath ... and specify the following server and client classpaths:
    1. In the Server Classpath text box, type the path to weblogic.jar. This file is provided by BEA and contains the WebLogic J2EE implementation and the implementation used for connecting to the naming mechanism of BEA WebLogic. The file has a size of about 40 MB and you can normally find it in a lib subdirectory of the BEA WebLogic home directory.
    2. In the Client Classpath text box, type all JAR files and classpaths that are required to connect to the EJB. You usually put the client-side stubs and additional classpath entries into the client classpath. WebLogic servers automatically generate the stubs when EJBs are deployed.
  5. Verify your settings and click Next. The names of all registered EJBs and RMI objects that are hooked into your WebLogic server are browsed.
  6. Choose the home interface that allows for the creation of instances of EJBs. It is typical for EJBs to have home interfaces that are used to create EJB instances. For example, choose ejb20-statelessSession-Traderhome to use the TraderHome interface.
  7. Click Finish.
  8. In the Load File Wizard, click Next. The home interface you have selected is browsed for the published methods it includes. A method named create is likely to be among these methods. Call this method to get a valid reference to an EJB object.
  9. Click Next and select the test case where Java Explorer should write code for the steps that are performed by the wizard. For example, you can put the steps that are referred to as bootstrapping into the init test case or an existing test case.
  10. Click Next.
  11. Check the Store as variable check box and type a name for the EJB reference obtained by the Java Explorer Wizard into the Variable name text box.
  12. Click OK. You can now call any of the EJBs business methods.
Parent topic: Vendor-Specific JNDI Settings
Related concepts
Java RMI
Test Case Characteristics
Animated Runs


Connecting to IBM WebSphere

To connect to an IBM WebSphere server:
  1. In the Connect to Naming Service dialog box, choose WebSphere Application Server from the Server list box.
  2. From the Factory list box, choose com.ibm.websphere.naming.WsnInitialContextFactory.
  3. In the Provider Url text box, type iiop://lab44:900. The port may vary depending on the configuration of the server.
  4. Click Edit Classpath ... and specify the following server and client classpaths:
    1. In the Server Classpath text box, type the path to csicpi.jar, which is the IBM implementation of J2EE. This file is provided by IBM and contains the IBM J2EE implementation.
    2. Additionally type the paths to the following required packages into the Server Classpath text box:
      WebSphere 4.x
      • ejbcontainer.jar
      • iwsorb.jar
      • j2ee.jar
      • jts.jar
      • ns.jar
      • ras.jar
      • ujc.jar
      • utils.jar
      • websphere.jar
      WebSphere 5.x
      • ffdc.jar
      • idl.jar
      • iwsorb.jar
      • j2ee.jar
      • naming.jar
      • namingclient.jar
      • ras.jar
      • wsexception.jar
      • ecutils.jar
      • tx.jar
      • utils.jar
      • ejbportable.jar
      • The properties directory, which is usually located in the WebSphere home directory.
      These files are shipped with each WebSphere installation and are normally found in the lib directory of WebSphere installations.
    3. In the Client Classpath text box, type all JAR files and classpaths that are required to connect to the EJB. You usually put the client-side stubs and additional classpath entries into the client classpath. WebSphere servers automatically generate the stubs when EJBs are deployed. You can normally find these stubs in the installedApps directory, which is located within the WebSphere home directory.
  5. Verify your settings and click Next. The names of all registered EJBs and RMI objects that are hooked into your WebSphere server are browsed.
  6. Choose the home interface that allows for the creation of instances of EJBs. It is typical for EJBs to have home interfaces that are used to create EJB instances. For example, choose cart to use the CartHome interface from the petstore sample.
  7. Click Finish.
  8. In the Load File Wizard, click Next. The home interface you have selected is browsed for the published methods it includes. A method named create is likely to be among these methods. Call this method to get a valid reference to an EJB object.
  9. Click Next and select the test case where Java Explorer should write code for the steps that are performed by the wizard. For example, you can put the steps that are referred to as bootstrapping into the init test case or an existing test case.
  10. Click Next.
  11. Check the Store as variable check box and type a name for the EJB reference obtained by the Java Explorer Wizard into the Variable name text box.
  12. Click OK. You can now call any of the EJBs business methods.
Parent topic: Vendor-Specific JNDI Settings
Related concepts
Java RMI
Test Case Characteristics
Animated Runs


Connecting to Sun

To connect to a Sun server:
  1. In the Connect to Naming Service dialog box, choose SUN J2EE Server from the Server list box.
  2. From the Factory list box, choose com.sun.jndi.cosnaming.CNCtxFactory
  3. In the Provider Url text box, type iiop://red:1050. The port may vary depending on the configuration of the server.
  4. Click Edit Classpath ... and specify the following server and client classpaths:
    1. In the Server Classpath text box, type the path to j2ee.jar. This file is provided by Sun and contains the J2EE implementation and the implementation used for connecting to the naming mechanism of Sun. You can normally find the file in a lib subdirectory of the J2EE home directory.
    2. In the Client Classpath text box, type all JAR files and classpaths that are required to connect to the EJB. You usually put the client-side stubs and additional classpath entries into the client classpath. Sun J2EE servers automatically generate the stubs when EJBs are deployed.
  5. Verify your settings and click Next. The names of all registered EJBs and RMI objects that are hooked into your Sun server are browsed.
  6. Choose the home interface that allows for the creation of instances of EJBs. It is typical for EJBs to have home interfaces that are used to create EJB instances.
  7. Click Finish.
  8. In the Load File Wizard, click Next. The home interface you have selected is browsed for the published methods it includes. A method named create is likely to be among these methods. Call this method to get a valid reference to an EJB object.
  9. Click Next and select the test case where Java Explorer should write code for the steps that are performed by the wizard. For example, you can put the steps that are referred to as bootstrapping into the init test case or an existing test case.
  10. Click Next.
  11. Check the Store as variable check box and type a name for the EJB reference obtained by the Java Explorer Wizard into the Variable name text box.
  12. Click OK. You can now call any of the EJBs business methods.
Parent topic: Vendor-Specific JNDI Settings


Connecting to JBoss

To connect to a JBoss server:
  1. In the Connect to Naming Service dialog box, choose JBoss Application Server from the Server list box.
  2. From the Factory list box, choose org.jnp.interfaces.NamingContextFactory
  3. In the Provider Url text box, type jnp://red:1099. The port may vary depending on the configuration of the server.
  4. Click Edit Classpath ... and specify the server and client classpaths. For additional information regarding the testing of JBoss application servers, contact Customer Care.
  5. Verify your settings and click Next. The names of all registered EJBs and RMI objects that are hooked into your JBoss server are browsed.
Parent topic: Vendor-Specific JNDI Settings


Working with RMI Over IIOP

To test RMI over IIOP:
  1. In the Workflow bar, click Start Here. The Load File Wizard opens.
  2. Click the Enterprise JavaBeans / RMI over IIOP option button.
  3. Click Next. The Connect to Naming Service dialog box opens.
  4. If available, select the application server vendor from the Server list box.
    Note: The entries in the list work as a template that pre-configures other settings, like initial context factory, protocol, and port, with default values. For additional information regarding the configuration of specific application server types, see Vendor-Specific JNDI Settings.
  5. In the Factory text box, specify the context factory of the naming service.
  6. In the Host/Port text boxes, type the URL where the naming service provider is to be hosted. The naming server provider URL is comprised by protocol, host, and port. You can also type the URL directly into the Provider URL text box.
  7. If required by the provider, type the credentials in the User and Password text boxes.
  8. Click Edit Classpath .... The Classpath Configuration dialog box opens.
  9. Choose Static and click Add entries to classpath to specify the archives that are necessary to connect to the naming service of the application server.
  10. Choose Dynamic and click Add entries to classpath to specify the archives that contain the client stubs of the application. For vendor-specific details, refer to the application server documentation. For additional information on classpaths, see Classpath Settings.
  11. Click OK.
  12. Back on the EJB Wizard, click Next to connect to the naming service. The Look up and narrow a Home Interface or Remote Object dialog box opens.
  13. In the naming service sub-folders, select the EJB Home interface, represented by a "hand holding a coffee bean" icon, or the remote object, represented by a satellite dish icon, for which Java Explorer should obtain a reference. The corresponding client stubs must have been added to the classpath of the project.
  14. Click Finish. You can now use the Load File Wizard to browse for the methods of the remote object and to specify which test case the methods are to be called from.
    Note: EJBs which implement the EJBLocalObject interface instead of the EJBHome interface are not displayed correctly in the JNDI tree.
Parent topic: Enterprise JavaBeans and RMI over IIOP
Related concepts
Vendor-Specific JNDI Settings


Testing the RMI Sample

To test the Silk Performer RMI sample:
  1. Launch the Product Manager RMI sample.
  2. Navigate to the <public user documents>\Silk Performer 21.0\SampleApps\RMILdap directory.
  3. Invoke the four batch files step1 through step4.
  4. In the Classes pane, right-click Remote Objects and choose New EJB. The EJB Wizard opens. The RMI objects are registered at a JNDI naming service.
  5. Type com.sun.jndi.cosnaming.CNCtxFactory into the Factory text box.
  6. Type iiop://localhost:1900 into the Provider Url text box.
  7. Click Edit Classpath ... and select <public user documents>\Silk Performer 21.0\SampleApps\RMILdap\RMILdap\ProductManager-server\ProductManager-server.jar.
  8. Back on the EJB Wizard, click Next to connect to the naming service. The Look up and narrow a Home Interface or Remote Object dialog box opens.
  9. Select the ProductManagerServicesLdap remote object. The RmiExtension helper class performs all necessary bootstrapping.
  10. Click the RmiExtension helper class in the Classes pane of the Loaded Components page.
  11. Click the createObject method of the class in the Input Data pane. The method includes a class to provide the parameters for the RMI connection settings.
  12. View the result of the createObject method in the Objects pane. The result is a stub class instance, which is used to communicate with the remote object on the server.
  13. Open the getProductsByName method in the Loaded Components page. The method requires a string as parameter. You can use * as a wildcard to get all products.
Parent topic: Enterprise JavaBeans and RMI over IIOP
Related concepts
Java RMI Samples


Java RMI

Java Explorer supports the following protocols for Java RMI:
  • RMI over IIOP
  • Java Remote Method Protocol (JRMP)
  • RMI Testing with JRMP
    Test RMI with JRMP to use an RMI registry.
Parent topic: Setting Up Tests
Related concepts
Enterprise JavaBeans and RMI over IIOP


RMI Testing with JRMP

The main difference between testing RMI with JRMP and testing RMI over IIOP is that with JRMP you need to connect to an RMI registry.

To test RMI with JRMP:

  1. In the Workflow bar, click Start Here. The Load File Wizard opens.
  2. Alternative: In the Classes pane, right-click Remote Objects and choose New RMI to start the RMI Wizard directly. In this approach, skip the next two steps.
  3. Click the RMI option button.
  4. Click Next. The Rmi Wizard dialog box opens.
  5. In the Host/Port text boxes, type the name and port of the host. For example, type localhost and 1099.
  6. Click Add archive(s) to classpath and specify the location of the RMI interfaces for the client. For example, <public user documents>\Silk Performer 21.0\SampleApps\Java\Lib\sampleRmi.jar.
  7. Back on the EJB Wizard, click Next to view all registered remote objects in the RMI registry. The Look up and narrow a Remote Object dialog box displays all registered remote objects in the RMI registry.
  8. Choose RemoteServer and click Next. The methods of the remote object are browsed.
  9. Select the first two methods by checking the appropriate check boxes.
    • echoFloat(float)
    • echoString(string)

    The selected methods are implemented by the sample RMI server. The other methods are inherited from base classes and don't need to be tested.

  10. Click Next and select the test case from which the methods should be called.
Parent topic: Java RMI


Testing Java Archives

Java archives normally contain many classes that need to be tested.

To test a Java archive:

  1. In the Workflow bar, click Start Here. The Load File Wizard opens.
  2. Click the Java Archive option button.
  3. Click Browse ... to browse for the JAR file that contains the classes to be tested. For example, load sampleBasis.jar. This archive is selected by default.
  4. Click Next. The Testing Java Classes dialog box opens.
  5. In the Class text box, type the name of the class to be tested.
  6. Choose the constructor of the class from the Constructor list box.
  7. Click Next. The instance of the class is created and the created object is browsed for the methods it includes.
  8. In the Method Invocation dialog box, select the toString method.
  9. Click Next.
  10. Choose a test case where Java Explorer should add the created scenario. The method toString returns a string. Therefore, Java Explorer asks you whether it should store the returned value or discard it.
Parent topic: Setting Up Tests


Test Class Wizard

You can create a test for a class or an instantiated object with the Test Class Wizard. To use the wizard, select a class in the Classes pane or an object in the Object pane and call the wizard, either through the context menu or the Workflow bar. You can also select methods that are to be called with the wizard.

Parent topic: Setting Up Tests


Secure Web Services

You can configure Java Explorer for the testing of secure Web services.

To test secure Web services, the following steps are required:
  • Create a truststore for your JDK.
  • Load a secure WSDL into Java Explorer.
  • Invoke Web service calls over a secure connection.

Java Explorer supports authentication of Web services. Use the Connection Settings dialog box to specify your credentials.

  • Creating a Truststore for Your JDK
    Create a truststore for your JDK to enable testing of a Web application.
  • Configuring Java Explorer to Use a Truststore
    Configure Java Explorer to use a truststore.
  • Loading a Secure WSDL
    Load a secure WSDL document into Java Explorer.
  • Working with Secure Web Service Calls
    Configure Java Explorer to use Apache Axis 1.4 or later to test secure Web services.
  • Specifying Web Service Connection Settings
    Specify the web service connection settings to configure Web service authentication.
  • Web Service Emitter Timeout for Axis 1.x
    Describes how you can specify a longer timeout for the process of generating the Java source code.
Parent topic: Setting Up Tests


Creating a Truststore for Your JDK

When you work with secure Web services, the Web service clients must trust the Web applications they interact with to be secure. The Web service client is typically a Web browser, but in this case the client is Java Explorer. To enable testing of a Web application, Java Explorer must accept the server certificate of the application or trust the certifying authority who issues the server certificate.

Your JDK installation includes a command-line tool called keytool. You can manage server certificates and certifying authorities with this tool. The easiest way of downloading server certificates is to export them from your Web server.

To create a truststore for your JDK:

  1. Export a CER certificate file from your Web browser to your local system. For information on exporting a certificate, refer to the Help of your browser.
  2. To add the saved certificate to your truststore, which is called mykeystore, enter the following into the command-line tool of your system:
    keytool
-import
-alias <alias name>
-file c:\<pathname>\<certificate file name>
-keystore mykeystore
    The command-line tool creates a file called mykeystore in your current working directory.
Parent topic: Secure Web Services


Configuring Java Explorer to Use a Truststore

Set the system property -Djavax.net.ss.trustStore=trustedcerts to configure a Java process to use a truststore. When you work with Java Explorer, you can specify the system properties in property files that reside at <Java Explorer Home>/Startup directory.

To configure Java Explorer to use a truststore:

  1. Open ./startup/gui.properties in a text editor.
  2. Add the following line:
    system.property.javax.net.ssl.trustStore=C:\\Temp\\mykeystore
  3. Open ./startup/runtime.properties in a text editor.
  4. Add the following line:
    system.property.javax.net.ssl.trustStore=C:\\Temp\\mykeystore
  5. Restart Java Explorer.
Parent topic: Secure Web Services


Loading a Secure WSDL

To load a secure WSDL document into Java Explorer:
  1. Copy the URL of the WSDL file into the address bar of Java Explorer.
  2. Press Enter.
    Note: Ensure that you have configured Java Explorer to use a truststore that accepts the server certificate of the URL.
  3. If loading the WSDL document fails, try the following:
    1. Open the WSDL document in a Web browser.
    2. Save the WSDL document to your local machine.
    3. Open the document with Java Explorer.
Parent topic: Secure Web Services
Related tasks
Setting Up a Test Using the Load File Wizard


Working with Secure Web Service Calls

To execute Web service calls over a secure connection, ensure that you have created a truststore for your JDK and that you have configured the Java Explorer Runtime process to use a truststore.

Note: Use Apache Axis 1.4 or later to test secure Web services.

To configure Java Explorer to use Apache Axis:

  1. Click Tools > Project Settings.
  2. Click the Web Service Plugin tab.
  3. Select Axis 1.4 or Axis2 1.5 from the Assigned Web Service Plugin list box.
    Note: The read-only Classpath pane displays the classpath configuration that belongs to the selected Axis version.
    The selected Axis version is stored persistently in the project file of Java Explorer.
  4. Click OK.
  5. Click Yes to confirm that you want to change the Web service library settings.
Parent topic: Secure Web Services
Related tasks
Creating a Truststore for Your JDK
Configuring Java Explorer to Use a Truststore


Specifying Web Service Connection Settings

To specify Web service connection settings:

  1. In the Loaded Components pane, click the Classes tab.
  2. Choose the loaded Web service class node to display the Input Data Properties.
  3. In the Input Data Properties pane, click ... to the right of the Connection text box.
  4. Configure the Web service endpoint and your user credentials.
  5. Click OK. Java Explorer saves your connection settings.
Parent topic: Secure Web Services


Web Service Emitter Timeout for Axis 1.x

Note: You do not need to specify timeouts with Axis2, as Axis2 handles timeouts itself.
When you generate Web service stub code for large WSDL files, the process of generating the Java source code may take longer than the default timeout specified by the Axis library. In such a case, the following exception is generated:
com.segue.jexplorer.datatyp.exception.JExpWsdlException:
Failed to generate Web Service proxy library(webAxisProxy1.jar).:
Failed to create java source from WSDL.:
java.io.IOException:WSDL2Java emitter timed out (this often means the WSDL
at the specific URL is inaccessible)!
at com.seque.jeplorer.runtime.plugin.impl.webservice.axis.JExpAxisProxyGen
.generateProxyLibrary(JExpAxisProxyGen.java:272) at
com.segue.jexplorer.runtime.plugin.impl.webservice.axis.JExpAxisProxyGen
.generateProxy(JExpAxisProxyGen.java:138) at
com.segue.jexplorer.runtime.communication.JExpRuntimeOperation
.generateWebServiceProxy(JExpRuntimeOperation.java:772)

You can specify a WSDL2Java emitter timeout in a configuration file called webservice.properties. The property in the file must be called emitter.timeout. The value must be specified in milliseconds.

The file is located under <install dir>\Java Explorer\Startup\webservice.properties and has the following content:
# For generating Web Service stub code with axis libraries
# a timeout in milliseconds may be specified for the emitter to
# generate the source files
emitter.timeout=5000
Parent topic: Secure Web Services


Negative Testing

Although extended support for negative testing is not available, you can ignore the expected exceptions.

Parent topic: Setting Up Tests


Animated Runs

Animated runs or test runs execute all test methods that are assigned to your test cases, with corresponding input and output data displayed in the Input Data and Output Data windows as they are submitted/received. Status symbols indicate the success/failure status of method calls after they have run.

Output of animated runs includes several logs and reports that help you to identify problems with tested components.

To configure settings for animated runs go to Tools > System Settings > Options. The following settings are available:

  • Always run Init Test Case
  • Always run End Test Case
  • Run all Test Cases during Animated Run
  • Invoke Delay, which is the time delay between method calls, in ms
Note: By default, there is a 2-second (2000 ms) delay between the invocation of method calls. This is because Java Explorer is designed to test the functionality of components, but not to overtax them with excessive load. Invocation delay settings can be configured on the Options page.
  • Executing an Animated Run
    Execute an animated run to execute all test methods that are assigned to your test cases, with corresponding input and output data displayed in the Input Data and Output Data windows.
  • Viewing Status of Animated Runs
    Explains that depending on the number of times a test case is called, which is defined by the CallCount property, you can see which iteration is currently executing in the Test Scenario window. You can also see the status of each test case and method.
Parent topic: Java Explorer Help


Executing an Animated Run

To execute an animated run:

  1. Click Run Test on the Workflow bar. The Animated Run dialog box displays.
  2. Alternative: Click Run > Animated Run.
  3. Check the check boxes that correspond to the test cases that are to be executed during the test run:
    • InitTestCase
    • TestCase
    • EndTestCase
    The default selections vary based on your option settings.
    Note: When test cases depend on each other for accessing global objects, ensure that you do not exclude test cases that define objects that are used by other test cases.
  4. Check the Do verifications check box to specify that verifications that are defined for output parameters should be performed.
  5. Click OK to begin the animated run.

    If you have specified a different calling count for your test cases than 1, the test cases are executed the number of times defined in this property.

    If the number of method calls reporting an error exceeds the number of allowed errors defined in the test case properties, the test case is aborted.

    Note: Animated runs can be aborted manually by either hitting Esc on your keyboard or by selecting Stop Run from the Run menu. Animated runs are aborted automatically when a verification with severity Error, the simulation is aborted fails.
    All global variables are initialized to their initial values. All random variables are reset.
Parent topic: Animated Runs


Viewing Status of Animated Runs

Depending on the number of times a test case is called, which is defined by the CallCount property, you can see which iteration is currently executing in the Test Scenario window. Each test case and test method has one of the following status icons:
Status Icon
Description
Green checkmark
OK
Blue V icon
Verified
Yellow triangle with exclamation mark
Warning
Red X
Error

Methods that fail due to thrown exceptions or failed verifications display failed or warning method call icons next to them. If a method call fails you can view a description of the failure by holding your cursor over the method.

Parent topic: Animated Runs


Analyzing Results

Once you have completed a test run, you can view the following three result files to assist you in analyzing test results:
Result File
Description
User report
View the user report generated during the last animated run. The report contains statistical information about each test case and each test method call.
Error report
View the error report generated during the last animated run. The report contains a description for every error that occurred.
Animation log
This file contains information about every method that has been called with their parameters and errors that occurred.
  • Viewing Result Files
    Open the Explore Results dialog box to select a result type.
  • User Report
    Explains that the user report offers information regarding time elapsed for each test case and test-method call.
  • Error Report
    Explains that the error report delivers an overview of all errors that occur during test runs.
  • Animation Log
    Explains that the animation log on the Output tab displays real-time information about the methods that were called in the most recent test run.
  • Exploring Object Properties
    Explore the properties of objects with Java Explorer.
  • Exploring Method Properties
    Explore the properties of methods with Java Explorer.
Parent topic: Java Explorer Help


Viewing Result Files

Before proceeding with this task you must execute a test.

  1. Click Results on the Workflow bar to display the Explore Results dialog box.
  2. Select the result type you want to generate.
  3. Alternative: You can also select result files from the Java Explorer Results menu or by clicking the Output tab above the Loaded Components pane.
Parent topic: Analyzing Results
Related tasks
Executing an Animated Run


Animation Log

The animation log on the Output tab displays real-time information about the methods that were called in the most recent test run. Additional information about passed parameters is also included. When exceptions are encountered, the animation log offers detailed stack traces for the exceptions.

You can access the animation log at any time by clicking the Output tab.

Parent topic: Analyzing Results


Exploring Object Properties

To explore the properties of an object:
  1. Click the Objects tab below the Loaded Components pane.
  2. Right click the object and select Quick Info. The Quick Info dialog box displays the internal state of the selected object.
  3. Optional: In the Quick Info dialog box, you can additionally view the following oroperties of an object:
    • Click Statics to display the static fields of the object.
    • Click None Public to display the private, package, and protected fields of the object.
    • Click Base Types to display the parent classes of the object.
Parent topic: Analyzing Results


Exploring Method Properties

To explore the properties of a method:
Right click the object in the Loaded Components pane and select Properties. The Method Properties dialog box displays the following properties:
  • Name
  • Input parameter types
  • Output parameter type
  • Exceptions
  • Modifiers
Parent topic: Analyzing Results


System and Project Settings

Java Explorer offers a number of system and project setting options.

  • System Settings
    Describes the system setting options that Java Explorer provides.
  • Project Settings
    Describes the project setting options that Java Explorer provides.
Parent topic: Java Explorer Help


System Settings

System settings are saved in the file JExplorer.conf located at C:\ProgramData\Silk\Silk Performer 21.0.

  • Accessing System Settings
    Access the Java Explorer system settings to edit the system setting options.
  • Processes
    Describes the processes that run when you start Java Explorer.
  • Configuring Default Value Settings
    Use the Default Values tab to change the input value parameters for method calls.
  • Configuring Verification Settings
    Configure the verification settings to change the behavior of verifications.
  • Configuring Code Generation Settings
    Configure the code generation settings to define how code is generated when you export to a standalone application, JUnit, or a Silk Performer Java Framework project.
  • Configuring Animated Run Settings
    Configure the animated run settings to define the behavior of animated runs.
  • Deleting Loaded-File Entries in History
    Open the loaded-file entries list to delete the classes, archives, and WSDL URLs that are loaded to Java Explorer.
  • Connection Settings
    Describes how you can define the default proxy connection that is used to communicate with a Web service.
  • JUnit Settings
    Describes how you can select the TestRunner that is used to run JUnit tests.
  • Silk Performer Settings
    Describes how you can configure the home directory and the project directory for Silk Performer.
Parent topic: System and Project Settings


Accessing System Settings

  1. Click Tools > System Settings. The System Settings dialog box opens.
  2. Click the tab that corresponds to the options you wish to configure. The dialog box provides the following tabs:
    • Runtime
    • Default Values
    • Options
    • History
    • Connection
    • JUnit
    • Silk Performer
Parent topic: System Settings


Processes

When you start Java Explorer, at least two processes are run. The first process displays the Java Explorer GUI and runs under SDK 1.4. The second process is the runtime process. This process instantiates and manages all Java objects that belong to the currently open project. The runtime process can run under any JDK. You can configure the JDK in the Project Settings dialog box.

The runtime process is started with the JDK that is configured and is initialized with the static classpath entries. After the runtime process is initialized, the UrlClassLoader is initialized with the dynamic classpath entries.

Parent topic: System Settings
Related concepts
Project Settings
Java Explorer Prerequisites


Configuring Default Value Settings

You can change the input value parameters for method calls. You can set default values for the following value types:
  • Default boolean, which can either be true or false.
  • Default double, which stands for all floating-point numbers.
  • Default int, which stands for all integer numbers.
  • Default string.
  1. Click Tools > System Settings. The System Settings dialog box opens.
  2. Click the Default Values tab.
  3. Click on the value that you wish to change and type the new value.
  4. Click OK to confirm your changes.
Parent topic: System Settings


Configuring Verification Settings

  1. Click Tools > System Settings. The System Settings dialog box opens.
  2. Click the Options tab.
  3. In the Verifications section, check the check boxes that correspond to the settings that you want to activate. The following options define the behavior of verifications:
    Option
    Description
    Automatically define a verification for stored values
    If checked, the default verifications are defined whenever you store an output value in a variable.
    Ignore Case (default value)
    If checked, the verification of string values in the Verification Wizard is case insensitive. By checking or unchecking this check box, you also check or uncheck the Ignore Case check box in the Verification Wizard.
    Check verifications during animated runs
    If checked, the verification is activated during animated runs. By checking or unchecking this check box, you also check or uncheck the Do Verifications check box on the Animated Runs dialog box.
  4. Click OK to confirm your changes.
Parent topic: System Settings


Configuring Code Generation Settings

  1. Click Tools > System Settings. The System Settings dialog box opens.
  2. Click the Options tab.
  3. In the Code Generation section, check the check boxes that correspond to the settings that you want to activate. The following options define how code is generated when you export to a standalone application, JUnit, or a Silk Performer Java Framework project:
    Option
    Description
    Try-Catch block in every method
    By checking or unchecking this check box, you also check or uncheck the init test case in the Verification Wizard.
    Verifications
    If checked, adds verifications to the generated code.
    Silk Performer Measures
    If checked, adds Silk Performer MeasureStart and MeasureStop functions to the generated Silk Performer Java Framework code. For additional information about measures, refer to Silk Performer Help.
  4. Click OK to confirm your changes.
Parent topic: System Settings
Related tasks
Defining Output Value Verifications


Configuring Animated Run Settings

  1. Click Tools > System Settings. The System Settings dialog box opens.
  2. Click the Options tab.
  3. In the Animated Run section, check the check boxes that correspond to the settings that you want to activate. The following options define the behavior of animated runs:
    Option
    Description
    Always run init test case
    By checking or unchecking this check box, you also check or uncheck the init test case on the Animated Run dialog box.
    Always run end test case
    By checking or unchecking this check box, you also check or uncheck the end test case on the Animated Run dialog box.
    Run all test cases during animated run
    By checking or unchecking this check box, you also check or uncheck all test cases on the Animated Run dialog box.
  4. To define the delay in milliseconds between the invocation of method calls in an animated run, type the delay into the Invoke Delay text box.
  5. Click OK to confirm your changes.
Parent topic: System Settings


Deleting Loaded-File Entries in History

Java Explorer tracks all classes, archives, and WSDL URLs that are loaded. Instead of typing the full name, you can select an entry from the history list if the class is loaded.

To delete loaded-file entries:

  1. Click Tools > System Settings. The System Settings dialog box opens.
  2. Click the History tab.
  3. Select the file that you want to delete in the Loaded file entries list box.
  4. Click Delete.
  5. Click Yes to confirm the deletion of the file entry.
Parent topic: System Settings


Connection Settings

Tools > System Settings > Connection

The Connection dialog box enables you to define the default proxy connection that is used to communicate with a Web service. The specified connection is also used to load a WSDL file from the Internet.

When you load a WSDL file, the Web service class inherits the settings in the Connection dialog box. If you change the settings in the dialog box after the Web service class is loaded, the changes are not reflected in the Web service class.

Parent topic: System Settings


JUnit Settings

Tools > System Settings > JUnit

The JUnit dialog box enables you to select the TestRunner that is used to run JUnit tests from the Kind of TestRunner to use list box. In the Archives necessary to run JUnit section, you can click the Add archive(s) to classpath button to specify the classpath information that is required to run the selected TestRunner.

Parent topic: System Settings


Silk Performer Settings

Tools > System Settings > Silk Performer

You can configure the home directory and the project directory for Silk Performer with the Silk Performer dialog box. The initial settings are detected by the Java Explorer setup.

Parent topic: System Settings


Project Settings

This section describes the project setting options that Java Explorer provides.

  • Configuring Runtime Settings
    Add a JDK version to the system to assign the version to your project.
  • Configuring Web Service Plug-In Settings
    Configure Java Explorer to use Apache Axis 1.4 or later to test secure Web services.
  • Configuring Classpath Settings
    Configure the classpath settings to define the classpaths that are used by Java Explorer.
  • Configuring Scripting Settings
    Explains that the Scripting dialog box defines the file names that are used to export the Java Explorer project.
Parent topic: System and Project Settings


Configuring Runtime Settings

To enable a specific JDK version for a project:

  1. Click Tools > System Settings. The System Settings dialog box opens.
  2. Click Add next to the Target JDK list box and browse for the Java Home Directory. For example, the Sun JDK version 1.4 might be installed under C:\j2sdk1.4.2_04. The IBM JDK version might be installed under C:\WebSphere\AppServer\java.
  3. Click OK. You can now select the added JDK version from any project.
  4. Click Tools > Project Settings. The Runtime tab of the Project Settings dialog box opens.
  5. Select the JDK from the Assigned Runtime list box.
  6. Click OK. The Java Runtime is now assigned to the current project.
Note: When you change the active JDK, the runtime process is restarted. Perform an animated run to update the objects in the runtime.
Parent topic: Project Settings


Configuring Web Service Plug-In Settings

Java Explorer supports Axis 1.4, Axis2 1.4 or later, and GlassFish Metro 1.5 out of the box.

Note: Use Apache Axis 1.4 or later to test secure Web services.
Note: Metro does not work with JDK 1.6 unless you install the latest JDK 1.6 updates.

To select a specific SOAP stack version for the project:

  1. Click Tools > Project Settings. The Runtime dialog box opens, and you can assign the SOAP stack version that is used for the current project.
  2. Click the Web Service Plugin tab.
  3. Select a SOAP stack library version from the Assigned Web Service Plugin list box and click OK. The Properties list box displays the classpath configuration that belongs to the selected SOAP stack version.
  4. Restart the Java Explorer runtime process to change the selected SOAP stack version.
  5. Click Yes to confirm the restart.
Parent topic: Project Settings


Configuring Classpath Settings

To configure the classpath settings:

  1. Click Tools > Project Settings.
  2. Click the Classpath tab.
  3. Add static classpaths to or remove static classpaths from the Static list. The static classpaths include entries that are defined as static or system classpaths. These entries are set when the runtime is created. When you change a static or system class you need to restart the runtime.
  4. Add classpaths to or remove classpaths from the Jdk list. The entries in the list reflect the classpaths for the currently configured JDK.
  5. Add classpaths to or remove classpaths from the Dynamic list. The entries in the list are dynamically added to the UrlClassLoader in the runtime process. When you add an entry to the list or change an entry, you do not need to restart the runtime.
  6. Check the Restart Runtime Process check box to restart the Java Explorer runtime process. The check box fulfills two purposes. Firstly, it signals if changes made to the classpaths require the restart of the runtime process, and secondly it allows you to explicitly force a restart of the runtime process.
  7. Check the Show Full Classpath check box to display all the internally used classpath entries. By default, only the static, dynamic, and JDK classpath entries are displayed and can be customized. When you check the check box, all other classpath entries, for example the Java Explorer archives, the Web service plug-ins, and others, are also visible. This is helpful for expert users and certain internal purposes, for example if you want to see if an archive of a test of a customer environment conflicts with a Web service plug-in.
    Note: The classpath tree is ordered by priority. Archives at the top of the tree have priority over archives at the end. You can move the entries up and down within a group or even between neighboring groups, unless the groups are read-only.
    Note: Check boxes indicate whether a classpath is static or dynamic, which means whether a change to the classpath group requires a restart of the runtime process or not.
  8. Optional: You can also edit runtime-specific classpath entries through the Project Settings dialog box.
    Note: The runtime classpath belongs to the System Settings and changes to it effect all projects. The classpath is stored in both the JExplorer.conf system settings file and the JEP project file. When you load a project, if the classpath entries in the project file do not match the classpath settings in the system settings, the system settings override the stored project settings.
Parent topic: Project Settings
Related concepts
Processes


Configuring Scripting Settings

The Scripting dialog box defines the file names that are used to export the Java Explorer project.

To configure the scripting settings:

  1. Click Tools > Project Settings.
  2. Click the Scripting tab.
  3. Type the file name of the exported Java test class for the Silk Performer Java Framework into the TestClass for Silk Performer text box.
  4. Type the file name of the exported JUnit test class into the TestClass for JUnit text box. This class extends junit.framework.TestCase.
  5. Type the file name of the exported standalone test class into the TestClass for Standalone text box. You can execute the class from the command line or integrate it into other test frameworks.
  6. Type the name of the BDL script file, that is generated for the Silk Performer Java Framework, into the TestScript for Silk Performer text box.
Parent topic: Project Settings


Exporting Projects

Once you have defined your test scenario you can either continue running tests in Java Explorer or you can export the underlying test code to the following environments:
Environment
Description
Silk Performer Java Framework Project
Export to Silk Performer to run tests based on the scenario you have defined in Java Explorer.
JUnit Test Case
Export to JUnit to directly execute the test cases with the JUnit Run Test Suite.
Standalone Console Application
Run the test scenario as a standalone application, independent of Java Explorer, or use the test scenario to record Web traffic with Silk Performer.
  • Exporting a Java Explorer Project
    Export test scenarios to other test environments to continue testing.
  • Silk Performer Java Projects
    Describes how to export projects to Silk Performer.
  • JUnit Test Cases
    Describes how to export projects to JUnit.
  • Standalone Console Applications
    Describes how you can use standalone console applications.
Parent topic: Java Explorer Help


Exporting a Java Explorer Project

To export a Java Explorer project:
  1. Click Export.
  2. Click on one of the following buttons to select the environment to which you want to export the test scenario:
    • Java Project Silk Performer
    • JUnit Test Case
    • Standalone Console Application
  3. Specify a name for the exported file in the corresponding text box.
  4. Specify a destination for the exported file in the Directory text box. By default, Java Explorer saves projects to the project directory at <my documents>\Silk Performer 21.0\Projects.
    Note: If you are calling a Web service in the Internet, ensure that you have set the correct proxy in Tools > Project Settings > Classpath.
Parent topic: Exporting Projects


Silk Performer Java Projects

You can create Silk Performer Java projects with the Java class and a BDF file that contains the calls to the Java class. The Java Profile Settings are saved in the Silk Performer project file, so the same Java Runtime and classpath settings are used in Java Explorer and Silk Performer. You can compile the Java test class in the Silk Performer GUI. When you start a test or a try-script run, the Java compiler and the BDL compiler are automatically invoked.

Java Explorer exports the following files to Silk Performer:
  • The Silk Performer project file, which is of type LTP.
  • The Silk Performer script file, which is of type BDF.
  • The Java test script, which is of type JAVA.
  • Silk Performer Java Framework
    Describes how you can use the Silk Performer Java Framework to coordinate development and testing efforts.
  • Working with Multiple Agents
    Configure your testing environment to enable the Java Framework to perform as intended.
Parent topic: Exporting Projects


Silk Performer Java Framework

The Silk Performer Java Framework enables developers and QA personnel to coordinate their development and testing efforts while working within their specialized environments. The developers work exclusively in their Java-programming environment while the QA personnel work exclusively in Silk Performer. The Silk Performer Java Framework thereby encourages efficiency and a tighter integration of QA and development.

Exporting to Silk Performer is valuable for QA personnel who are proficient in facilitating analysis of Java components with Silk Performer and wish to create Silk Performer projects, test case specifications, and scripts from which they can run tests.

When you directly export a project to Silk Performer as a Java project, a default Silk Performer project file of type LTP is created. You can then test a project with multiple virtual users. You can also gather and analyze performance data for each method call in the project.

Parent topic: Silk Performer Java Projects
Related concepts
Java Framework Approach


Working with Multiple Agents

Usually, load testing with Silk Performer is done through multiple agents. To enable the framework to work smoothly:
  1. Install a JDK on each agent machine. The version of the JDK should be the same version, or later, as the one used for the Java Explorer project.
    Note: Install the JDK in the same directory on each machine.
  2. Ensure that the same classpath is available on each agent machine. For example, to load test a WebLogic EJB, you must install the package weblogic.jar in the same directory on each agent machine. The same applies to EJB stubs.
Parent topic: Silk Performer Java Projects


JUnit Test Cases

JUnit is a widely used regression testing framework. You can export JUnit TestSuites with Java Explorer. The export generates a Java test class for JUnit and two batch files for compiling and running the test class. For additional details on JUnit, visit https://bugs.eclipse.org/bugs/.

  • Exporting a JUnit TestSuite
    Export your test scenario as a JUnit TestSuite to perform regression tests.
  • Test Case Execution Sequence
    Describes the differences in the test case execution sequence between Java Explorer and JUnit.
Parent topic: Exporting Projects


Exporting a JUnit TestSuite

To export a JUnit TestSuite:
  1. Click Export > JUnit Test Case.
  2. Click Open Dialog ... next to the File Name text box. The Scripting page of the Project Settings dialog box opens.
  3. Specify a name for the exported file in the Test Class for JUnit text box.
  4. Click OK. The Project Settings dialog box closes.
  5. Click Browse ... next to the Directory text box to select the target directory.
  6. Check the Open Test Suite in JUnit check box to start the JUnit testrunner directly from the Java Explorer GUI.
  7. Click OK. Java Explorer confirms that the settings are correct. If the settings are not correct, the JUnit page of the System Settings dialog box opens. You can select the TestRunner that is to be used to run JUnit tests from the Kind of TestRunner to use list box. The Add archive(s) to classpath button next to the Archives necessary to run JUnit box enables you to specify the classpath information required to run the selected TestRunner.
Parent topic: JUnit Test Cases


Test Case Execution Sequence

There are differences in the way that JUnit and Java Explorer run tests. In JUnit TestSuites, values and global variables that need to be initialized in the init() test case cannot be passed from one test case to the next.

Example

The execution sequence of the following Java Explorer project, that contains an init() test case, an end() test case, and two test cases, is:
  1. InitTestCase
  2. TestCase1
  3. TestCase2
  4. EndTestCase
In JUnit, the execution sequence of the same project is:
  1. InitTestCase (setUp)
  2. TestCase1 (testMethod1)
  3. EndTestCase (tearDown)
  4. InitTestCase (setUp)
  5. TestCase2 (testMethod2)
  6. EndTestCase (tearDown)
Parent topic: JUnit Test Cases


Standalone Console Applications

With Java Explorer, you can compile the test cases in a test scenario into a standalone console application, which is a Java class that can run independent of Java Explorer, for example from the commandline. A standalone console application calls all test methods in the main method.

You can use standalone console applications to either run test scenarios independent of Java Explorer, or to generate network traffic that can be recorded by Silk Performer. Silk Performer can generate Web BDL scripts based on such network traffic.

  • Exporting Standalone Console Applications
    Export a standalone console application to either run test scenarios independent of Java Explorer, or to generate network traffic that can be recorded by Silk Performer.
  • Recording a Standalone Console Application
    Record a standalone console application to create a Web BDL script with all the HTTP/TCP calls of the application to a Web service.
Parent topic: Exporting Projects


Exporting Standalone Console Applications

  1. Click Export > Standalone Console Application. The Export Standalone Java application dialog box opens.
  2. Type a name for the exported standalone console application into the File name text box.
  3. Click Browse ... next to the Directory text box and select the destination directory for the standalone console application.
  4. Click OK. A JAVA and a BAT file are saved to the current project directory by default.
  5. Open a command prompt in the folder to which you have exported the standalone console application.
  6. Run <project name>.bat, where <project name> is the name of your current Java Explorer project.
  7. Check the status information which is listed in the command window.
Parent topic: Standalone Console Applications


Recording a Standalone Console Application

To record a standalone application with Silk Performer:
  1. Launch Silk Performer.
  2. Click File > New Project and create a new Web project.
  3. Create a new recording profile for the standalone console application.
  4. Specify a name for the profile.
  5. Specify the path to the batch file.
  6. Specify Custom Application as the application type.
  7. Select Winsock.
  8. Begin recording the application. After recording you should have a Web BDL script that contains all the HTTP/TCP calls of the console application to a Web service.
Parent topic: Standalone Console Applications


Java Framework Developer Guide

  • Tools and Samples
    Explains the tools, sample applications and test projects that Silk Performer provides for testing Java and .NET.
  • Testing Java Components
    Explains that the Java Framework encourages efficiency and tighter integration between QA and development by enabling developers and QA personnel to coordinate their development and testing efforts while working entirely within their specialized environments.
  • Java Framework
    Explains that as a powerful extension to the Silk Performer Benchmark Description Language, the Java Framework enables you to implement user behavior in Java.
Parent topic: Java Testing Support


Java Framework

As a powerful extension to the Silk Performer Benchmark Description Language, the Java Framework enables you to implement user behavior in Java. When testing an existing Java application you do not need to spend much time creating test scripts. The only effort required is embedding existing Java source code into the framework.

  • Java Framework Overview
    Explains the basic requirements for generating a benchmark executable within the Java Framework.
  • Using Java Code for Load Testing
    Explains how to transfer Java code to the Silk Performer Workbench, where you can use it to execute load tests.
  • Switching between 32-bit and 64-bit Java
    Explains how to switch between 32-bit and 64-bit Java and what the Java architecture effects during test execution.
  • Java Framework Architecture
    The Java Framework is the technology that connects Java and BDL and hence opens up a variety of possibilities.
  • Runtime-to-Java Communication
    Explains the functions that are available for invoking the methods of a Java class from within a test script.
  • Java-to-Runtime Communication
    Explains the functionality offered by the SilkPerformer class. Also covers sample Java Framework applications and installation requirements.
  • Programming With Java Framework
    Explains how to implement a Java Framework test project using Silk Performer.
  • Visual Programming with Java Explorer
    Explains that Java Explorer offers a convenient alternative to scripting test classes by hand.
  • Structure of a Java Framework Project
    Explains that Java Framework projects consist of at least one BDL script, one or more Java source files, class files (compiled Java files), and/or JAR files (collections of class files).
  • Advanced Usage
    Explains that when working with a Java Framework script template you are only required to have a basic knowledge of the available Java Framework functions.
  • Java Test Class
    Explains that within a Silk Performer test script, the Java test class enables you to implement the behavior of virtual users in Java.
  • JVM Option Settings
    Explains how to use JavaSetOption to determine options such as Java version, Java home directory, and the class path.
  • Java User Implementation (deprecated)
    Lists deprecated technology that is outdated and has been replaced by newer technology.
Parent topic: Java Framework Developer Guide


Java Framework Overview

To generate a benchmark executable and run a load test with the help of the Java Framework, two source files are normally required:

  • A Java class, with the file extension .java. It implements the behavior of a virtual user.
  • A Silk Performer test script with the file extension .bdf. It invokes Java method calls.

Silk Performer lets you call Java methods of any Java object from a BDL context including passing parameters of any type and number. Return values can be retrieved equally. When a Java method returns a complex object, a handle to the Java object is returned in its place. The handle can be passed to other method calls as an input parameter, or public methods may be invoked on the object. There is also support for static methods, cast operations, and exception handling.

Java-based tests are driven by BDL scripts. BDL implements a set of functions that enable you to:

  • Set JVM options
  • Load a JVM
  • Load Java classes
  • Invoke methods on loaded Java classes

The silk.performer package provides the SilkPerformer class, which enables the Java side to communicate with the Silk Performer's runtime system. It exposes a set of testing methods that are also available in BDL.

Parent topic: Java Framework


Using Java Code for Load Testing

The Silk Performer Java Framework allows you to model virtual users in Java code, access useful functionality from Silk Performer's runtime environment, and it helps you to generate the necessary BDL stub code where necessary.

There are a number of ways to integrate your Java code. The diagram below shows the options you have:

  • Your first option is to script Java code within your preferred Java IDE.
    • When you work with Eclipse, you can use the Silk Performer Eclipse plugin. It lets you export your code wrapped in a Silk Performer Java Framework project and open it in the Workbench.
    • When you work with another Java IDE, first build .jar files from your source files. Then use Silk Performer's import tools: the JUnit import tool for JUnit tests and the Java Class import tool for generic Java code. This way Silk Performer generates all necessary stub code for you.
  • Your second option is to write Java code directly within the Workbench. Create a Java Framework project and write your code into the .java file, which is automatically created, using Silk Performer's editor. Silk Performer offers syntax highlighting and allows to compile the Java code using the configured Java Development Kit within the Workbench.
  • Your third option is to create Java code within Java Explorer. Java Explorer lets you create code visually, so you do not have to write your code manually. Transferring the Java code from Java Explorer to the Silk Performer Workbench is easy due to the seamless integration of the two solutions.

Depending on how you import Java code to the Workbench, Silk Performer creates different sets of files within the Java Framework project. This results in different call sequences. The diagram below shows three types of call sequences:

  • Sequence 1 is the default call sequence. Note that the communication between BDL and the Java wrapper is bidirectional. This means that you can call Java code from the .bdf script and Silk Performer functionality from the .java script. Code within the .java file can then call code from further classes or .jar files.
  • Sequence 2A applies when Java code is imported using the Java Class Import tool. In this case, Java code that is part of the .jar files is directly called from BDL.
  • Sequence 2B applies when JUnit tests are imported using the JUnit Import tool. Java code within .jar files is called from BDL - just like in sequence 2 A. However, in this case the .jar file consists of the unit test (which itself is a .jar file), which again can call Java code from other .jar files.

Parent topic: Java Framework
Related concepts
Java Support
JUnit Integration


Java Framework Architecture

The Java Framework is the technology that connects Java and BDL and hence opens up a variety of possibilities.

It enables you to utilize your Java code for
  • functional testing,
  • load testing, and
  • monitoring.
Using the Java Framework, you can test and monitor server components through a variety of Java technologies, like
  • EJB,
  • SOAP,
  • RMI,
  • or JDBC.
It enables you to both create new and use existing Java code, by
  • visual creation,
  • manual scripting, or
  • importing.
It offers you to use a number of tools to do so like
  • the Silk Performer Workbench
  • Eclipse or any other Java IDE
  • specialized import tools
  • Java Explorer

For more information, see Using Java Code for Load Testing.

The Java Framework BDL API is the "membrane" between the generic Silk Performer BDL code and Java code. All the possibilities to communicate from BDL to Java is covered by Runtime-to-Java Communication, the reverse direction of the communication is described in Java-to-Runtime Communication.

Parent topic: Java Framework
Related tasks
Programming With Java Framework


Runtime-to-Java Communication

Silk Performer provides the following functions for invoking the methods of a Java class from within a test script:

  • JavaSetOption: Sets options for the Java Virtual Machine.
  • JavaCreateJavaVM: Initializes and starts the Java Virtual Machine (JVM).
  • JavaLoadObject: Instantiates a Java object and returns a handle on it.
  • JavaLoadString: Instantiates a Java string object and returns a handle on it.
  • JavaCallMethod: Invokes either a dynamic or a static Java method.
  • JavaFreeObject: Frees a Java object.
  • JavaCastObject: Casts an object to a type of your choice.
  • JavaGetBoolean: Retrieves the Boolean return value.
  • JavaGetFloat: Retrieves the float return value.
  • JavaGetNumber: Retrieves the int return value.
  • JavaGetObject: Retrieves a handle on the object returned by the last call of JavaCallMethod on the specified object or class.
  • JavaGetString: Retrieves the string return value
  • JavaGetUserObject: Returns the handle on the JavaUser object loaded by JavaUserInit command.
  • JavaSetChar: Sets a char parameter for the next function or constructor call.
  • JavaGetChar: Retrieves the ordinal number of the char return value.
  • JavaSetBoolean: Sets a Boolean parameter for the next function or constructor call.
  • JavaSetFloat: Sets a float parameter for the next function or constructor call.
  • JavaSetNumber: Sets a numeric parameter for the next function or constructor call.
  • JavaSetObject: Sets an object parameter for the next function or constructor call.
  • JavaSetString: Sets a string parameter for the next function or constructor call.
  • JavaSetByteArray: Convenience function derived from JavaSetString function.
  • JavaSetCharArray: Convenience function derived from JavaSetString function.
  • JavaRegisterException: Registers a Java exception string under a custom error number.
  • JavaUnregisterErrorNumber: Unregisters an exception message.
  • JavaGetLastException: Retrieves the last exception message.

Convenience function to call JUnit test methods:

  • JUnitCallMethod: Invokes a JUnit conform method of a class derived from junit.framework.TestCase. Prepares the method execution by invoking the setUp() method and finishes the test by invoking the tearDown() method.

Deprecated Java Framework functions:

  • JavaUserInit: Calls the JavaUserInit method of the Java class that implements the behavior of the virtual user.
  • JavaUserRun: Calls the JavaUserRun method of the Java class that implements the behavior of the virtual user.
  • JavaUserMethod: Calls an additional method of the Java class that implements the behavior of the virtual user.
  • JavaUserShutdown: Calls the JavaUserShutdown method of the Java class that implements the behavior of the virtual user.
Parent topic: Java Framework


Java-to-Runtime Communication

Silk Performer Class

Note: For detailed information on all Java Framework classes and methods, view the Java documentation (HTML). The Java documentation is located in your Silk Performer installation folder: \Silk\Silk Performer <version>\Doc\JavaFramework

The SilkPerformer class is used to access runtime information and to forward user information to the Silk Performer runtime environment. Here is the functionality offered by the SilkPerformer class:

  • Measure functions for timers and counters
  • Synchronization of users (checkpoint = rendezvous) (global functions)
  • Extended file functions (file load functions)
  • Output functions for logging and errors (Print, Write and Rep functions)
  • Global attribute get and set functions accessible from both Java and BDL (AttributeSet, AttributeGet functions)
  • Test functions (Get functions)
  • Random functions (Rnd functions)
  • Date time format functions (format functions

Class Files

The silk.performer package contains classes that enable the Java user implementation to communicate with the Silk Performer runtime environment. The class files are bundled in the javaUserFramework.zip archive. See the Classfiles folder in the installation home directory.

  • SilkPerformer class
  • FileEx
  • MeasureCounter
  • MeasureTimer
  • PrintStream
  • ReflectionUtil

Java Framework Template

A reference implementation of a BDL script called NewJavaFramework.bdf is included.

Sample Java Class

A sample Java class belonging to a BDL script called NewJavaFramework.java is included.

Sample Applications

Three online samples are available. The sample files and related documentation are available at: <public user documents>\Silk Performer 21.0\Samples\JavaFramework\.

  • Java Framework sample: This sample demonstrates the basic usage of the Java Framework API.
  • Java RMI and JDBC: These samples demonstrate how to use the Java Framework API for RMI and JDBC replay.
  • BankSample: This sample demonstrates some advanced features of the Java Framework API.

Installation Requirements

A Java Virtual Machine compatible with Oracle’s Java Runtime Environment (JRE) 7 or 8 must be installed on each agent machine. Note however that a full installation of a Java Development Kit (JDK) is recommended so that manually created Java test classes can be compiled.

Parent topic: Java Framework


Programming With Java Framework

Explains how to implement a Java Framework test project using Silk Performer.

  1. Add a new Java Framework script to your project. Within Silk Performer, choose File > New > Java Framework Scripts (.bdf/.java).
  2. Enter a name for the Java class, for example Testclass. Then Save the .bdf and .java templates.
  3. Open the Java class by double clicking it in the Project tree menu. Implement the desired Java test code in one or more member functions of the Java class. For example, public void doFoo() throws SilkPerformerException. If you prefer, you can open and modify the Java class in an IDE instead. Note that Java Explorer offers powerful scripting functionality.
  4. Modify the BDF file and make sure that the methods of the Java class are called with correct parameters. Use JavaSet<Datatype> functions to set the function parameters. Use JavaGet<Datatype> functions to retrieve return values.
  5. Open Profile settings and configure a Java Virtual Machine for the test run. If the Java class requires additional Java archives, add them to the classpath. The project directory is added to the classpath automatically and does not have to be configured explicitly.
  6. Invoke a Try Script run. The Java and BDL script will then be compiled automatically.
Parent topic: Java Framework


Visual Programming with Java Explorer

Rather than scripting test classes by hand, Java Explorer offers a convenient means of creating projects for testing web services, Enterprise Java Beans, and remote objects. Any existing Java Explorer project can be exported to Silk Performer.

Parent topic: Java Framework


Structure of a Java Framework Project

A Java Framework project consists of at least one BDL script. Additionally, a project may contain one or more Java source files, class files (compiled Java files), and/or JAR files (collections of class files).

The structure of the BDL script follows the standard syntax. It usually consists of an Init transaction, in which the Java environment is initialized, one or several transactions defining user behavior, and an end transaction in which the Java environment is deleted. The BDL script is used as a starting point for the Java runtime initialization while later in the script. execution of virtual user behavior, or at least part of it, is transferred to the Java environment. This is done by instantiating Java objects within the VM and invoking methods on them.

A Java test class template and corresponding test script can automatically be generated by choosing File > New > Java Framework Scripts (.bdf/.java). A dialog box opens. Enter the name of the Java test class that is to be generated.

BDL scripts for invoking existing Java test classes and existing JUnit test classes can easily be created using the Java / JUnit import tool.

  • User Group Definitions
    Shows how the users to be simulated are defined in the workload section of your test script.
  • Initialization Transaction
    Explains that the first transaction enables virtual machine initialization. Also details the function calls that must be performed with the transaction.
  • Java Method Calls
    Explains the main transactions that allow you to define the actions that a virtual user is to perform during a test.
  • Parameterized Java Method Calls
    Explains that attribute functions can be used to pass parameters from BDL to Java code and that you can call test methods in a Java test class that expect or return simple or complex parameters.
  • End Transaction
    Explains that an end transaction, executed at the end of a test, implements user termination.
Parent topic: Java Framework


User Group Definitions

The users to be simulated are defined in the workload section of the test script. A virtual user is denoted by the transactions to be called, along with their frequency.

Usually, user behavior implementation is divided into at least three separate parts: initialization, user actions, and shutdown. Note the user group definition in the BDL sample below:

dcluser
  user
    JavaUser
  transactions
    TInit         : begin;
    TMyJavaTrans  : 1;
    TEnd          : end;

Here is a BDL sample that includes multiple transactions:

dcluser
  user
    JavaUser
  transactions
    TInit           : begin;
    TMyTransaction1 : 5;
    TMyTransaction2 : 2;
    TMyTransaction3 : 8;
    TEnd            : end;
Parent topic: Structure of a Java Framework Project


Initialization Transaction

The first transaction executed in a test enables virtual machine initialization. The following function calls must be performed within this transaction:

JavaCreateJavaVM() initializes and starts the Java Virtual Machine.

JavaSetOption() starts the Java Virtual Machine. Several parameters are required, including home directory, Java version, and classpath. These may be configured in the Java section of the active profile or scripted by the JavaSetOption command.

JavaLoadObject is used to create a Java object. It is necessary to instantiate the class where the Java test code resides. For example, if the Java test code was implemented in a class called Test.java, the following method call would instantiate the class and store a handle on it in a global variable. The handle is used whenever a reference to the test class is required.

hTestObj := JavaLoadObject("Test");

If the Java test class calls SilkPerformer functions, then a reference to the SilkPerformer context object must be passed to the testclass. The SilkPerformer context object must be instantiated first, then the handle on it can be passed to the constructor of the test class by the JavaSetObject command.

hPerf := JavaLoadObject("silk/performer/SilkPerformer");
JavaSetObject(JAVA_STATIC_METHOD, hPerf);

The corresponding code in the test class must be a constructor that takes the SilkPerformer context object as a parameter. It makes sense to store the context object as a member variable so that it can be used by all method calls in the Java test class.

private SilkPerformer SilkPerformer = null;
public Test(SilkPerformer perf)
{
  SilkPerformer = perf;
}

To avoid memory leaks, references to Java objects in BDL should be freed by the JavaFreeObject command. The handle on the SilkPerformer context object is only used in the TInit transaction, so it can be freed at the end of the transaction. Note that only the reference to the object is freed, the Java object itself remains alive as long as there are Java references to it. The handle on the instantiated test object is needed throughout the test. It is freed in the TEnd transaction.

JavaFreeObject(hPerf);

Implementation of the initial transaction should resemble the following:

var
  hTestObj   : number;

dcltrans
  transaction TInit
  var
    hPerf : number;
  begin
    JavaCreateJavaVM();

    hPerf := JavaLoadObject("silk/performer/SilkPerformer");
    JavaSetObject(JAVA_STATIC_METHOD, hPerf);
    hTestObj := JavaLoadObject("Test");
    JavaFreeObject(hPerf);
  end TInit;
Parent topic: Structure of a Java Framework Project
Related concepts
Instantiating Java Objects
Java Test Class
Related reference
JavaSetObject Function
JavaCreateJavaVM Function
JavaFreeObject Function


Java Method Calls

The main transactions allow you to define most of the actions that a virtual user is to perform during a test. These actions are defined in any member method of the Java test class, which is defined in the respective Java script. To call a test method called doFoo for example, the main transaction in the test script would contain the following function call:

JavaCallMethod(hTestObj, "testFoo") calls the testFoo method of the Java test class that is defined in the respective Java source file, for example Test.java.

Here is an example TMyJavaTrans transaction:

dcltrans
  transaction TMyJavaTrans
  begin
    JavaCallMethod(hTestObj, "doFoo");
  end TMyJavaTrans;
Note: To create a custom timer measure for a Java or JUnit method call, specify the timer name as the third optional parameter of the respective JavaCallMethod or JUnitCallMethod command.
Parent topic: Structure of a Java Framework Project
Related reference
JavaCallMethod Function


Parameterized Java Method Calls

As long as test code is parameterized in the Java test class, it may be sufficient to call simple Java methods that do not take parameters or have return values. Often however it is desirable to customize test code in BDL and execute it in Java. Attribute functions can be used to pass parameters from BDL to Java code, but with Silk Performer it is also possible to call test methods in a Java test class that expect or return simple or complex parameters.

To call a test method that takes parameters, use the following function calls prior to invoking the test method:

  • JavaSetNumber( in hObject : number, in nParam : number, in sType : string optional );
  • JavaSetBoolean( in hObject : number, in bParam : boolean );
  • JavaSetFloat( in hObject: number, in fParam : float, in sType : string optional );
  • JavaSetObject( in hObject : number, in hParam : number, in sType : string optional );
  • JavaSetString( in hObject : number, in sParam : string allownull );
  • JavaSetChar( in hObject : number, in nParam : number );
  • JavaSetByteArray( in hObject : number, in sParam : string allownull, in nLen : number optional );
  • JavaSetCharArray( in hObject : number, in sParam : string allownull, in nLen : number optional );

The first parameter of the functions must be a valid handle on a Java object, usually the handle on the Java test object that was retrieved in the TInit transaction.

The data type of the first parameter of the Java test method must match the first usage of the JavaSet* function, and so on. In parameters are only valid for the following method call on a referenced object.

To call a test method that returns a parameter, use the following function calls after invoking the test method:

  • JavaGetBoolean( in hObject: number ): boolean;
  • JavaGetFloat( in hObject: number ): float;
  • JavaGetNumber( in hObject: number ): number;
  • JavaGetObject( in hObject : number ): number;
  • JavaGetString( in hObject : number, out sBuffer : string, in nBufLen : number optional );
  • JavaGetChar( in hObject: number ): number;

Here is an example parameterized Java method call:

dcltrans
  transaction TMyJavaTrans
  var
    fValue : float;
  begin
    // set the first parameter
    JavaSetString(hTestObj, "1");
    // set the second parameter
    JavaSetNumber(hTestObj, 1);
    // invoke the method
    JavaCallMethod(hTestObj, "doFoo");
    // retrieve the result
    fValue := JavaGetFloat(hTestObj);
    Print("doFoo returned "+String(fValue));
  end TMyJavaTrans;
Parent topic: Structure of a Java Framework Project
Related reference
JavaSetNumber Function
JavaSetBoolean Function
JavaSetFloat Function
JavaSetObject Function
JavaSetString function
JavaGetNumber Function
JavaGetFloat Function
JavaGetString Function


End Transaction

The end transaction, executed at the end of a test, implements user termination. This transaction should free all references on all remaining Java test objects.

JavaFreeObject(in hObject: number) takes a handle on a Java object as a parameter and frees all references to it.

Here is an example end transaction:

dcltrans
transaction TEnd
  begin
    JavaFreeObject(hTestObj);
  end TEnd;
Parent topic: Structure of a Java Framework Project
Related reference
JavaFreeObject Function


Advanced Usage

Using a Java Framework script template requires that you have only a basic knowledge of the available Java Framework functions. If a Java test driver is already available for reuse, then a template project can be generated in which the Java test class acts as an interface between the original test driver and the Silk Performer script.

Java test drivers can also be invoked directly from Silk Performer scripts. Normally, you have to update the BDL script, the Java test class, and the Java test driver. By calling the Java test driver directly, you avoid having to update the Java test class. To call a test driver directly from BDL, additional syntax is often required to call static and overloaded methods or to reuse complex objects.

  • Static Java Method Calls
    Explains how to invoke and define input parameters for static Java methods
  • Distinguishing Java Methods
    Explains that input parameters specified with JavaSet* functions must exactly match the formal data type of the Java function. Also includes a Java exception example.
  • Instantiating Java Objects
    Explains how the JavaLoadObject function is used to instantiate Java objects, and additionally obtain handles on Java objects.
  • Java Objects as Return Parameters
    Explains how the JavaGetObject function can be used to retrieve a handle on complex Java objects.
  • Exception Handling of Java Method Calls
    Explains that each exception that is not handled by the invoked Java method itself is thrown to the BDL script where a native Java error is raised.
Parent topic: Java Framework


Static Java Method Calls

Static methods can be invoked just like any other method using the JavaCallMethod function. Since static methods are defined on a Java class and not on a Java object, the constant JAVA_STATIC_METHOD must be used in place of a handle to a Java object, for example hTestObj. The second parameter defining the method name now begins with the fully qualified class name, where the method is defined, then a '.' symbol, and then the method name. A fully qualified class name means that the package that contains the class must also be specified. Use the '/' symbol as a separator between subpackages.

JavaCallMethod(JAVA_STATIC_METHOD, "test/mypackage/Test.doFoo") calls the static doFoo method of the Test class in the mypackage subpackage in the package test.

Like member methods, static methods may also expect and return parameters. To define an input parameter for a static method, use the following function calls prior to invoking the test method:

  • JavaSetNumber(JAVA_STATIC_METHOD, in nParam : number, in sType : string optional );
  • JavaSetBoolean(JAVA_STATIC_METHOD, in bParam : boolean );
  • JavaSetFloat(JAVA_STATIC_METHOD, in fParam : float, in sType : string optional );
  • JavaSetObject(JAVA_STATIC_METHOD, in hParam : number, in sType : string optional );
  • JavaSetString(JAVA_STATIC_METHOD, in sParam : string allownull );
  • JavaSetChar(JAVA_STATIC_METHOD, in hObject : number, in nParam : number );
  • JavaSetByteArray(JAVA_STATIC_METHOD, in hObject : number, in sParam : string allownull, in nLen : number optional );
  • JavaSetCharArray(JAVA_STATIC_METHOD, in hObject : number, in sParam : string allownull, in nLen : number optional );

The datatype of the first parameter of the static Java test method must match the first usage of the JavaSetParameter function, and so on. In parameters are only valid for the following static method call.

To call a static Java method that returns a parameter, use the following function calls after invoking the test method:

  • JavaGetBoolean(JAVA_STATIC_METHOD): boolean;
  • JavaGetFloat(JAVA_STATIC_METHOD): float;
  • JavaGetNumber(JAVA_STATIC_METHOD): number;
  • JavaGetObject(JAVA_STATIC_METHOD): number;
  • JavaGetString(JAVA_STATIC_METHOD, out sBuffer : string, in nBufLen : number optional );
  • JavaGetChar(JAVA_STATIC_METHOD, in hObject: number ): number;

Here is an example of a parameterized static Java method call:

dcltrans
  transaction TMyStaticJavaTrans
  var
    fValue : float;
  begin
    ThinkTime(0.2);
    // set the first parameter
    JavaSetString(JAVA_STATIC_METHOD, "1");
    // set the second parameter
    JavaSetNumber(JAVA_STATIC_METHOD, 1, JAVA_BYTE);
    // invoke the method
    JavaCallMethod(JAVA_STATIC_METHOD, "test/mypackage/Test.doFoo");
    // retrieve the result
    fValue := JavaGetFloat(JAVA_STATIC_METHOD);
    Print("doFoo returned "+String(fValue));
  end TMyStaticJavaTrans;

Additional Samples

<public user documents>\Silk Performer 21.0\Samples\JavaFramework\JavaFrameworkSample.bdf

<public user documents>\Silk Performer 21.0\Samples\JavaFramework\JavaFrameworkSample.java

Parent topic: Advanced Usage
Related reference
JavaSetNumber Function
JavaSetBoolean Function
JavaSetFloat Function
JavaSetObject Function
JavaSetString function
JavaGetNumber Function
JavaGetBoolean Function
JavaGetFloat Function
JavaGetString Function


Distinguishing Java Methods

Input parameters specified with JavaSet* functions must exactly match the formal data type of the Java function. Some BDL functions, such as JavaSetNumber, can be used for more than one Java data type. The third optional parameter of the BDL function allows you to distinguish between the various Java data types (in the following example, byte, short, int, and long_.

Java code example

public void doFoo(byte b) {}
public void doFoo(int i) {}

BDL code example

JavaSetNumber(hTestObj, 127, JAVA_BYTE);
JavaCallMethod(hTestObj, "doFoo");

If the actual parameters specified by JavaSet* functions and the formal parameters of the Java method do not match, a java.lang.NoSuchMethodError exception will be thrown.

The following sample shows such a NoSuchMethodError.

Native: 1007 - Java Exception, Native Error 3:
java.lang.NoSuchMethodError: doFoo, Test, doFoo((F))

The log output shows that no method named doFoo defined in a class Test could be found with the method signature doFoo((F)). As abbreviations for the method parameters, standard Java element type encoding is used.

Additional Samples

<public user documents>\Silk Performer 21.0\Samples\JavaFramework\JavaFrameworkSample.bdf

<public user documents>\Silk Performer 21.0\Samples\JavaFramework\JavaFrameworkSample.java

Parent topic: Advanced Usage


Instantiating Java Objects

The JavaLoadObject function is used to instantiate Java objects, and additionally obtain handles on Java objects. Such handles can later be used to call methods on objects or they can be used as input parameters for other method calls. For the JavaLoadObject function, you must provide fully qualified names of classes to instantiate them as parameters. The ‘/’ character must be used as a package separator.

For example, to instantiate a Java object of class java.util.ArrayList in a TMain transaction, the BDL code looks like this:

  transaction TMain
  var hList : number;
  begin
    // invoking constructor of java.util.ArrayList
    hList := JavaLoadObject("java/util/ArrayList");
    // use the object
    // ...
    // free reference on the object when done
    JavaFreeObject(hList);
  end TMain;

If a Java class has a constructor that takes parameters, use JavaSet* functions to set those parameters. In the Java Framework, constructor calls are treated like static method calls, so use the constant JAVA_STATIC_METHOD instead of an object handle as the first parameter for JavaSet* functions.

For example, to invoke the constructor ArrayList(int initialCapazity) of class java.util.ArrayList in a TMain transaction, the BDL code looks like this:

  transaction TMain
  var hList : number;
  begin
    // putting necessary parameters on the stack
    JavaSetNumber(JAVA_STATIC_METHOD, 100);
    // invoking constructor of java.util.ArrayList
    hList := JavaLoadObject("java/util/ArrayList");
    // use the object
    // ...
    // free reference on the object
    JavaFreeObject(hList);
  end TMain;

The JavaLoadString function was introduced for convenience; it simplyfies the instantiation of java.lang.String objects.

To create a custom timer measure for a Java object instantiation, specify the timer name as the third optional parameter of the respective JavaLoadObject or JavaLoadString command.

Parent topic: Advanced Usage


Java Objects as Return Parameters

Java method calls can return complex Java objects. The JavaGetObject function can be used to retrieve a handle on such objects. Java objects can also be used as input parameters for other Java method calls. The JavaSetObject function is used for this purpose.

Input parameters specified with the JavaSetObject function must exactly match the formal parameters of the Java method call. If the formal and actual data type do not match exactly, but their assignments are compatible, then a kind of cast operation must be performed. For example, the formal data type is java.lang.Object. The actual datatype is java.lang.String. Strings are assignment compatible to objects.

One time cast operation: The third optional parameter of the JavaSetObject function allows you to specify the data type that is to be used for the next Java method call.

transaction TMyJavaTrans
var
  hValue :number;
  hVector :number;
begin
  hValue := JavaLoadString("myValue");
  hVector := JavaLoadObject("java/util/Vector");
  JavaSetObject(hVector, hValue, "java/lang/Object");
  JavaCallMethod(hVector, "add");
end TMyJavaTrans;

A java.util.Vector object expects a java.lang.Object object as parameter for its add method. So, as shown above, the Java string hValue must be treated as a java.lang.Object object for the call of the add method. Therefore the third optional parameter of JavaSetObject is set to java/lang/Object.

Permanent cast operation: If a Java object that is referenced in BDL code needs to have a specific data type for several Java method calls, then the JavaCastObject function can be used to permanently change the data type of the object.

transaction TMyJavaTrans
var
  hValue :number;
  hVector1 :number;
  hVector2 :number;
begin
  hVector1 := JavaLoadObject("java/util/Vector");
  hVector2 := JavaLoadObject("java/util/Vector");
  hValue := JavaLoadString("myValue");
  JavaCastObject(hValue, "java/lang/Object");

  JavaSetObject(hVector1, hValue);
  JavaSetObject(hVector2, hValue);
  JavaCallMethod(hVector1, "add");
  JavaCallMethod(hVector2, "add");
end TMyJavaTrans;

The actual datatype of a referenced Java object in BDL is slightly different from what is commonly considered to be the actual datatype of an object in the Java world. If an object is retrieved from a collection class, then the actual data type of the referenced object equals the formal data type of the method used to access the object.

transaction TMyJavaTrans
var
  hObj :number;
  hVector :number;
begin
  hVector := JavaLoadObject("java/util/Vector");
    … /* some methods filling the Vector */
  JavaSetNumber(hVector, 0);
  JavaCallMethod(hVector, "elementAt");
  hObj := JavaGetObject(hVector);
end TMyJavaTrans;

So in the BDL context, the actual data type of the hObj reference is java/lang/Object, because the formal return value of the elementAt method is java/lang/Object. The real actual data type of the Java object in the Java virtual machine is unknown.

You can pass a null object to a Java method call. The following function call can be used to define a null parameter:

JavaSetObject(hTestObj, JAVA_NULL_OBJECT);

Parent topic: Advanced Usage
Related reference
JavaSetObject Function
JavaGetObject Function
JavaCastObject Function


Exception Handling of Java Method Calls

Each exception that is not handled by the invoked Java method itself is thrown to the BDL script where a native Java error is raised. The raised error contains the name of the exception class and the exception message. However, the raised error does not contain the stack trace of the exception.

The exception stack trace, which belongs to the native Java error, is written to the virtual user log file.

  JavaCallMethod()
  {
    handle       = 0x012fdde8
    Meth. name   = "doFakeScenario"
    return value = false
    Exception    = "java.lang.RuntimeException: something unexpected thrown in my java code
    at Test.anotherSubMethod(Test.java:40)
    at Test.aSubMethod(Test.java:35)
    at Test.doFakeScenario(Test.java:47)
"
  }

Developers often rely on output written to the command console when debugging Java applications. When doing a Try Script run, all command console output of the Java application is captured as RepMessage with severity informational. These messages can be viewed in the VU output console and the virtual user report file.

Advanced Exception Handling

Each exception that is not caught by the Java test driver is thrown to the BDL script, where an error under facility Native Java (1007) is raised. In most cases the error subcode is 0. To distinguish different Java exceptions in BDL, error subcodes can be assigned to specific exception messages. Use JavaRegisterException to assign an error subcode to a specific Java exception. These error subcodes can be helpful for other BDL functions, such as ErrorAdd, which can be used to change the severity of errors.

Parent topic: Advanced Usage
Related concepts
Virtual User Report Files
Related reference
JavaRegisterException Function
JavaUnregisterException Function
JavaUnregisterErrorNumber Function
ErrorAdd Function


Java Test Class

Within a Silk Performer test script, the Java test class enables you to implement the behavior of virtual users in Java. You can use all available Java classes to create user behavior that is as realistic as possible; you can also use a number of Silk Performer functions that can be accessed through an instance of the SilkPerformer class.

  • Java Test Class Overview
    Explains what is required to implement the Java test class. Also details use of some member methods that contain Java test code.
  • Members
    Explains that an instance of the SilkPerformer class enables access to each of the functions provided by the Silk Performer runtime system.
  • Constructor
    Explains that the constructor of the Java test class is required to assign a SilkPerformer context object to the previously defined member.
  • Example Test Method
    Explains that any number of member or static methods may be called within a Silk Performer test script.
Parent topic: Java Framework


Java Test Class Overview

A Java test class template can be generated automatically by choosing New > Java Framework Scripts (.bdf/.java). A dialog box opens, requesting the name of the Java test class that is to be generated.

To enable use of Silk Performer functions, the implementation of the Java test class must contain the following:

  • Instance of the SilkPerformer class
  • Constructor to enable access to the Silk Performer runtime system

Additionally, there can be any number of member methods containing Java test code. An automatically generated Java test class will contain one member method, for example:

public void doFoo()

These elements are detailed below:

Required Package

To access several functions that are provided by the Silk Performer runtime system, you must import the SilkPerformer class. This class is provided in the silk.performer package. The javaUserFramework.zip file, located in the Classfiles subfolder of the Silk Performer home directory, is automatically included in the classpath.

Default classpath entries such as javaUserFramework.zip are defined in perfrun.xml in the Silk Performer home directory.

At the beginning of your Java script, import the SilkPerformer class using the following statement:

import silk.performer.SilkPerformer;

Class Definition

The Java test class is defined immediately following the import statement. If Test is chosen as the name of the Java test class, the class definition in the Java script will appear as follows:

public class Test
{
  ...
}
Parent topic: Java Test Class


Members

As a member of the Java test class, an instance of the SilkPerformer class enables access to each of the functions provided by the Silk Performer runtime system. The member is initialized when the constructor of the Java test class is called.

private SilkPerformer SilkPerformer = null;
Parent topic: Java Test Class


Constructor

The constructor of the Java test class is required to assign a SilkPerformer context object, which is an instance of the SilkPerformer class, to the previously defined member called SilkPerformer. The SilkPerformer context object is passed to the constructor through the constructor’s parameter. The constructor definition should resemble the following:

public Test(SilkPerformer perf)
{
  SilkPerformer = perf;
}
Parent topic: Java Test Class


Example Test Method

Any number of member or static methods may be called within a Silk Performer test script. The methods may take any basic or complex parameters and have any return values. The only restriction is that arrays of basic and complex parameters are not supported.

As a member method example, here is the implementation of the doFoo() method:

public void doFoo() throws SilkPerformerException
{
  if (SilkPerformer != null)
    SilkPerformer.Print("Method \"Foo\" entered.");
  SilkPerformer.MeasureStart("Foo");
  SilkPerformer.MeasureStop("Foo");
}
Note: Any method invoked on the SilkPerformer context object can throw a SilkPerformer exception, for example when the execution of the test is stopped. SilkPerformerException must not be caught by the test code. Exceptions must be thrown on the method caller, which is the Silk Performer runtime.
Parent topic: Java Test Class


JVM Option Settings

The JavaSetOption(<option id>, <option string>) BDL function can be used to determine options such as Java version, the Java home directory, and the class path. This function and the allowed option identifiers are defined in the Java.bdh file.

It is recommended that you set Java options in the profile settings. When Java options are set in both profile settings and BDL the settings made in BDL take precedence.

Note: When using the Eclipse plug-in, the Java settings defined in Eclipse have precedence over all other settings.

Option Identifiers

  • JAVA_VERSION - (must be defined) Determines the JVM version (1.1.x, 1.2.x, 1.3.x, or 1.4.x).
  • JAVA_HOME - (recommended) Determines the installation directory of the JVM that should be used for replay. Loading of the JVM is independent of the PATH environment, so it is possible to switch between JVMs without changing the system PATH environment.
  • JAVA_CLASSPATH - (recommended) Determines the class path for the JVM. The system class path is appended by default (-classpath).
  • JAVA_DLL - Allows you to specify an individual DLL file path for implementing the JVM that is to be loaded.
  • JAVA_VERBOSE - Enables the verbose option (-verbose) of the JVM. By default, this option is disabled.
  • JAVA_DISABLE_COMPILER - Disables the JIT (Just In Time compiler) of the JVM. By default the JIT is enabled.
  • JAVA_CMDLINE_OPTIONS - Enables you to specify any commandline options that are to be passed to the JVM.
  • JAVA_USE_SYSTEM_CLASSPATH - Determines that the system class path should be appended. By default it is appended.
  • JAVA_DESTROY_JVM_ON_SHUTDOWN - When not set (the default), the current thread is detached from the JVM upon shutdown, but the JVM is not destroyed. When the option is set, all Java threads are killed and the JVM is destroyed upon shutdown. Note that to do this, JVMDI must be enabled by setting -Xdebug -Xnoagent -Djava.compiler=NONE in the commandline options.
  • JAVA_SUPPRESS_EXCEPTIONS – When not set (the default), Java exceptions raise BDL errors. When set, Java exceptions are suppressed and must be checked manually using the JavaGetLastException() command

Examples

  • JavaSetOption(JAVA_VERSION, JAVA_V14); // JVM v1.4.x

    JavaSetOption(JAVA_HOME, "j2sdk1.4.0_01");

    JavaSetOption(JAVA_CLASSPATH, "c:/myApplication/classes;c:/myTools/tools.zip");

    JavaSetOption(JAVA_DISABLE_COMPILER, YES);

    JavaSetOption(JAVA_CMDLINE_OPTIONS, ENABLE_JVMDI);

Parent topic: Java Framework


Java User Implementation (deprecated)

This topics lists deprecated technology that is outdated and has been replaced by newer technology.

The Java User methodology simplifies use of the Java Framework. The Java User class works as an additional layer between BDL and the Java application under test. It defines a JavaUserInit(), a JavaUserShutdown() function, and optionally, a JavaUserRun() or custom methods, all with Boolean return values.

The Init transaction in BDL must call the JavaUserInit() function, the End transaction must call the JavaUserShutdown() function. Any further BDL transactions may either call the JavaUserRun() function or one of the custom methods. A Silk Performer object, for enabling Java-to-runtime Communication, is automatically passed to the Java User class.

  • Public JavaUserImplementation(SilkPerformer perf) // Constructor
  • Public Boolean JavaUserInit() throws Exception
  • Public Boolean JavaUserRun() throws Exception // optional
  • Public Boolean anyMethodName throws Exception // optional
  • Public Boolean JavaUserShutdown() throws Exception
Parent topic: Java Framework


TrueLog Explorer 21.0

Welcome to TrueLog Explorer 21.0.

TrueLog Explorer supports Silk Performer testing efforts with a framework from which you can customize test scripts and perform exhaustive analysis of returned test results.

With an array of tools and reports, TrueLog Explorer helps you build automatic content verification into scripts, insert parsing functions for static session data, and gain insight into the root causes of errors via TrueLog On Error functionality.

  • Getting Started
    Provides overview information regarding TrueLog Explorer, TrueLog files, analyzing tests, and the sample applications.
  • Customizing Session Handling
    Illustrates how to parse out hard-coded session data that sometimes appears in record TrueLogs. Session-handling customization enables you to maintain state information during testing.
  • Adding Verifications
    Explains how to create verification checks for HTML page titles, HTML content, HTML tables, and HTML source code.
  • Customizing User Data
    This section explains how user-input data can be parameterized to better emulate real-world user activity during load testing.
  • Working With Database Applications
    Explains how to apply TrueLog Explorer script-customization features to the testing of applications that rely on common database APIs.
  • Working With XML Applications
    Describes the script-customization and TrueLog-analysis features that are provided for the testing of XML-based applications.
  • Working With SAPGUI Applications
    For SAPGUI-based applications, TrueLog Explorer offers TrueLog recording, TrueLog replay, basic TrueLog analysis, data parsing, content verification, and user-input data customization.
  • Working With Oracle Forms Applications
    Explains how to customize an Oracle Forms test script based on the results of a Try Script run.
  • Working With Citrix Applications
    Explains that in addition to offering TrueLog recording, TrueLog replay, and basic TrueLog analysis for the testing of applications that are hosted by Citrix servers, TrueLog Explorer also offers user-input data customization.
  • Working With TCP/IP and UDP-Based Applications
    Explains how to apply TrueLog On Error and test-script analysis features to the testing of TCP/IP and UDP protocol based applications.
  • Working With Terminal-Emulation Applications
    Explains how to customize a terminal emulation test script based on the results of a Try Script run.
  • Working With AJAX-Enhanced Web Applications
    This section explains how to "pretty" format JSON and XML data and how to apply TrueLog Explorer script customization features to the testing of applications that utilize AJAX techniques.
  • Customizing TrueLog Explorer
    This section explains how to adapt TrueLog Explorer customization, view, and TrueLog generation features to your specific needs.


Getting Started

This section provides overview information regarding TrueLog Explorer, TrueLog files, analyzing tests, and the sample applications.

  • TrueLog Explorer Overview
    Provides an overview of TrueLog Explorer, including supported application types and its built-in load testing methodology.
  • What You Can Do with TrueLog Explorer
    Details TrueLog Explorer's features and functionality.
  • Tour of the UI
    Introduces the main elements of the TrueLog Explorer interface, including its test-script customization and verification features.
  • Best Practice Use of TrueLog Explorer
    Outlines an effective, typical workflow using TrueLog Explorer to examine a test run and customize a test script.
  • Understanding TrueLog
    Provides an overview of the history files in which extensive detail regarding data/page requests and server responses are recorded during testing.
  • Analyzing Tests
    Illustrates how to use TrueLog Explorer to analyze the results of a Try Script run.
  • Working With Silk Performer
    Explains some of the TrueLog Explorer-specific functionality offered by Silk Performer.
  • TrueLog Explorer for Silk Test
    Describes the version of TrueLog Explorer that accompanies Silk Test.
  • Perspectives
    Describes the TrueLog Explorer two view perspectives and explains when each perspective is used.
  • Sample Applications
    Describes the sample Web applications and database application that ship with Silk Performer.
Parent topic: TrueLog Explorer 21.0


TrueLog Explorer Overview

TrueLog Explorer supports Silk Performer testing efforts with a framework from which you can customize test scripts and perform exhaustive analysis of returned test results.

With an array of tools and reports, TrueLog Explorer helps you build automatic content verification into scripts, insert parsing functions for static session data, and gain insight into the root causes of errors via TrueLog On Error functionality.

Built-in load testing methodology

TrueLog Explorer has been designed around a best-practice approach to load-test script customization and error analysis that guides you from session-handling customization and content verification to user-data customization and, finally, to error analysis. TrueLog Explorer’s workflow bar guides you through this methodology step by step, enabling you to augment tests with session handling, verification checks, and parameterized input data. Ultimately, the workflow bar enables you to run TrueLog On Error analysis.

Note: Most of the examples included in this help system relate specifically to Web applications. However, many of the illustrated concepts can be applied to database, Citrix, Oracle Forms, SAPGUI, AJAX-enhanced Web, terminal emulation-screen applications, and XML-based applications. Many of the concepts can also be applied to the testing of UDP- and TCP/IP-based applications, such as POP3, SMTP, and custom protocols. TrueLog analysis is available for these applications, but script customization is not.
Parent topic: Getting Started


What You Can Do with TrueLog Explorer

TrueLog Explorer enables you to perform the following tasks:
  • Find replay errors quickly and easily – Using TrueLog compare mode, you can automatically detect differences between record and replay sessions to determine whether your application is functioning as intended. Both record and replay sessions are rendered visually so you can compare differences side by side and view errors as they appear to the user.
  • Customize session handling – TrueLog Explorer parsing functions allow you to replace static session IDs in scripts with dynamic session IDs, thereby maintaining state information for successful load-test runs. These functions are available for Web, database, and XML applications.
    Note: Silk Performer's recording techniques automatically generate scripts with session data that is specific to the recorded test run. Scripts themselves do not contain static session information. So customization of session handling is generally not required for most applications.
  • Parameterize input data – With user-data customization, you can make your test scripts more realistic by replacing static, recorded, user-input data with dynamic, parameterized user data that varies with each transaction. Manual scripting is not required to run such data-driven tests. This feature is available for Web, database, XML, Citrix, SAPGUI, terminal emulation, and Oracle Forms applications.
  • Add verifications to test scripts – With the Add Verifications tool, you can gain insight into data that is downloaded during tests, enabling you to verify that content sent by servers is received by clients. Verifications remain useful after system deployment for ongoing performance management. This feature is available for Web, database, XML, SAPGUI, Citrix, terminal emulation, and Oracle Forms applications. TrueLog Explorer supports bitmap and window verification for applications that are hosted by Citrix servers.
  • Analyze TrueLog On Error – TrueLog On Error files provide complete error histories of all errors that occur during tests, making them uniquely well-suited for root-cause analysis. TrueLogs allow you to drill down through real content to analyze error conditions. They display errors in the context of the sessions within which they occur and are closely integrated with test scripts.
  • Visualize and customize database operations – Database operations such as SQL queries can be customized in the same way that HTML operations are customized. Verifications can also be applied to result-set data.
  • Visualize and customize XML – TrueLog Explorer includes an intuitive XML viewer that enables close inspection of all XML-based data, including SOAP requests and responses. Customization and visual verification of XML data is also available.
  • Visualize and customize Citrix – You can record, replay, and customize onscreen events such as mouse moves, mouse clicks, keyboard inputs, and window creations/destructions for Citrix-enabled applications. Screen synchronization functions are also available for verification purposes.
  • Visualize and customize terminal emulation – You can record, replay, and customize test scripts for terminal emulation protocols VT100+, IBM 3270, and IBM 5250. Test scripts can be customized with value parsing, status-value parsing, value verification, and status-value verification.
  • Analyze TCP/IP and UDP test results – Record and replay TrueLogs for applications that use UDP and TCP/IP based protocols, such as POP3, SMTP, and custom protocols, can be compared to identify session-dependent information and analyze errors.
  • Analyze GUI-level test results – Record and replay TrueLogs for the testing of GUI-level (fat client) applications in remote desktop sessions.
Parent topic: Getting Started


Tour of the UI

Take some time to acquaint yourself with the TrueLog Explorer interface to make your test-script customization and verification tasks easier to organize and perform.

The main sections of the TrueLog Explorer interface are highlighted below.

Tour of the UI

Main Menu

The main menu provides access to TrueLog Explorer results-analysis and script-customization features.
Note: Depending on the protocol type of the open TrueLog, certain menu items may not be accessible.

Toolbar

The toolbar provides access to frequently used features.
Note: Depending on the protocol type of the open TrueLog, certain toolbar buttons may not be accessible.

Workflow Bar

The workflow bar facilitates the primary actions related to analyzing test-run results and customizing scripts. The workflow bar reflects TrueLog Explorer's built-in load-testing methodology by supporting its five primary tasks:

  • analyzing test runs
  • customizing session handling
  • customizing user data
  • adding verifications
  • analyzing TrueLog On Error

API Node Tree Menu

The menu tree, located on the left side of the interface, allows you to expand and collapse each TrueLog API node. Click a node to display its contents on the Content pane and its history details on the Information pane.

Content Pane

TrueLog Explorer provides multiple views of all sent and received data. Depending on the type of application under test (Web, XML, database, TCP/IP, UDP, Oracle Forms, SAPGUI, Citrix, or other), the Content pane offers different viewing options:
Response
(Web-based applications only)

The Response page displays the visually rendered response from the server. HTML, XML, and JSON can be visually rendered. All other content cannot be rendered and will display in their raw format. In such a case, the tab displays Response (Raw). To change the render mode, right-click the Response tab and select a mode.

SQL Command
(database applications only)

The SQL Command page displays SQL statements associated with the selected database call, including input and result data. It is the same as the Response page for other protocols.

Differences
(Web-based applications only)

The Differences page lists the In Body differences between selected nodes. This page is helpful in finding dynamic information in server responses. It is the first place to look for session information.

Note: The Differences page is only available in difference mode.
Request
(Web-based applications only)

The Request page displays out-data (data sent by an application to a server) in a rendered format. With XML, an XML menu tree representation is displayed. With HTML, posted data (either the POST data of a HTTP-POST command or the query string data of a HTTP-GET command) are displayed within the HTML page that includes the HTML form that corresponds to the posted data. Only context-full HTML form data submissions (HTML form data submitted with WebPageSubmit, not submissions via WebPageForm) are displayed on the Request page. Elements are displayed in magenta. Attributes are displayed in cyan.

To search for content in rendered view, right-click in the rendered view and choose Find. The global find option is not able to search rendered view.

Note: Response and Request pages can display content from different API nodes simultaneously. When the Response page is the result of an HTML-FORM submission of a preceding Web page, the Request page displays the Web page that contains the submitted values. These values are visible via mouse-over.
Form Controls
(Oracle Forms only)

The Form Controls page displays the properties of Oracle Forms controls (state and content). In compare mode, this page compares the states of controls between record and replay.

Screen
(Citrix only)

The Screen page displays rendered application GUIs, window synchronization functions, and user input values.

Window
(Citrix only)

Displays the window that is referenced by the window parameter of the current function.

Start Request
(SAPGUI only)

The Start Request page displays the state of a SAPGUI application before each server round trip.

End Request
(SAPGUI only)

The End Request page displays the state of a SAPGUI application after each server round trip.

Host Screen
(Terminal-emulation applications only)

The Host Screen page displays the visually rendered response from the server for the selected API node in a terminal view.

Information Pane

The Information pane offers data regarding testing scripts and test runs, including BDL scripting, HTTP headers, and timing statistics. Depending on the type of application under test (Web, XML, database, Oracle Forms, SAPGUI, Citrix, TCP/IP, UDP, or other), the Information pane offers different views.

Info

The Info page displays general information about the open TrueLog file and the selected API node.

BDL

The BDL page displays the BDL script that corresponds to the open TrueLog. The BDL script is automatically positioned to the line of the selected API node.

References

This page is active only for nodes that return HTML data. The References page displays a simple DOM (Document Object Model) of the selected HTML including the elements Hyperlinks, Frames,Embedded documents, and Forms.

Form Data

A convenient tool for viewing and working with all customizable controls that are included on Oracle Forms screens or submitted to Web servers.

Out Header

The Out Header page contains the exact HTTP header that the application (Silk Performer in the case of replay TrueLogs, the browser in the case of record TrueLogs) sends to the server.

Out Body

In the case of HTTP, this page contains data sent with HTTP-POST commands from the application to the server. For TCP/IP and UDP, this page contains data sent with WebTcpipSend functions from the application to the server. For Citrix, this page contains data strings. When using the Oracle Forms log levels of Normal and Debug (this can be set in replay profile settings), the Out Body page contains Oracle Forms messages that are sent for current actions (for example, clicking a button).

You can switch between hexadecimal and textual presentation of data ( Settings > Options > Display > Data Format ). By default TrueLog Explorer selects the best representation of data (for example, binary for images, text for HTML documents).

In Header

The In Header page contains the exact HTTP header that the server sends to the application.

In Body

The In Body page contains data received by the application from the server. The data is presented in raw format as it is received from the server (no rendering for HTML, no menu tree representation for XML).

Statistics
For Web applications on protocol-level, the Statistics page shows timing statistics for Web pages. It includes timing information for each Web page component and communication element. It shows exact response times, including the composition for each individual component, in graphical view. This assists you in pinpointing the root causes of errors and slow page downloads. The Statistics page includes the following data for each page component:
  • DNS lookup time: The time taken to resolve an IP address from the domain / host name supplied
  • Connect time: The time taken for the simulated user to connect to the server
  • Time for SSL handshake: The time taken to exchange encryption keys with the server
  • Time for sending of data: The time from the first byte of the client request until the last byte of the client request
  • Server busy time: Measures the time from the last byte of the client request until the first byte of the server response
  • Response receive time: The time from the first byte of the server response until the last byte of the server response, including all docs but not embedded objects
  • Cache statistics
For Web browser-driven - AJAX applications, the Statistics page shows timing statistics for Web pages. It includes timing information for each Web page component and communication element. It shows exact response times, including the composition for each individual component, in graphical view. This assists you in pinpointing the root causes of errors and slow page downloads. The Statistics page includes the following data for each page component:
  • DNS lookup time: The time taken to resolve an IP address from the domain / host name supplied
  • Connect time: The time taken for the simulated user to connect to the server
  • Net round trip: The time from the first byte of the client request until the last byte of the server response, including all documents but not embedded objects.
  • Cache statistics
Controls

The Controls page is a convenient tool for viewing and working with customizable control values that are included within SAPGUI windows.

Host Screen Info

The Host Screen Info page logs additional information for each host screen, including status (a name/value pair). When a field name is selected, the corresponding field in the Host Screen window above is selected. General screen information. For example, cursor position and screen dimensions is also included.

Parent topic: Getting Started
Related concepts
Visual Analysis with TrueLog Explorer


Best Practice Use of TrueLog Explorer

Best practice use of TrueLog Explorer involves the following steps.

Most likely you will not perform these steps in a simple one-time-through sequence. These tasks are to be performed iteratively. For example, you may make a customization, check the outcome, then make another customization, and check the outcome of that customization.

Note: To enable the insertion of timers and other script-modification features, your TrueLog must be up-to-date (in sync). If your TrueLog is not up-to-date, execute a Try Script run to synchronize it.
Analyzing a Test
This process involves examining the outcome of a previous test run, reviewing a Virtual User Summary Report, locating replay errors, and comparing a replay session alongside an original record session. This process allows for the error checking of script customizations.
Customizing Session Handling
Session-handling errors occur when outdated session data that is embedded in a load-test script is rerun in a subsequent test run. TrueLog Explorer automates the process of identifying such static data and replacing it with dynamic data to facilitate successful test runs. No manual editing of code is required.
Note: Because the Silk Performer script recording techniques generate context-full scripts that do not contain static session information, session handling customization is generally not required.
Customizing User Data
To better simulate real-world conditions during load testing, the actions that virtual users take against servers should vary with each simulated transaction. User input data customization allows the specification of data files (for example, lists of names/addresses, numbers, and products) from which data is to be pulled when the test script simulates such user tasks as form-field data entry. With random functions, randomized data can also be generated for input fields.
Customizing User Data
To better simulate real-world conditions during load testing, the actions that virtual users take against servers should vary with each simulated transaction. User input data customization allows the specification of data files (for example, lists of names/addresses, numbers, and products) from which data is to be pulled when the test script simulates such user tasks as form-field data entry. With random functions, randomized data can also be generated for input fields.
Adding Verification Functions
After the completion of customizing how a test script handles session information and virtual user data input, functions can be built into scripts to automatically check if the application under test returns accurate data. Such content verifications confirm whether or not elements, such as graphics and data, are actually received by clients under real-world conditions. When such elements are not received, verifications raise errors.
Extending Customization via Silk Performer
Although TrueLog Explorer automates most BDL scripting automatically, more sophisticated verifications and customizations can be coded into scripts manually via Silk Performer.
Analyzing TrueLog On Error
After a test has been run, TrueLog On Error files provide complete histories of all erroneous transactions that are encountered during testing. TrueLog On Error enables you to drill down through real content to perform root-cause analysis on system and application faults.
Parent topic: Getting Started


Understanding TrueLog

Provides an overview of the history files in which extensive detail regarding data/page requests and server responses are recorded during testing.

  • TrueLog Overview
    Provides an overview of the history files in which extensive detail regarding data/page requests and server responses are recorded during testing.
  • Visual Verification Under Load
    Describes how TrueLogs facilitate visual verification under load.
  • Request and Response Logs for Root-Cause Analysis
    Describes the log information that can be used to identify the root causes of errors and assist in resolving problems.
  • TrueLog On Error Files
    Describes why you may want to record TrueLog On Error to reduce TrueLog size.
  • Stepping Through TrueLogs
    Navigate through recorded TrueLog nodes at a specified interval to advance through recorded TrueLog data.
  • Specifying Protocol-Based TrueLog Types
    The TrueLog Explorer feature set varies based on the protocol of the active TrueLog. You may need to change the protocol type, especially if you use Oracle Forms.
Parent topic: Getting Started


TrueLog Overview

Because Silk Performer links sessions with test scripts and captures all data sent between clients and servers, it is uniquely able to incorporate replay results into the customization and verification of scripts.

This TrueLog technology represents a tremendous advantage in error reproduction and root-cause analysis. TrueLogs are history files in which extensive detail regarding data and page requests and server responses are recorded during testing. For Web testing, this detail includes complete page contents. Such information is valuable for identifying the causes of system failures.

TrueLogs allow you to drill down through real content that is captured during error conditions in client-server and Web-based applications. For HTML applications, TrueLog Explorer allows for the analysis and manipulation of TrueLog files by way of an intuitive, rendered HTML interface that mirrors what virtual users see during testing, including session context.

Because TrueLogs are tightly coupled with sessions and test scripts, they enable script customization in real-time. When a script customization is made, its effects can instantly be checked using a trial script run, or Try Script run, by reviewing the TrueLog to determine whether the customization worked. If a customization does not work, a TrueLog shows you the system requests and responses in the session that led to the error. This process can be repeated until all customizations operate as intended.

TrueLog and TrueLog On Error files carry the file extension .xlg. XLZ files are zipped TrueLog files that are handled as unzipped TrueLog files within TrueLog Explorer. Zipped TrueLogs minimize download times. Silk Performer does not use zipped TrueLogs.

Parent topic: Understanding TrueLog


Visual Verification Under Load

Web-based applications do not commonly use HTTP error codes to send error information. Instead, they typically send error information within HTML content. In such scenarios, errors are normally detected only when scripts attempt to call links on pages that include error messages rather than their original content. Such attempts typically lead to link not found errors. Such messages generally are insufficient for uncovering the reasons why errors occurred and determining how errors can be reproduced in debugging environments. The only way to track down the causes of such elusive errors is to record error histories under load and determine the actions of the virtual users and the server before the error occurred.

TrueLogs provide this information even when several thousand virtual users are simulated and errors occur only occasionally over long periods of time.

TrueLogs facilitate visual verification under load, which reveals elusive application-level errors that usually are encountered only by subsets of users when applications are under heavy load. For most applications, this sort of load is only experienced once an application is deployed. Typical non-HTTP errors for Web applications include incorrect text on Web pages, incorrect value computations, and application-related messages such as Servlet Error and Server Too Busy.

Parent topic: Understanding TrueLog


Request and Response Logs for Root-Cause Analysis

Visual verification under load on its own does not provide much value because it does not indicate the root causes of application-level errors. For this reason TrueLogs record all relevant user interactions and server responses, including those that occur in the moments preceding errors.

A virtual user may run into an application-level error if a link not found error is displayed when a returned Web page does not include a certain link. The Web server might not have been able to return the complete Web page, or the application server might not have been able to deliver the page’s dynamic content in a timely manner. Using TrueLog Explorer to analyze the TrueLog history that was recorded in the moments preceding such an error allows you to visually inspect the click path that led to the error. Such TrueLog history offers valuable information that can be used to identify the root cause of the error and ultimately fix it.

The following image offers a visual log that reveals the click path of a transaction that led to an error. This TrueLog reveals that a title-verification error resulted from an error message returned by the Web server.

TrueLog On Error Example

Parent topic: Understanding TrueLog


TrueLog On Error Files

Because TrueLog files can become large in size, Silk Performer can be configured to generate TrueLogs only when they encounter errors during load testing. Nothing is recorded while systems run accurately. Such targeted TrueLog generation is known as TrueLog On Error and results in smaller TrueLog files that are focused on error conditions.

When errors are encountered during test runs, TrueLog On Error files reveal the sources of the errors. After a test run, click Analyze TrueLog On Error on the workflow bar to access and analyze the corresponding TrueLog file.

Parent topic: Understanding TrueLog


Stepping Through TrueLogs

The Step through TrueLog dialog box assists you in advancing through recorded TrueLog data at a specified interval.

  1. Select a TrueLog in the TrueLog menu tree. TrueLog content appears on the Response and Information pages.
  2. Choose Edit > Step through TrueLog . Alternative: Click Step through TrueLog on the toolbar. The Step through TrueLog dialog box opens.
  3. Specify the interval at which you want to advance through the TrueLog's recorded-data nodes.
  4. Click Find Next and Find Previous to navigate between nodes at the specified interval.
Parent topic: Understanding TrueLog


Specifying Protocol-Based TrueLog Types

The TrueLog Explorer feature set varies based on the protocol of the open TrueLog. For example, the Form Data tab is available only when a Web TrueLog is open; the Round trips option is available on the Step through TrueLog dialog box only when an SAPGUI TrueLog is open; and the Stable Screen option is available on the Step through TrueLog dialog box only when a terminal emulation TrueLog is open

  1. Choose Edit > TrueLog Type .
  2. Choose the feature set that you want TrueLog Explorer to load. The default protocol is Web.
    Note: Oracle Forms is a mixed protocol that often incorporates Web calls in its scripts. You may want to select the Web-based protocol feature set to customize session handling, parse values out of HTML, and run searches on the HTML included in Oracle Forms scripts.
Parent topic: Understanding TrueLog


Analyzing Tests

Once a BDL-formatted test script has been recorded and saved using the Silk Performer Recorder, you should test the script by performing a Try Script run. Try Script runs are not actual load tests; they are trial test runs that provide you the opportunity to see if your script requires debugging. It is recommended that you perform a Try Script run each time a customization is added to a script. When a Try Script run is initiated via the Try Script button, TrueLog Explorer opens automatically with the TrueLog of the most recent test run open.

Test analysis with TrueLog Explorer involves the following three tasks:
  • Viewing Virtual User Summary reports
  • Finding errors
  • Comparing replay test runs with recorded test runs
  • Visual Analysis
    Explains how TrueLog Explorer can visually render Web content that is displayed by applications under test.
  • Opening a TrueLog
    Open a TrueLog or TrueLog On Error to analyze a test run or to customize a test script.
  • Analyzing a Test Run
    Analyzing a test run may involve viewing a summary report, looking for errors, or comparing replay/record test runs.
  • Virtual User Summary Reports
    Explains how virtual user summary reports summarize Try Script runs with basic descriptions and timing averages.
  • Finding Errors
    Following a Try Script run you need to examine any erroneous requests and make any necessary customizations.
  • Inserting Timer Functions
    Timers can measure the amount of time between the execution of one transaction and another.
  • Performance Analysis (HTTP)
    Explains how to analyze the performance of a Web (HTTP) application under “no-load” conditions.
  • Performance Analysis (AJAX)
    Explains how to analyze the performance of a Web (AJAX) application under “no-load” conditions.
  • Viewing an Overview Page
    After verifying the accuracy of a test run, open the Overview page to analyze performance details.
  • Replay and Record TrueLogs
    Explains that test scripts can be verified by comparing replay TrueLogs alongside TrueLogs that were generated during application recording.
  • TrueLog On Error
    Illustrates how to analyze the transactions that precede error conditions. TrueLog On Error is less of a drain on memory and processing than is standard TrueLog.
  • Closing a TrueLog
    Once you have finished analyzing a TrueLog, you may want to close it to clean up the menu tree.
Parent topic: Getting Started


Visual Analysis

TrueLog Explorer can visually render the Web content that is displayed by applications under test, showing you exactly what your virtual users see during tests.

Though SQL commands, Oracle Forms controls, TCP/IP operations, and UDP operations do not have high-level interfaces comparable to Web content, TrueLog Explorer compare mode allows the comparison of recorded database, Oracle Forms, Citrix, TCP/IP, and UDP TrueLogs with replayed database, Oracle Forms, Citrix, TCP/IP, and UDP TrueLogs.

Parent topic: Analyzing Tests


Opening a TrueLog

  1. Choose File > Add TrueLogs or File > Add TrueLog On Error Files . The Open dialog box opens with the specified file type selected in the Files of Type list box.
  2. Navigate to the directory of the relevant test and select the file to be explored.
  3. Optional: Check the Open in Compare View check box to open the file in Compare view.
  4. Click OK.
Note: Multiple TrueLogs can be open in TrueLog Explorer simultaneously.
Parent topic: Analyzing Tests


Analyzing a Test Run

  1. Open the TrueLog you want to analyze or modify.
  2. Click Analyze Test on the workflow bar. The Workflow - Analyze Test dialog box opens.
  3. Select one of the following options:
    • Show the virtual user summary report
    • Find errors
    • Compare your test
Parent topic: Analyzing Tests


Virtual User Summary Reports

Explains how virtual user summary reports summarize Try Script runs with basic descriptions and timing averages.

  • Virtual User Summary Reports Overview
    Virtual user summary reports are summary reports of individual Try Script runs that offer basic descriptions and timing averages.
  • Displaying a Virtual User Summary Report
    Create a virtual user summary report to analyze summary information from individual Try Script runs.
Parent topic: Analyzing Tests


Virtual User Summary Reports Overview

Virtual user summary reports are summary reports of individual Try Script runs that offer basic descriptions and timing averages. Each report tracks a single virtual user. Data is presented in tabular format.
Note: Because virtual user summary reports require significant processing, they are not generated by default.

To enable the automatic display of virtual user reports at the end of animated Try Script runs, or when clicking the root node of a TrueLog file in the menu tree, check the Display virtual user report check box at Settings > Options > Workspace > Reports .

Virtual user summary reports include details related to:
  • Virtual users
  • Uncovered errors
  • Response time information tracked for each transaction defined in a test script
  • Page timer measurements for each downloaded Web page
  • Measurements related to each Web form declared in a test script, including response time measurements and throughput rates for form submissions using POST, GET, and HEAD methods.
  • Individual timers and counters used in scripts (Measure functions)
  • Information covering IIOP, Web forms, TUXEDO, SAP, and others
Parent topic: Virtual User Summary Reports


Displaying a Virtual User Summary Report

  1. Open the TrueLog you want to analyze or modify.
  2. Click Analyze Test on the workflow bar. The Workflow - Analyze Test dialog box opens.
  3. Click the Show the virtual user summary report link.
Parent topic: Virtual User Summary Reports


Finding Errors

TrueLog Explorer helps you find errors quickly after Try Script runs. Erroneous requests can then be examined and necessary customizations can be made.

Note: When viewed in the menu tree, API nodes that contain replay errors are tagged with red “X” marks.
  1. Open the TrueLog you want to analyze or modify.
  2. Click Analyze Test on the workflow bar. The Workflow - Analyze Test dialog box opens.
  3. Click the Find errors link. The Step through TrueLog dialog box appears with the Errors option selected.
  4. Click Find Next to step through TrueLog result files one error at a time. You can select different increments by which to advance through the TrueLog to visually verify that the script worked as intended (Whole pages, HTML documents, Form submissions, or API calls).
Parent topic: Analyzing Tests


Inserting Timer Functions

To insert a new timer session, you must load a replay TrueLog and enable TrueLog Explorer Explorer mode.

Note: To enable the insertion of timers and other script-modification features, your TrueLog must be up-to-date (in sync). If your TrueLog is not up-to-date, execute a Try Script run to synchronize it.

Measure functions, or timers, can be inserted into BDL scripts to measure the amount of time that transpires from the execution of one transaction to the execution of the next transaction. The results of measure functions are displayed along with summary reports for virtual users.

Note: You can insert a new timer session between the MeasureStart and MeasureStop functions of any preexisting timer.
  1. Right-click an API node in the menu tree where the timer is to begin and choose Start New Timer. The Start Timer dialog box opens.
  2. Enter a name for the timer and click OK. A new MeasureStart function is inserted into the BDL script at that node.
  3. Right-click the API node where the timer is to end and choose Stop Timer. The Stop Timer dialog box opens.
  4. Select the timer that you want to stop and click OK. A new MeasureStop function is inserted into the BDL script at that node.
Note: When inserting multiple timers into a single script, or if you are uncertain if you have stopped all inserted timers, use the New Timer Session function to stop all previous timers before inserting timers. New Timer Session inserts a MeasureStop function for all unresolved timers before inserting a MeasureStart for a new timer session.
Parent topic: Analyzing Tests


Performance Analysis (HTTP)

After verifying the accuracy of a test run, TrueLog Explorer can analyze the performance of the application under “no-load” conditions via the Statistics tab under the Information pane. The Overview page details total page response times, document download times (including server busy times), and time elapsed for receipt of embedded objects.

Detailed Web page statistics show exact response times for individual Web page components. These detailed statistics assist you in pinpointing the root causes of errors and slow page downloads.

Detailed Web page drill-down results include the following data for each page component:
Time | Description
DNS | The time to translate a host name into an IP address.
Connect | The time to establish a connection to a server.
SSL Handshake | The time to establish a secure layer on an existing connection. The client and server exchange certificates and agree on an encryption technology including related keys to secure data transmission.
Send | The time to hand over the request data from Silk Performer to the operating system. This value does not include the time required to send the request data from the operating system to the server.
Server busy | The time to send the request data from the operating system to the server, the time to calculate the response data on the server, and the time to send the first byte of the response data from the server to the client (including network latency).
Receive | The time to receive the entire response data.
Cache statistics |
Parent topic: Analyzing Tests


Performance Analysis (AJAX)

After verifying the accuracy of a test run, TrueLog Explorer can analyze the performance of the application under “no-load” conditions via the Statistics tab under the Information pane. The Overview page details total action times and document download times (including server busy times and time elapsed for receipt of embedded objects).

Detailed Web page statistics show exact response times for individual Web page components. These detailed statistics assist you in pinpointing the root causes of errors and slow page downloads.

Detailed Web page drill-down results include the following data for each page component:
  • DNS lookup time
  • Connection time
  • Net round trip
  • Cache statistics

Parent topic: Analyzing Tests


Viewing an Overview Page

  1. Select an API node for which you would like to view statistics.
  2. Click the Statistics tab. The Statistics view opens.
Parent topic: Analyzing Tests


Replay and Record TrueLogs

By comparing a TrueLog that has been generated during the script development process alongside the corresponding TrueLog was recorded originally, you can verify that the test script runs accurately.

  • Replay and Record TrueLogs Overview
    Explains that test scripts can be verified by comparing replay TrueLogs alongside TrueLogs that were generated during application recording.
  • Comparing Replay and Record TrueLogs
    After a test run, comparing a replay TrueLog to the corresponding record TrueLog allows you to see exactly how the test runs differed.
  • Synchronizing Replay and Record TrueLogs
    Synchronize corresponding API nodes between replay and record TrueLogs to look for differences between the TrueLogs.
  • Auto-Syncing Replay and Record TrueLogs
    In compare mode you can maintain automatic synchronization between corresponding API nodes in replay and record TrueLogs.
Parent topic: Analyzing Tests
Related concepts
Customizing Session Handling


Replay and Record TrueLogs Overview

By comparing a TrueLog that has been generated during the script development process alongside the corresponding TrueLog was recorded originally, you can verify that the test script runs accurately.

With Web application testing, TrueLog Explorer shows the actual Web pages that are received during tests. Live monitoring of downloaded data is available via TrueLog Explorer animated mode. Data is displayed as it is received during testing.

For Web testing, TrueLog Explorer provides different views of sent and received data in the Content pane:
  • the Response tab: displays the received data either as rendered HTML, as pretty-formatted JSON, XML or in raw format. If the default display mode is not suitable, right-click the tab and select a different option.
  • the Differences tab: displays the differences between replay and record TrueLogs
  • the Request tab: displays posted data from pages that include user interface controls such as text entry fields.
Note: Windows displaying content presented during replay have green triangles in their upper left corners. Windows displaying content originally displayed during application recording have red triangles in their upper left corners.
Tip: If your analysis shows invalid session handling, click Customize Session Handling on the workflow bar.
Note: Multiple entry points and approaches are available for the comparison of TrueLogs. Replay TrueLogs do not necessarily need to be open in the replay menu tree and record TrueLogs do not necessarily need to be open in the record menu tree. Two TrueLogs can even be compared with one another. The procedure is the same for all TrueLog comparisons.
Parent topic: Replay and Record TrueLogs


Comparing Replay and Record TrueLogs

  1. Choose File > Add TrueLogs or File > Add TrueLog On Error Files . The Open dialog box opens with the specified file type selected in the Files of Type list box.
  2. Navigate to the directory of the relevant test and select the file to be explored.
  3. Optional: Check the Open in Compare View check box to open the file in Compare view.
  4. Click OK.
  5. Click Analyze Test on the workflow bar. The Workflow - Analyze Test dialog box opens.
  6. Click Compare your test. The corresponding record TrueLog opens in Compare view and the Step through TrueLog dialog box displays with the Whole pages option selected. With this selected, node-by-node comparison of the TrueLogs can be conducted.
  7. Click Find Next to step through TrueLog result files one page at a time. Experiment with different increments by which to advance through the TrueLogs to visually verify that your script ran as intended (HTML documents, Errors, Form submissions, or API calls).
    Note: Sub-panes related to record sessions have red triangles in their upper-left corners, while sub-panes related to replay sessions are marked with green triangles.
Parent topic: Replay and Record TrueLogs


Synchronizing Replay and Record TrueLogs

In compare mode you can synchronize corresponding API nodes between replay and record TrueLogs to identify differences between recorded values and replayed values.

Note: This feature is disabled when automatic synchronization of TrueLogs is enabled.
  1. Enable compare mode by doing one of the following:
    • Choose View > Compare Mode .
    • Click the Compare Mode button on the toolbar.
  2. Open a set of corresponding record and replay TrueLogs.
  3. Right-click an API node and choose Synchronize TrueLogs. TrueLog Explorer locates the API node in the matching TrueLog that best correlates with the selected API node.
Parent topic: Replay and Record TrueLogs
Parent topic: Replay and Record TrueLogs
Related tasks
Auto-Syncing Replay and Record TrueLogs


Auto-Syncing Replay and Record TrueLogs

In compare mode you can maintain automatic synchronization between corresponding API nodes in replay and record TrueLogs.

  1. Enable compare mode by doing one of the following:
    • Choose View > Compare Mode .
    • Click the Compare Mode button on the toolbar.
  2. Open a set of corresponding record and replay TrueLogs.
  3. Synchronize the TrueLogs by doing one of the following:
    • Click Keep TrueLogs Synchronized on the toolbar.
    • Choose View > Keep TrueLogs Synchronized.
    Now when you click an API node in either TrueLog, TrueLog Explorer automatically selects the API node in the other TrueLog that best correlates with the selected API node.
Parent topic: Replay and Record TrueLogs
Related tasks
Synchronizing Replay and Record TrueLogs


TrueLog On Error

TrueLog On Error files provide complete histories of the transactions that precede errors uncovered during load tests. They enable you to drill-down through real content to analyze error conditions.

TrueLog On Error files maintain histories of all client requests and server responses. Because they present errors in the context of the sessions within which they occur and are closely integrated with test scripts, TrueLog On Error files are uniquely suited for root-cause analysis of system and application faults.

Because TrueLog On Error is recorded only when errors are encountered, it is much less of a drain on memory and processing than is standard TrueLog.

It is typical after running a test to have multiple TrueLog On Error files open in TrueLog Explorer (one TrueLog for each virtual user who returns an error). With the TrueLog Explorer Find Errors feature, errors can be identified chronologically, regardless of which TrueLogs the errors were recorded in. This simplifies the process of analyzing errors. There is no need to manually review all open TrueLogs to find the next error in a sequence.

  • Analyzing TrueLog On Error
    After a load test is run, analyze the complete history of erroneous transactions.
Parent topic: Analyzing Tests


Analyzing TrueLog On Error

Complete a load test.
  1. Click the Silk Performer Explore Results button. The Workflow - Explore Results dialog box appears.
  2. Click TrueLog Explorer.
    Note: The TrueLog Explorer option is disabled if no TrueLogs are found.
    TrueLog Explorer launches with all of the TrueLog On Error files that were generated for the current test open. The Find Error dialog box is displayed.
    Note: If more than 100 TrueLog files are associated with the test, a dialog appears stating that only the first 100 TrueLogs will be opened automatically.
  3. Select All Open TrueLogs (the default) from the Search in list box. Search sequentially for errors in all open TrueLogs.
  4. Select a TrueLog in the menu tree
  5. Select selected TrueLog only from the Search in list box. Search sequentially for errors in only a selected TrueLog.
    Note: TrueLog On Error files are listed chronologically.
  6. Select the type of error you’re looking for (error, warning or informational) in the Find what portion of the dialog.
  7. Specify a search strategy (Start from selected node or Start with first error) in the Search strategy portion of the dialog.
  8. Navigate between errors using the Find Next and Find Previous buttons.
    Tip: When testing Web applications, errors often occur one or two steps before they manifest themselves in page content as non-loading images, error messages, etc.
Parent topic: TrueLog On Error


Closing a TrueLog

Once you have finished analyzing a TrueLog, you may want to close it to clean up the menu tree.

  1. In the TrueLog menu tree, select the TrueLog that you want to close.
  2. Choose File > Remove selected TrueLog . Alternative: To close all open TrueLogs, choose File > Remove all TrueLogs .
Parent topic: Analyzing Tests


Working With Silk Performer

It is assumed that you are already familiar with Silk Performer functionality. Refer to Silk Performer Help for full details regarding its use and interaction with TrueLog Explorer.

  • Exploring TrueLogs from Silk Performer
    Open TrueLog Explorer from Silk Performer using one of the methods described.
  • Enabling TrueLog Via Silk Performer
    You can enable TrueLog and TrueLog On Error generation for your tests via Silk Performer.
  • Try Script Runs
    Explains how to use Try Script runs to compare original record sessions against replay sessions to identify session information that may require parsing, or to test verification functions.
Parent topic: Getting Started


Exploring TrueLogs from Silk Performer

TrueLog Explorer opens automatically with the most recently generated TrueLog when you initiate a Try Script run by clicking Try Script on Silk Performer's workflow bar. Additionally, TrueLog Explorer can be opened from Silk Performer by any of the following methods:
  • The replay TrueLog of the most recent Try Script run can be opened at the corresponding node by right-clicking within the script in Silk Performer's script editor and choosing Locate In Recent Try Script TrueLog.
  • The replay TrueLog of the current run can be opened at the corresponding node by right-clicking a virtual user output in Silk Performer’s Output view on the Virtual User page and choosing Explore TrueLog.
  • Record TrueLogs can be opened by right-clicking scripts in Silk Performer’s project menu tree and choosing Explore Recorded TrueLog.
  • The replay TrueLog of the most recent Try Script run can be opened by right-clicking a script in Silk Performer’s project menu tree and choosing Explore Recent Try Script TrueLog.
  • Replay TrueLogs can be opened by choosing Results > Explore TrueLog .
  • The replay TrueLog of the current run can be opened by right-clicking virtual users in Silk Performer’s Monitor/Virtual User view and choosing Explore TrueLog.
Parent topic: Working With Silk Performer


Enabling TrueLog Via Silk Performer

TrueLog Explorer relies on Silk Performer for the writing of TrueLog and TrueLog On Error files. With Try Script runs, which are the most common scenario for use of TrueLog files, TrueLog files are automatically enabled. No configuration is necessary.

Because normal TrueLog generation can produce large amounts of data and degrade performance, consider TrueLog On Error, which only records TrueLog information when transactions fail.

The following table identifies the options for enabling TrueLog and TrueLog On Error:
Options | Steps
Silk Performer Results toolbar | Click Generate TrueLog Files on the Silk Performer Results toolbar to record all TrueLog activity, or click Generate TrueLog On Error Files to generate TrueLog only when failed transactions occur.
Silk Performer menu | Choose Settings > Active Profile > Results > TrueLog . Check the TrueLog files (.xlg) check box to record all activity, or check the TrueLog On Error files (.xlg) check box to generate TrueLog only when failed transactions occur. Click OK.
Silk Performer’s Workload Configuration page | To enable TrueLog On Error for your tests, check the check box in the Settings section on Silk Performer’s Workload Configuration page.
Parent topic: Working With Silk Performer


Try Script Runs

Try Script runs are Silk Performer test runs that are used to evaluate the readiness of test scripts. In Try Script runs, original recorded sessions are compared against replay sessions to identify session information that may require parsing or to test verification functions.

  • Executing a Try Script Run from TrueLog Explorer
    From TrueLog Explorer, compare original record sessions against replay sessions to identify session information that may require parsing, or to test verification functions.
  • Executing a Try Script Run from Silk Performer
    From Silk Performer, compare original record sessions against replay sessions to identify session information that may require parsing, or to test verification functions.
Parent topic: Working With Silk Performer


Executing a Try Script Run from TrueLog Explorer

Choose Script > Do a Try Script Run . Silk Performer then opens and runs the specified test script.

Parent topic: Try Script Runs


Executing a Try Script Run from Silk Performer

  1. On the Silk Performer workflow bar, click Try Script. The Try Script dialog box opens.
  2. Click Run.
    Note: To open TrueLog Explorer during the Try Script run, select the Animated Run with TrueLog Explorer check box on the Try Script dialog box.
Parent topic: Try Script Runs


TrueLog Explorer for Silk Test

An alternative version of TrueLog Explorer ships with Silk Test, Silk’s functional-testing tool. The version of TrueLog Explorer that accompanies Silk Test is set to Viewer mode, meaning that Silk Test TrueLogs support only the examination of results within test cases. They do not offer script customization, which is available for most Silk Performer-based TrueLogs.

Silk Performer utilizes Silk Test to execute GUI-level (fat client) tests in remote-desktop sessions. For full details, see the Silk Performer Help.

For information about Silk Test’s interaction with TrueLog Explorer, refer to the TrueLog Explorer Help that ships with Silk Test.

Parent topic: Getting Started


Perspectives

TrueLog Explorer offers two viewing modes, or perspectives, to accommodate various TrueLog types. The default, most commonly used view perspective for Silk Performer users is the Explorer perspective. Explorer perspective offers the full range of script customization features offered by TrueLog Explorer. Explorer perspective enables all functionality offered by the TrueLog Explorer workflow bar. By default, attended Silk Performer tests always produce Explorer-perspective TrueLogs.

Viewer perspective enables only a subset of the context-menu commands across all TrueLog Explorer views and disables the workflow bar. The intent of this perspective is to offer a simplified view for users who are not customizing their scripts, and to support TrueLog types for which script customization is unavailable. By default, unattended Silk Performer tests and Silk Test tests always produce Viewer-perspective TrueLogs.

  • Switching to Viewer Perspective
    Switch from Explorer perspective to Viewer perspective if you will not be using script customization features.
  • Switching to Explorer Perspective
    Switch from Viewer perspective to Explorer perspective to take advantage of the full range of script customization features.
Parent topic: Getting Started


Switching to Viewer Perspective

Toggling between Explorer and Viewer perspectives is enabled for TrueLog types that offer the Explorer perspective. For TrueLog types that do not support the Explorer perspective, Viewer perspective is the only available mode.

Choose one of the following options:

  • Click Enable Viewer perspective (the eye icon on the toolbar).

  • Choose View > Perspective > Viewer .

Parent topic: Perspectives


Switching to Explorer Perspective

Toggling between Explorer and Viewer perspectives is enabled for TrueLog types that offer the Explorer perspective. For TrueLog types that do not support the Explorer perspective, Viewer perspective is the only available mode.

Choose one of the following options:

  • Click Enable Explorer perspective (the magnifying glass icon on the toolbar).

  • Choose View > Perspective > Explorer .

Parent topic: Perspectives


Sample Applications

This Help references three sample applications: a Web 2.0 application, a classic pure HTML Web application, and a database application. Use these applications to acquaint yourself with Silk Performer’s and TrueLog Explorer’s functionality before you begin working with sensitive data.

  • Sample Web 2.0 Application
    Explains that Silk Performer offers a modern sample Web application that you can use to learn about Web 2.0 application testing.
  • Sample Classic Web Application
    Use this application to acquaint yourself with TrueLog Explorer’s pure HTML Web-application testing capabilities.
  • Sample Database Application - Customer OCI
    Use this application to acquaint yourself with TrueLog Explorer’s database-application capabilities.
Parent topic: Getting Started


Sample Classic Web Application

ShopIt simulates a simple, pure HTML e-commerce Web site with a catalog of camping merchandise that is available for simulated online purchase. Use this application to experiment with TrueLog Explorer’s pure HTML Web-application capabilities.

  • ShopIt Overview
    The ShopIt sample application simulates a simple e-commerce Web site with a catalog of camping merchandise that is available for simulated online purchase.
  • Installing ShopIt V 6.0
    ShopIt V 6.0 is the sample web application provided by Silk Performer.
Parent topic: Sample Applications


ShopIt Overview

ShopIt simulates a simple e-commerce Web site with a catalog of camping merchandise that is available for simulated online purchase. Use this application to experiment with TrueLog Explorer’s Web-application capabilities.

ShopIt is designed to generate errors, including session errors and missing Web links that are the result of out-of-stock merchandise. The session errors are the result of session information that is embedded in JavaScript and is not detectable by Silk Performer’s context management. The test script that includes this hard-coded session data must be customized before the script can run error-free.

Note: See the ShopItV60.exe readme, which is available in the setup, for the latest information about ShopIt.

Software Requirements for ShopIt

A Windows operating system that includes IIS 4 or IIS 5 with Active Server Pages and Microsoft Internet Explorer (version 5.0 or later) is required.

Parent topic: Sample Classic Web Application


Sample Database Application - Customer OCI

Customer OCI, the sample database application, simulates a simple application that allows you to add, edit, and delete customer contact information.

  • Customer OCI Overview
    Customer OCI, the sample database application, simulates a simple application that allows you to add, edit, and delete customer contact information.
  • Accessing Customer OCI
    Use the sample database application to record sample database sessions that include the insertion of new customer records and database queries.
  • PersonPB
    Describes how to set up and how to work with PersonPB.
Parent topic: Sample Applications
Parent topic: Working With Database Applications


Customer OCI Overview

Customer OCI, the sample database application, simulates a simple application that allows you to add, edit, and delete customer contact information. Use this application to record sample database sessions that include the insertion of new customer records and database queries. You can use the resulting TrueLogs to acquaint yourself with TrueLog Explorer database functionality.

Two versions of Customer OCI are provided:
  • Person PB V6 - OCI7
  • Person PB V7 - OCI8

Both versions are identical except they use different versions of PowerBuilder (versions 6 and 7) and different versions of OCI (versions 7 and 8).

Note: The sample TrueLogs were created using Person PB V7 - OCI8.

Software requirements for Customer OCI

To run Customer OCI, you must have:
  • Oracle8 or Oracle9 client installation
  • Access to an Oracle database
Parent topic: Sample Database Application - Customer OCI


Accessing Customer OCI

Use Customer OCI, the sample database application, to record sample database sessions that include the insertion of new customer records and database queries. Customer OCI is part of the Silk Performer installation.

Determine which version you want to access and then perform one of the following steps:
  • To access PersonPB V6 - OCI7, choose Start > Programs > Silk > Silk Performer 21.0 > Sample Applications > Database Samples > PersonPB V6 - OCI7 sample application .
  • To access PersonPB V7 - OCI8, choose Start > Programs > Silk > Silk Performer 21.0 > Sample Applications > Database Samples > PersonPB V7 - OCI8 sample application .
Parent topic: Sample Database Application - Customer OCI


PersonPB

The PersonPB application that accompanies Silk Performer is required to perform all steps described in the Oracle tutorials of the Silk Performer Tutorials book. The application provides a simple user interface to search an Oracle database for customers, to update customer records, to insert new customer records, and to remove obsolete customer data.

Keep in mind that the application was developed chiefly for demonstration purposes. Database traffic generated by the application can easily be recorded with the Silk Performer Recorder and BDL scripts based on the captured database traffic are easy to understand since they contain mostly simple Oracle API function calls.

To work with the PersonPB application, you need one of the following:
  • Oracle 9.x database or later
  • SQLNet client (with compatible database version)
  • Setting Up PersonPB
    Describes how to set up the application parameters for PersonPB.
  • Working with PersonPB
    Describes how to search for, update, create, and remove customer data.
Parent topic: Sample Database Application - Customer OCI


Setting Up PersonPB

Once you have successfully installed Silk Performer, the PersonPB application is located in the SampleApp subdirectory. For more details on how to install Silk Performer, refer to the installation help.

The PersonPB application provides a number of settings to specify the application behavior. Since these settings affect the SQL statements rather than the user interface, you need to record the database traffic using the Silk Performer API Recorder for the differences to become visible.

To set up the application parameters:

  1. From the PersonPB menu bar, click File > Parameter.
  2. Specify the Static Bind setting. If this option is checked, each select-list item is defined separately. Otherwise, all select-list items are described using a single operation.
  3. Specify the Disable Bind setting. If this option is checked, parameters within SQL statements are replaced with constants rather than being bound to the corresponding program variables.
  4. Enter the number of Rows to fetch per iteration. Only the specified number of rows is available after a fetch operation.
  5. Specify the SQL cache size. This setting determines the maximum number of database cursors used by the application.
  6. Click OK to save your changes.
  7. In the Customer OCI window, select either the Serializable option or the Read Committed option. See the Oracle documentation for an exact isolation level description. The isolation level determines how transactions modifying the database are handled.
    Note: To replay a test script using multiple virtual users, the isolation level of the traffic-generating application has to be set to Read Committed.
Parent topic: PersonPB


Working with PersonPB

This section describes the PersonPB user interface provided to search a database for customers, to update customer records, to create new customer records, and to remove obsolete customer data.

  • Connecting PersonPB to a Database
    Describes how to connect PersonPB to your Oracle database.
  • Searching for Customers
    Describes how to search the database for customer records.
  • Updating a Customer Record
    Describes how to update customer records in the database.
  • Creating a Customer Record
    Describes how you can create new customer records.
  • Removing a Customer Record
    Describes how to remove customer records.
  • Using Stored Procedures
    Describes how to create a stored procedure and how to use it.
Parent topic: PersonPB


Connecting PersonPB to a Database

Before you can work with PersonPB, you must establish a connection between PersonPB and your Oracle database. To connect to an Oracle database using OCI 7, start with step one. To connect to an Oracle database using OCI 8, start with step two.
  1. Launch the PersonPB V6 application for OCI 7 by clicking Start > Programs > Silk > Silk Performer <version number> > Sample Applications > Database Samples > PersonPB V6 - OCI7 Sample Application.
  2. Launch the PersonPB V7 application for OCI 8by clicking Start > Programs > Silk > Silk Performer <version number> > Sample Applications > Database Samples > PersonPB V7 - OCI8 Sample Application.
  3. On the Login dialog box, enter the connection string to access your Oracle database. A connection string is used to request a connection to a remote Oracle database. The SQL Net Easy Configuration tool, part of the Oracle client software, can be used to set up connection strings. For more information, refer to the documentation accompanying your Oracle software.
  4. Enter your user name and your password and click Login. The Customer OCI window displays.
Parent topic: Working with PersonPB


Searching for Customers

Before you can search the database for customer records, follow the steps in the topic Connecting to a Database.

  1. On the Customer OCI dialog box, click Cancel.
  2. Specify any search criteria (Firstname, Lastname, Address 1, and so on).
  3. Click Select. The search results display in the customer list.
Parent topic: Working with PersonPB


Updating a Customer Record

Before you can update customer records, follow the steps in the topic Connecting to a Database.

  1. On the Customer OCI dialog box, select a customer.
  2. Update the customer information in the corresponding fields.
  3. Click Update. The updated information displays in the customer list.
Parent topic: Working with PersonPB


Creating a Customer Record

Before you can create customer records, follow the steps in the topic Connecting to a Database.

  1. On the Customer OCI dialog box, click Cancel.
  2. Enter the new customer data, at least the first name and the last name.
  3. Click Insert.
    Note: Since the new customer record is not selected automatically, you have to click Select for the new customer to become visible in the list.
Parent topic: Working with PersonPB


Removing a Customer Record

Before you can remove customer records, follow the steps in the topic Connecting to a Database.

  1. On the Customer OCI dialog box, select at least one customer.
  2. From the customer list, select the customer record you want to remove.
  3. Click Delete.
Parent topic: Working with PersonPB


Using Stored Procedures

Before you can create a stored procedure to insert a new customer, follow the steps in the topic Connecting to a Database.

The PersonPB application supports stored procedures to insert new customer records. Stored procedures are available mainly to demonstrate additional Silk Performer Recorder features.
  1. On the Customer OCI dialog box, make sure no stored procedures exist.
  2. Click Create. You can now use the stored procedure to insert a new customer.
  3. Click Cancel.
  4. Enter the new customer data, at least its first and its last name.
  5. Click Insert using SP.
    Note: Since the new customer record is not selected automatically, you have to click Select for the new customer to become visible.
  6. To drop a stored procedure, click Drop.
Parent topic: Working with PersonPB


Customizing Session Handling

Illustrates how to parse out hard-coded session data that sometimes appears in record TrueLogs. Session-handling customization enables you to maintain state information during testing.

  • Session-Handling Overview
    Offers an overview of the issues related to session handling and how script customization can overcome those issues.
  • Determining When to Customize Session Handling
    Explains that if static session IDs in scripts are not replaced with dynamic values generated at runtime, Web applications are likely to generate errors, such as Your session has expired. Please return to the login screen.
  • Customizing Session Handling
    When recorded test scripts include hard-coded session-dependent information, the scripts will cause errors when they are subsequently run. Such static session information needs to be replaced with a recording rule or a parsing function.
  • Self-Learning Recorder
    Describes how the Silk Performer self-learning recorder supports applications that rely heavily on client-side scripting.
  • Parsing Functions
    Explains how parsing functions can be used to maintain state information during load testing and to simulate real-world user-data input.
  • Session Handling for Web Applications
    Explains the forms that session IDs typically take when they are returned by Web servers.
  • Session-Handling Customization Process
    Describes the typical process of identifying and customizing relevant session information.
  • Using HTTP Parsing Rules
    Introduces Silk Performer recording-rule capabilities.
Parent topic: TrueLog Explorer 21.0


Session-Handling Overview

Session-handling customization is the process of manipulating server responses in such a way that application state information is preserved during load testing.

In their responses to clients, servers often generate information at runtime that is used to identify future client requests as coming from the same computer during the same user session. Servers may send out unique strings, commonly known as session IDs. If not updated in test scripts, such session information can create problems in subsequent test runs.

When replayed test runs are compared to originally recorded test runs and outdated session information is discovered, that information must be replaced with dynamic variables in future test runs. Otherwise test scripts pass along invalid session IDs or other session information.

TrueLog Explorer identifies differences that are relevant for customization in yellow and non-relevant differences that do not require customization in blue.

Note: Because Silk Performer recording techniques generate context-full scripts that do not contain static session information, session handling customization is generally not required for most applications. So if you do not detect any problems when you analyze your test you can skip session-handling customization and proceed with user data customization.
Note: The examples presented here relate specifically to Web applications, however, the same principles can be applied to database and XML-based applications. Though Oracle Forms, SAPGUI, Citrix, terminal emulation, TCP/IP and UDP record/replay TrueLogs can be compared using TrueLog Explorer, session-handling customization is not available for those application types.
Parent topic: Customizing Session Handling


Determining When to Customize Session Handling

When a WebPageUrl call in a script uses a URL that contains a session ID as part of the query string, that same hard-coded static session ID will be sent to the server when the script is replayed. The session ID, however, will not correctly identify the replay session. It will only identify the earlier recorded session, causing the script replay to generate an error.

Without replacing static session IDs in scripts with dynamic values generated at runtime, Web applications are likely to generate errors, such as Your session has expired. Please return to the login screen.

Because of Silk Performer session-handling methods, session customization is not required for most Web applications. In the rare instances where manual session customization is required, TrueLog Explorer facilitates the process.

Silk Performer uses two session-ID handling methods that reduce the need for manual handling of hard-coded session IDs:

Cookie Management

Silk Performer automatically handles dynamic session ID values for servers that use cookies to exchange session information. Because Silk Performer accurately emulates browser cookie management, it can send cookies to servers in the same way that browsers do, and thereby eliminate the need for manual interaction to maintain state.

Page-level Web API

Using page-level API for recording (the default setting) delivers scripts that generate context-full Web API function calls, such as WebPageLink and WebPageSubmit. Context-full Web API calls work at the HTML level, not the HTTP level, and therefore don't use URLs as parameters. Manual session customization isn't required for context-full API calls. The Silk Performer page-level API is used when the application type Web business transaction (HTML/HTTP) is selected in the Outline Project dialog box.
Note: It is strongly recommended that the Silk Performer page-level API be used rather than the Silk Performer low-level, browser-based API.

When client-side JavaScript is relied upon for the dynamic generation of HTML, the Silk Performer Recorder occasionally loses HTML context and scripts context-less Web API calls. Context-less Web API calls, such as WebPageUrl and WebPageForm, contain URLs as parameters. In these rare instances scripts may contain hard-coded session IDs that can be found in the URL parameters of Web API calls and in the form fields declared in the DCLFORM sections of scripts.

Example

The following context-full script does not require customization.

transaction TMain
  begin
    WebPageUrl("http://myHost/ShopIt/"); // first call always context-less
    WebPageLink("Join the experience!");
    WebPageSubmit("Enter", SHOPIT_MAIN_ASP001);
    WebPageLink("Products");
  end TMain;

dclform
  SHOPIT_MAIN_ASP001:
    "SessionID"       := "" <USE_HTML_VAL>, // hidden value:
                                            // LGIJALLCGEBMIBIMFKOEJIMM2
                                            // recognized as a hidden
                                            // form field, the value is
                                            // taken from the actual
                                            // HTML form field.
    "name"            := "Tester",          // changed
    "New Name Button" := "" <USE_HTML_VAL>; // unchanged value: "Enter"

Example

Following is a script with context-free functions (static session data that needs to be customized is included in the DCLFORM section):

transaction TMain
begin
  WebPageUrl("http://myHost/ShopIt/"); // first call always context-less
  WebPageUrl("http://myHost/ShopIt/main.asp", NULL, SHOPIT_MAIN_ASP001);
  WebPageForm("http://myHost/ShopIt/main.asp", SHOPIT_MAIN_ASP002);
  WebPageUrl("http://myHost/ShopIt/products.asp");
end TMain;

dclform
  SHOPIT_MAIN_ASP001:
    "from"     := "welcome";

  SHOPIT_MAIN_ASP002:
    "SessionID"       := "LGIJALLCGEBMIBIMFKOEJIMM2",
    "name"            := "Tester",
    "New Name Button" := "Enter";
Parent topic: Customizing Session Handling


Customizing Session Handling

You can create a new recording rule in TrueLog Explorer using values that you have specified in a parsing function. For example, creating a recording rule from a session-customization parsing function allows you to record an application while avoiding session customization issues entirely.

  1. Select a TrueLog in the menu tree.
  2. Click Customize Session Handling on the workflow bar. The Workflow - Customize Session Handling dialog box opens.
  3. Click the Find differences link to view a differences table on the Differences page. This step reveals instances in which the server responded with different (or dynamic) information during the replay session compared to of the record session. Such static information may need to be replaced with a variable.
    Note: When the corresponding record TrueLog is not already open, a dialog box opens asking if you want to have the corresponding record TrueLog opened.
    1. Click OK.
  4. Step through the HTML server responses using the Step Through TrueLog dialog box. Recorded responses are displayed alongside the corresponding replayed responses. Only those differences that indicate that static information is included in the test script and being sent back to the server need to be parsed. For example, a difference between replay and record sessions might be due to an e-commerce site running out of stocked merchandise. Such a difference would not be appropriate for script customization because it is not session related.

    Tip: The column headers on the Differences page offer helpful mouse-over tooltips that describe the elements contained in each column.
  5. Double-click one of the errors listed on Differences page. The Insert parsing function dialog box opens with the boundary values already inserted. There is no need to locate and enter these values manually.
  6. Optional: Click Create Recording Rule to create a recording rule based on the values of the parsing function. This enables you to record the application in the future without having to care about session customization again.
  7. Back on the Insert parsing function dialog box, click OK.
  8. Click Customize Session Handling on the workflow bar once the script has been successfully modified.
  9. Click Try Script Run to see if the script runs correctly now that session handling has been modified. A new Try Script run is initiated.
  10. Analyze the results of the subsequent test run to determine whether or not session handling customization was successful.
Parent topic: Customizing Session Handling


Self-Learning Recorder

The Silk Performer self-learning Recorder is adept at supporting applications that rely heavily on client-side scripting. Equipped with advanced context management techniques, the recorder is able to generate Web scripts that maintain page context even when page requests are executed via JavaScript functions.

Maintaining page context means that Web pages are requested in the context of the links or submit forms that call them. Such context-full Web page request functions reference Web pages via their links or form names rather than simply by their URLs. To do this, Silk Performer parses through Web-server traffic for links for form submissions to identify the pages that called the content.

Parent topic: Customizing Session Handling


Parsing Functions

Parsing functions can be used to maintain state information during load testing and to simulate real-world user-data input. Parsing functions (which are stored in BDL variables) read session-related values in server responses. They then use parsed values as parameterized data that is sent back to servers as part of a query string post or URL data.
Note: Parsing functions are different from verification functions, which only check for the presence of specified input values.
  • Parsing Functions Overview
    Explains how parsing functions can be used to maintain state information during load testing and to simulate real-world user-data input.
  • HTML Content Parsing Functions
    Lists the HTML content parsing functions that can be applied to rendered, visible HTML content.
  • Response Data Parsing Functions
    Lists the data parsing functions that can be applied to response data returned by servers.
Parent topic: Customizing Session Handling


HTML Content Parsing Functions

HTML content parsing functions can be applied to rendered, visible HTML content. They are applied in TrueLog Explorer Rendered view. HTML parsing functions allow for the parsing of HTML content that can be viewed in Web browsers.

The following HTML content parsing functions are available:
  • WebParseHtmlBound and WebParseHtmlBoundEx
  • WebParseHtmlBoundArray (not supported by TrueLog Explorer)
  • WebParseHtmlTitle
  • WebParseTable
  • WebParseResponseTag (not supported by TrueLog Explorer)
  • WebParseResponseTagContent (not supported by TrueLog Explorer)
Parent topic: Parsing Functions


Response Data Parsing Functions

Data parsing functions can be applied to response data returned by servers. In cases where HTML documents are returned from servers, this includes the complete source code of documents. These parsing functions are applied on the TrueLog Explorer Source page.

The following data parsing functions are available:
  • WebParseDataBound and WebParseDataBoundEx (these functions replace the obsolete WebParseResponseData functions)
  • WebParseDataBoundArray (not supported by TrueLog Explorer)
  • WebParseResponseHeader (not supported by TrueLog Explorer)
Note: Visual parsing with TrueLog Explorer is not currently available for TCP/IP and UDP-based applications. However, BDL functions that allow you to parse response data from WebTcpipRecv functions are available.
Parent topic: Parsing Functions


Session Handling for Web Applications

Session IDs are sent to clients in a number of ways. Most often they are included in cookies, hyperlink URLs, URLs of embedded objects, and HTML form fields. Session IDs are likewise returned to servers within cookies, URLs, and HTTP post data. See the examples below:

Example: Session information included in a cookie:

Information sent to the client:

Set-Cookie: SessionID=LGIJALLCGEBMIBIMFKOEJIMM; path=/

Information returned to the server:

Cookie: SessionID=LGIJALLCGEBMIBIMFKOEJIMM

Example: Session information included in a URL:

Information sent to the client:

<html>
  …
<a href="/ShopIt/acknowledge.asp?SessionID=LGIJALLCGEBMIBIMFKOEJIMM" >
  Enter Shop
</a>
…
</html>

Information returned to the server:

GET /ShopIt/acknowledge.asp? SessionID = LGIJALLCGEBMIBIMFKOEJIMM HTTP/1.1

Example: Session information hidden in a form field:

Information sent to the client:

<html>
  …
<form action="kindofpayment.asp" method="post" >
  Currently we only accept Credit Cards
<input type="hidden" name="SessionID" value="LGIJALLCGEBMIBIMFKOEJIMM">
<input type="text" name="name" value="Jack " >
  <input type="submit" name="paymentButton" value="Submit">
</form>
…
</html>

Information returned to the server:

POST /ShopIt/kindofpayment.asp HTTP/1.1
…
SessionId=LGIJALLCGEBMIBIMFKOEJIMM&name=Jack&paymentButton=Submit
Parent topic: Customizing Session Handling


Session-Handling Customization Process

Session-handling customization typically follows a standard process. The high-level steps outlined below should be followed for each session ID:
  1. Determine whether or not a session ID needs to be customized.
  2. Search for the first response (Web API call in a script) in which the session ID is sent from the server to the client.
  3. Parse the session ID in the response into a variable.
  4. Replace all occurrences of the hard-coded session ID in the script with the variable.
  • Session ID Identification
    Explains how to determine whether or not a session ID needs to be customized.
  • Searching for the First response (Web API)
    Session-handling customization requires that you search for the first response (Web API call in a script) in which a session ID is sent from a server to a client.
  • Parsing and Replacing Session IDs
    Describes the conditions for parsing and replacing session IDs.
Parent topic: Customizing Session Handling


Session ID Identification

Because session IDs differ between recorded and replayed sessions, they are easily identified by comparing a record TrueLog to a replay TrueLog.

Session IDs can be found easily with TrueLog Explorer. Click Customize Session Handling on the workflow bar to automatically open the recorded TrueLog file that is associated with the open replay TrueLog. By reading through record and replay TrueLogs line by line, the differences in HTML responses between record and replay scripts can easily be identified
Note: Manual line-by-line reading is not required because the Differences page automatically lists the differences for you.

Session IDs should be customized when differing phrases in server response data from recorded sessions can also be found in the URLs of Web API calls or in form fields included in the DCLFORM sections of scripts.

Not all differences between returned data from record sessions and returned data from replay sessions are relevant for session customization. Only when the differences between record and replay sessions are embedded in scripts should session customization be considered. Such instances are indicated by a yellow warning message on the Differences page and by the column BDL Occurrences (when it has a value greater than 0).

Differences that most likely require customization are indicated by orange exclamation points on the Differences page. Differences that most likely do not require customization are indicated with blue question marks (replacing the occurrences of such strings in HTML is not recommended; parsing functions may be inserted for them, but replacements will not be made). Blue exclamation points are informational comments only.

Parent topic: Session-Handling Customization Process


Searching for the First response (Web API)

Session-handling customization requires that you search for the first response (Web API call in a script) in which a session ID is sent from a server to a client.

  1. Select a replay TrueLog from the menu tree.
  2. Click Compare mode on the toolbar.
  3. Click Diff Mode on the toolbar. The Differences page lists any differences it identifies between the TrueLogs.
  4. Right-click a listing on the Differences page and choose either Go to First Occurrence in BDL script or Go to First Occurrence in HTML.
Parent topic: Session-Handling Customization Process


Parsing and Replacing Session IDs

Once the session IDs and Web API calls of BDL scripts that return session IDs have been identified, the session IDs must be parsed from the responses to the Web API calls. All occurrences of hard-coded session IDs must be replaced with variables. TrueLog Explorer supports this task so that manual customization of scripts is not required. TrueLog Explorer generates appropriate parsing and replacement statements automatically.

  • Parsing and Replacing Session IDs
    To support session handling, hard-coded session information must be located and parsed into dynamic variables.
  • Parsing and Replacement Statements - Example
    Provides example code of the parsing and replacement statements that are required for the customization of session handling.
  • Manual Selection of Differences
    Describes how manual selection of parsed differences allows for more control over how phrases are parsed out.
  • Parsing Functions in Scripts
    Explains that parsing functions must be inserted before the Web API calls that initiate the parsing of response data.
Parent topic: Session-Handling Customization Process


Parsing and Replacing Session IDs

  1. Select a replay TrueLog from the menu tree.
  2. Click Customize Session Handling. The Workflow - Customize Session Handling dialog box opens.
  3. Click Find Differences. A dialog box displays, asking you if you want TrueLog Explorer to locate and display the associated record TrueLog.
  4. Click Yes. The associated record TrueLog opens in Compare View and the Step through TrueLog dialog box opens.
    Note: The Differences page identifies differences between record and replay data that may require customization. Use the Step through TrueLog dialog box to step through Whole pages of content and advance between API nodes until you find a difference that requires customization.
  5. Double-click a listing on the Differences page to open the Insert Parsing Function dialog box.
  6. Right-click a listing and choose Customize Session Handling. The Insert Parsing Function dialog box opens.
  7. The Insert Parsing Function dialog box offers parameters by which the parsing function can be adjusted. Though the default settings will likely be correct, you can adjust the following :
    1. Case sensitivity - Select this option if you want the parsing function to be case sensitive.
    2. Variable name - Enter the name of the variable that should receive the result of the parsing function.
    3. Left boundary - This field displays the left boundary of the specified text (the text that is located before the specified text).
    4. Right boundary - This field displays the right boundary of the specified text (the text that follows the specified text).
    5. Insert informational statement into script - Select Print statement to insert an informational print statement into the script after the Web page call. This will write the result of the parsing function to the Silk Performer Virtual User Output window.
    6. Select Writeln Statement (write line Statement) to write the parsed value to an output file to facilitate debugging (in addition to writing the value to the Virtual User Output window as a Print statement does). Because generating output files alters the time measurements of load tests, these files should only be used for debugging purposes and should not be generated for full load tests.
    7. Replace with variable - Checking this check box replaces all occurrences of the parsed text with the specified variable.
  8. Optional: Click Create Recording Rule if you want to create a recording rule based on the values you have specified. Refer to the Silk Performer Help for detailed information on creating recording rules.
  9. Click OK. Parsing and replacement statements required for customizing the handling of the selected session ID are generated.
  10. Run a Try Script to verify the customization and ensure that the session handling issue has been resolved. API nodes marked with green check marks indicate that no session errors were encountered during the Try Script run. Red X marks indicate that script replay errors are still present.
Parent topic: Parsing and Replacing Session IDs


Parsing and Replacement Statements - Example

The sample code below shows an example of the parsing and replacement statements that are required for the customization of session handling.

Note: The original session ID has been commented out, but it is still visible in the script.

The WebParseDataBoundEx function generated by TrueLog Explorer parses the value found between the boundaries name=\" and \" in the HTML document returned from the subsequent WebPageLink call. It then stores the actual value in the sSessionInfo1 variable. The parsing function must be specified before the Web API call from which the response data is to be parsed. To facilitate debugging, TrueLog Explorer inserts a Print statement that writes the parsed value to the Silk Performer Virtual User Output window. The session ID variable is assigned to the sFormSid1 form field variable, which is used directly in the DCLFORM script section in place of the constant session ID value (858891446).

Example

transaction TMain
begin
  ...
  WebParseDataBoundEx(sSessionInfo1, STRING_COMPLETE,
    "name=\"", 3, "\"", WEB_FLAG_IGNORE_WHITE_SPACE |
    WEB_FLAG_CASE_SENSITIVE, 1);
  WebPageLink("Check out", "ShopIt - Check Out"); // Link 3
  Print("sSessionInfo1: " + sSessionInfo1);

  ...

  sFormSid1 := sSessionInfo1;
  WebPageUrl("http://lab3/ShopItV60/kindofpayment.asp",
    "kindofpayment.asp", SHOPITV60_KINDOFPAYMENT_ASP004);
  ...
end TMain;

dclform
  ...
  SHOPITV60_KINDOFPAYMENT_ASP004:
    ...
//     "sid"                       := "858891446";
    "sid"                       := sFormSid1;
  ...
Parent topic: Parsing and Replacing Session IDs


Manual Selection of Differences

Selecting differences manually on the In Body page rather than relying on the Differences page allows for more control over how phrases are parsed out.

For example, using the Differences page when a session ID is embedded in multiple places in an HTML page, only the first occurrence of the phrase is parsed out. This is true even if the boundaries used for parsing are not adequate.

Manually selecting an occurrence that you want to parse out allows you to select more accurate boundaries.

  • Selecting Differences Manually
    Selecting differences manually in Source or In Body view allows for more control over how phrases are parsed out.
Parent topic: Parsing and Replacing Session IDs


Selecting Differences Manually

  1. Select a replay TrueLog from the menu tree.
  2. Click Compare mode on the toolbar.
  3. Identify a difference between the TrueLogs on the In Body page.
  4. Right-click the different phrase in the record TrueLog. If the phrase selected is static data contained in the BDL script, a context menu displays.
  5. Choose Customize Session Handling. The Insert Parsing Function dialog box opens.

You must now configure the parsing function as required.

Parent topic: Manual Selection of Differences


Parsing Functions in Scripts

Parsing functions must be inserted into scripts at a point before the Web API calls that initiate the parsing/verification of response data. Multiple parse/verification functions can be specified before each Web API call.

The order of parse/verification functions is not relevant. An exception to this rule includes WebParseDataBound and WebVerifyDataBound using the flag WEB_FLAG_SYNCHRON.

Example

Example of a BDL script utilizing a verification function:

WebVerifyHtml("Proper equipment leads to a successful trip", 1, ...);
WebPageLink("ShopIt");
Parent topic: Parsing and Replacing Session IDs


Using HTTP Parsing Rules

The HTTP parsing example is designed to give you an overview of Silk Performer recording-rule capabilities.

HTTP parsing rules specify when the recorder is to generate the parsing function WebParseDataBoundEx() for dynamically changing values and where it substitutes parsing results. Parsing rules enable the recorder to automatically generate working scripts. It typically eliminates the need for visual session customization with TrueLog Explorer.

  • Web Application Parsing Rule - Example
Parent topic: Customizing Session Handling


Web Application Parsing Rule - Example

ShopIt, the sample Web application, was deliberately built so that the Silk Performer recorder must script the context-less function WebPageUrl() with a form definition that contains a session ID. This is achieved by having JavaScript assemble the URL. Recording ShopIt without recording rules results in a script that has a hard-coded session ID.

In this guided HTTP parsing rule example the context less function WebPageUrl() is scripted with a form definition that contains a session ID. Upon executing a Try Script run, the hard-coded session ID causes a replay error.

The session-handling customization feature of TrueLog Explorer solves this problem by modifying the script as shown below:

Example

var
  sFormSid1     : string (100);
  sSessionInfo1  : string (100);

  ...

  WebParseDataBoundEx(sSessionInfo1, STRING_COMPLETE,
    "name=\"", 5, "\"", WEB_FLAG_IGNORE_WHITE_SPACE, 1);
  WebPageLink("Check out", "ShopIt - Check Out"); // Link 3
  Print("sSessionInfo1: " + sSessionInfo1);

  ...

  sFormSid1 := sSessionInfo1;
  WebPageUrl(sParsedUrl,
    "Unnamed page", SHOPITV60_KINDOFPAYMENT_ASP004);

  ...

dclform
  ...
  SHOPITV60_KINDOFPAYMENT_ASP004:
    "choice"                    := "CreditCard",
    "price"                     := "115.8",
//     "sid"                       := "858891471";
    "sid"                       := sFormSid1;

Custom Recorder Details

The script runs correctly now that it has been customized. However a problem exists in that each script that is to be recorded in the future will also have be customized.

HTTP parsing rules enable the Silk Performer recorder to continue this type of customization automatically in the future; recorded scripts can be generated automatically without manual interaction.

To do this, research must be done into how each session ID can be parsed. The customization offered by TrueLog Explorer reveals the API calls where each session ID first occurs, and the boundaries that can be used to parse each session ID.

Using TrueLog Explorer, the first occurrence of each session ID can be located in the HTML code.

<script LANGUAGE="JavaScript">
  function doProcess(mylink)
  {
    scheme="http://";
    server="lab3";
    serverport="";
    path="/ShopItV60/";
    file="kindofpayment.asp?";
    name="858891471";
      price="115.8";
    choice="CreditCard";
    mylink.href=scheme + server + serverport + path + file + "choice=" +
      choice + "&price=" + price + "&sid=" + name;
  }
</script>

The left boundary name=" and the right boundary " identified by TrueLog Explorer are good choices for the parsing of the session ID.

Now an initial version of an HTTP parsing rule can be written for the Recorder.

<RecordingRuleSet>

  <HttpParsingRule>
    <Name>ShopIt V5.1 Session Id</Name>

    <Search>
      <SearchIn>Body</SearchIn>
      <LB>
        <Str>name=&quot;</Str>
      </LB>
      <RB>
        <Str>&quot;</Str>
      </RB>
    </Search>

    <ScriptGen>
      <VarName>ShopItSessionId</Varname>
    </ScriptGen>

  </HttpParsingRule>

</RecordingRuleSet>

Since ShopIt session IDs do not appear in HTTP response headers, it is specified that only response bodies are to be searched (using the Search\SearchIn attribute).

It is specified that the session ID can be found by searching for the left boundary (the boundary is specified in the Search\LB\Str attribute).
Note: The quotation symbol (") has been encoded in XML using the character sequence &quot;.

A single quotation symbol marks the end of the session ID. This is specified with the Search\RB\Str attribute. Here again, the quotation symbol has been encoded.

Finally, specifics have been defined regarding how the variable for the parsing result is to be named. The name is specified using the ScriptGen\VarName attribute.

This rule file can be saved to the Silk Performer Include directory to make it globally available to all projects. The file name can be of any length, but the file extension .xrl must be used. Alternatively, if the recording rule is to be used with only one project, the file can be saved to the Documents directory of a specific Silk Performer project.

Parent topic: Using HTTP Parsing Rules


Adding Verifications

This section provides an overview of creating verification checks for HTML page titles, HTML content, HTML tables, and HTML source code.

Note: Content verifications are currently unavailable for TCP/IP- and UDP-based applications.
  • Verifications Overview
    Provides an overview for creating Web content verification checks for HTML page titles, HTML content, HTML tables, and HTML source code.
  • Verification Checks
    Explains the advantages of including verification checks in test scripts.
  • Inserting Content-Verification Functions
    Verification functions enable you to verify that content that is received by a client is identical to what was sent by the server under no-load conditions.
  • HTML Verification Functions
    Lists the functions that verify text-based content that is displayed in Web browsers.
  • Response-Data Verification Functions
    Lists the functions that are available for verification of response data that are returned by servers.
Parent topic: TrueLog Explorer 21.0
Related tasks
Adding Verification Statements Using Rendered XML View
Adding Verification Statements Using Plain-Text View


Verifications Overview

TrueLog Explorer enables you to create Web content verification checks for HTML page titles, HTML content, HTML tables, and HTML source code. By selecting text that you want to verify either in HTML source code or directly in rendered HTML view, all required verification functions can be generated and automatically inserted into your BDL script.

Visual Data Verification

TrueLog Explorer offers you two approaches to content verification. The easiest approach enables you to create content verification checks via a simple point-and-click interface.

Response Data Verification

Response data verification offers a more powerful, but more complex means of verifying server functionality. As with visual data verification, response data verification is also set up via a point-and-click interface. With visual data verification, you work in rendered HTML view and verify content that the application exposes to the end user. With response data verification, you verify data that are returned by servers that are not visible to the end user, such as HTML code and XML code.

Depending on the functions you select, TrueLog Explorer can generate response-data verification functions that apply to complete response data returned by servers or only to selections within specified boundaries.

Parent topic: Adding Verifications


Verification Checks

Explains the advantages of including verification checks in test scripts.

  • When to Use Verification Checks
    Explains the advantages of including verification checks in test scripts.
  • Automatically Generating Verifications During Recording
    Generate HTML page title verifications and response data digest verifications automatically during recording sessions.
  • Verification Checks with TrueLog Explorer
    Add content checks to your test scripts to verify that the content that is to be sent by servers is in fact received by clients under real-world conditions.
  • Enabling Verification Checks During Replay
    Enable or disable verification checks during replay via Silk Performer profile settings.
Parent topic: Adding Verifications


When to Use Verification Checks

Application errors often do not result in erroneous HTTP responses. More commonly, applications respond with incorrect data values or error messages that are incorporated into HTML content, such as Servlet Exception Occurred or Server Too Busy error messages. Because checks of HTTP status code do not uncover this class of error, application errors are often overlooked unless verification functions that check for non-standard HTTP errors are built into test scripts.

When verifications are built into test scripts, tests go from being simple load tests to hybrid load/functionality tests. Such scripts can be utilized without incurring significant performance loss, even in large load test scenarios. This functionality allows you to detect a class of error that other load tools are unable to detect because errors that occur only under load are undetected with standard load test scripts.

TrueLog Explorer offers the following means of enhancing test scripts with verification functionality:
  • Enabling the Silk Performer Recorder to automatically generate verification checks during recording.
  • Allowing users to apply verification checks visually in Rendered view via a point-and-click interface. No editing of BDL code is required. TrueLog Explorer automatically adds verification functions to scripts.
  • Directly enhancing scripts by manually inserting coded verification functions.
Parent topic: Verification Checks


Inserting Content-Verification Functions

  1. Open the TrueLog you want to analyze or modify.
  2. Select a TrueLog API node that includes content that you want to have verified (for example, text or an image).
  3. Select the content that is to be verified on the Source page.
    Note: This step is not required for page-title and page-digest verification functions.
  4. Click Add Verifications on the workflow bar. The Workflow - Add Verifications dialog box opens.
  5. Select a pre-enabled verification:
    • Verify the page title
    • Verify the selected text
    • Verify the selected text in an HTML table
    • Verify the digest
  6. Complete the following dialog box. Specify how verification functions should be inserted into the BDL script.
    Note: Left and right boundaries are automatically identified for you.
  7. Repeat the process for each verification you want to add to the BDL script.
  8. Click Yes on the Workflow - Add Verifications dialog box. A Try Script run is initiated.
  9. Confirm that verifications have passed successfully. API nodes that include verifications are indicated with blue “V” symbols.
The load testing script should be ready to run without error when the following tasks have been completed:
  • Customize how the application handles session information and user-input data.
  • Insert any required verification functions.
  • Complete any required manual BDL script editing via Silk Performer.
Parent topic: Adding Verifications


HTML Verification Functions

HTML verifications check rendered, visible Web content. They verify text-based content that is displayed in Web browsers. The following HTML verification functions can be applied in Rendered view:
  • WebVerifyHtmlTitle – Verifies page title.
  • WebVerifyHtml – Verifies text-based content.
  • WebVerifyHtmlBound(Ex) – Verifies content within bounds.
  • WebVerifyTable – Verifies content within an HTML table.
  • WebVerifyHtmlDigest – Verifies the digest of an HTML page.
  • Generating a Title-Verification Function
    Use WebVerifyHtmlTitle to check the titles (contents of HTML <title/> tags) of selected HTML pages.
  • Generating a Text-Verification Function
    Use WebVerifyHtml to verify selected text in Rendered view.
  • Generating a Text-Verification Function Within Boundaries
    Use WebVerifyHtmlBound(Ex) to verify selected text in Rendered view.
  • Generating an HTML Text-Verification Function
    Use WebVerifyTable to verify text selected within an HTML table cell in Rendered view.
  • Generating an HTML Digest Verification Function
    Use WebVerifyHtmlDigest to calculate and verify a Web page digest against a precalculated digest.
Parent topic: Adding Verifications


Generating a Title-Verification Function

The WebVerifyHtmlTitle function checks the titles (contents of HTML <title> tags) of selected HTML pages. No text selection is required to apply title verifications.

  1. In the menu tree, select the Web page that you want to verify.
  2. Perform one of the following steps:
    • Choose Script > Verify Page Title .
    • Click Add Verifications and then click Verify page title on the Workflow - Add Verifications dialog box.
    The page title is included in the constant value text box, and the constant value option button is selected.
  3. Optional: To verify against an existing parameter or a new parameter, click the parameter value option button.
    1. Click [...] to browse to and select a parameter.
    2. If no parameters exist, click Next to open the Parameter Wizard and create a new parameter.
  4. From the Verify that the page title list box, select one of the following choices:
    • is equal to
    • is different from
    • contains
    • does not contain
  5. Check the relevant check boxes to make the verification case-sensitive or to apply it as a script-wide rule.
  6. In the Severity group box, specify the severity that should be raised if the verification returns a negative result.
  7. Click OK. The function is then added to your test script.

Code Example

The following sample code (in bold) is generated automatically for title verifications:

transaction TMain
begin
  ...
  WebVerifyHtmlTitle("ShopIt - Greetings",
    WEB_FLAG_IGNORE_WHITE_SPACE |
    WEB_FLAG_EQUAL | WEB_FLAG_CASE_SENSITIVE, 1,
    SEVERITY_ERROR, bVerifyTitleSuccess1);
  WebPageUrl("http://myHost/shopit");
  ...
Parent topic: HTML Verification Functions


Generating a Text-Verification Function

The WebVerifyHtml function verifies selected text in Rendered view. TrueLog Explorer automatically detects the number of occurrences of selected text in HTML documents.

  1. In the menu tree, select the Web page that you want to verify.
  2. In Rendered view, select the appropriate text.
  3. Perform one of the following steps:
    • Choose Script > Verify Selected Text .
    • Right-click the selected text and choose Verify Selected Text.
    • Click Add Verifications and choose Verify selected text in HTML page from the Workflow - Add Verifications dialog box.
    The selected text is displayed in the constant value text box, and the constant value option button is selected.
  4. Optional: To verify against an existing parameter or a new parameter, click the parameter value option button.
    1. Click [...] to browse to and select a parameter.
    2. If no parameters exist, click Next to open the Parameter Wizard and create a new parameter.
  5. Optional: To make the verification more tolerant, adjust the following settings:
    Note: The settings on this dialog box are automatically set to values that guarantee a successful verification for the current page. Only in cases in which you want to make a verification more tolerant should these settings be changed (for example, by changing "exactly" "2" times to "at least" "1" time, or by making a verification case-insensitive).
    1. From the Occurs list box, select one of the following choices:
      • exactly
      • at least
      • at most
    2. Type a number in the time(s) in this page text box.
  6. Check the relevant check boxes to make the verification case-sensitive or to apply it as a script-wide rule. A result variable name is displayed in the Result variable name text box.
  7. Optional: Edit the Result variable name.
  8. Ensure that the Require boundary strings check box is unchecked.
  9. In the Severity group box, specify the severity that should be raised if the verification returns a negative result.
  10. Click OK. The function is then added to your test script.

Code Example

The following sample code (in bold) is generated automatically for HTML text verifications:

transaction TMain
begin
  ...
  WebVerifyHtml("Hi Tester! ", 1, WEB_FLAG_IGNORE_WHITE_SPACE |
    WEB_FLAG_EQUAL | WEB_FLAG_CASE_SENSITIVE, NULL,
    SEVERITY_ERROR, nVerifyHtmlResult1);
  WebPageSubmit("Enter", SHOPIT_MAIN_ASP001, "ShopIt - Main menu");
  ...
Parent topic: HTML Verification Functions


Generating a Text-Verification Function Within Boundaries

The WebVerifyHtmlBound(Ex) function verifies text selected in Rendered view. TrueLog Explorer automatically detects unique boundaries that identify the position of selected text.

Note: With Silk Performer, TrueLog Explorer uses WebVerifyHtmlBoundEx instead of WebVerifyHtmlBound.
  1. In the menu tree, select the Web page that you want to verify.
  2. In Rendered view, select the appropriate text.
  3. Perform one of the following steps:
    • Choose Script > Verify Selected Text .
    • Right-click the selected text and choose Verify Selected Text.
    • Click Add Verifications and choose Verify selected text in HTML page from the Workflow - Add Verifications dialog box.
    The selected text is displayed in the constant value text box, and the constant value option button is selected.
  4. Optional: To verify against an existing parameter or a new parameter, click the parameter value option button.
    1. Click [...] to browse to and select a parameter.
    2. If no parameters exist, click Next to open the Parameter Wizard and create a new parameter.
  5. Check the relevant check boxes to make the verification case-sensitive or to apply it as a script-wide rule. A result variable name is displayed in the Result variable name text box.
  6. Optional: Edit the Result variable name.
  7. Check the Require boundary strings check box. This disables the occurs frequency settings.

    Left and right boundaries appear in the Left boundary and Right boundary text boxes. Boundary strings cannot be edited from this dialog box.

  8. In the Severity group box, specify the severity that should be raised if the verification returns a negative result.
  9. Click OK. The function is then added to your test script.

Code Example

The following sample code (in bold) is generated automatically for HTML text verifications within boundaries:

transaction TMain
begin
  ...
  WebVerifyHtmlBound("Name:", "Address", "Tester",
    WEB_FLAG_IGNORE_WHITE_SPACE | WEB_FLAG_CASE_SENSITIVE,
    NULL, SEVERITY_ERROR, bVerifyHtmlBoundSuccess2);
  WebPageSubmit("Submit", SHOPIT_KINDOFPAYMENT_ASP002”);
  ...
Parent topic: HTML Verification Functions


Generating an HTML Text-Verification Function

The WebVerifyTable function verifies text selected within an HTML table cell in Rendered view. TrueLog Explorer automatically identifies the HTML table as well as the row and column of the selected cell.

  1. In the menu tree, select the Web page that you want to verify.
  2. In Rendered view, select the relevant text in a table cell.
  3. Perform one of the following:
    • Choose Script > Verify Selected Text in HTML Table .
    • Click Add Verifications and select Verify selected text in HTML table on the Workflow - Add Verifications dialog box.
    The selected row and column are displayed in the Verify that list boxes. Specify a different row or column as required.
  4. From the list box, select one of the following choices:
    • is equal to
    • is different from
    • contains
    • does not contain
    The selected text is displayed in the value text box, and the value option button is selected.
  5. Optional: To verify against an existing parameter or a new parameter, click the parameter value option button.
    1. Click [...] to browse to and select a parameter.
    2. If no parameters exist, click Next to open the Parameter Wizard and create a new parameter.
  6. Specify whether the verification is to be Case sensitive.
  7. In the Severity group box, specify the severity that should be raised if the verification returns a negative result.
  8. Click OK. The function is then added to your test script.

Code Example

The following sample code (in bold) is generated automatically for HTML table verifications:

transaction TMain
begin
  ...
  WebVerifyTable(7, 3, 1, "115.8",
    WEB_FLAG_IGNORE_WHITE_SPACE |
    WEB_FLAG_CONTAINS | WEB_FLAG_CASE_SENSITIVE,
    NULL, SEVERITY_ERROR, bVerifyTableSuccess1);
  WebPageLink("Add to basket", "ShopIt - Basket");
  ...
Parent topic: HTML Verification Functions


Generating an HTML Digest Verification Function

The WebVerifyHtmlDigest function calculates and verifies a Web page digest against a precalculated digest. A digest is a character frequency table that is calculated for certain characters within a rendered HTML page. If an HTML document is contained within a frame set, text is verified only for the frame that contains the selected text, not the entire page.

  1. In the menu tree, select the Web page that you want to verify.
  2. Choose Rendered view.
  3. Perform one of the following steps:
    • Choose Script > Verify Page Digest .
    • Click Add Verifications and then click Verify digest on the Workflow - Add Verifications dialog box.
    A name for the digest is displayed in the Constant name text box.
  4. Optional: Edit the Constant name text box.
  5. In the Verify group box, specify how the verification should be applied:
    • All characters
    • Printable characters
    • Alphanumeric characters
  6. In the Severity group box, specify the severity that should be raised if the verification returns a negative result.
  7. Click OK. The function is then added to your test script.

Code Example

The following sample code (in bold) is generated automatically for HTML digest verifications:

const
  HTML_DIGEST_1     :=
"\h01910000000011D063032CCB7D023EFBBD02000000000000000000000000000000001
602010601010703010108010503020201"
"\h03010201030502010105010403070103010205050402060107050102";

transaction TMain
begin
  ...
  WebVerifyHtmlDigest(HTML_DIGEST_1, 79, 0, 0, NULL,
    SEVERITY_ERROR);
  WebPageLink("Check out", "ShopIt - Check Out"); // Link 3
  ...
Parent topic: HTML Verification Functions


Response-Data Verification Functions

Response-data verification functions verify that correct response data is returned by servers. In the case of Web applications, data verifications include comprehensive source code checks.

Response data verification functions can be applied visually by selecting data, such as code or text, in Source view. TrueLog Explorer can generate the following data-verification functions:
  • WebVerifyData – Verifies selected data.
  • WebVerifyDataBound(Ex) – Verifies selected data within boundaries.
  • WebVerifyDataDigest – Verifies a data digest.
  • Generating an HTML Data-Verification Function
    Use WebVerifyData to verify selected data, such as code or text, in Source view.
  • Generating a Data-Verification Function Within Boundaries
    Use WebVerifyDataBound(Ex) to verify selected data, such as code or text, in Source view.
  • Generating an HTML Data-Digest Verification Function
    Use WebVerifyDataDigest to calculate and check a Web-page digest against a precalculated digest.
Parent topic: Adding Verifications


Generating an HTML Data-Verification Function

The WebVerifyData function verifies selected data, such as code or text, in Source view. TrueLog Explorer automatically detects the number of occurrences of selected data in selected HTML documents.

  1. In the menu tree, select the Web page that you want to verify.
  2. Select the relevant data in Source view.
  3. Perform one of the following steps:
    • Choose Script > Verify Selected Text .
    • Right-click the selected text and choose Verify Selected Text.
    • Click Add Verifications and choose Verify selected text in HTML page from the Workflow - Add Verifications dialog box.
    The selected text is displayed in the constant value text box, and the constant value option button is selected.
  4. Optional: To verify against an existing parameter or a new parameter, click the parameter value option button.
    1. Click [...] to browse to and select a parameter.
    2. If no parameters exist, click Next to open the Parameter Wizard and create a new parameter.
  5. Specify the frequency by which the selected text is to appear, as follows:
    1. From the Occurs list box, select one of the following choices:
      • exactly
      • at least
      • at most
    2. Type a number in the time(s) in this page text box.
  6. Check the relevant check boxes to make the verification case-sensitive or to apply it as a script-wide rule. A result variable name is displayed in the Result variable name text box.
  7. Optional: Edit the Result variable name.
  8. Ensure that the Require boundary strings check box is unchecked.
  9. In the Severity group box, specify the severity that should be raised if the verification returns a negative result.
  10. Click OK. The function is then added to your test script.

Code Example

The following sample code (in bold) is generated automatically for data verifications:

transaction TMain
begin
  ...
  WebVerifyData("main.asp?from=welcome", 1,
    WEB_FLAG_IGNORE_WHITE_SPACE |
    WEB_FLAG_EQUAL | WEB_FLAG_CASE_SENSITIVE, 1,
    SEVERITY_ERROR, nVerifyDataResult1);
  WebPageUrl("http://myHost/shopit/", "ShopIt - Greetings");
  ...
Parent topic: Response-Data Verification Functions


Generating a Data-Verification Function Within Boundaries

The WebVerifyDataBound(Ex) function verifies selected data, such as code or text, in Source view. TrueLog Explorer automatically detects unique boundaries that identify the position of selected data.

Note: TrueLog Explorer uses WebVerifyDataBoundEx instead of WebVerifyDataBound.
  1. In the menu tree, select the Web page that you want to verify.
  2. Select the relevant data in Source view.
  3. Perform one of the following steps:
    • Choose Script > Verify Selected Text .
    • Right-click the selected text and choose Verify Selected Text.
    • Click Add Verifications and choose Verify selected text in HTML page from the Workflow - Add Verifications dialog box.
    The selected text is displayed in the constant value text box, and the constant value option button is selected.
  4. Optional: To verify against an existing parameter or a new parameter, click the parameter value option button.
    1. Click [...] to browse to and select a parameter.
    2. If no parameters exist, click Next to open the Parameter Wizard and create a new parameter.
  5. Check the relevant check boxes to make the verification case-sensitive or to apply it as a script-wide rule. A result variable name is displayed in the Result variable name text box.
  6. Optional: Edit the Result variable name.
  7. Check the Require boundary strings check box. This disables the occurs frequency settings.

    Left and right boundaries appear in the Left boundary and Right boundary text boxes. Boundary strings cannot be edited from this dialog box.

  8. In the Severity group box, specify the severity that should be raised if the verification returns a negative result.
  9. Click OK. The function is then added to your test script.

Code Example

The following sample code (in bold) is generated automatically for data verifications within boundaries:

transaction TMain
begin
  ...
  WebVerifyDataBound("ahref=\"", "\"", "main.asp?from=welcome",
    WEB_FLAG_IGNORE_WHITE_SPACE | WEB_FLAG_CASE_SENSITIVE, 1,
    SEVERITY_ERROR, bVerifyDataBoundSuccess1);
  WebPageUrl("http://myHost/shopit/", "ShopIt - Greetings");
  ...
Parent topic: Response-Data Verification Functions


Generating an HTML Data-Digest Verification Function

The WebVerifyDataDigest function calculates a Web page digest and then subsequently verifies content against the precalculated digest. In the case of HTML or XML source code, a digest consists of a character-frequency table, which is calculated for certain characters in a page-response body.

  1. In the menu tree, select the Web page that you want to verify.
  2. Open Source view.
  3. Perform one of the following steps:
    • Choose Script > Verify Page Digest .
    • Click Add Verifications and then click Verify digest on the Workflow - Add Verifications dialog box.
    A name for the digest is displayed in the Constant name text box.
  4. Optional: Edit the Constant name text box.
  5. In the Verify group box, specify how the verification should be applied:
    • All characters
    • Printable characters
    • Alphanumeric characters
  6. In the Severity group box, specify the severity that should be raised if the verification returns a negative result.
  7. Click OK. The function is then added to your test script.

Code Example

The following sample code (in bold) is generated automatically for data digest verifications:

const
  DATA_DIGEST_1     :=
"\h019200000000E7FBEFFFAEF7FD2AFEFFFF2B000000000000000000000000000000004
F06040072000800020038000600060002"
"\h0006000A0035004B0024000E00050001000100010001000200010002000F0059005A0
058000100030007000300020003000100";
"\h1200010001000600020003000100150013000200010001000300010003000300A1002
30047003E00BA002100710056009B0001"
"\h000D0062003C00620079003E000300AE006D00BC0023000E002C0005000E000200020
0";

transaction TMain
begin
  ...
  WebVerifyDataDigest(DATA_DIGEST_1, 188, 0, 0, 1,
    SEVERITY_ERROR);
  WebPageUrl("http://lab3/ShopItV60/default.asp", "ShopIt - Greetings");
  ...
Parent topic: Response-Data Verification Functions


Customizing User Data

This section explains how user-input data can be parameterized to better emulate real-world user activity during load testing.

  • User-Input Data
    Explains how user-input data customization allows you to make test scripts more realistic by replacing recorded input data with parameterized data.
  • User-Data Customization Scenarios
    Explains the five scenarios within which user-data customization is typically employed.
  • Customizing HTML User Data
    Explains how to customize HTML user data based on parameters.
  • Form Data View
    Describes the Form Data view, which provides a convenient means of viewing and customizing all customizable form fields.
  • Multi-Column Data Files
    Explains the advantages of using multi-column data files.
Parent topic: TrueLog Explorer 21.0


User-Input Data

The visual user-input data customization feature allows you to make your test scripts more realistic by replacing recorded user-input data with parameterized data.

Without user-input data customization, all simulated transactions are identical and do not account for the variables that are typically experienced in real world environments.

For example, you can customize the user-input data that is entered into forms during testing using the Parameter Wizard. The Parameter Wizard lets you specify the values that are to be entered into form fields during testing. This enables test scripts to be more realistic by replacing recorded user-input data with randomized, parameterized user data.

User data customization can be used to:
  • Perform functional tests by challenging servers with different values each time certain transactions are executed.
  • Simulate realistic user behavior by selecting submitted values based on given probability distributions.

TrueLog Explorer Workflow

User data customization is best performed:
  • After session information has been parsed from test scripts
  • Before server responses have been verified
Parent topic: Customizing User Data


User-Data Customization Scenarios

There are five scenarios within which user-data customization is typically employed:
  • The posting of HTML forms by means of WebPageSubmit
  • The posting of XML data by means of WebUrlPostBin or WebCustomRequestBin
  • The posting of data for database applications by means of binding input data to SQL commands and stored procedures for database applications including Oracle OCI, DB2 CLI, and ODBC (by means of OraSet*, Ora8Set*, and OdbcSet*).
  • The posting of Oracle Forms control value changes (user input) by means of OraForms*Set functions.
  • The posting of Citrix user-input actions (for example, mouse events and keyboard inputs) by means of CitrixKey* and CitrixMouse* functions.
Note: User-data customization is not supported for terminal emulation applications, though input parameters can be manually edited in terminal-emulation test scripts.

In the case of HTML, parameterization is performed via form declarations. Parameterization replaces hard-coded form field values, as declared in the dclform sections of test scripts, with random variables.

For XML and database applications, parameterization takes place in the parameters of the above-mentioned function calls, where hard-coded parameter values are replaced with data-driven variables or random variables.

Parent topic: Customizing User Data


Customizing HTML User Data

Explains how to customize HTML user data based on parameters.

  • Customizing HTML User Data With a New Parameter
    Explains the process of creating a parameter based on a random variable.
  • Customizing HTML User Data With an Existing Parameter
    Emulate irregular and diverse user behavior by customizing HTML user data with an existing parameter.
Parent topic: Customizing User Data


Customizing HTML User Data With a New Parameter

Before proceeding, ensure that all static session information has been removed from your test script and that the most recent Try Script run produced a TrueLog that is open in TrueLog Explorer.

With HTML-based applications, the goal of user-data customization is to customize values submitted to form fields.

This task explains the process of creating a parameter based on a random variable.

  1. Choose File > Add TrueLogs to load a TrueLog into TrueLog Explorer. The TrueLog must be based on a Try Script that has had all static session information removed from it.
  2. Click Customize User Data on the workflow bar. The Workflow - Customize User Data dialog box opens.
  3. Click the Customize user input data in HTML forms link. TrueLog Explorer then performs the following actions:
    • Selects the first WebPageSubmit API call node in the menu tree.
    • Opens the Step through TrueLog dialog box (with the Form submissions option button selected).
    • Displays Request view

      Request view shows the page that contains the HTML form that was submitted by the selected WebPageSubmit call. When your cursor passes over a form control, a tool tip shows the control’s name in addition to its initial and submitted values; an orange line indicates the corresponding BDL form field declaration in Form Data view below.

  4. Click Find Next or Find Previous on the Step through TrueLog dialog box to browse through all WebPageSubmit calls in the TrueLog (these are the calls that are candidates for user-data customization).
    Note: Highlighted HTML controls in Request view identify form fields that can be customized.
  5. On the Request page, right-click the form control that you want to customize and choose Customize Value. You can replace the recorded values with various types of input data (including predefined values from files and generic random values) and generate code into your test script that substitutes recorded input data with your customizations. The Parameter Wizard opens.
    With the Parameter Wizard you can modify script values in two ways:
    • Use an existing parameter that is defined in the dclparam or dclrand sections of your script.
    • Create a new parameter based on a new constant value, random variable, or values in a multi-column data file.

    After you create a new parameter, that parameter is added to the existing parameters and is available for further customizations.

  6. Click the Create new parameter option button and then click Next to create a new parameter. The Create New Parameter page opens.
  7. Click the Parameter from Random Variable option button and then click Next. The Random Variable page opens.
  8. From the list box, select the type of random variable that you want to insert into your test script and then click Next. A brief description of the selected variable type appears in the lower window. The Name the variable and specify its attributes page opens.
  9. Enter a name for the variable in the Name text box.
  10. Optional: Create a new random variable file by clicking New in the File group box.
  11. Specify whether the values should be called in Random or Sequential order. The Strings from file random variable type generates data strings that can either be selected randomly or sequentially from a specified file.
  12. In the File group box, select a preconfigured data source from the Name list box and then click Next. The Choose the kind of usage page displays.
  13. Specify the new random value to use by selecting one of the following choices:
    • Per usage
    • Per transaction
    • Per test
  14. Click Finish. Your test script now uses the random variable for the given form field in place of the recorded value. The new random variable function appears on the BDL page.

Initiate a Try Script run with the random variable function in your test script to confirm that the script runs without error.

Parent topic: Customizing HTML User Data


Customizing HTML User Data With an Existing Parameter

  1. Choose File > Add TrueLogs to load a TrueLog into TrueLog Explorer. The TrueLog must be based on a Try Script that has had all static session information removed from it.
  2. Click Customize User Data on the workflow bar. The Workflow - Customize User Data dialog box opens.
  3. Click the Customize user input data in HTML forms link.
  4. Click Find Next or Find Previous on the Step through TrueLog dialog box to browse through all WebPageSubmit calls in the TrueLog.
    Note: These are the calls that are candidates for user data customization.
    The Request page shows the page that contains the HTML form that was submitted by the selected WebPageSubmit call. When the cursor passes over a form control, a tool tip shows the name of the control in addition to its initial and submitted values.
    Note: Highlighted HTML controls on the Request page identify form fields that can be customized.
  5. On the Request page, right-click the form control that you want to customize and choose Customize Value. You can replace the recorded values with various types of input data (including predefined values from files and generic random values) and generate code into your test script that substitutes recorded input data with your customizations. The Parameter Wizard opens.
    With the Parameter Wizard you can modify script values in two ways:
    • Use an existing parameter that is defined in the dclparam or dclrand sections of your script.
    • Create a new parameter based on a new constant value, random variable, or values in a multi-column data file.

    After you create a new parameter, that parameter is added to the existing parameters and is available for further customizations.

  6. Select Use existing parameter. This allows specification of an existing parameter that is defined in the dclparam or dclrand sections of the test script.
  7. From the list box, select the datatype to use. This list shows all the variables that have been defined in the dclparam and dclrand sections of the test script.
  8. Click Finish. The test script will be modified with the new parameter.
  9. Click Find Next on the Step through TrueLog dialog box to locate the next form field to be customized.
Parent topic: Customizing HTML User Data


Form Data View

For each function call that changes input data, you can customize input data from both the Request view and the Form Data view. The Form Data view offers a convenient means of viewing and customizing all customizable form fields. The Form Data view is a representation of the forms section of the BDL script with all included name/value pairs.

Right-click a control and choose Customize Value (just as with Request view) to open the Parameter Wizard.

Controls for which user data has already been customized are displayed with a green outline.

Parent topic: Customizing User Data


Multi-Column Data Files

Parameterization from multi-column data files is a powerful means of parameterizing data. It defines files in which specific combinations of string values are stored. Each column in a data file corresponds to a specific parameter. Multi-column data files enable a data-driven test model and allow you to cover all user-data input with a single data file.

Parent topic: Customizing User Data
Parent topic: SAPGUI Test-Script Customization
Parent topic: Oracle Forms User-Input Data Customization


Working With Database Applications

This section explains how to apply TrueLog Explorer script-customization features to the testing of applications that rely on common database APIs.

  • Working With Database Applications - Overview
    Explains how to apply TrueLog Explorer script-customization features to the testing of applications that rely on common database APIs.
  • Sample Database Application - Customer OCI
    Use this application to acquaint yourself with TrueLog Explorer’s database-application capabilities.
  • Database TrueLog Structure
    Describes the views that are available to assist you in analyzing database TrueLogs.
  • Correlations
    Explains how to identify correlations between database input and output parameters.
  • Database Parsing Function
    Describes the Parse Element Value function, which generates a parsing statement for one element of a result set.
  • Input Parameter Customization
    Describes assigning input parameter customization to SQL statements.
  • Verifications for Result-Set Data
    Apply verifications to the result sets of database operations such as SQL queries. Verifications enhance your test results by raising errors when anticipated test results are not returned during test runs.
Parent topic: TrueLog Explorer 21.0


Working With Database Applications - Overview

Silk Performer offers enhanced database support, including enhanced support for Microsoft ODBC and Oracle Call Interface 8 (OCI8), the standard interface for accessing Oracle databases (versions 8 and 9).

Silk Performer database support includes the following APIs:

  • Oracle OCI 7.0

  • Oracle OCI 8.0
  • Microsoft ODBC
  • IBM DB2/CLI
For database applications, TrueLog Explorer offers the same script customization features that are available for Web-based applications, including:
  • User input-data customization
  • Verification functions
  • Customization of output-input correlations (comparable to session-handling customization in Web applications)
Note: TrueLog On Error Analysis for databases is not currently supported.

Before proceeding with this chapter, it is essential that you familiarize yourself with TrueLog Explorer basic functionality.

Parent topic: Working With Database Applications


Database TrueLog Structure

TrueLog Explorer supports the visualization of database requests and responses in the same way that it supports the visualization of HTTP client requests and HTTP/HTML server responses for Web applications. Although with database TrueLogs, a readable database format is presented rather than a GUI as is the case with HTML TrueLogs.

TrueLog Explorer acts as a database browser in which SQL statements and their corresponding input parameters and output parameters can be viewed concurrently. Each supported database API presents data in the same TrueLog format.

The five windows that are offered with database TrueLogs are as follows:
  • Menu tree - Lists all relevant database API calls (those that send or retrieve data).
  • Input parameter - SQL input (bind) data sent to the database.
  • SQL command - Corresponding SQL command.
  • Result set - Output SQL data received by the client.
  • Information - Data regarding the test run.

The only view tabs that are active and applicable to database TrueLogs are SQL Command, Info, and BDL.

Graphic that shows the window layout

Graphic that shows the TrueLog structure

Parent topic: Working With Database Applications


Correlations

This section explains how to identify correlations between database input and output parameters.

  • Output-Input Correlations
    Provides an overview of the output-input correlation feature, which enables you to step through record and replay API calls side-by-side.
  • Replacing Session Data with Variables
    Replace session-relevant data with variables to compare replay test runs with record sessions. The differing values are then used as the basis for searches of correlations between output and input values.
  • Manual Correlation
    Explains when to manually search for correlations between output and input values.
Parent topic: Working With Database Applications


Output-Input Correlations

TrueLog Explorer output-input correlation allows you to step through record and replay API calls side-by-side. It also identifies correlations between database input and output parameters. Similar to session-handling customization for Web applications, output-input correlation compares replay test runs to record sessions to identify differences that may indicate session-relevant values. The differing values are then used as the basis for searches of correlations between output and input values within test-run scripts. Ultimately, TrueLog Explorer enables you to modify identified dynamic values in your test scripts.

The output-input correlation feature is accessible from the workflow bar when database TrueLogs are open in TrueLog Explorer.

Database-error types are specific to the database type under test. Unique constraint errors typically result when identical data is submitted to a database multiple times. Such errors commonly present themselves when unique values that are used as primary keys in database tables, such as user IDs and order numbers, are submitted. When such personal information is submitted more than once, errors are raised. This type of duplication is the sort of session information that can be identified in test scripts and customized using TrueLog Explorer.

An output-input correlation is illustrated in the following two BDL code examples. The input parameter of the execution call is 2288. Because this value occurred in an output parameter table of a previous call, a correlation has been identified.

The value of the output parameter (2290) is parsed into a variable (sParam1) so that it can be used to set the value of the input parameter in future test runs.

Parent topic: Correlations


Replacing Session Data with Variables

  1. Choose File > Add TrueLogs . The Open dialog box opens.
  2. Select a replay database TrueLog and click OK. The replay TrueLog opens in TrueLog Explorer.
  3. Click Output-Input Correlations on the workflow bar. The Workflow - Output-Input Correlations dialog box displays.
  4. Click Find Differences. A message box asks if you want to have the associated record TrueLog opened automatically.
  5. Click OK. Compare mode is enabled. The record TrueLog is opened and the Step through Correlations dialog box displays.
  6. Using the default selections (Different result sets and Record TrueLog value) click Find Next to advance to the first difference between recorded result set data and replayed result set data. Differences are dynamic data returned by the database server, which are potential candidates for correlation. If dynamic data are used in further SQL commands or stored procedures as input parameters, then they constitute correlations between output and input data.
  7. Click Correlate. The Output - Input Correlations dialog box opens.

    If a dynamic value occurs as an input value in another SQL command or stored procedure, the statement/procedure name will appear in the Use output parameter value as input for following calls window. TrueLog Explorer can create a variable to subsequently replace the input parameter values of these calls with output parameter values.

    Note: If No correlating values appears in the Use output parameter value as input for following calls window, then no correlations have been found. Click Cancel to return to the Step through Correlations dialog box.
  8. Click Check to select the identified statement name (there may be several).
  9. Click Goto to see the input value in the context of the test script.
  10. If you believe that the input value should be customized, click Customize to modify the input parameters in the test script by replacing them with variables.

    Graphic that shows the dynamic key

    Graphic that shows run-time value

Initiate a Try Script run to confirm that the script runs without error.

Parent topic: Correlations


Manual Correlation

Manual correlation is only recommended for applications with which you have advanced knowledge. To perform manual correlation, right-click a replay parameter in the SQL Command view and choose Find Correlation.

Manual correlation is available in In Body view (input parameters), Out Body view (result sets), and SQL Command view. When used in In Body view, TrueLog Explorer searches for correlating values (in Out Body view) that precede the SQL command. When used in Out Body view, TrueLog Explorer searches for correlating values (in In Body view) that follow the SQL command. When used in SQL Command view, TrueLog Explorer searches for correlating values (in Out Body view) that precede the SQL command, in case parameters are hard-coded in SQL commands.

For example:

INSERT INTO MY_PERSON (P_NO, P_FIRSTNAME, P_LASTNAME)
VALUES ( 2289, "Michael", "Smith" )
Parent topic: Correlations


Database Parsing Function

For database TrueLogs, TrueLog Explorer offers a single parsing function, Parse Element Value. This parsing function is available from the context menu in the SQL window’s Output data view.

The function generates a parsing statement for one element of a result set. Example:

Ora8StmtExecute(ghSvcCtx0, ghStmt0);
Ora8StmtFetch(ghStmt0, ORA_FETCH_ALL, 100); // rows fetched: 1
sParam2 := RsGetString("1", 4);
Print("sParam2: " + sParam2);

Depending on the data type (number, float, or string), the appropriate parsing function is then generated (RsGetInt, RsGetFloat, or RsGetString).

Parent topic: Working With Database Applications


Input Parameter Customization

For effective load testing, it is recommended that parameterized input data be assigned to SQL statements so that values are submitted each time database tests are run. Otherwise, identical recorded input parameter values will be sent with each test run, which is not a realistic simulation of real-world user activity. TrueLog Explorer enables you to visually generate code in your test scripts that substitutes recorded input parameter values with customized input parameters.

Note: The same method is used with the customization of user data for Web applications.

You can use Customer OCI, the sample database application, to experiment with the customization of user-input data. Scripts that replay simple recorded business transactions can be customized with variables that input randomized data into otherwise constant data fields. Input-data values may be constant values, random values, or values drawn from preconfigured data files, such as CSV files.

  • Creating an Input Parameter Based on a Multi-Column Data File
    Parameterization from multi-column data files is a powerful means of parameterizing data. It defines files in which specific combinations of string values are stored.
Parent topic: Working With Database Applications


Creating an Input Parameter Based on a Multi-Column Data File

Parameterization from multi-column data files is a powerful means of parameterizing data. It defines files in which specific combinations of string values are stored. Each column in a data file corresponds to a specific parameter. Multi-column data files enable a data-driven test model and allow you to cover all user-data input with a single data file.

  1. Choose File > Add TrueLogs . The Open dialog box opens.
  2. Select a replay database TrueLog and click OK. The replay TrueLog opens in TrueLog Explorer.
  3. Click Customize Input Parameters on the workflow bar. The Workflow - Customize Input Parameters dialog box opens.
  4. Click Customize input parameters. The first API node in the test script that includes input parameters is selected and the Step through TrueLog dialog box opens with the Input parameters option button selected.
    Note: If you do not want to customize input parameters for the selected node, click Find Next to advance to the next node that incorporates input parameters.

    Graphic that shows data customization
  5. In Input Parameter or SQL Command view, right-click an input parameter and choose Customize Value. Two methods are available for modifying values in scripts. You can use an existing parameter that has previously been defined in the dclparam or dclrand sections of the BDL script, or you can create a new parameter. New parameters can be created from constant values, random variables, or variables based on data in multi-column data files. The Parameter Wizard - Customize Value dialog box opens.
  6. Click the Parameter from Multi-column Data File option button and click Next. The Parameter Wizard - Parameter from Multi-column Data File page opens.
  7. Perform one of the following steps:
    • Select a preconfigured multi-column data file from the File name list box.
    • Create a new multi-column CSV (Comma Separated Values) file by clicking New file. Then, enter a name for the new file and click OK.
  8. Right-click columns to edit column names, add/delete rows, or add/delete entire columns.
    Note: Each column represents a separate parameter that is assignable to a single input value.
  9. Type data into the data fields as appropriate. Alternatively, you can select column header names directly to customize them.
  10. Customize Handle name or the Parameter name as required.
  11. Click Next to save the file. The Choose the Insert Attribute of the Parameter page opens.
  12. In the Row selection order group box specify the order in which the values from the multi-column data file are to be assigned:
    • Random - Using function FileGetRndRow, the parameter will be assigned from a random row in the data file.
    • Sequential (machine-wide) - Using the functions FileCSVLoadGlobal and FileGetNextRow, the parameter will be assigned from the next sequential row in the data file, on a machine-wide basis. All virtual users on a machine will use the same global row pointer for the current row.
    • Sequential (test-wide) - Using the functions FileCSVLoadGlobal and FileGetNextUniqueRow, the parameter will be assigned from the next sequential row in the data file, on a test-wide basis. All virtual users across all machines will use the same global row pointer for the current row. Check Remove used data rows to automatically remove data from the data file, once it has been used.
      Note: The removed data cannot be restored.
  13. In the Attribute group box, specify the frequency at which new insertions should be inserted. For example, specify if a new username should be inserted with each transaction or only once per test.
    • Per transaction
    • Per test

    All available user groups and transactions are available from the Per transaction list boxes.

  14. Click Finish. TrueLog Explorer modifies the test script and saves the multi-column data file.
Customized input parameters are indicated in green.

Initiate a Try Script run with the random variable function in your test script to confirm that the script runs without error.

Parent topic: Input Parameter Customization


Verifications for Result-Set Data

TrueLog Explorer allows you to apply verifications to the result sets of database operations such as SQL queries. Verifications enhance your test results by raising errors when anticipated test results are not returned during test runs. By selecting output data and applying simple commands, all required verification functions can be generated and automatically inserted into your BDL scripts.

TrueLog Explorer offers two database operation verification options:
  • Verification of element values
  • Verification of result-set row counts
  • Verifying a Database Operation Element Value
    Verify element values in result-set data to enhance your test results by raising errors when anticipated test results are not returned during test runs.
  • Verifying a Database Result Set Row Count
    Result set row-count verifications confirm that returned database result sets include the specified number of rows.
Parent topic: Working With Database Applications


Verifying a Database Operation Element Value

  1. Choose File > Add TrueLogs . The Open dialog box opens.
  2. Select a replay database TrueLog and click OK. The replay TrueLog opens in TrueLog Explorer.
  3. Choose Edit > Step through TrueLog . Alternative: Click Step through TrueLog on the toolbar. The Step through TrueLog dialog box opens.
  4. Click the Result sets option button.
  5. Click Find Next to advance to the first database command that returns a result set. For example, you might want fetch commands, such as Ora8StmtFetch. The first data element in the set is selected.
  6. Perform one of the following steps:
    • Right-click a data element to verify and choose Verify Element Value.
    • Click Add Verifications on the workflow bar and click Verify the element value.
    The identified data element and its row or column specifications display in the value text box, and the value option button is selected.
  7. Optional: To verify against an existing parameter or a new parameter, click parameter value.
    1. Click [...] to browse to and select a parameter. If no parameters exists, the Parameter Wizard opens, enabling you to create a new parameter.
    2. Click OK.
  8. In the Severity group box, specify the severity that is raised if the verification returns a negative result.
  9. Check the appropriate check boxes to make the verification case-sensitive or apply it as a script-wide rule. A result variable name is displayed in the Result variable name text box.
  10. Click OK. The function is added to the test script.

Initiate a Try Script run to confirm that the script runs without error.

Parent topic: Verifications for Result-Set Data


Verifying a Database Result Set Row Count

Result set row-count verifications confirm that returned database result-sets include the specified number of rows. Errors are raised if returned result sets have less or more than the specified number of rows.

  1. Choose File > Add TrueLogs . The Open dialog box opens.
  2. Select a replay database TrueLog and click OK. The replay TrueLog opens in TrueLog Explorer.
  3. Choose Edit > Step through TrueLog . Alternative: Click Step through TrueLog on the toolbar. The Step through TrueLog dialog box opens.
  4. Click the Result sets option button.
  5. Click Find Next to advance to the first database command that returns a result set. For example, you might want fetch commands, such as Ora8StmtFetch. The first data element in the set is selected.
  6. Perform one of the following steps:
    • Right-click a data element to verify and choose Verify Result Set Row Count.
    • Click Add Verifications on the workflow bar and click Verify the row count.
    The row count of the current database result is displayed in the value text box, and the value option button is selected.
  7. Optional: To verify against an existing parameter or a new parameter, click parameter value.
    1. Click [...] to browse to and select a parameter. If no parameters exists, the Parameter Wizard opens, enabling you to create a new parameter.
    2. Click OK.
  8. Specify whether or not the row count must match exactly, at least, or at most the current row count.
  9. In the Severity group box, specify the severity that is raised if the verification returns a negative result.
  10. Click OK. The function is added to the test script.

Initiate a Try Script run to confirm that the script runs without error.

Parent topic: Verifications for Result-Set Data


Working With XML Applications

This section describes the script-customization and TrueLog-analysis features that are provided for the testing of XML-based applications.

  • Working With XML Applications - Overview
    Describes the script-customization and TrueLog-analysis features that are provided for the testing of XML-based applications.
  • XML TrueLog Structure
    XML TrueLogs support the visualization of XML elements, attributes, and values via a readable XML menu tree presentation.
  • XML Parsing Functions
    Explains how XML parsing functions can parse out the values of specific elements and attributes within XML documents.
  • Customizing Session Handling for XML Applications
    Describes the process of manipulating server responses to preserve state information during the load testing of XML-based applications.
  • User-Input Data Customization
    Describes the process of using parameterization to replace hard-coded element and attribute values with custom values.
  • Verification Functions for XML Applications
    Verification functions verify the values of specified XML elements and attributes during test runs.
Parent topic: TrueLog Explorer 21.0


Working With XML Applications - Overview

TrueLog Explorer offers the same support for XML-based applications that it does for HTML-based applications, including:

  • Session handling
  • Input-data customization
  • Verification functions
  • TrueLog On Error analysis

The TrueLog Explorer Web-service support features an intuitive XML data interface that facilitates interaction and analysis of XML TrueLogs.

The TrueLog Explorer XML API works comparably to its Web API. XML data access functions for querying and verifying hold an advantage over Web functions because they allow you to specify the exact locations of values, even when values are specified multiple times. The Web API only allows for the specification of left/right boundaries using WebParseDataBound functions that are not flexible enough to adapt to server data changes.

Before proceeding with this chapter, it is essential that you familiarize yourself with TrueLog Explorer basic functionality.

Sample Web Service

The sample scripts included in this chapter are based on SOAP/XML messages taken from the sample Web service. The scripts were generated using .NET Explorer and exported for use with Silk Performer.

To view the sample Web service using .NET Explorer, navigate to: http://demo.borland.com/BorlandSampleService/BorlandSampleService.asmx?WSDL

Parent topic: Working With XML Applications


XML TrueLog Structure

XML TrueLogs support the visualization of XML elements, attributes, and values via a readable XML menu tree presentation.

  • UI Overview of XML TrueLogs
    Explains how XML TrueLogs are visualized in TrueLog Explorer.
  • Menu Tree
    Organizes the TrueLog data that is downloaded during load tests into expandable/collapsible API nodes.
  • Content Pane
    Offers viewing options for received data.
  • Information Pane
    Offers data regarding testing scripts and test runs, including BDL scripting, HTTP headers, and timing statistics.
Parent topic: Working With XML Applications


UI Overview of XML TrueLogs

XML TrueLogs support the visualization of XML elements, attributes, and values via a readable XML menu tree presentation. This XML control displays the response data of selected API calls in an intuitive XML interface on the Rendered page. The In Body page presents the raw data that is returned by the server. Out Body presents the raw data that is sent to the server.

See the following topics for details on the three main elements of an XML TrueLog.

Parent topic: XML TrueLog Structure


Menu Tree

The menu tree, located on the left side of the interface, allows you to expand and collapse each TrueLog API node. Click a node to display its contents on the Content pane and its history details on the Information pane.

Parent topic: XML TrueLog Structure


Content Pane

TrueLog Explorer provides multiple views of all received data. Depending on the type of application under test (Web, XML, database, TCP/IP, or UDP), the Content pane offers different viewing options:

Item | Description
Response (HTML & XML) | The Response page displays the visually rendered response from the server for the selected API node in the menu tree. HTML responses are rendered by an Internet Explorer control running behind the Response page. XML responses are displayed by an XML control that displays XML data in a menu tree format. Responses that are neither HTML or XML are not rendered and must be viewed using the In Body page. You can right-click elements and attributes in the XML control to expand the menu tree by one or more levels.
SQL Command | Suppressed for XML
Differences (HTTP based applications) | The Differences page lists the In Body differences between selected nodes. This page is helpful in finding dynamic information in server responses. It is the first place to look for session information. Only applicable in difference mode.
Request (HTML & XML) | Displays the request data returned by the server. It displays posted XML data in a menu-tree formatted XML control. Elements are displayed in magenta. Attributes are displayed in cyan.
Parent topic: XML TrueLog Structure


Information Pane

The Information pane offers data regarding testing scripts and test runs, including BDL scripting, HTTP headers, and timing statistics. Depending on the type of application under test (Web, XML, database, Oracle Forms, SAPGUI, Citrix, TCP/IP, UDP, or other), the Information pane offers different views.

Item | Description
Info

The Info page displays general information about the open TrueLog file and the selected API node.

BDL

The BDL page displays the BDL script that corresponds to the open TrueLog. The BDL script is automatically positioned to the line of the selected API node.

References | Suppressed for XML
Out Header (HTTP)

The Out Header page contains the exact HTTP header that the application (Silk Performer in the case of replay TrueLogs, the browser in the case of record TrueLogs) sends to the server.

In Header (HTTP)

The In Header page contains the exact HTTP header that the server sends to the application.

Out Body (HTTP, TCP/IP, UDP) | Contains data sent with HTTP-POST commands from the application to the server.
In Body (HTTP, TCP/IP, UDP)

The In Body page contains data received by the application from the server. The data is presented in raw format as it is received from the server (no rendering for HTML, no menu tree representation for XML).

Statistics (HTTP)
For Web browser-driven - AJAX applications, the Statistics page shows timing statistics for Web pages. It includes timing information for each Web page component and communication element. It shows exact response times, including the composition for each individual component, in graphical view. This assists you in pinpointing the root causes of errors and slow page downloads. The Statistics page includes the following data for each page component:
  • DNS lookup time: The time taken to resolve an IP address from the domain / host name supplied
  • Connect time: The time taken for the simulated user to connect to the server
  • Net round trip: The time from the first byte of the client request until the last byte of the server response, including all documents but not embedded objects.
  • Cache statistics
Parent topic: XML TrueLog Structure


XML Parsing Functions

XML parsing functions can be applied in a structured manner to XML content returned by servers. XML parsing functions parse out the values of specific elements and attributes within XML documents.
Note: XML parsing is recommended only for enhanced verifications and customizations, not session-handling customization.

Elements and attributes are accessed via XML Path Language (XPath), a standardized language for addressing elements within XML documents. XML parsing functions are applied on the Rendered page. Web API style parsing can be executed against XML via the Source page.

XML parsing functions include:

  • WebXmlParseNodeValue
  • WebXmlParseNodeAttribute
Note: Hierarchical structured values can not be parsed out using the XML control.
Parent topic: Working With XML Applications


Customizing Session Handling for XML Applications

Normally session information is not included in XML code, so XML session-handling customization is rarely required.

In those rare instances where session information is included in XML code, proceed with the session-handling customization process outlined for Web-based applications.

Parent topic: Working With XML Applications


User-Input Data Customization

The goal of user-input data customization is to customize the values of submitted XML data elements and attributes. Data that may, for example, come from recorded SOAP traffic.

With HTML, hard-coded form-field values, as declared in the DCLFORM sections of test scripts, are replaced with random variables. In such instances, parameterization takes place in form declarations.

With XML, hard-coded element and attribute values, as declared by the post data parameters of corresponding functions, are replaced with random variables. Parameterization takes place in the post data parameters of WebUrlPostBin, WebCustomRequestBin, and WebPagePost calls (WebPagePost is generated by .NET Explorer. It is the page-level API call used for HTTP-POST commands).

User-input data customization can be used for the following:

  • Perform functional tests by challenging servers with different values each time certain transactions are executed.
  • Simulate real-world user behavior by selecting submitted values based on given probability distributions.
Note: To set up parameterization for the values of submitted XML data elements and attributes, proceed with the user-input data process outlined for Web-based applications.
Parent topic: Working With XML Applications


Verification Functions for XML Applications

XML verification functions verify the values of specified XML elements and attributes (which are identified by XPath queries) during test runs.

  • Verification Functions for XML Applications
    Verification functions verify the values of specified XML elements and attributes during test runs.
  • Inserting an XML Verification Function
    All parsing and verification functions must be specified before the Web API calls that initiate the parsing/verification of response data.
Parent topic: Working With XML Applications


Verification Functions for XML Applications

XML verification functions verify the values of specified XML elements and attributes (which are identified by XPath queries) during test runs. XML verification functions are inserted by right-clicking within the Rendered page.

TrueLog Explorer offers the following XML verification functions:
  • WebXmlVerifyNodeValue - Checks a selected element’s value. This function is generated when Verify Element Value is selected from the XML tree-control context menu.
  • WebXmlVerifyNodeAttribute - Checks a selected attribute’s value. This function is generated when Verify Attribute Value is selected from the XML tree-control context menu.

Verification Checks During Replay

Verification functions can be enabled/disabled via Silk Performer profile settings. From within Silk Performer, choose Settings > Active Profile , then choose Replay > Web > Verification > HTML > XML .

The XML Verification check box enables/disables the functions WebXmlVerifyNodeValue and WebXmlVerifyNodeAttribute.

Profile settings in scripts can be overridden using the WebSetOption BDL function.

Parent topic: Verification Functions for XML Applications
Related tasks
Adding Verification Statements Using Rendered XML View
Adding Verification Statements Using Plain-Text View


Inserting an XML Verification Function

All parsing and verification functions must be specified before the Web API calls that initiate the parsing/verification of response data. Multiple parse/verification functions can be specified before each Web API call.
Note: The order in which parsing/verification functions are inserted into a test script is not relevant.
  1. Select and right-click an XML element or attribute on the Rendered page and choose Verify Element Value. Alternative: When verifying an attribute, the context menu instead offers the Verify Attribute Value command. The Insert XML Verification Function dialog box opens. The selected element value is pre-loaded into the value edit box and the value option button is selected.
  2. To verify against a parameter, click the parameter option button. In addition to being able to verify against a constant value, you can also verify against either an existing parameter or a new parameter.
    1. Click [...].
    • If a parameter already exists, you can browse to and select the parameter.
    • If no parameters exist, click [...]. The Parameter Wizard opens enabling you to create a new parameter.
  3. Specify the frequency by which the selected element is to appear:
    • Select exactly, at least, or at most from the occurs list box.
    • Enter a number in the time(s) field.
    Note: The settings on this dialog are automatically set to values that guarantee a successful verification for the current page. Only in cases in which you want to make the verification more tolerant should these settings be changed (for example, by changing exactly 2 times to at least 1 time, or by making a verification case-insensitive).
  4. Check the exact XPath query check box if the element is to be verified only in the specified XPath.
  5. Specify whether or not the verification is to be applied as a script-wide rule and/or case sensitive by checking the appropriate check boxes. A pre-loaded result variable name appears in the Result variable name text box; edit this name as required.
  6. In the Severity portion of the dialog, specify the severity that is to be raised if the verification returns a negative result (Error, Warning, Informational, or Custom).
  7. Click OK to add the function to your test script. XML attribute verification is identical to XML element verification, except that an attribute name must also be specified.
  8. Initiate a Try Script run to confirm that your script customization runs accurately.
Parent topic: Verification Functions for XML Applications


Working With SAPGUI Applications

For SAPGUI-based applications, TrueLog Explorer offers TrueLog recording, TrueLog replay, basic TrueLog analysis, data parsing, content verification, and user-input data customization.

Before proceeding with this chapter, it is essential that you familiarize yourself with TrueLog Explorer basic functionality.

  • SAPGUI TrueLog Structure
    Describes the elements of a SAPGUI TrueLog.
  • SAPGUI TrueLog Functions
    Describes the SapGuiActiveSetWindow and SapGuiRoundTrip functions.
  • Stepping Through SAPGUI TrueLogs
    Following a test run, you have options for navigating through the resulting TrueLog.
  • Analyzing SAPGUI Test Scripts
    Following the generation of a test script, you can determine if the script runs without error by performing a Try Script run.
  • Replay and Record TrueLogs
    Explains how to analyze differences between SAP record and replay TrueLogs.
  • SAPGUI Test-Script Customization
    Describes the available options for customizing test scripts with verification functions, parsing functions, and parameterized input data.
  • Verification and Parsing Functions
    Explains how verification functions verify whether the content that is to be sent by servers is in fact received by clients and the usefulness of adding a SAPGUI parsing function.
Parent topic: TrueLog Explorer 21.0


SAPGUI TrueLog Functions

TrueLog Explorer offers two high-level SAPGUI functions:
  • SapGuiActiveSetWindow – These are top-level API nodes that indicate the generation of a new GUI window. All actions taken on windows are grouped below a SapGuiActiveSetWindow function.
  • SapGuiRoundTrip – These are virtual nodes; there are in fact no API calls called SapGuiRoundTrip that are sent to the server. These nodes are used to group all client-side actions that occur in the course of a server round-trip. Both the before and after states of round-trips can be viewed. Multiple round-trip nodes may be included under each SapGuiSetActiveWindow node.

Graphic that displays the SapGuiActiveSetWindow function
Parent topic: Working With SAPGUI Applications


Stepping Through SAPGUI TrueLogs

Following tests, it is typical to have multiple TrueLog On Error files open in TrueLog Explorer (one TrueLog for each virtual user who returns an error). You can jump from one error to the next sequentially as they occurred in time. This feature simplifies the process of analyzing errors because there is no need for you to manually review all open TrueLogs to find the next error in a sequence.

  1. After the completion of a load test, click Silk Performer Explore Results.
    Note: TrueLog On Error files are generated only when the Silk Performer Generate TrueLog On Error option is enabled.
    The Explore Results dialog box displays.
  2. Click TrueLog Explorer.
    Note: The TrueLog Explorer button is disabled when either no errors are detected during a test or when Truelog On Error is not enabled. In such instances, proceed directly to analyzing results with Performance Explorer.
    TrueLog Explorer launches with the TrueLog On Error files that were generated for the current test, and the Step through TrueLog dialog box displays.
  3. In the Step through TrueLog dialog box, select the appropriate option button. You can advance through:
    • All API calls (each API node)
    • All Roundtrips (SapGuiRoundtrip calls)
    • All Windows (SapGuiSetActiveWindow nodes)
    • All Customizable calls (the next node in which field value changes can be customized)
    • All errors
    TrueLog On Error files are searched sequentially, as they are recorded in time.
  4. Click Find Next to advance to the first API call, roundtrip, window, customizable call, or error.
Error messages are displayed in the Info pane. Each API node that contains a replay error is tagged with a red “X” in the TrueLog menu tree.
Parent topic: Working With SAPGUI Applications


Analyzing SAPGUI Test Scripts

Following the generation of a test script, you can determine if the script runs without error by running a Try Script run. A Try Script run determines if a script accurately recreates the intended transactions.

The default option settings for Try Script runs include live display of data downloaded during testing and the writing of log and report files.

With Try Script runs, only a single virtual user is run and the stress test option is enabled so that there is no think-time delay between transactions.

  1. Click Try Script on the Silk Performer workflow bar. The Try Script dialog box displays.
  2. To view rendered page transitions during a Try Script run, check the Animated Run with TrueLog Explorer check box.
  3. Click Run.
    Note: You are not running an actual load test here, only a test run to see if your script requires debugging.
    The Try Script run begins. The Silk Performer Monitor pane opens, giving you detailed information about the run’s progress.

    TrueLog Explorer opens, showing you the data that is downloaded during the Try Script run. Each main SAPGUI window accessed during recording is listed as a high-level SapGuiSetActiveWindow API node in the TrueLog menu tree. All recorded server round-trips and user actions are listed as subnodes of corresponding SapGuiSetActiveWindow nodes.

Parent topic: Working With SAPGUI Applications


Replay and Record TrueLogs

This section explains how to analyze differences between SAP record and replay TrueLogs.

  • Comparing Replay and Record TrueLogs
    Compare the values and states of controls and screenshots captured during recording and replay to see if there are any differences.
  • Synchronizing Replay and Record TrueLogs
    Synchronize corresponding API nodes between replay and record TrueLogs to look for differences between the TrueLogs.
Parent topic: Working With SAPGUI Applications


Comparing Replay and Record TrueLogs

When testing SAPGUI applications, differences can occur in corresponding control values between replay and record TrueLogs. Some differences may result in replay errors.

  1. Open a replay Truelog and click Analyze Test. The Analyze Test dialog box displays.
  2. Click Compare your test. The associated record TrueLog opens in compare view. The Step through TrueLog dialog box displays.
  3. In the Step through TrueLog dialog box, select the appropriate option button. You can advance through:
    • All API calls (each API node)
    • All Roundtrips (SapGuiRoundtrip calls)
    • All Windows (SapGuiSetActiveWindow nodes)
    • All Customizable calls (the next node in which field value changes can be customized)
    • All errors
    TrueLog On Error files are searched sequentially, as they are recorded in time.
  4. Click Find Next to advance to the first API call, roundtrip, window, customizable call, or error.
  5. Visually compare the values and states of the controls and screenshots to see if there are any differences. Based on any differences you discover, complete any required customizations.
  6. Click Try Script Run to confirm that your customizations run without error.
  7. Repeat this procedure as many times as is required until your script is fully customized and all necessary customizations have been added.
  8. Turn off compare mode by performing one of the following steps:
    • Choose View > Compare Mode .
    • Click the Compare Mode icon.
Parent topic: Replay and Record TrueLogs


SAPGUI Test-Script Customization

After you generate a test script with Silk Performer and execute a Try Script run, TrueLog Explorer can help you customize the script with the following:
  • Content-verification functions – Using the Add Verifications tool, you can gain insight into data that is downloaded during tests, enabling you to verify that the content that is to be sent by the server is in fact received. Verifications remain useful after system deployment for ongoing performance management.
  • Parsing functions – TrueLog Explorer allows you to insert SAPGUI parsing functions visually in Source view and on the Controls page. Manual code writing is not required; TrueLog Explorer automatically generates parsing functions in scripts.
  • Parameterized input data – With user data customization, you can make your test script more realistic by replacing static user-input data with dynamic, parameterized data that changes with each transaction. Manual scripting is not required to create these data-driven tests.

For each SAPGUI function call that changes input data, you can verify return values, parse values, and customize input data. These operations can be executed from both Source view (by right-clicking within a control) and the Controls menu tree.

  • Customizing User-Input Data for a Form Field
    Make your test script more realistic by replacing static user-input data with dynamic, parameterized data that changes with each transaction.
  • Multi-Column Data Files
    Explains the advantages of using multi-column data files.
  • SAPGUI Controls Menu Tree
    Explains that the Controls menu tree offers a convenient means of viewing and customizing form fields.
  • Copy Control ID Function
    Explains how the Copy Control ID function copies the control ID of a selected SAPGUI control to the clipboard. This eases non-visual scripting of special calls.
Parent topic: Working With SAPGUI Applications


Customizing User-Input Data for a Form Field

Under real world conditions, SAPGUI-application users submit unpredictable combinations of data into forms. One goal of effective SAPGUI application testing is to emulate such irregular and diverse user behavior in test scripts.

You can customize the user-input data that is entered into forms during testing with the Parameter Wizard. The Parameter Wizard lets you specify values to be entered into form fields, enabling your test scripts to be more realistic by replacing recorded user input data with randomized, parameterized data.

  1. Select a TrueLog in the TrueLog menu tree. TrueLog content appears on the Response and Information pages.
  2. Choose Edit > Step through TrueLog . Alternative: Click Step through TrueLog on the toolbar. The Step through TrueLog dialog box opens.
  3. Click the Customizable calls option button and click Find Next to step through all form fields in the TrueLog that offer input customization.
    Note: Controls that can be customized are outlined in orange. Controls that have already been customized are outlined in green. Controls that are outlined in blue can have their values parsed or verified, but they cannot be customized.
  4. On the Request page, right-click the form control that you want to customize and choose Customize Value. You can replace the recorded values with various types of input data (including predefined values from files and generic random values) and generate code into your test script that substitutes recorded input data with your customizations. The Parameter Wizard opens.
    With the Parameter Wizard you can modify script values in two ways:
    • Use an existing parameter that is defined in the dclparam or dclrand sections of your script.
    • Create a new parameter based on a new constant value, random variable, or values in a multi-column data file.

    After you create a new parameter, that parameter is added to the existing parameters and is available for further customizations.

  5. Click the Create new parameter option button and then click Next to create a new parameter. The Create New Parameter page opens.
  6. Click the Parameter from Random Variable option button and then click Next. The Random Variable page opens.
  7. From the list box, select the type of random variable that you want to insert into your test script and then click Next. A brief description of the selected variable type appears in the lower window. The Name the variable and specify its attributes page opens.
  8. Enter a name for the variable in the Name text box.
  9. Click Finish. Your test script now uses the random variable for the given form field in place of the recorded value. The new random variable function appears on the BDL page.

Initiate a Try Script run with the random variable function in your test script to confirm that the script runs without error.

Parent topic: SAPGUI Test-Script Customization


SAPGUI Controls Menu Tree

For each SAPGUI function call that changes input data, you can verify return values, parse values, and customize input data from both Source view and the Controls menu tree in the information pane. The Controls menu tree offers a convenient means of viewing and customizing form fields. The Controls menu tree is a visual representation of the form section of the BDL script, with all included name/value pairs.

Controls that can be customized are outlined in orange or blue. Controls that are outlined in orange generally offer value parsing, value verification, and user-input data customization. Controls that are outlined in blue offer value parsing and value verification, but not user-input data customization. Right-click a control and choose the script customization type that you want to execute.

Controls for which user data has already been customized appear with a green outline.

Parent topic: SAPGUI Test-Script Customization


Copy Control ID Function

The Copy Control ID function copies the control ID of a selected SAPGUI control to the clipboard. This eases non-visual scripting of special calls within Silk Performer. To copy a control ID, right-click a GUI control and choose Copy Control ID. The control ID is then copied to the clipboard.

Note: Controls can be selected either in Source view or in the Controls menu tree.
Parent topic: SAPGUI Test-Script Customization


Adding a Value Verification

By right-clicking a SAPGUI control that you want to have verified, the required verification function can be generated and inserted into your BDL script. TrueLog Explorer offers one pre-enabled value verification function for SAPGUI applications.

  1. In either Source view or the Controls menu tree, select a control field for which you want to verify the return value. Controls that can be verified have blue outlines around them. Most controls that are outlined in orange can also be verified.
  2. Right-click within the control field and choose Verify Value. The Insert Value Verification Function dialog box displays. Use this dialog to specify the type of verification function that should be inserted into the BDL script.
  3. From the Verify that the value of the selected control list box, select is equal to or is not equal to (based on your requirements).
  4. Specify whether the verification should use a constant value or a parameter value.
  5. Specify whether the verification is to be Case sensitive and if white spaces should be ignored.
  6. In the Severity group box, specify the severity that should be raised if the verification returns a negative result.
  7. Click OK. The function is then added to your test script.

Once the BDL script has been successfully modified, repeat this process for each verification that you want to add to your BDL script.

Parent topic: Verification and Parsing Functions


Adding a SAPGUI Parsing Function

For any SAPGUI function call in which input data is inserted, you can insert a parse-value function. Value parsing can be useful for enabling replay when session-specific strings must be parameterized to enable accurate replay. For instance, you might parse customer IDs into a parameter that is inserted into a customer ID field.

Though toolbars and title bars cannot be parsed, most common controls can be parsed, including text fields, field labels, combo boxes, buttons, and more.

  1. In Source view or the Controls menu tree, select a control field for which you want to parse a value. Controls that can be verified have blue outlines around them. Most controls that are outlined in orange can also have their values parsed.
  2. Right-click within the control field and choose Parse Value. The Insert Value Parsing Function dialog box opens and offers settings by which the parsing function can be adjusted.
  3. Optional: In the Parameter name text box, enter a name for the parameter that is to receive the result of the parsing function.
  4. Optional: In the Informational statement insertion area, click Print statement to insert an informational print statement into the script.
    The result of the parsing function will be written to the Silk Performer Virtual User Output window.
  5. Optional: In the Informational statement insertion area, click Writeln statement (write line statement) to write the parsed value to an output file to facilitate debugging (in addition to writing the value to the Virtual User Output window as a Print statement does).
    Because generating output files alters the time measurements of load tests, these files should only be used for debugging purposes and should not be generated for full load tests.
  6. Click OK. The parsing statement is inserted into your test script.
Once you have customized how your script handles session information and user-input data, you have added all necessary verification functions, and have completed any required manual BDL script editing via Silk Performer, your testing script should run without error.
Parent topic: Verification and Parsing Functions


Working With Oracle Forms Applications

This section explains how to customize an Oracle Forms test script based on the results of a Try Script run.

  • Working With Oracle Forms Applications - Overview
    Explains how to customize an Oracle Forms test script based on the results of a Try Script run.
  • Customizing Oracle Applications 12i Session Information
    TrueLog Explorer can assist you in customizing hard-coded session information in your recorded test scripts so that they can be replayed.
  • Oracle Forms TrueLog Structure
    Explains the Oracle Forms TrueLog structure and the Form Controls window.
  • Oracle Forms User-Input Data Customization
    Explains how user-input data customization can make your test script more realistic by replacing static recorded user input data with dynamic, parameterized user data that changes with each transaction.
  • Content Verification Functions for Oracle Forms
    Explains how adding content verifications to your test scripts can verify whether the content that is to be sent by servers is in fact received by clients under real-world conditions.
  • Completing Your Oracle Forms Script Customizations
    Summarizes the steps that must be completed to successfully customize an Oracle Forms test script.
Parent topic: TrueLog Explorer 21.0


Oracle Forms TrueLog Structure - Overview

Oracle Forms applets are commonly incorporated into applications that are built on both the Oracle Forms protocol and the HTTP protocol. When such applications are recorded, the resulting BDL scripts include both Oracle Forms and Web function calls. Oracle Forms TrueLogs support such mixed protocols. The TrueLog menu tree lists both the Oracle Forms and HTTP function calls that are included in the active BDL script. Each API node in the menu tree signifies a unique function call.

Oracle Forms TrueLogs feature a Form Controls window that displays the elements of the selected Oracle Forms applet window in tabular-data representation (otherwise this binary protocol would be unreadable). For the HTTP calls that call the HTML pages in which Oracle Forms applets are embedded, the Form Controls window displays fully rendered HTML.

Oracle Forms TrueLogs have a unique structure. Each OraFormsSetWindow call results in a new top-level node. An OraFormsSetWindow call is scripted for each window that is activated during a recording session. All actions that are performed on a window (for example, editing of a text control, selecting a list entry, etc.) are shown as sub-nodes of each OraFormsSetWindow.

OraFormsInit is included in the Init transaction. OraFormsDestroy is included in the End transaction. The first Oracle API call in the main transaction is OraFormsConnect.

Parent topic: Oracle Forms TrueLog Structure


Terminal Messages

Terminal messages are used to end communication round-trips between client and server. There are three terminal-message types:

Terminal 1 messages:
This is the most straightforward message-termination method. Terminal 1 messages are always initiated by the client. An example is the client asking the server, “The user just pressed this button, what should I show in the UI?” The server then responds with the requested answer and terminates the exchange with a Terminal 1 message.
Terminal 2 messages:
Sometimes, communication between client and server is more complicated. For example, if the client says, “The user just pressed this button, what should I show in the UI?” but the server needs more information from the client before it can provide an answer. The server responds with a Terminal 2 message, asking something like, “What is the state of option button XYZ?” If the client has a prepared, scripted response for this request, it will provide the answer to the server’s question and end communication with a Terminal 2 message. The server will then provide a scripted response to the client’s original question and end the communication with a Terminal 1 message.
This type of exchange can be illustrated as follows:
  1. Request from client (Terminal 1, Out Body tab)
  2. Request from server (Terminal 2, In Body tab)
  3. Response from client (Terminal 2, Out Body tab)
  4. Response from server (Terminal 1, In Body tab)
Terminal 3 messages:
Indicates that the server has spontaneously initiated a Get call requesting a value from the client. These are requests that are not initiated by the client. Example: The server says, “I have emptied my cache, please tell me the value of option button XYZ again.” The client then needs to respond with the appropriate answer and terminate communication with a Terminal 3 message.
Terminal 3 messages sometimes result in replay-script breakage. Because these server requests are unanticipated, the client can only provide a default answer, such as null. If the server accepts the default answer provided by the client, for example if the server does not really need a specific answer to its Get call, then replay will continue (this is often the case). If however the server finds the default response to be unacceptable, you must manually script an OraFormsSet and an OraFormsOnMessageGet function to prepare the correct response for the server’s Get call.
Example:
OraFormsSetRectangle("VISIBLERECT", 0, 0, 119, 24, ORA_SET_TYPE_MESSAGEGET);
OraFormsOnMessageGet("LINE_CUSTOMER_ITEM_DSP_0"); // Requested Item
OraFormsMouseClick("LINE_CUSTOMER_ITEM_DSP_0", 70, 18, 0); // Requested Item
Terminal -1 messages:
Indicates an error in communication between client and server. Replay has failed because the server has received an unacceptable answer to its request.
Parent topic: Oracle Forms TrueLog Structure


Analyzing Errors in Oracle Forms Tests

Complete an Oracle Forms load test.

After tests, it is typical to have multiple TrueLog On Error files open in TrueLog Explorer (one TrueLog for each virtual user who returns an error). With the TrueLog Explorer Find Errors feature, you can jump from one error to the next chronologically, regardless of which TrueLogs the errors were recorded in. This simplifies the process of analyzing errors because there is no need for you to manually review all open TrueLogs to find the next error in a sequence.

  1. Click the Silk Performer Results button.
    Note: TrueLog On Error files are generated only when the Silk Performer Generate TrueLog On Error option is enabled.
    The Explore Results dialog box opens.
  2. Click TrueLog Explorer.
    Note: The TrueLog Explorer button is disabled in the following situations:
    • No errors are detected during a test
    • Truelog On Error is not enabled
    In such instances, proceed directly to analyzing results with TrueLog Explorer.
    TrueLog Explorer launches, with the TrueLog On Error files that were generated for the current test and the Step through TrueLog dialog box open.
  3. Advance through all Forms windows (OraFormsSetWindow calls), all API calls (each API node), or all errors.
    1. Select the appropriate radio button on the dialog box.
    TrueLog On Error files are searched chronologically.
  4. Click Find Next to advance through the TrueLog. Error messages are displayed on the Info page. API nodes that contain replay errors are tagged with red “X” marks in the TrueLog menu tree.
Parent topic: Oracle Forms TrueLog Structure


Analyzing Oracle Forms Test Scripts

Once you have generated a test script you can determine if the script runs without error by performing a Try Script run. A Try Script run determines if a script accurately recreates the recorded interactions.

Default option settings for Try Script runs include live display of data downloaded during testing and the writing of log and report files.

With Try Script runs, only a single virtual user is run and the stress test option is enabled so that there is no think-time delay between transactions.

  1. In Silk Performer, click Try Script on the workflow bar. The Try Script dialog box opens.
  2. Check the Animated Run with TrueLog Explorer check box to view page transitions during the Try Script run.
  3. Click Run.
    Note: You are not running an actual load test here, only a test run to see if your script requires debugging.
    The Try Script run begins. The Monitor pane opens, giving you detailed information about the progress of the run.
  4. Silk Performer opens, showing you the data that is downloaded during the Try Script run.

    Each main Oracle Forms window accessed during recording is listed as a high-level API node in the TrueLog Explorer menu tree. All recorded actions are listed as subnodes.

  5. If any errors occur during the Try Script run, TrueLog Explorer will assist you in locating them and customizing your script.
Parent topic: Oracle Forms TrueLog Structure


Comparing Oracle Forms Replay and Record TrueLogs

Open a TrueLog with TrueLog Explorer.

When testing Oracle Forms applications, differences can occur in corresponding control values between replay and record TrueLogs. More severe errors can also result in differences between record and replay TrueLogs (for example, a message box might indicate that a duplicate record has been entered (likely because a required input-data customization has not been performed on the test script).

  1. Click Analyze Test. The Workflow - Analyze Test dialog box opens.
  2. Click Compare your test. The associated record and replay TrueLogs open in compare view. The Step through TrueLog dialog box also opens.
  3. Select a criteria by which to search:
    • Forms windows
    • API calls
    • Errors
  4. Click Find Next. The first set of corresponding Forms windows, API calls, or errors in the record and replay TrueLogs are displayed.
  5. Compare the states of the controls to see if there are differences. TrueLog Explorer highlights any name or control value that changes between record and replay. This helps you identify where customizations may be necessary and where verifications may be beneficial.
  6. Complete any required customizations (based on differences you have discovered).
    1. Click Try Script Run.
    Tests to see if the customizations run without error.
  7. Repeat this procedure as many times as is required until all necessary customizations have been added.
  8. Click Compare Mode to disable compare mode.
Parent topic: Oracle Forms TrueLog Structure


Unanticipated Get Calls

The vast majority of server requests are anticipated and accurately handled by recorded scripts. Occasionally during script replay a server spontaneously sends out additional Get calls that it did not send out during script recording. In such instances the client can only respond with default answers to the server. If the server accepts a default answer, replay continues without error. If the server finds the default answer to be unacceptable though, you must manually script an OraFormsSet and an OraFormsOnMessageGet function to prepare the correct response for the server’s Get call.

For example, the server spontaneously sends a Get request asking for the VALUE property of a certain UI control. Because there is no scripted function in the script to handle this Get request, the client responds with the default value of null for strings. The server does not accept this answer. Connection to the client is aborted and the replay script runs into errors.

To prepare for manual scripting of an additional Get function to manage this situation, it is necessary that you analyze the in-data and out-data that is exchanged between the client and server. This analysis can only be conducted if you have set the Silk Performer logging level to debug.

Note: If logging level was not set to debug before your test was run, after you change the setting you will need to rerun your test to generate the required debug data.
Note: Also, the record=names parameter on the Oracle Forms server must be enabled to allow accurate recording of scripts.

The OraFormsOnMessageGet function that you script must provide an answer that is different than the default answer for the subsequent Get call on the relevant UI element.

Note: It is actually an OraFormsSet function that provides the answer in the script (in the line preceding the OraFormsOnMessageGet function call).

As the following BDL script example illustrates, when a Get call is handled, you have to read the script from bottom to top:

Example

OraFormsSetRectangle("VISIBLERECT", 0, 0, 119, 24, ORA_SET_TYPE_MESSAGEGET);
OraFormsOnMessageGet("LINE_CUSTOMER_ITEM_DSP_0"); // Requested Item
OraFormsMouseClick("LINE_CUSTOMER_ITEM_DSP_0", 70, 18, 0); //
Requested Item

This code sample can be read as: The client will perform a mouse click on the UI element LINE_CUSTOMER_ITEM_DSP_0. This is represented by the OraFormsMouseClick function. Upon the mouse click, you expect to receive a Get call from the server. To prepare for the Get call in advance of the mouse click, you insert the OraFormsOnMessageGet function. You then expect the server to ask for the property VISIBLERECT so you place the property value of type rectangle on the stack before the OraFormsOnMessageGet function using the OraFormsSetRectangle function.

Parent topic: Oracle Forms TrueLog Structure


Setting Silk Performer Log Level to Debug

To prepare for manual scripting when an unanticipated get call is received, it is necessary that you analyze the in-data and out-data that is exchanged between the client and server. This analysis can only be conducted if you have set the Silk Performer log level to debug.

  1. In Silk Performer, choose Settings > System .
  2. Click the Oracle Forms group button.
  3. Select debug from the Log level list box.
Parent topic: Oracle Forms TrueLog Structure


Oracle Forms User-Input Data Customization

Once you have generated a test script with Silk Performer and executed a Try Script run, TrueLog Explorer can help you customize the script with parameterized input data.

With user data customization you can make your test scripts more realistic by replacing static recorded user input data with dynamic, parameterized user data that changes with each transaction. Manual scripting is not required to create such data-driven tests.

  • Multi-Column Data Files
    Explains the advantages of using multi-column data files.
  • Customizing Oracle Forms User-Input Data
    Under real world conditions, Web application users submit unpredictable combinations of data into forms. One goal of effective Web application testing is to emulate such irregular and diverse user behavior by customizing user input data for test scripts.
  • Input Data Customizable Functions
    Lists the input data functions that can be customized.
Parent topic: Working With Oracle Forms Applications


Customizing Oracle Forms User-Input Data

Under real world conditions, Web application users submit unpredictable combinations of data into forms. One goal of effective Web application testing is to emulate such irregular and diverse user behavior using test scripts.

You can customize the user-input data that is entered into forms during testing with the TrueLog Explorer Parameter Wizard. The Parameter Wizard lets you specify values to be entered into form fields, enabling your test scripts to be more realistic by replacing recorded user input data with randomized, parameterized user data.

  1. Select a node in the TrueLog menu tree that includes user-data input. You can customize the input values of controls that have yellow backgrounds.
  2. Right-click in the Value column of a control and choose Customize Value. With the Parameter Wizard, you can modify script values in either of the following ways:
    • Use an existing parameter that is defined in the dclparam or dclrand sections of your script.
    • Create a new parameter based on a new constant value, random variable, or values in a multi-column data file.
  3. Click the Create new parameter option button.
    1. Click Next
    The Create New Parameter dialog box opens.
  4. Click the Parameter from Random Variable option button.
    1. Click Next
    The Random Variable Wizard opens.
  5. Select the type of random variable you want to insert into your test script from the list box A brief description of the highlighted variable type appears in the lower pane.
    1. Click Next
    The Name the variable and specify its attributes page appears. The Strings from file random variable type generates data strings that can either be selected randomly or sequentially from a specified file.
  6. Type a name for the variable in the Name field.
    1. Select the order in which the values are to be called.
    • Random
    • Sequential
  7. Select a preconfigured datasource from the File/Name list box. Alternative: New random variable files can be created by clicking New.
  8. Select Per test random value generation.
    1. Click Finish.
    This modifies the BDL form declaration of your test script so that it uses the random variable for the given form field in place of the recorded value. The new random variable function appears below in BDL view.

Initiate a Try Script run with the random variable function in your test script to confirm that the script runs without error.

Parent topic: Oracle Forms User-Input Data Customization


Content Verification Functions for Oracle Forms

TrueLog Explorer offers pre-enabled verification functions for Oracle Forms applications. Simply right-click the objects that you want to have verified and choose a verification function. The specified verification function will be generated and inserted into your BDL script automatically.

TrueLog Explorer enables you to insert content-verification functions into test scripts to verify the accuracy of content that is returned by application servers during testing.

By comparing replay test runs with record test runs (a uniquely powerful approach to the challenge of testing end-user experience in client/server environments) TrueLog Explorer allows you to confirm visually whether or not embedded objects, text, graphics, table data, SQL responses and more are actually downloaded and displayed by clients while systems are under load. This allows you to detect a class of errors that other Web-traffic simulation tools are not able to detect: errors that occur only under load that are not detected with standard load test scripts.

Content verifications remain useful after system deployment as they can be employed in on-going performance management.

  • Inserting an Oracle Forms Verification Function
    TrueLog Explorer offers verification functions for Oracle Forms applications. Specified verification functions are generated and inserted into your BDL script automatically.
Parent topic: Working With Oracle Forms Applications


Inserting an Oracle Forms Verification Function

Perform an Oracle Forms Try Script test run. Open the resulting TrueLog in TrueLog Explorer.

  1. With an Oracle Forms TrueLog open in TrueLog Explorer, select a TrueLog node that offers verifiable data.
  2. Right-click a verifiable value and choose Verify Value. The Add Forms Control Verifications dialog box opens.
  3. Click the Verify the Value link. The Insert Value Verification Function dialog box appears.
  4. Select one of the following values from the drop list:
    • is equal to
    • is different from
    • contains
    • does not contain
  5. Specify verification case sensitivity and white space details.
  6. Specify the severity that is to be raised if the verification returns a negative result.
  7. Specify if verification should be against a parameter.
  8. Click OK on the Insert Value Verification Function dialog box. The verification function is added to your test script.
  9. Click Yes on the Add Verifications dialog box to perform a Try Script run.
  10. Confirm that verifications have been passed successfully. API nodes that include verifications are indicated with blue “V” symbols
Parent topic: Content Verification Functions for Oracle Forms


Completing Your Oracle Forms Script Customizations

Once the following steps have been completed your Oracle Forms test script should run without error.
  • Customize how the script handles session information and user-input data.
  • Add any required verification functions.
  • Complete any required manual BDL script editing via Silk Performer.
Parent topic: Working With Oracle Forms Applications


Working With Citrix Applications

In addition to offering TrueLog recording, TrueLog replay, and basic TrueLog analysis for the testing of applications that are hosted by Citrix servers, TrueLog Explorer also offers user-input data customization. The functionality described here can also be applied to the testing of Citrix NFuse sessions.

Before proceeding with this chapter, it is essential that you familiarize yourself with TrueLog Explorer basic functionality.

Note: For detailed information regarding the use of Silk Performer in testing applications that are hosted by Citrix servers, refer to the Citrix Tutorial.
  • Silk Performer Citrix Player
    Silk Performer relies on its own Citrix player for replay, rather than TrueLog Explorer.
  • Citrix TrueLogs
    TrueLog Explorer may optionally be opened along with the Citrix player during Try Script runs.
  • Synchronization Problems in Citrix Scripts
    Windows may fail to be activated and screen synchronizations may fail when the Citrix player encounters different values during replay than were captured during recording.
  • Citrix User-Input Data Customization
    Explains that with user-input data customization you can make your test scripts more realistic by replacing static recorded input data with dynamic, parameterized data that changes with each transaction.
  • Citrix Parsing and Verification Functions
    Silk Performer support for optical character recognition (OCR) simplifies session-dependent verifications and parsing by recognizing text values in the screenshots of captured application states.
  • OCR Verification and Parsing
    Explains how to parse and verify strings that are generated through OCR.
Parent topic: TrueLog Explorer 21.0


Silk Performer Citrix Player

Silk Performer relies on its own Citrix player for replay, rather than TrueLog Explorer. The Silk Performer Citrix player opens when Try Script runs begin, replaying all recorded actions in full animation. Mouse movements and operations are simulated with an animated mouse icon.

The Silk Performer Citrix player includes a Log window with three panes that detail different aspects of each Try Script run:

Script
This pane lists all of the executed BDL script functions and the currently executing BDL function.
Windows
This pane includes a stack of all the client windows that are accessed during the current session, including window captions, styles, sizes, and positions. Top-level windows carry a window icon and are listed above sub-windows.
Log
This pane lists all informational messages and events, including executed BDL functions, and window creation/activation/destruction.
Parent topic: Working With Citrix Applications


Citrix TrueLogs

TrueLog Explorer may optionally be opened along with the Citrix player during Try Script runs (by selecting the Animated Run with TrueLog Explorer check box on the Try Script dialog box). TrueLog Explorer displays the data that is actually downloaded during Try Script runs. Each main window accessed during recording is listed as a top-level API node in the TrueLog Explorer menu tree. Actions recorded against those windows are listed as subnodes.

By selecting a high-level synchronization node you see a window as it appeared after the last synchronization function (the bitmap captured during replay).

Window synchronization functions are visualized with colored borders. Window creations are indicated with green borders. Window activations are indicated with blue borders. Window destructions are indicated with yellow borders.

TrueLogs work in complement with the Citrix player by visualizing screen states. For example, if you are not sure which window is indicated by a certain window ID that is listed in the Citrix Player Log window, you can find the corresponding synchronization function in the corresponding TrueLog and thereby access a bitmap that shows the window in question.

User input nodes (CitrixUserInput and related functions) reflect keyboard and mouse input. CitrixMouseClick functions offer two track vector parameters (X and Y coordinates). Red squares indicate mouse-click start points. Red cross-marks indicate mouse release points. A red line between a start and end point indicates the path of the mouse. If there is no move while the button is pressed then only a red cross is displayed. Onscreen tool tips offer additional information (right-click, left-click, double-click, etc).

Value strings (keyboard input) are visualized onscreen as floating red text until target window captions are identified (in subsequent nodes) to indicate where strings are to be input.

Parent topic: Working With Citrix Applications


Synchronization Problems in Citrix Scripts

Windows may fail to be activated and screen synchronizations may fail when the Citrix player encounters different values during replay than were captured during recording. Sometimes the causes of synchronization problems are not apparent, they may be due to a change in screen position of only a single pixel. Such differences are best assessed visually using a bitmap viewing program.

More common than screen synchronization failures are windows not being activated during replay. In such cases, the screenshots associated with the corresponding user actions may explain the fault. Sometimes there is no user fault and a window is activated only sporadically. In such cases, you must remove the associated CitrixWaitForWindow function.

TrueLog Explorer captures screenshots when errors occur (the default setting) and writes these bitmaps to disk. Visual comparison of record and replay screens can be achieved by comparing TrueLog On Error bitmaps with the bitmaps that are captured by Silk Performer along with each synchronization function (the default setting). By default the recorder writes screenshots to the screenshots directory in the project directory. Replay stores screenshots in the current result directory.

Note: The Silk Performer Dump window region of unsuccessful screen synchronizations Citrix option must be activated (the default) to have these bitmaps captured and saved.
Parent topic: Working With Citrix Applications


Citrix User-Input Data Customization

With user-input data customization you can make your test scripts more realistic by replacing static recorded input data with dynamic, parameterized data that changes with each transaction. Manual scripting is not required for such data-driven tests.

During testing you can customize the user input that is entered into applications that are hosted by Citrix terminal services in two ways:

  • The Parameter Wizard allows you to specify values to be entered with keyboard events, enabling your test scripts to be more realistic by replacing recorded user-input data with randomized, parameterized user data.
  • Visual customization allows you to customize mouse events such as clicks, drags, and releases by right-clicking within rendered screenshots that are captured during recording.
  • Customizing Citrix User-Input Data
    Use the Parameter Wizard to make your test scripts more realistic by replacing static recorded input data with dynamic, parameterized data.
  • Customizing Mouse Events
    Visually customize the behavior of recorded mouse events.
Parent topic: Working With Citrix Applications


Customizing Citrix User-Input Data

Use the Parameter Wizard to make your test scripts more realistic by replacing static recorded input data with dynamic, parameterized data.

  1. Select a node in the menu tree that reflects user data input (for example, select a CitrixKeyString node that specifies a keyboard data string).
  2. Right-click the input data string (shown as floating red text) and choose Customize User Input.
  3. The Parameter Wizard opens. Select Create new parameter and click Next. With the Parameter Wizard, you can modify script values in either of the following ways:
    • Use an existing parameter that is defined in the dclparam or dclrand sections of your script.
    • Create a new parameter based on a new constant value, random variable, or values in a multi-column data file.
  4. The Create New Parameter dialog box opens. Select the Parameter from Random Variable option button and click Next.
  5. The Choose the kind of usage dialog box opens. Specify whether the new random value should be used Per usage, Per transaction, or Per test.
  6. Click Finish to modify the BDL form declaration of your test script so that it uses the random variable for the given form field in place of the recorded value. The new random variable function displays below in BDL view.
  7. Initiate a Try Script run with the random variable function in your test script to confirm that the script runs without error.
Parent topic: Citrix User-Input Data Customization


Customizing Mouse Events

The behavior of recorded mouse events can be visually customized.

  1. In the menu tree, select a CitrixMouseClick node that includes mouse activity. Red squares indicate mouse-click start points. Red cross-marks indicate mouse-release points. A red line between a start and end point indicates the path of the mouse. Onscreen tooltips offer additional information (right-click, left-click, double-click, etc).
  2. Right-click anywhere on the screen and select Customize User Input. The Customize Mouse Event dialog box opens.
  3. Click at the screen position where you want the customized mouse move to begin.
  4. Click Customize to accept the customization and modify the BDL script accordingly.
Your mouse event customization now appears in the recorded TrueLog bitmaps in green. The mouse customization also appears in the BDL script in green text. CitrixMouseClick functions offer two track vector parameters (X and Y coordinates). The next time this script executes, it will use the new screen coordinates you have specified.
Parent topic: Citrix User-Input Data Customization


Citrix Parsing and Verification Functions

Silk Performer support for optical character recognition (OCR) simplifies session-dependent verifications and parsing by recognizing text values in the screenshots of captured application states. As is the case with other TrueLog formats (Web, database, etc), verification and parsing functions are added via TrueLog Explorer after script recording.

Note: To enable optical character recognition (OCR) for parsing and verification functions in TrueLog Explorer, you must first generate a font database using Silk Performer system settings.

Window Position and State

Window positions and state (maximized/minimized) are important for ensuring accurate replay as TrueLog Explorer scripts screen coordinates where selected text is to be read relative to the desktop, not individual windows. So if a window appears in a different position during replay than it did during recording, OCR operations will not locate the specified text. If it is not possible to specify an absolute position of a conversion-region, your script must be manually updated using coordinates that are relative to windows.

  • Verification Functions
    Silk Performer supports bitmap and window verification for applications that are hosted by Citrix servers.
  • Inserting OCR Verification Functions
    Generate an OCR verification function to perform session-dependent verifications in Citrix tests.
  • Inserting OCR Parsing Functions
    Silk Performer supports text parsing for applications that are hosted by Citrix servers.
Parent topic: Working With Citrix Applications


Verification Functions

Although input value verification and response data verification are not supported for Citrix, Silk Performer does support bitmap and window verification for applications that are hosted by Citrix servers.

Parent topic: Citrix Parsing and Verification Functions


Inserting OCR Verification Functions

Bitmap and window verification for applications hosted by Citrix servers does not allow for the verification of session-dependent data (for example, login names). However, using OCR techniques, Silk Performer enables the storing of recognizable text values in variables, thereby simplifying session-dependent verifications in Citrix load tests.

  1. Using Silk Performer, record a Citrix session.
  2. Run a Try Script run, with the Animated Run with TrueLog Explorer check box checked on the Try Script dialog box. This opens TrueLog Explorer.
  3. When the Try Script run is complete, select the API node that includes the bitmap screengrab of the screen on which you want to verify text.
  4. Click and drag your cursor onscreen to select the screen region that includes the text you want to use for verification.
  5. Right-click in the selected area and choose Verify Text.
  6. The Insert Text Verification Function dialog box opens. The selected text is pre-loaded into the constant value text box and the constant value option button is selected by default.
    Tip: In addition to verifying against a constant value, you can also verify against a parameter (either an existing parameter or a new parameter). To verify against a parameter, select the parameter option button. If a parameter already exists, clicking [...] allows you to browse to and select a parameter. If no parameters exist, clicking [...] launches the Parameter Wizard, enabling you to create a new parameter.
  7. Specify the OCR technique that should be used to verify the text. While font-based OCR needs fewer resources, the fuzzy OCR produces better results for texts displayed with font smoothing techniques. Help the fuzzy OCR to provide better results by specifying the language of the text.
  8. From the Verify that the text in the selected rectangle is list box, select equal or not equal.
  9. Specify whether or not the verification is to be Case sensitive and if it should Ignore whitespaces.
  10. In the Severity portion of the dialog box, specify the severity that is to be raised if the verification returns a negative result (Error, Warning, Informational, or Custom). Click OK.
  11. A confirmation dialog box opens. Click OK to add the OCR verification function to your Citrix test script.
Parent topic: Citrix Parsing and Verification Functions


Inserting OCR Parsing Functions

  1. Using Silk Performer, record a Citrix session.
  2. Run a Try Script run, with the Animated Run with TrueLog Explorer check box selected on the Try Script dialog box. This opens TrueLog Explorer.
  3. When the Try Script run is complete, select the API node that includes the bitmap screengrab of the screen from which you want to parse text.
  4. Click and drag your cursor onscreen to select the screen region that includes the text you want to parse.
  5. Right-click in the selected area and select Parse Text.
  6. The Insert Parsing Function dialog box offers parameters by which the parsing function can be configured. Though the default settings will likely be correct, you can adjust:
    Parameter name
    Enter the name of the parameter that is to receive the result of the parsing function.
    Informational statement insertion
    • Select Print statement to insert an informational Print statement into the script after the Web page call. This writes the result of the parsing function to Silk Performer's Virtual User Output window.
    • Select Writeln statement (“write line” statement) to write the parsed value to an output file to facilitate debugging (in addition to writing the value to the Virtual User Output window as a Print statement does). Because generating output files alters test-time measurements, these files should only be used for debugging purposes and should not be generated for full load tests.
    OCR Technique
    Specify the OCR technique that should be used to verify the text. While font-based OCR needs fewer resources, the fuzzy OCR produces better results for texts displayed with font smoothing techniques. Help the fuzzy OCR to provide better results by specifying the language of the text.
  7. Click OK.
  8. A confirmation dialog box opens. Click OK to add the OCR parsing function to your Citrix script.
Parent topic: Citrix Parsing and Verification Functions


OCR Verification and Parsing

This section explains how to parse and verify strings that are generated through OCR.

  • How OCR Verification and Parsing Works
    String verification through optical character recognition (OCR) is achieved using CitrixVerifyText and CitrixVerifyTextFuzzy API calls.
  • Configuring Silk Performer for OCR
    Generate a font database to enable optical character recognition (OCR) for Citrix parsing and verification functions.
  • Generating a Text-Synchronization Function
    Generate a CitrixWaitForText function to pause script execution until specified text or a text pattern appears at a specified screen position.
Parent topic: Working With Citrix Applications


How OCR Verification and Parsing Works

String verification through optical character recognition (OCR) is achieved using CitrixVerifyText or CitrixVerifyTextFuzzy API calls. These functions are inserted via TrueLog Explorer during script customization. CitrixVerifyText and CitrixVerifyTextFuzzy functions compare text strings in replay bitmaps to determine if they are identical.

CitrixParseText and CitrixParseTextFuzzy functions are available for parsing text.

Silk Performer offers two distinct OCR techniques:

  1. Font-based OCR approach: The font-based approach compares text bitmaps to bitmaps of system fonts. This approach relies on pattern databases to recognize varying fonts and text styles. Font databases must be generated before font-based OCR can be used. Characters are only recognized if they can be exactly reproduced by a system font and its styles. OCR results may be poor if font smoothing techniques such as anti-aliasing or ClearType are used. The font-based OCR approach is optimized for performance and resource consumption.
  2. Fuzzy OCR with language affinity: Through fuzzy text recognition this approach analyzes text images using a character and language knowledge base. Rather than comparing images to font bitmaps, the fuzzy OCR uses proprietary text and language recognition algorithms.
Only Citrix TrueLogs show verification and parsing API calls in the menu tree. With other TrueLog modes (for example, Web and database), new API nodes are not added to the menu tree.
Note: OCR operations should be performed on static content. When synchronizing on window events it is possible that screen refresh may be slightly delayed, which will result in timing-dependent outcomes. If a screen changes too frequently the correct image may not be selected for comparison if timing is off. Therefore you should script a wait or a CitrixWaitForScreen function call before all OCR verification or parsing functions.
Parent topic: OCR Verification and Parsing


Configuring Silk Performer for OCR

To enable optical character recognition (OCR) for Citrix parsing and verification functions using the font-based OCR approach, you must generate a font database via Silk Performer system settings.

Font-based optical character recognition relies on font, or “pattern” databases to recognize fonts and text styles in bitmaps. The default set of fonts covers most scenarios, however in some situations you may wish to add additional fonts or font styles. A new database should be generated whenever new fonts are added or removed from the system.

Including too many fonts in the database can slow down processing and lead to contradictory reading, so it is recommended that you only include those fonts that are used in the bitmaps from which you will be capturing text strings.

  1. In Silk Performer, go to Settings > System... and choose the Citrix icon.
  2. On the Font-based OCR page, use Add >> and Add All to move those fonts that you want to have used for OCR from the System Fonts list box to the Chosen Fonts list box.
  3. Use Remove All and << Remove to delete unnecessary fonts from the Chosen Fonts list box.
  4. In the Sizes text box, specify the font size range that should be used (for example, 8-20).
  5. Define which font styles should be included by checking the Italic, Bold, and Underlined check boxes.
  6. Click Generate Font Database.
  7. The Build Font Base dialog box opens. Click OK to confirm that you want to replace the existing font database with a new database.
  8. Click the Fuzzy OCR tab and select a language. This setting helps the fuzzy OCR engine to deliver better results for a particular language.
  9. Click OK on the System Settings dialog box to accept the changes.
Parent topic: OCR Verification and Parsing


Generating a Text-Synchronization Function

TrueLog Explorer offers the CitrixWaitForText synchronization function that pauses script execution until specified text or a text pattern appears at a specified screen position. This feature can be used to synchronize screens and user input. For example, you might want a script to pause execution until a specified dialog text says "ready" instead of "processing" before pressing OK. Such an action is difficult to synchronize when you are not sure of processing duration. The scripting of this function would read CitrixWaitForText(... "ready", ...), preceding a CitrixMouseClick(...) function.

  1. Using Silk Performer, record a Citrix session.
  2. Run a Try Script run with the Animated Run with TrueLog Explorer check box selected on the Try Script dialog box. TrueLog Explorer launches.
  3. When the Try Script run is complete, select the API node that includes the bitmap screengrab of the screen on which you want to wait for a specific text string.
  4. Click and drag your cursor onscreen to select the screen region that includes the text you want to synchronize.
  5. Right-click in the selected area and choose Synchronize Text.
  6. The Insert Text Synchronization Function dialog box opens. Enter a constant value for which the script should wait, or select a parameter value. Click OK to insert the function into your script.
Parent topic: OCR Verification and Parsing


Working With TCP/IP and UDP-Based Applications

This section explains how to apply TrueLog On Error and test-script analysis features to the testing of TCP/IP and UDP protocol based applications.

TrueLog Explorer serves as an effective viewer for TCP/IP and UDP based TrueLogs (For example, SMTP, POP3, and custom protocols). TrueLog Explorer enables you to compare replay TrueLogs with record TrueLogs. Script customizations (session handling, user-input data parameterization, and verification functions) are not available for TCP/IP and UDP TrueLogs.

Before proceeding with this chapter, it is essential that you familiarize yourself with TrueLog Explorer basic functionality.

  • TCP/IP and UDP TrueLog Structure
    Describes the view types that are available with TCP/IP and UDP TrueLogs.
  • Setting ASCII and Hexadecimal Viewing Options
    Though Auto view mode automatically selects the most appropriate data representation mode for you, TrueLog Explorer gives you the option of changing your view of TCP/IP and UDP functions between ASCII and Hexadecimal format.
  • Comparing TCP/IP and UDP Record and Replay TrueLogs
    When a TCP/IP and UDP replay TrueLog is compared alongside a corresponding record TrueLog and the dynamics of the protocols are uncovered, those dynamics must be customized for future test runs.
Parent topic: TrueLog Explorer 21.0


TCP/IP and UDP TrueLog Structure

TCP/IP and UDP TrueLogs are structured and viewed in the same way that HTML TrueLogs are structured and viewed. One exception is that TCP/IP and UDP do not offer a high-level rendered interface as HTML does.

Display of the Response page is suppressed for TCP/IP and UDP TrueLogs, except when Web API calls are included in them.

Content Pane

For TCP/IP and UDP based TrueLogs, TrueLog Explorer provides the following data views in the Content pane:

Item | Description
Response | Suppressed for TCP/IP and UDP, except when Web API calls are included.
Differences | The Differences page lists the In Body differences between selected nodes. This page is helpful in finding dynamic information in server responses. It is the first place to look for session information. Note: The Differences page is only available in difference mode.
Request | Suppressed for TCP/IP and UDP.

Information Pane

The Information pane offers data regarding TCP/IP and UDP test scripts and test runs. It offers the following views:

Item | Description
Info | The Info page displays general information about the open TrueLog file and the selected API node.
BDL | The BDL page displays the BDL script that corresponds to the open TrueLog. The BDL script is automatically positioned to the line of the selected API node.
References | Suppressed for TCP/IP and UDP
Out Header | Suppressed for TCP/IP and UDP
In Header | Suppressed for TCP/IP and UDP
Out Body | For TCP/IP and UDP, this page contains data sent with WebTcpipSend functions from the application to the server.
In Body | Contains the responses that are sent from the server to the application (for example, WebTcpipRecv functions)
Statistics | Suppressed for TCP/IP and UDP
Parent topic: Working With TCP/IP and UDP-Based Applications


Setting ASCII and Hexadecimal Viewing Options

Though Auto view mode automatically selects the most appropriate data representation mode for you (for example, binary for images, text for HTML documents), TrueLog Explorer gives you the option of changing your view of TCP/IP and UDP functions between ASCII and hexadecimal format.

  1. Choose Settings > Options > Display .
  2. Uncheck the Auto view mode check box in the Data format section of the dialog box.
  3. Check the Show binary data check box.
  4. Click OK.
Parent topic: Working With TCP/IP and UDP-Based Applications


Comparing TCP/IP and UDP Record and Replay TrueLogs

When a TCP/IP and UDP replay TrueLog is compared alongside a corresponding record TrueLog and the dynamics of the protocols are uncovered, those dynamics must be customized for future test runs otherwise session-relevant data will be passed along during tests and errors will result. To customize the dynamics of these protocols, TrueLog Explorer offers TCP/IP and UDP recording rules.

Note: Automatic session handling customization is not available for TCP/IP and UDP based applications. Dynamic BDL parsing functions must be coded manually via Silk Performer.
  1. In compare mode, open a TCP/IP or UDP replay TrueLog and the corresponding record TrueLog.
  2. Click the Response tab.
    Note: Difference tables are not enabled for binary content, so the Differences page is not available.
  3. Click Step through TrueLog. The Step Through TrueLog dialog box opens.
  4. Click the API calls option button. The TrueLog API calls with the recorded responses are displayed alongside the corresponding replay responses. Those differences that indicate that dynamics are included in the test script must be customized via Silk Performer recording rules.
Parent topic: Working With TCP/IP and UDP-Based Applications


Working With Terminal-Emulation Applications

This section explains how to customize a terminal emulation test script based on the results of a Try Script run.

  • Working With Terminal-Emulation Applications - Overview
    In addition to offering TrueLog recording, TrueLog replay, and basic TrueLog analysis for terminal-emulation applications, TrueLog Explorer also offers parsing, content verification, and input-parameter customization.
  • Terminal-Emulation TrueLog Structure
    Describes the views that are available for terminal emulation TrueLogs.
  • Customizing Host Screen Display
    You can change the font or font size of text displayed in Host Screen view if the pre-defined font does not correctly display the characters that are received by the application under test.
  • Stepping Through Terminal-Emulation TrueLogs
    You can jump from one error to the next sequentially as they occurred in time, regardless of which TrueLogs the errors were recorded in. This simplifies the process of analyzing errors.
  • Analyzing Terminal-Emulation Test Scripts
    Once you have generated a test script you should determine if the script runs without error by performing a Try Script run. A Try Script run will determine if the script accurately recreates the recorded interactions.
  • Comparing Replay and Record TrueLogs
    When testing terminal emulation applications, differences can occur in corresponding field values between replay and record TrueLogs. Some differences may result in replay errors.
  • Terminal-Emulation TrueLog Functions
    Six terminal emulation functions are available for insertion into test scripts.
  • Customizing User Input Data
    Visually customize the user input data in your terminal emulation script to make the script more realistic.
  • Verification Functions for Terminal-Emulation Applications
    Explains how to verify content and fields for terminal emulation API calls.
  • Parsing Functions for Terminal-Emulation Applications
    Explains how value parsing can be used to enable accurate replay when session-specific strings must be parameterized.
Parent topic: TrueLog Explorer 21.0


Working With Terminal-Emulation Applications - Overview

In addition to offering TrueLog recording, TrueLog replay, and basic TrueLog analysis for terminal-emulation applications, TrueLog Explorer also offers parsing, content verification, and input-parameter customization. TrueLog functionality is supported for the following protocols: VT100+, IBM 3270, and IBM 5250.

Before proceeding with this chapter, it is essential that you familiarize yourself with TrueLog Explorer basic functionality.

User Data Customization

User data customization via TrueLog Explorer and the Parameter Wizard is supported for both TN3270 and TN5250 protocol terminal emulation applications.

On-Screen Event Synchronization

Functions are available for synchronization of on-screen events in record and replay scenarios, though the functions cannot be inserted using TrueLog Explorer.

Note: For additional details regarding Silk Performer support for terminal emulation applications, please see Miscellaneous Tutorials, a PDF that accompanies your Silk Performer installation at Documentation > Tutorials.
Parent topic: Working With Terminal-Emulation Applications


Terminal-Emulation TrueLog Structure

TrueLog Explorer supports the visualization of terminal emulation requests and responses in the same way that it supports the visualization of HTTP client requests and HTTP/HTML server responses.

The three windows that are displayed with terminal emulation TrueLogs are listed below:

  • TrueLog menu tree – Lists all terminal emulation API calls that were included in the test run.
  • Content pane – Displays the state of the terminal emulation application at each API node.
  • Information pane – Displays data related to the most recent test run. The view tabs in this pane that are active and applicable to terminal emulation TrueLogs are Info, BDL, In Body, Out Body, and Host Screen Info.

Parent topic: Working With Terminal-Emulation Applications


Customizing Host Screen Display

You can change the font or font size of text displayed in Host Screen view (within the Content pane). This may be necessary if the pre-defined font (lucida console) does not correctly display the characters that are received by the application under test.

Font type:

To change the font, you must change the following key in the Windows registry:
HKEY_CURRENT_USER\Software\Silk\Silk Performer\21.0\SystemSettings\Layout\GreenScreen Font Name

Font size:

To change the size of the displayed characters, you must change the following key in the Windows registry:
HKEY_CURRENT_USER\Software\Silk\Silk Performer\21.0\SystemSettings\Layout\GreenScreen Font Size
Enter the size of the font (default is 10).
Parent topic: Working With Terminal-Emulation Applications


Stepping Through Terminal-Emulation TrueLogs

After tests, it is typical to have multiple TrueLog On Error files open in TrueLog Explorer (one TrueLog for each virtual user who returns an error). With TrueLog Explorer Find Errors feature, you can jump from one error to the next sequentially as they occurred in time, regardless of which TrueLogs the errors were recorded in. This simplifies the process of analyzing errors. There is no need for you to manually review all open TrueLogs to find the next error in a sequence.

  1. After the completion of a test, within Silk Performer, click Explore Results.
    Note: TrueLog On Error files are generated only when the Silk Performer Generate TrueLog On Error option is enabled.

    The Explore Results dialog box opens.

  2. Click TrueLog Explorer.
    Note: TrueLog Explorer is disabled both when no errors are detected during a test and when Truelog On Error is not enabled. In such instances, proceed directly to analyzing results with Performance Explorer.
    TrueLog Explorer opens with the TrueLog On Error files that were generated for the current test, and the Step through TrueLog dialog box opens.
  3. Using the Step through TrueLog dialog box, click the appropriate option button to advance through all Stable Screens (WebTelnetRecvCommand calls), API calls (each API node), and Errors. TrueLog On Error files are searched sequentially as they were recorded in time.
    Note: When multiple WebTelnetRecvCommand calls are clustered in a sequence, clicking Find Next with the Stable Screens option automatically advances focus to the final WebTelnetRecvCommand call in the sequence.
  4. Click Find Next to advance to the first stable screen, API call, or error. Error messages are displayed on the Info page. API nodes that contain replay errors are tagged with red “X” marks in the menu tree.

To view the originally recorded TrueLog that corresponds to the open replay TrueLog, right-click the replay TrueLog’s virtual-user node in the menu tree and choose Open Associated Record TrueLog. Each server response is then available for viewing on the Host Screen page.

Parent topic: Working With Terminal-Emulation Applications


Analyzing Terminal-Emulation Test Scripts

Once you have generated a test script you should determine if the script runs without error by performing a Try Script run. A Try Script run will determine if the script accurately recreates the recorded interactions.

The default option settings for Try Script runs include live display of data downloaded during the test run and the writing of log and report files.

With Try Script runs only a single virtual user is run and the stress test option is enabled so that there is no think-time delay between transactions.

  1. Click Try Script on the workflow bar. The Try Script dialog box opens.
  2. To view rendered page transitions during a Try Script run, check the Animated Run with TrueLog Explorer check box.
  3. Click Run.
    Note: You are not running an actual load test here, only a test run to see if your script requires debugging.

    The Try Script run begins. The Monitor window opens, giving you detailed information about the run’s progress.

    TrueLog Explorer opens, showing you the data that is actually downloaded during the Try Script run. Each main terminal emulation window accessed during recording is listed as a high-level WebTelnetRecvCommand API node in the menu tree.

Parent topic: Working With Terminal-Emulation Applications


Comparing Replay and Record TrueLogs

When testing terminal emulation applications, differences can occur in corresponding field values between replay and record TrueLogs. Some differences may result in replay errors.

  1. Open a replay TrueLog and click Analyze Test on the workflow bar. The Analyze Test dialog box opens.
  2. Click Compare your test run.
  3. The associated record TrueLog opens in compare view. The Step through TrueLog dialog box also opens.
  4. Select an interval to search by (Stable Screens, API nodes, or Errors).
  5. Click Find Next to advance to the first set of corresponding stable screens, API calls, or errors in the record and replay TrueLogs. Visually compare the values and states of the controls and screenshots to see if there are any differences.
  6. Once you have completed any required customizations (based on differences you have discovered), click Try Script Run to confirm that your customizations run without error.
  7. Analyze the results of subsequent test runs to determine whether your customizations were successful or if further customization is required.
  8. Click Compare Mode to disable compare mode.
  9. Repeat this procedure as many times as is required until your script is fully customized and all necessary customizations have been added.
Parent topic: Working With Terminal-Emulation Applications

Synchronizing Record and Replay TrueLogs

When in compare mode, you can synchronize corresponding API nodes between replay and record TrueLogs.

  1. Enable compare mode.
  2. Open a set of record and replay TrueLogs.
  3. Right-click an API node for which you want to establish synchronization.
  4. Select Synchronize TrueLogs. TrueLog Explorer then locates the API node in the matching TrueLog that best correlates with the selected API node.


Terminal-Emulation TrueLog Functions

Six terminal emulation functions are available for insertion into test scripts.

WebTelnetScreenVerifyText
Verifies onscreen text (available from Host Screen view).
WebTelnetScreenGetText
Parses onscreen text (available from Host Screen view).
WebTelnetScreenVerifyField
Verifies a text field (available from Host Screen Info view).
WebTelnetScreenGetField
Parses text from a field (available from Host Screen Info view).
WebTelnetScreenVerifyStatus
Verifies a field's status (available from both views).
WebTelnetScreenGetStatus
Parses a field's status (available from both views).
Parent topic: Working With Terminal-Emulation Applications


Customizing User Input Data

Note: Visual user input data customization for terminal emulation is supported for both TN3270 and TN5250 protocol scripts.
  1. With a terminal emulation TrueLog loaded into TrueLog Explorer, select the WebTelnetSendRecordExecute API call (in the API node tree menu) that includes the user input data that is to be customized.
  2. Select the Host Screen tab. The Host Screen tab displays a screen capture of the user input screen.
  3. Select the Host Screen Info tab. The Host Screen Info tab includes a list of all user input data fields that are available on the selected screen. The input fields are numbered and listed in the order in which they appear on the screen. When you select an input field entry on the Host Screen Info tab the corresponding field is highlighted in the screen capture on the Host Screen tab.
    Note: Only input fields that had data entered into them during recording are highlighted and available for customization.
  4. On the Host Screen Info tab, right-click the field entry that you want to customize and select Customize User Input. The Parameter Wizard launches.
  5. Use the Parameter Wizard to define how you want input data parameters to appear in your script. See Silk Performer Help for details on working with the Parameter Wizard. Modifications that you make to your script using the Parameter Wizard can be viewed on the BDL tab.

Execute a Try Script run to verify that the new parameter inserts user input data as required.

Parent topic: Working With Terminal-Emulation Applications


Verification Functions for Terminal-Emulation Applications

This section explains how to verify content and fields for terminal emulation API calls.

  • Verification Functions for Terminal-Emulation Applications
    Content verification functions may be inserted for any terminal emulation API call. For example, for a WebTelnetSendCommand function call in which input data is entered, you can insert a return value verification function.
  • Inserting a Content-Verification Function
    You can define a verification function for a terminal emulation text field to verify an onscreen text string in Host Screen view.
  • Inserting a Status-Verification Function
    A status is a name-value pair. A status-verification function enables you to verify a status value in a terminal-emulation input field.
  • Inserting a Field-Verification Function
    You can define a field-verification function for a terminal-emulation input field to verify text in the field.
Parent topic: Working With Terminal-Emulation Applications


Verification Functions for Terminal-Emulation Applications

TrueLog Explorer allows you to easily add content verifications to test scripts to verify that the content that is to be sent by servers is in fact received by clients under real-world conditions. Content verification functions may be inserted for any terminal emulation API call. For example, for a WebTelnetSendCommand function call in which input data is entered, you can insert a return value verification function. Verification functions can be inserted through context menus in both Host Screen view and Host Screen Info view.

By comparing replay test runs with record test runs, a uniquely powerful approach to the challenge of testing end-user experience in client/server environments, TrueLog Explorer allows you to confirm visually whether or not input data are actually downloaded and displayed by clients while terminal-emulation applications are under heavy load. This allows you to detect a class of errors that other terminal emulation traffic simulation tools are not able to detect: errors that occur only under load that are not detected with standard load test scripts.

Content verifications remain useful after system deployment as they can be employed in ongoing performance management.

By right-clicking an input field that you want to have verified in Host Screen or Host Screen Info views, the required verification function can be generated and inserted into your BDL script. TrueLog Explorer offers three pre-enabled verification functions (WebTelnetScreenVerifyText, WebTelnetScreenVerifyField, and WebTelnetScreenVerifyStatus).

Content Verification vs. Field Verification

Content verifications enable you to select and setup verifications for onscreen text strings in Host Screen view, regardless of their placement on screen. Field verifications enable you to set up verifications for pre-defined regions (fields) within a terminal view. An application might define an entire screen as a single field, or a page might be built of header fields, footer fields, body fields, and so forth. Fields are often used as input areas, but they do not necessarily need to accept input. On-screen characters do not necessarily need to reside within fields.

Parent topic: Verification Functions for Terminal-Emulation Applications


Inserting a Content-Verification Function

  1. In Host Screen Info view, right-click an input field for which you want to verify the return value.
  2. Select Verify Selected Text.
  3. The Insert Verification Function dialog box opens. Use this dialog box to specify the type of verification function that should be inserted into the BDL script. From the Verify that the sequence of characters starting at column x, row x list box, select is equal to or is not equal to.
  4. Specify if the verification should be against a constant value or a parameter value.
  5. Specify whether or not the verification is to be Case sensitive and if white spaces should be ignored.
  6. In the Severity portion of the dialog box, specify the severity that is to be raised if the verification returns a negative result (Error, Warning, Informational, or Custom).
  7. Click OK to add the verification function to your test script. Once the BDL script has been successfully modified, repeat this process for each verification you want to add to the BDL script.
Parent topic: Verification Functions for Terminal-Emulation Applications


Inserting a Status-Verification Function

A status-verification function enables you to verify a status value in a terminal-emulation input field. A status is a name-value pair (it is the value of the status name that is verified).

  1. Right-click an input field in Host Screen Info view.
  2. Choose Verify Status Value.
  3. The Insert Status Value Verification Function dialog box opens. Use this dialog box to specify the type of verification function that should be inserted into the BDL script. From the Verify that the value of the status list box, select the name of the status you want to verify.
  4. Select is equal to or is not equal to to define the status state you want to verify.
  5. Specify if the verification should be against a constant value or a parameter value.
  6. Specify whether or not the verification is to be Case sensitive and if white spaces should be ignored.
  7. In the Severity portion of the dialog box, specify the severity that is to be raised if the verification returns a negative result (Error, Warning, Informational, or Custom).
  8. Click OK to add the status-verification function to your test script. Once the BDL script has been successfully modified, repeat this process for each status verification that you wish to add to the BDL script.
Parent topic: Verification Functions for Terminal-Emulation Applications


Inserting a Field-Verification Function

You can define a field-verification function for a terminal-emulation input field to verify text in the field.

  1. Right-click a field in Host Screen Info view and choose Verify field.
  2. The Insert Field Verification Function dialog box opens. Use this dialog box to specify the type of verification function that should be inserted into the BDL script.
  3. Select is equal to (or is not equal to) as the operator for the verification.
  4. Specify if the verification should be against a constant value or a parameter value.
  5. Specify whether or not the verification is to be Case sensitive and if white spaces should be ignored.
  6. In the Severity portion of the dialog box, specify the severity that is to be raised if the verification returns a negative result (Error, Warning, Informational, or Custom).
  7. Click OK to add the verification function to your test script. Once the BDL script has been successfully modified, repeat this process for each additional verification that you want to add to your BDL script.
Parent topic: Verification Functions for Terminal-Emulation Applications


Parsing Functions for Terminal-Emulation Applications

This section explains how value parsing can be used to enable accurate replay when session-specific strings must be parameterized.

  • Parsing Functions for Terminal-Emulation Applications
    Explains how value parsing can be used to enable accurate replay when session-specific strings must be parameterized.
  • Inserting a Content-Parsing Function
    Insert a content parsing function to parse a text value from a recorded TrueLog into a parameter.
  • Inserting a Status-Parsing Function
    Insert a status-parsing function to parse a status value from a recorded TrueLog into a parameter.
  • Inserting a Field-Parsing Function
    Insert a field-parsing function to parse field text from a recorded TrueLog into a parameter.
Parent topic: Working With Terminal-Emulation Applications


Parsing Functions for Terminal-Emulation Applications

A parsing function can be inserted for any screen text, field, or status in a terminal-emulation TrueLog. Value parsing can be useful for enabling replay when session-specific strings must be parameterized to enable accurate replay (for example, you might parse newly created customer IDs into parameters that are inserted into the customer ID fields of invoices).

Content Parsing vs. Field Parsing

Content parsing functions enable you to select and set up parsing for onscreen text strings in Host Screen view, regardless of their placement on screen. Field parsing functions enable you to set up parsing for pre-defined regions (fields) within a terminal view. An application may define an entire screen as a single field, or a page may be built of header fields, footer fields, or body fields. Fields are often used as input areas, but they do not necessarily need to accept input. Onscreen characters do not necessarily need to reside within fields.

Parent topic: Parsing Functions for Terminal-Emulation Applications


Inserting a Content-Parsing Function

  1. Within Host Screen view, select text for which you want to parse a value.
  2. Right-click and choose Parse Selected Text.
  3. The Insert Parsing Function dialog box offers settings by which the parsing function can be adjusted. Though the default settings will likely be appropriate, you can adjust the following settings:
    • Parameter name: Enter a name for the parameter that is to receive the result of the parsing function.
    • Informational statement insertion: Check Print statement to insert an informational Print statement into the script. This will write the result of the parsing function to the Silk Performer Virtual User Output window. Check Writeln statement to write the parsed value to an output file to facilitate debugging (in addition to writing the value to the Virtual User Output window as a Print statement does). Because generating output files alters the time measurements of tests, these files should only be used for debugging purposes and should not be generated for full load tests.
  4. Click OK to insert the parsing statement into your test script.
Parent topic: Parsing Functions for Terminal-Emulation Applications


Inserting a Status-Parsing Function

  1. Right-click a status in Host Screen Info view and choose Parse Status Value.
    Note: This function can also be accessed by right-clicking a field in Host Screen view.
  2. The Insert Status Parsing Function dialog box offers settings by which the parsing function can be adjusted. Though the default settings will likely be appropriate, you can adjust the following settings:
    • Status: From the list box of existing status names, select the status for which you want to insert a parsing function.
    • Parameter name: Enter a name for the parameter that is to receive the result of the parsing function.
    • Informational statement insertion: Check Print statement to insert an informational Print statement into the script. This will write the result of the parsing function to the Silk Performer Virtual User Output window. Check Writeln statement to write the parsed value to an output file to facilitate debugging (in addition to writing the value to the Virtual User Output window as a Print statement does). Because generating output files alters the time measurements of tests, these files should only be used for debugging purposes and should not be generated for full load tests.
  3. Click OK to insert the parsing statement into your test script.
Parent topic: Parsing Functions for Terminal-Emulation Applications


Inserting a Field-Parsing Function

  1. Right-click a field in Host Screen Info view and choose Parse Field Text.
  2. The Insert Field Parsing Function dialog box offers settings by which the parsing function can be adjusted. Though the default settings will likely be appropriate, you can adjust the following settings:
    • Parameter name: Enter a name for the parameter that is to receive the result of the parsing function.
    • Informational statement insertion: Check Print statement to insert an informational Print statement into the script. This will write the result of the parsing function to the Silk Performer Virtual User Output window. Check Writeln statement to write the parsed value to an output file to facilitate debugging (in addition to writing the value to the Virtual User Output window as a Print statement does). Because generating output files alters the time measurements of tests, these files should only be used for debugging purposes and should not be generated for full load tests.
  3. Click OK to insert the parsing statement into your test script.
Parent topic: Parsing Functions for Terminal-Emulation Applications


Working With AJAX-Enhanced Web Applications

This section explains how to "pretty" format JSON and XML data and how to apply TrueLog Explorer script customization features to the testing of applications that utilize AJAX techniques.

The Silk Performer recorder can record and (with the assistance of TrueLog Explorer) replay Web applications that utilize AJAX (Asynchronous JavaScript and XML) requests. This is possible because Silk Performer recognizes asynchronous AJAX requests and responses that arrive in the form of either XML or JSON within HTML responses.

For more information about AJAX, see the Silk Performer Help.

  • AJAX-Support Overview
    Explains how to access values within AJAX requests for the purposes of customizing scripts, parsing data, and customizing session-dependent information.
  • Enabling Pretty-Formatted JSON and XML Viewing in TrueLog Explorer
    Enable pretty-formatted JSON and XML viewing on the Rendered page if TrueLog Explorer is unable to detect JSON or XML data.
Parent topic: TrueLog Explorer 21.0


AJAX-Support Overview

TrueLog Explorer and Silk Performer enable access to values within AJAX requests. This facilitates TrueLog Explorer script customizations such as input-data parameterization, verification functions, parsing functions, and session-information customization within AJAX responses.

Pretty Formatted JSON and XML Data

JSON and XML are data-structure formats commonly used in AJAX applications, REST techniques, and other environments. TrueLog Explorer supports pretty-formatted viewing of XML and JSON-formatted byte streams in recorded scripts. Enhanced rendering of JSON formatted data enables the customization of string values via TrueLog Explorer customization functions, such as string verification and parsing.

Pretty-formatted JSON view is also supported in compare mode, in which you can compare record and replay sessions side by side and automatically detect differences.

Note: TrueLog Explorer offers the option of viewing JSON data in either pretty-formatted JSON-rendering view or as a raw JSON byte stream, though script customization features such as verification and parsing are not supported in raw data view.

Pretty-formatted data viewing is also available in Silk Performer to facilitate readability and B.F. script customizations.

Parent topic: Working With AJAX-Enhanced Web Applications


Customizing TrueLog Explorer

This section explains how to adapt TrueLog Explorer customization, view, and TrueLog generation features to your specific needs. TrueLog Explorer option settings enable you to configure the display of data, the definition of delimiters for detecting differences, and the generation of virtual user reports. Customization features enable you to customize UI commands and the display of toolbars.

Compare mode enables the direct comparison of record and replay TrueLogs, one API node at a time. Differences mode automatically identifies and lists differences between record and replay TrueLogs for Web, XML, and database applications via the Differences page. Differences mode also displays differences in text-based format on the In Body, Out Body, In Header, Out Header, and BDL pages by rendering differing text in green and red.

When enabled, TrueLog Explorer animation displays replay content (graphics, text, and SQL commands) in real-time as it is downloaded.

Finally, as the generation of TrueLog files can be CPU/memory intensive, this section shows you how to use Silk Performer to adjust the characteristics of TrueLogs and the criteria by which they are generated.

  • TrueLog Explorer Option Settings
    Details the option settings that are available on the Options dialog box.
  • Customizing Toolbars and Commands
    This section explains how to customize toolbars and the commands that display on toolbars.
  • View Modes
    This section explains the view modes that are available for viewing TrueLogs.
  • Data Animation
    Explains how when animation is enabled, content received from servers during virtual user execution is displayed in real time, as users would see it.
  • TrueLog Impact on Scalability
    Explains how TrueLog generation affects performance and memory usage in your testing environment.
  • Custom Content Types and File Extensions
    Explains how you can add custom content-types and file extensions to some values in the registry.
  • TrueLog Generation Settings
    Explains how you can adjust TrueLog recording levels to minimize impact on performance and memory.
  • TrueLog Tree Filter
    Describes how to use the TrueLog tree filter to hide nodes and make a tree short and clear.
Parent topic: TrueLog Explorer 21.0


TrueLog Explorer Option Settings

TrueLog Explorer option settings, available on the Options dialog box, enable you to configure application settings such as the display of HTML documents, incoming and outgoing data, the definition of delimiters (which pinpoint differences between TrueLogs), and the generation of virtual user reports.

  • Setting Display Options
    Options are available for rendering HTML documents, displaying data format, and applying filters.
  • Inserting Delimiter Characters
    Insert characters or text to delimit differences between TrueLogs. Delimiters determine if a sequence is handled as a single difference or as multiple differences.
  • Inserting HTML Delimiter Characters
    HTML delimiters are characters or text that delimit differences between HTML TrueLogs. They determine if a sequence is handled as a single difference or as multiple differences.
  • Setting Workspace Options
    Describes how to enable the automatic display of virtual user reports and how to set auto expansion levels for your XML and project trees.
Parent topic: Customizing TrueLog Explorer


Setting Display Options

  1. Choose Settings > Options . The Display page opens.
  2. Specify how HTML documents are rendered.
    • To enable the execution of client-side scripts when rendering HTML documents, check the Script execution check box.
    • To view images or frames when rendering HTML documents, check the Frame and image loading check box.
    • To enable the execution of applets or ActiveX controls when rendering HTML documents, check the Applet execution check box.
  3. Specify how incoming and outgoing data should be displayed on the Out Header, Out Body, In Header, and In Body pages.
    • To view text-formatting symbols, such as \r\n for a carriage return and new line and "." for a white space, check the Show white spaces check box.

      This option is only relevant when viewing data in text format.

    • To view data in binary format, check the Show binary data check box.
  4. Click OK.
Parent topic: TrueLog Explorer Option Settings


Inserting Delimiter Characters

TrueLog Explorer general compare tags allow you to define delimiters, which are characters or text that delimit differences between TrueLogs. Delimiters determine if a sequence is handled as a single difference or as multiple differences. Delimiters are used for all document types except HTML.

  1. Choose Settings > Options and then click the Compare tags tab. The Compare tags page opens.
  2. In the General compare tags table, type character or text delimiters.
    Tip: Click Default to discard your changes and revert to the default settings.
  3. Click OK.
Parent topic: TrueLog Explorer Option Settings


Inserting HTML Delimiter Characters

HTML delimiters are characters or text that delimit differences between HTML TrueLogs. They determine if a sequence is handled as a single difference or as multiple differences.

  1. Choose Settings > Options and then click the Compare tags HTML tab. The Compare tags HTML page opens.
  2. In the HTML compare tags table, type character or text delimiters.
    Tip: Click Default to discard your changes and revert to the default settings.
  3. Click OK.
Parent topic: TrueLog Explorer Option Settings


Setting Workspace Options

  1. Click Settings > Options and the Workspace tab.
  2. To enable the automatic display of virtual user reports at the end of animated Try Script runs or when the root nodes of TrueLog files are selected in the tree, check the Display virtual user report check box.
  3. To automatically expand your XML trees by a specific number of levels, set the Auto expansion level of XML tree.
  4. To automatically expand your project tree by a specific number of levels, set the Auto expansion level of Log tree.
  5. To store the expansion levels of project trees and automatically apply them when reopening a TrueLog, check the Retain expansion state check box.
  6. Click OK.
Parent topic: TrueLog Explorer Option Settings


Customizing Toolbars and Commands

This section explains how to customize toolbars and the commands that display on toolbars.

  • Specifying Which Toolbars are Displayed
    You can customize the set of toolbars that appear on the TrueLog Explorer interface.
  • Creating a Custom Toolbar
    Add a custom toolbar to the TrueLog Explorer interface.
  • Customizing Toolbar Command Buttons
    You can define which command buttons display on specific toolbars.
Parent topic: Customizing TrueLog Explorer


Specifying Which Toolbars are Displayed

You can customize the set of toolbars that appear on the TrueLog Explorer interface.

  1. Choose Settings > Customize . The Toolbars page opens.
  2. Check the check boxes next to the toolbars that you want to have displayed.
  3. Optional: To specify that you want to enable tooltips (roll-over UI control descriptions), check the Show Tooltips check box.
  4. Optional: To specify that you want to enable TrueLog Explorer “cool look,” check the Cool Look check box.
    Cool look replaces Windows 3.1 style drop-shadow buttons with non-drop-shadow buttons.
  5. Click OK. Alternative: Click Apply to immediately apply your selections to the UI.
Parent topic: Customizing Toolbars and Commands


Creating a Custom Toolbar

  1. Choose Settings > Customize . The Toolbars page opens.
  2. Click the Toolbars tab.
  3. Click New. The New Toolbar dialog box opens.
  4. Enter a name for the toolbar and then click OK.
  5. Click OK.

Customize the command buttons that are displayed on the new toolbar.

Parent topic: Customizing Toolbars and Commands


Customizing Toolbar Command Buttons

You can define which command buttons display on specific toolbars.
Note: The Menu toolbar cannot be customized.
  1. Choose Settings > Customize . The Toolbars page opens.
  2. Click the Commands tab.
  3. In the Categories list box, select the toolbar for which you want to customize the command buttons.
  4. Click available commands in the Buttons box to read their descriptions in the Description box.
  5. Drag the commands that you want to include on the toolbar onto the toolbar name in the Categories list box.
  6. Click OK.
Parent topic: Customizing Toolbars and Commands


View Modes

You can view differences in TrueLogs using compare and difference modes. Compare mode enables the direct comparison of record and replay TrueLogs, one API node at a time. Differences mode automatically identifies and lists differences between record and replay TrueLogs for Web, XML, and database applications via the Differences page. Differences mode also displays differences in text-based format on the In Body, Out Body, In Header, Out Header, and BDL pages by rendering differing text in green and red.

  • Compare Mode
    Explains that in compare mode, replay TrueLogs are compared alongside the corresponding TrueLogs that were generated during application recording.
  • Difference Mode
    Explains that difference mode automatically lists the differences that are detected between record and replay TrueLogs.
Parent topic: Customizing TrueLog Explorer


Compare Mode

In compare mode, replay TrueLogs are compared alongside the corresponding TrueLogs that were generated during application recording. Default view displays replay TrueLogs (with a green triangle in the upper-left corner). Compare view displays record TrueLogs (with a red triangle in the upper-left corner).

TrueLogs are opened in compare view when a corresponding record TrueLog is open or when the Open in Compare View check box is checked on the Open dialog box.

Note: TrueLogs are automatically opened in compare mode when you execute Find Differences from the Workflow - Customize Session Handling dialog box.
  • Enabling Compare Mode
    Use compare mode to compare a replay TrueLog alongside a corresponding record TrueLog to analyze playback errors.
Parent topic: View Modes


Enabling Compare Mode

Use compare mode to compare a replay TrueLog alongside a corresponding record TrueLog to analyze playback errors. When you check the Open in Compare View check box on the Open dialog box, TrueLogs are opened in compare mode automatically. Otherwise, TrueLogs are opened in default view.

Note: Compare mode offers the option of having record and replay Source pages oriented vertically rather than horizontally. To compare Source pages vertically, choose View > Compare Vertically .
  1. Select a TrueLog in the TrueLog menu tree.
  2. Perform one of the following steps:
    • Click Compare Mode.
    • Choose View > Compare Mode .
Note: Multiple entry points and approaches are available for the comparison of TrueLogs.
Parent topic: Compare Mode


Difference Mode

Comparing TrueLogs that are generated during Try Script runs alongside the corresponding TrueLogs that were generated during application recording is an effective means of pinpointing problems in load testing scripts.

Difference tables, available from the Differences page, automatically list the differences that are detected between replay TrueLogs and corresponding record TrueLogs.

Difference mode, which is enabled by default, is a special kind of compare mode in which text differences in the In Body, Out Body, In Header, and Out Header pages are marked in color (red and green with a gray background).

  • Enabling Difference Mode
    Show text differences on the In Body, Out Body, In Header, and Out Header pages in color (red and green with gray background).
  • Viewing a Difference Table
    Automatically list the differences that are detected between replay TrueLogs and corresponding record TrueLogs.
Parent topic: View Modes


Enabling Difference Mode

Note that difference mode is enabled by default.

Perform one of the following steps:
  • Choose View > Diff Mode .
  • Click the Diff Mode icon.
Parent topic: Difference Mode


Viewing a Difference Table

Ensure that difference mode is enabled before you begin this task (difference mode is enabled by default).

  1. Open a pair of corresponding record and replay TrueLogs.
  2. Enable compare mode by choosing View > Compare Mode .
  3. Click the Differences tab. The differences that are detected between replay TrueLogs and corresponding record TrueLogs are listed automatically.
Parent topic: Difference Mode


Data Animation

When animation is enabled, content received from servers during virtual user execution is displayed in real time, as users would see it. In the case of Web application testing, this means that you can see page content loading (graphics, text, and embedded objects) as virtual users see it. Animation is enabled by default.

TrueLog animation is helpful when you execute a load test with TrueLog On Error enabled and you detect errors with individual users using the error count in Silk Performer Virtual User view in the Monitor window. You can view TrueLog On Error files immediately using the context menu within Virtual User view by clicking Explore TrueLog. However, this only works for virtual users that are running on the controller machine, as you do not have access to TrueLogs for remote agents during load tests.

Pausing, Resuming, and Stopping Animation

To pause or resume animation choose Animation > Pause Animation . Alternative: Press Ctrl+P on your keyboard.

To stop animation choose Animation > Abort Animation .

Parent topic: Customizing TrueLog Explorer


TrueLog Impact on Scalability

TrueLog generation is only useful in as much as it is adaptable to your load-testing environment. Therefore, memory and performance requirements must be kept to a minimum.

The two major factors affecting TrueLog scalability are:
  • Performance downgrade
  • Memory usage

Performance Downgrade

Performance downgrades related to TrueLog generation can range from 0% - 10%. This is because runtime keeps all relevant data in memory and attempts to keep necessary memory allocations to a minimum. Note that the performance impact of TrueLog On Error is negligible.

Memory Usage

In terms of scalability, there is a tremendous difference between TrueLog and TrueLog On Error. The TrueLog feature immediately writes each request and response to a TrueLog file. The formatting of the TrueLog file produces high internal CPU usage and a large amount of IO for the writing of the TrueLog file.

As a result, TrueLog generation is often not suitable for load testing.

Since TrueLogs can become large in size, you can configure Silk Performer to generate TrueLogs only when errors are encountered during testing. While systems run accurately, nothing is recorded. Such targeted TrueLog generation is known as TrueLog On Error and results in smaller, focused TrueLog files.

Memory requirements for TrueLog On Error are largely dependant on the BDL scripts that are utilized. Therefore, generic percentages can not be given, especially in cases where TrueLog On Error is configured to log complete transactions. Note that this applies only to TrueLog On Error files for which the non-default Store TrueLog for one transaction setting has been selected. In such cases, memory usage correlates with the number and size of requested Web pages included in transactions. With the default Store TrueLog based on content history setting, the length of transactions has no impact. Content histories usually do not exceed five Web pages, and these are the only pages that must be stored.

Parent topic: Customizing TrueLog Explorer


Custom Content Types and File Extensions

TrueLog Explorer supports custom handling of special content types and URL file extensions. You can add custom content-types and file extensions to some values in the Registry to change product behavior. The relevant settings can be found in the registry (HKEY_CURRENT_USER\Software\Silk\Silk TrueLog Explorer\15.5\).

The following four registry values exist, among others:
  • MaskContentTypes
  • MaskExtensions
  • SuppressContentTypes
  • SuppressExtensions

These values contain lists of content-types and file extensions that need special handling. The Mask* values apply to textual data, which can be rendered as plain text in HTML view. The Suppress* values apply to binary (non-text) data, which can not properly be rendered.

  • Suppressing File Download Dialog Boxes
    Explains how to adjust registry settings to suppress certain content types, such as unwanted dialog boxes.
Parent topic: Customizing TrueLog Explorer


Suppressing File Download Dialog Boxes

  1. In TrueLog Explorer, select the node where the file download dialog box opens.
  2. Click the In Header tab and examine the page.
  3. If the content-type seems unfamiliar, such as app/fireclick.x-hint.1, perform the following steps:
    1. Close TrueLog Explorer.
    2. Add the unfamiliar content-type to the MaskContentTypes value. Strings are separated by semicolons.
    3. Start TrueLog Explorer. Registry settings are only read upon startup.
    4. If the download box still opens, add the previous content-type to the SuppressContentTypes value. The File Download dialog box should no longer open.
  4. If the content-type seems okay, examine the URL.
    1. If you notice an extension other than .html, .js, .pl, .chtml, .jar, .class, or .vbs, close TrueLog Explorer and examine the In Body page to see whether the response body consists of textual or binary data.
    2. If you see textual data on the In Body page, add the URL file extension to the MaskExtensions value.
    3. If the data seems to be binary, add the file extension to the SuppressExtensions value. Extensions are separated by semicolons.
    4. Start TrueLog Explorer. Registry settings are only read upon startup.
Parent topic: Custom Content Types and File Extensions


TrueLog Generation Settings

Overview

TrueLogs are usually not enabled during load testing as they are CPU and I/O intensive. Typically, TrueLogs are enabled during script development/verification only. TrueLog On Error files are usually enabled during load testing as they are optimized for performance and have only a slight impact on CPU. TrueLog On Error files can be activated for large tests without major impact on replay performance, even when a moderate number of errors are anticipated.

Silk Performer’s generation of TrueLog On Error has a slight impact on scalability however. To keep this impact as low as possible, the Silk Performer TrueLog recording level can be adjusted in the following ways:
  • TrueLog length
  • Severity of incidents for which TrueLog is recorded
  • Inclusion of embedded objects

The TrueLog generation options detailed in the following sections can be configured by choosing Settings > Active Profile > Results > TrueLog within Silk Performer. This same page is also used to enable the generation of TrueLog On Error (.xlg) files for each virtual user in tests (using the TrueLog On Error files (.xlg) check box).

Length of TrueLogs

TrueLog On Error tracking can be configured to store complete transactions one transaction at a time, or in the case of Web applications, the five most recent pages of content history.

Generating TrueLog based on complete transactions - This setting tracks each erroneous transaction, rather than all relevant pages (content history). As memory consumption is dependent on the length of each transaction, use this option only when memory is of no concern or when transactions are short.

Generating TrueLog based on content history - This setting stores recent page history only, and drops non-relevant pages from memory. This approach makes memory consumption more predictable and manageable. Although, consumption is still dependent on the sizes of pages stored in memory.

Severity

You can define the severity of incidents that trigger the writing of TrueLog data to disk (initially stored in RAM) using the Generate TrueLog On Error for setting.

Embedded Objects

Log all embedded objects - TrueLogs contain the response bodies of all embedded objects. Even when request and response headers are no longer contained in the history, the content of embedded objects may still be displayed in the browser. This can be a matter of concern when a page does not request an image from a server because it is a cache hit or when the server responded with a 304 not modified error. To guarantee that all embedded objects are displayed, Silk Performer stores the contents of each embedded object in a global process-spanning cache.

Exclude cached embedded objects - When a global store for cached objects is not enabled, some images will not load. This setting provides a small gain in performance and requires less memory.

Exclude all embedded objects - When embedded object bodies are not logged at all, embedded objects do not load. This setting significantly reduces memory consumption. However, the visual information that is offered with this approach is greatly compromised.

In cases where TrueLog On Error information is recorded based on content history, the impact on memory usage per virtual user can be estimated based on sample tests. The numbers below were calculated based on sample tests run against well known Web sites, including Amazon.com and IBM.com.
Setting | Additional memory consumption
Exclude all embedded objects | 80%
Exclude cached embedded objects | 125%
Log all embedded objects | 130%
Note: The settings that require the least amount of memory (storing TrueLog data based on content history and excluding all embedded objects) are sufficient for logging all relevant data. However, the visual information they offer is greatly compromised.
Parent topic: Customizing TrueLog Explorer


TrueLog Tree Filter

The TrueLog tree filter allows you to hide nodes and make a tree short and clear. This can be especially helpful when you work with large TrueLog files. You may want to hide image nodes during session customization.

Note that a filter applies to a specific TrueLog. You can apply several filters with different settings to different TrueLogs. To enable and disable a filter, select a TrueLog in the tree and click Toggle Tree Filter on the Tree Filter toolbar. If this toolbar is not visible, enable it by clicking View > Toolbars and Docking Windows. When a filter is active, the keyword filtered displays beside the TrueLog root node and filter icons display beside the visible nodes.

To configure a TrueLog tree filter, click View > Configure Tree Filter or use the button on the toolbar. You can specify general settings and type-specific settings. Select a TrueLog type and click the check boxes to show and hide specific nodes.

You can apply the filter in two ways:

  • Apply filter: Applies the filter to the selected TrueLog. The filter settings are saved in a .view file, which is located in the same folder as the TrueLog file. When you move the TrueLog file, make sure to move the settings file as well.
  • Apply filter and save as default: Applies the filter and saves the settings as default. When you open another TrueLog of the same project and enable the filter, the default settings are applied. The default settings are saved in a .view file, which is located in the project folder.

In Compare Mode TrueLog Explorer shows two trees, one for the main view and one for the compare view. You can synchronize the filters in both trees by clicking View > Keep Tree Filters Synchronized.

Parent topic: Customizing TrueLog Explorer


Performance Explorer 21.0

Welcome to Performance Explorer 21.0.

Performance Explorer allows you to view measures obtained through real-time monitoring and to analyze results of completed load tests. A variety of tools and features enables exhaustive analysis, reporting, and processing of all captured data.

  • Getting Started
    Introduces Performance Explorer.
  • Results Analysis
    Gives an overview of how analyzing results works in Performance Explorer.
  • Reporting
    Lists the report types Performance Explorer provides and explains how to work with reports.
  • Real-Time Monitoring
    Gives an overview of how to monitor systems with Performance Explorer by creating and configuring charts that show the system performance in real-time.
  • Built-In Measures
    Describes what measures are and provides a list of measures and measure groups.
  • Command Line Parameters
    Introduces the parameters that you can execute from a command line interface.
  • Customizing Visualization
    Performance Explorer offers numerous possibilities to customize the appearance of charts, graphs, and reports.


Getting Started

  • Performance Explorer Overview
    Provides an overview of the two main capabilities of Performance Explorer: results analysis and real-time monitoring.
  • Terminology
    Declares important terms that are used in Performance Explorer and throughout the Performance Explorer Help.
  • Time Series Data Files
    Describes the types of time-series files.
  • Starting Performance Explorer
    Lists several ways to start Performance Explorer.
  • Tour of the UI
    Introduces the main sections of the Performance Explorer user interface.
Parent topic: Performance Explorer 21.0


Performance Explorer Overview

Performance Explorer offers two main capabilities:
  • Results Analysis
  • Real-Time Monitoring

Results Analysis

With the Results Analysis functionality of Performance Explorer, you can analyze the results of a completed load test by creating charts, tables, and reports. With charts, you can visualize the data that was collected during the load test, and reports as well as tables help you to summarize important data and findings. The basis for all charts, tables, and reports is the data in the .tsd files. During each load test, Silk Performer captures a big amount of data and stores it in several time-series data (.tsd) files. When a load test is completed, you can load the data (the .tsd files) in Performance Explorer and visualize and edit them according to your requirements. All charts are fully customizable, and they can contain as many measures as required. You can open multiple charts using measures from one or multiple tests to show similarities and differences. Performance Explorer provides a variety of templates for charts, tables, and reports. Furthermore, you can place information on client and server performance in a single chart, so that you can directly view the effect of server performance on client behavior. By saving your changes as a template, you can reuse your individual settings.

Real-Time Monitoring

With the Real-Time Monitoring functionality of Performance Explorer, you can monitor a broad range of systems by creating and configuring charts that show the system performance in real-time. It is possible to open multiple charts at the same time, which allows you to watch the performance of two or more systems simultaneously, for example the web server performance and the operating system performance. Adding measures to a chart is easy and intuitive in Performance Explorer: You can drag a single measure or a set of measures from the tree onto the chart.

Parent topic: Getting Started


Terminology

The following terms are used in Performance Explorer and throughout the Performance Explorer Help. To avoid misconceptions and to keep explanations clear and straightforward, these terms are declared here.
Term | Description
Chart | A chart is the drawing area, where measures are visually represented as graphs. A chart can also be described as the sum of all displayed graphs
Graph | A graph is a graphical representation of a measure. When you drag a measure onto a chart, it appears as a graph with a particular color, style, and width.
Series | A series is a sequence of values of a certain measure. For example: The measure Active users has the values 2, 4, 6, 8. This sequence of values is a series.
Measure | A measure is the smallest grouping entity for the values that are collected during a load test or during a monitoring session for a particular measuring point. A measure has a name and type. A set of measured values that are related to the measure is stored as a series in a time series data (.tsd) file. For example: Requests sent or Trans. (busy) ok[s] are measures.
Report | In a report, you can summarize particular results and important findings of a load test. A report consists of tables and charts with descriptive text. In Performance Explorer you can create these kinds of reports: html overview reports, word overview reports, and comparison reports (region, user type, and custom comparison reports).
Table | A table shows the data that was collected during a load test or during a monitoring session in a tabular form.
Monitor Chart | A monitor chart displays graphs that are updated in real-time. The dynamic monitor charts are used for monitoring sessions, while static charts are used for the results analysis of a completed load test.
Monitor Writer | A monitor writer is a graphical and textual summary of a monitoring session.
System | A system is a machine, technology, or application that can be monitored. Performance Explorer supports a broad range of systems for monitoring.
Parent topic: Getting Started


Time Series Data Files

TSD File | Naming | Description
User File | u@<...>.tsd | A user file contains the time series data from one virtual user. During a load test, user files are generated on the agents.
Agent File | a@<...>.tsd | An agent file contains the time series data from one agent. During a load test, agent files are generated on the agents.
Intermediate File | i@<...>.tsd | An intermediate file contains all time series data from one agent including the time series data from all virtual users running on that agent. When the load test is complete, intermediate files are generated on the agents by merging the user files and the agent files together. When merged, the intermediate files are transferred to the controller.
Merged File | m@<...>.tsd | A merged file contains the time series data from all agents. It is generated on the controller by merging the intermediate files together. The merged file can be described as the master file, which holds all the time series data of a load test.
Agent File per User Type | t@<...>.tsd | An agent file per user type contains the time series data from one user type of one agent. Do not confuse it with a user file. Several virtual users can be assigned to one user type. Therefore, the agent file per user type usually holds the time series data from several user files. When the load test is complete, the agent files per user type are generated on the agents by merging user files with the same user type together. When merged, the agent files per user type are transferred to the controller.
Merged File per User Type | k@<...>.tsd | A merged file per user type contains the time series data from one user type of all agents. It is generated on the controller by merging the agent files with the same user type together.
Region File | n@<...>.tsd | A region file contains the time series data from one cloud region. It is generated on the controller by merging the intermediate files of cloud agents of the same region together.
Real-Time File | r@<...>.tsd | A real-time file contains the time series data that is collected and calculated during server-side monitoring.

Parent topic: Getting Started


Starting Performance Explorer

Before you start working with Silk Performer, make sure that you know how your application is set up and deployed. For example, find out which of your machines powers the database and application servers.

Here are some ways to start Performance Explorer:
  • From the Windows start menu: ClickStart > Programs > Silk > Silk Performer <version> > Analysis Tools > Silk Performance Explorer.
  • From Silk Performer: Click Results > Monitor Server.
  • From Silk Performer: Click Results > Explore Time Series.
  • From Silk Performer: Click Tools > Silk Performance Explorer.
  • From a command-line tool.

When editing a new template or launching Performance Explorer from the Silk Performer results menu, the program opens with several predefined monitor graphs and a predefined data source (your local machine).

Parent topic: Getting Started


Tour of the UI

These are the main sections of the Performance Explorer user interface:

Tour of the UI

(1) Ribbon

The ribbon in Performance Explorer contains 4 permanent tabs and 2 contextual tabs. While the permanent tabs are always visible, the contextual tabs are only visible if a chart or a report is open and active. These are the permanent tabs:

  • Results: This tab contains all commands around displaying and analyzing results.
  • Reports: This tab contains all commands around creating and working with reports.
  • Real-Time Monitoring: This tab contains all commands around the real-time monitoring functionality of Performance Explorer.
  • Window: This tab contains several window commands, like tiling or cascading windows, resetting the layout, and so on.

These are the contextual tabs:

  • Chart: This tab is visible when a chart is active. It contains all commands that control the appearance of charts and graphs.
  • Series: This tab is visible when a chart is active. It contains all commands that control the appearance of series.

(2) Chart/Report

In this area the charts and reports are displayed. You can easily drag measures from the tree onto a chart. By using the commands in the contextual tabs, you can adjust the appearance of charts, graphs, and reports. For example: In a chart, you can change colors, line width, line styles, enable scaling, display markers, null values, measure bounds, and so on.

(3) Tree

The tree area consists of the following four trees (the tree tabs display on the bottom of the tree area): The Explore tree shows the measures of a load test or single .tsd file. The Monitor tree shows the measures of the system that is to be monitored. The Silk Central tree shows the measures of a load test that is managed and invoked through Silk Central. The Client-Side-Measures tree shows client-side measures.

You can drag measures from the tree onto a chart. You can double-click the white-space in the tree to add a load test or a system.

(4) Measure List

The measure list is visible when a chart is open and active. It lists all measure that display in the chart. You can click the check boxes to turn the measures in the chart on and off. The list also supports multi-select functionality, so switching on and off several or all measures concurrently is possible.

(5) Log Window

The log window lists all events that occur during performance monitoring, including errors and query states. You can switch the log window on and off in the Window tab and you can right-click in the log window and copy or clear the log.

Parent topic: Getting Started


Results Analysis

With the Results Analysis functionality of Performance Explorer, you can analyze the results of a completed load test by creating charts, tables, and reports. With charts, you can visualize the data that was collected during the load test, and reports as well as tables help you to summarize important data and findings. The basis for all charts, tables, and reports is the data in the .tsd files. During each load test, Silk Performer captures a big amount of data and stores it in several time-series data (.tsd) files. When a load test is completed, you can load the data (the .tsd files) in Performance Explorer and visualize and edit them according to your requirements. All charts are fully customizable, and they can contain as many measures as required. You can open multiple charts using measures from one or multiple tests to show similarities and differences. Performance Explorer provides a variety of templates for charts, tables, and reports. Furthermore, you can place information on client and server performance in a single chart, so that you can directly view the effect of server performance on client behavior. By saving your changes as a template, you can reuse your individual settings.

Although there is no particular workflow in Performance Explorer, users usually follow this progression of steps:
  • Adding: Add results to the Performance Explorer workspace.
  • Visualizing: Create charts, tables, and reports based on the loaded results.
  • Analyzing: Analyze the results (by analyzing errors, comparing graphs, finding root causes).
  • Processing: Resample or merge the results and export the data.
  • Adding Results
    Describes various ways to add results to Performance Explorer.
  • Visualizing Results
    Describes how to visualize results in Performance Explorer with the help of charts, tables, and reports.
  • Analyzing Results
    Lists the features that allow you to analyze the results of load tests.
  • Processing Results
    Describes the following possibilities to process results in Performance Explorer: resampling, merging, and exporting.
  • Viewing Results
    Results can be converted to HTML documents and viewed in a web browser.
Parent topic: Performance Explorer 21.0


Adding Results

Before you can start visualizing, analyzing, and processing results, you have to add them to Performance Explorer. A typical way is to directly open the results from Silk Performer, by clicking the charts or buttons on the Load Test Summary page.

However, you can also start with a blank Performance Explorer workspace and ...
  • add all results of a specified load test
  • import results from Silk Central
  • add single .tsd files
  • Adding Load Test Results
    Describes how to add load test results to Performance Explorer.
  • Adding Results from Silk Central
    Describes how to import load test results from Silk Central in Performance Explorer.
  • Adding Single Result Files
    Describes how to add single result files (.tsd files) to Performance Explorer.
Parent topic: Results Analysis


Adding Load Test Results

If you want to add the results of a load test, specify a results folder and all .tsd files are added to the Performance Explorer workspace.
  1. Open Performance Explorer.
  2. In the Results tab, in the Add group, click Load Test Results.
  3. Specify a project directory and a load test and click Add.
The added results appear in the Explore tree.
Tip: You can also double-click the white space in the tree to add results, or you right-click in the tree and use the commands in the context-menu.
Parent topic: Adding Results


Adding Results from Silk Central

You can import results from Silk Central (as described below) or you can start Performance Explorer directly from Silk Central.
  1. Open Performance Explorer.
  2. In the Results tab, in the Add group, click From Silk Central.
  3. Follow the wizard to add result files to the workspace.
The added results appear in the Silk Central tree.
Tip: You can also double-click the white space in the tree to add results, or you right-click in the tree and use the commands in the context-menu.
Parent topic: Adding Results


Adding Single Result Files

You can choose single .tsd files (even from different load tests) and add them to the Performance Explorer workspace.
  1. Open Performance Explorer.
  2. In the Results tab, in the Add group, click Result Files.
  3. Follow the wizard to add result files to the workspace.
The added results appear in the Explore tree.
Tip: You can also double-click the white space in the tree to add results, or you right-click in the tree and use the commands in the context-menu.
Parent topic: Adding Results


Visualizing Results

When you have added results to the Performance Explorer workspace, you can visualize them with the help of charts, tables, and reports.

  • Creating Charts
    Describes how to create charts in Performance Explorer.
  • Creating Tables
    Describes how to create tables in Performance Explorer.
  • Creating Reports
    Describes how to create reports in Performance Explorer.
Parent topic: Results Analysis


Creating Charts

  1. Open Performance Explorer.
  2. In the Results tab, in the New group, click Chart to create an empty chart.
  3. Select a .tsd file in the dialog. This dialog only appears if you have not yet added results to the workspace.
  4. Drag measures from the tree onto the chart.
Tip: You can also click the Chart drop-down arrow and click Predefined Chart to create a chart from a template or click Empty VUser-based Chart to create an empty chart, which shows the number of virtual users on the x-axis.
Parent topic: Visualizing Results


Creating Tables

  1. Open Performance Explorer.
  2. In the Results tab, in the New group, click Table to create an empty table.
  3. Select a .tsd file in the dialog. This dialog only appears if you have not yet added results to the workspace.
  4. Drag measures from the tree onto the table.
Tip: You can also click the Table drop-down arrow and click Predefined Table to create a table from a template.
Parent topic: Visualizing Results


Creating Reports

  1. Open Performance Explorer and add results to the workspace.
  2. In the Reports tab, in the Overview Report and Comparison Report groups, click one of the following buttons:
    • Word
    • HTML
    • Region
    • User Type
    • Custom
For more information on the various reports, see the respective topics in the Reporting section.
Parent topic: Visualizing Results


Analyzing Results

Performance Explorer provides a number of features that allow you to analyze the results of a load test. You can perform a comprehensive error analysis with the Analyze Errors feature, you can compare measures from various load tests with the feature Compare Graphs, and you can use the Find Root Cause capability.

  • Analyzing Errors
    Display all errors in a graphical format and drill down to find detailed information.
  • Error Analysis Graph
    Describes the information displayed in the Error Analysis graph
  • Analyzing Root Causes
    Correlate client and server-side measurements to better identify server-side problems.
  • Comparing Graphs
    Describes how to use the Compare Graph feature of Performance Explorer.
Parent topic: Results Analysis


Analyzing Errors

Performance Explorer includes a feature that assists you in analyzing the errors that occur during load tests. While the overview report displays some error information, the Analyze Errors feature displays all errors in a comprehensive error chart and lists detailed information.

Before you follow the steps below, configure and execute a load test in Silk Performer.

  1. When your load test is completed, the Load Test Summary page displays. Click Analyze errors in the Next Steps area. Performance Explorer opens and displays the error chart.
  2. You can also click the Load Test Results chart or you click Analyze Load Test in the Next Steps area. Performance Explorer opens. Then, on the Results tab, in the Analyze group, click Analyze Errors. An error chart opens. You can zoom into the chart to drill down to the specific information you need.
Tip: You can also start with a blank Performance Explorer workspace. On the Results tab, in the Analyze group, click Analyze Errors and specify a .tsd file.
Parent topic: Analyzing Results


Error Analysis Graph

The Error Analysis graph contains the following information:
View | Description
Error Groups | The Error Groups pane displays group information for all the errors that occurred during the analyzed load test. Use the zoom and shift features to view information for specific time frames.
Error Details | The Error Details pane list all occurrences of errors in the selected time span. Double-click an error or right-click an error and select Show TrueLog to invoke TrueLog Explorer with the respective TrueLog file that contains visualized information for the error occurrence to help you find the root cause of the selected error.
Legend | The Legend pane lists the displayed curves of the chart, which by default is only the error summary of the error analysis. It also displays more detailed information about occurrences, minimum and maximum values, and so on. Hold your cursor over the graph to see the number of error occurrences for a specific time frame. The Value column updates as you move your cursor over the graph.
Parent topic: Analyzing Results


Analyzing Root Causes

Before you perform this task, specify the time-series data (TSD) file that is to be used as the data source for the graph.

Performance Explorer’s automatic result-correlation feature facilitates root-cause analysis of network and server bottlenecks by correlating client-side issues with corresponding server-side measurements. Automatic result correlation identifies the server-side measurements that are most closely associated with specific client-side errors, thereby enabling you to better identify server-side problems and expedite debugging efforts. Result correlation also works in the reverse: Server-side issues can be correlated with client-side measures.

Automatic result correlation statistically correlates key measures with dependent measures. For example, if a significant increase in server response time is detected by a client-side measure at 18:20 (6:20 p.m.), automatic result correlation can identify the server-side measures that contributed to this drop in client-side performance.

  1. Click within the measurement graph that you want to analyze and drag your cursor to the right to select the time frame to analyze.
    Note: To slide the time line forward or backward in time, right-click the time line and drag your mouse right or left. The time line can also be moved vertically along its Y axis.
    Note: To select a shorter period of time for analysis, drag the time line to the right. To select a longer period of time for analysis, drag the time line to the left.
  2. Click Find Root Cause on the workflow bar. Alternative: Right-click in the graph and choose Root Cause Analysis. The Find Root Cause - Correlation Settings dialog box opens. The base measure appears in the Base Measure box.
  3. From the Correlate with list box, select the type of measurement you want to correlate with the base measurement.
  4. Adjust the date- and time-selection settings by selecting a new start date, start time, end date, or end time from the appropriate list box. Date and time selection settings are defined automatically based on the time frame selected in the time line.
  5. In the Results area, specify how to filter measure results based on how well they match. Choose one of the following options:
    • Click the Best [x] correlation numbers option button and specify the number of measures to be returned in the text box.
    • Click the Minimum correlation of [x]% option button and specify a minimum correlation relevance by typing a value in the text box.
  6. Click Next.
    Note: If you are correlating against client and server measures, client measures, or server measures, advance to step 10.
    The Correlation Measures Properties page opens.
  7. When correlating against a custom measure, you must define which measure groups are to be correlated. Select the groups you want to correlate against by checking the Measures check boxes.
  8. Optional: Add other measures by clicking Add File and browsing to and selecting a time-series data file. You can also remove measures by selecting them and clicking Remove File.
  9. Click Next to run the correlation. The Correlation Results page opens.

    By default, returned measures are listed in order of degree of correlation, and all correlations are selected.

  10. Click the Correlation Group and Name column headers to sort returned measures.
  11. Uncheck the check boxes for the measures that you do not want to include in the correlation graph.
  12. Click Finish to generate the correlation graph.
Parent topic: Analyzing Results


Comparing Graphs

When you have created and customized a chart with measures of interest, you might want to compare these measures with measures from a different user type, from different agents, different regions, or from a different load test. Performance Explorer provides the Compare Graph feature for this purpose. When you click Compare Graph, Performance Explorer creates a new chart with the selected measure and automatically adds the ones you want them to compare with.

  1. Create a new chart: On the Results tab, in the New group, click Chart.
  2. If you have not already loaded result files into Performance Explorer, select a .tsd file in the dialog.
  3. Drag the measures of your interest from the tree onto the graph.
  4. On the Results tab, in the Analyze group, click the drop-down arrow below Compare Graph and select one of the following options:
    • With other User Types: Creates a new chart with the selected measures from the active chart and adds the same measures from all user types.
    • With other Agents: Creates a new chart with the selected measures from the active chart and adds the same measures from all agents.
    • With other Regions: Creates a new chart with the selected measures from the active chart and adds the same measures from all regions.
    • With other TSD File: Creates a new chart with the selected measures from the active chart and adds the same measures from a different .tsd file.
  5. If you chose to compare graphs with another .tsd file, Performance Explorer prompts you to select the .tsd file.
Parent topic: Analyzing Results


Processing Results

With Performance Explorer, you can process results in various ways:
  • You can resample results by changing the interval and redefining the time frame.
  • You can merge the results of two or more load tests.
  • You can export results to process them in third-party tools like spreadsheet programs.
  • Resampling Load Test Results
    Resample the result files of a load test by changing the interval and redefining the time frame.
  • Resampling Single Result Files
    Resample a result file by changing the interval and redefining the time frame.
  • Merging Load Test Results
    Merge the results of two or more load tests (from the same project) into one result folder. This allows you to analyze all results in a single report.
  • Merging Single Result Files
    Manually merge files together when the controller loses contact with agents.
  • Exporting TSD Files As CSV Files
    Describes how to specify all necessary settings to export the content of a .tsd file to a .csv file.
  • Using the TSD File Export Tool
    The TSD File Export Tool is a command-line tool that allows you to automate exporting the content of .tsd files to .csv files.
Parent topic: Results Analysis


Resampling Load Test Results

Specify a load test results folder and resample the data of the containing .tsd files by changing the interval and redefining the time frame.

  1. On the Results tab, in the Data Processing group, click Resample Load Test Results.
  2. Specify the Source directory of the load test that contains the .tsd files that are to be resampled. Specify the name of the Target folder and click Next.
  3. Specify an Output interval. For longer running load tests, an increased output interval is useful because it results in a smaller target file.
  4. Choose one of the following merge types:
    • Click Relative to specify that all series start at the same time.
    • Click Absolute to consider the individual start time of each series.

      If you merge files from different load tests, the start times of those files are different, so use the Relative merge type.

      If you click Absolute, you can specify a time frame. Only data within this time frame is merged into the target file.

  5. Adjust the date and time settings by selecting a new start date/time and end date/time. Date and time settings are defined automatically based on the time frame selected in the time line.
  6. Click Next or Finish to start the resampling process.
Parent topic: Processing Results


Resampling Single Result Files

Specify a result file and resample the containing data by changing the interval and redefining the time frame. Increasing the output interval is useful to make result files smaller in size and to smoothen the corresponding graphs.

  1. On the Results tab, in the Data Processing group, click Resample Single Result File.
  2. Specify the Source file. This is the .tsd file that is to be resampled. Specify the name of the Destination file and click Next. The format of the destination file will be m@@<sourcefilename>_r.tsd
  3. Specify an Output interval. For longer running load tests, an increased output interval is useful because it results in a smaller target file.
  4. Choose one of the following merge types:
    • Click Relative to specify that all series start at the same time.
    • Click Absolute to consider the individual start time of each series.

      If you merge files from different load tests, the start times of those files are different, so use the Relative merge type.

      If you click Absolute, you can specify a time frame. Only data within this time frame is merged into the target file.

  5. Adjust the date and time settings by selecting a new start date/time and end date/time. Date and time settings are defined automatically based on the time frame selected in the time line.
  6. Click Next or Finish to start the resampling process.
Parent topic: Processing Results


Merging Load Test Results

To run a big load test, it can be necessary to start the load test from multiple controllers. Consequently, Silk Performer will generate multiple result folders - one folder per controller. Use the Merge Results feature to merge the results into one result folder. This allows you to view all metrics in a single comprehensive report.

Note: Results from different projects cannot be merged.
  1. On the Results tab, in the Data Processing group, click Merge Results.
  2. Drag two or more load test result folders from a file explorer onto the table or click Add to browse for result folders.
  3. Specify a master load test in the Master column. Some values from the result files cannot be merged (like the project description). In such a case, Performance Explorer will use the value of the master load test.
  4. Select a Merge type:
    • absolute: In a report, the results will display with their actual start time on the time line. For example: If you started a load test on Controller B 10 seconds after you started the load test on Controller A, the results will display on the time line accordingly.
    • relative: In a report, all results will display with the same start time on the time line, regardless of the actual start times of the load tests.
  5. Specify an Interval for the merged .tsd files. The minimum interval (shown in the Interval list) is the lowest common multiple of the intervals from all .tsd files that are located in the specified results folders.
  6. Specify a Target folder. The merged results will be stored in this folder.
  7. Click Merge.
When the results are merged successfully, Performance Explorer displays an overview report. This newly created report has the workload type Merged Workload, which contains all executed usergroups.
Parent topic: Processing Results


Merging Single Result Files

Merging single result files is useful in the following situations:
  • You want to create a custom .tsd file based on selected source .tsd files.
  • You want to recreate the merged .tsd file (m@...tsd) to include results from agents that have lost connection during a load test. If the controller-agent connection fails, agent files reside on the agent in the local results directory. Depending on when the connection is lost, you might find either user-only or merged agent files. If you want these results included in the intermediate file of your load-test controller, you must manually merge the files.
  1. If necessary, copy all files you want to merge into a single directory.
  2. Choose Wizard > Custom Merge Wizard . The Custom Merge Wizard opens.
  3. Select the directory where all the files are stored and select all the files to merge.
  4. Click Finish.
A new, merged file containing all the data is generated.
Note: Make sure to not select .tsd files with the same or dependent data. For example: Merging User Type .tsd files and merged User Type .tsd files results in multiple aggregation of the same series, which usually is not a reasonable scenario.
Parent topic: Processing Results


Exporting TSD Files As CSV Files

With the TSD to CSV feature, you can export the content of a .tsd (time series data) file to a .csv (comma separated values) file. You can then analyze and edit the data in an external spreadsheet program.

You can also use the TSD File Export Tool, a command-line tool that allows you to automate the export process.

  1. On the Results tab, in the Data Processing group, click TSD to CSV.
  2. Select a Source file, specify a name and location for your Export file, and click Next.
  3. Select the measures you want to export and click Next.
  4. Select an Export type:
    • Click Standard and specify the data source elements of the result file that must be included in the .csv file.
    • Click Dump to include all meta data in the .csv file.
  5. You can Include header information in the .csv file. Select the comma or the semicolon as your separator and select how a decimal point is to be displayed in the .csv file.
  6. Click Finish to export the data and generate the .csv file.
  7. To view the output file, click Yes on the subsequent dialog.
Parent topic: Processing Results


Using the TSD File Export Tool

The TSD File Export Tool is a command-line tool that allows you to automate exporting the content of .tsd files to .csv files. You can also use the TSD to CSV feature in Performance Explorer, which provides a user interface for the export settings.

  1. Open the tool from the Microsoft Windows start menu: Start > Programs > Silk > Silk Performer <version> > Analysis Tools > TSD File Export Tool.
  2. At the command prompt, enter specifications for the file export based on the following syntax:
    Tsd2Csv tsdFile [csvFile] [-Delimiter char] [-DecimalPoint
                char] [-dump]
    Command | Description
    tsdFiles | Enter the path and name of the .tsd file that is to be exported.
    [csvFile] | Enter the path and name of the .csv file that is to be created.
    [-Delimiter char] | Define the delimiter character.
    [-DecimalPoint char] | Define the character that signifies decimal points in the output file.
    [-dump] | Ignores -DecimalPoint parameter.
  3. Press Enter to generate the .csv file.

Example

Tsd2Csv "input.tsd" "output.csv" -Delimiter "," -DecimalPoint "."
Parent topic: Processing Results


Viewing Results

Performance Explorer can convert charts, reports, and tables into HTML documents and display these in a web browser. This enables you to include charts, reports, and tables in any kind of documents, publish them online, or print them in useful formats.

  • Viewing Charts in a Web Browser
    View a chart in a web browser to prepare it for publication on the web.
  • Viewing Reports and Tables in a Web Browser
    View an HTML overview report or table in a web browser to prepare it for publication on the web.
  • Exporting Charts
    Export a chart or chart data to use it in external programs or to publish or send it through email.
  • Exporting Reports and Tables
    Export reports or tables to use it in external programs or to publish or send it through email.
  • Exporting Reports Through the Command-Line Interface
    Export reports through the command-line interface to ease access to the reports.
Parent topic: Results Analysis


Viewing Charts in a Web Browser

Create or open the graph that you want to view in a Web browser.

  1. Create or open the chart that you want to view in a web browser.
  2. On the Chart tab, in the Data group, click View in Browser.
  3. Enter a Caption and a Description for the chart and click OK. The caption and description display in the browser above the chart.
Parent topic: Viewing Results


Viewing Reports and Tables in a Web Browser

Create or open the report that you want to view in a Web browser.

  1. Create or open the HTML overview report or table that you want to view in a web browser.
  2. On the Reports tab, in the Tasks group, click Open in Browser.
  3. Enter a Caption and a Description for the report or table and click OK. The caption and description display in the browser above the chart.
Parent topic: Viewing Results


Exporting Charts

You can export charts in various formats to present them to an audience that has not access to Performance Explorer.

  1. Create or open the chart that you want to export.
  2. On the Chart tab, in the Chart group, click the drop-down arrow below Export.
    • Click CSV File to export the chart data to a .csv file. On the subsequent dialog, you can select from a range of file formats, like .htm, .mht, or .jpg. The .csv format is the default value.
    • Click Excel Document to export the chart data to a Microsoft Excel document. A chart is automatically created in Excel.
Tip: The .mht format allows you to easily send charts through email. The .html format allows you to publish charts on the web. The .csv format allows you to further process data in external spreadsheet programs. The picture formats allow you to insert charts as pictures in other documents.
Parent topic: Viewing Results


Exporting Reports and Tables

You can export reports and tables in various formats to present them to an audience that has not access to Performance Explorer.

  1. Create or open the report or table that you want to export.
  2. On the Reports tab, in the Tasks group, click Save as.
  3. On the subsequent dialog, select a directory, enter a file name, select a file format, and click Save.
Tip: The .mht format allows you to easily send reports or tables through email. The .html format allows you to publish reports or tables on the web. The .csv format allows you to further process data in external spreadsheet programs.
Tip: You can also export reports through the command line interface. This allows you to automate the export process.
Parent topic: Viewing Results


Exporting Reports Through the Command-Line Interface

HTML reports can also be exported as Web archives (MHT files) through the command-line interface. To export reports, use the command-line parameter /EXPORTOVR:<target file>.

This parameter saves the active OVR as HTML or as an MHT file, depending on the file extension of the target file specification.

Note: The last loaded TSD file, or the last TSD file specified through the command line (/TSD:<tsd file>) is used for exporting.

The command-line parameter /ACTION:OVERVIEWREPORT[:<template>] allows you to specify a template file for the report.

The following example illustrates exporting a Web archive file through the command line:

/TSD:<tsdFile> /ACTION:OVERVIEWREPORT /EXPORTOVR:c:\test.mht

Parent topic: Viewing Results


Reporting

Creating reports is one possibility to summarize and analyze the data that was collected during a load test. Learn about the report types Performance Explorer provides and how to create and work with reports.

  • Word Overview Reports
    Word overview reports display important load test result information in a Microsoft Word document.
  • HTML Overview Reports
    HTML overview reports display important load test result information.
  • Comparison Reports
    Lists the three types of comparison reports Performance Explorer provides.
Parent topic: Performance Explorer 21.0


Word Overview Reports

Performance Explorer allows you to view your load test results in a Microsoft Word document. This is especially useful if you want to further process your results for presentation and add custom formatting.

  • Creating Word Overview Reports
    Describes the possibilities to create and view Word overview reports.
  • Creating a Template for Word Overview Reports
    Describes how to create a template that you can use when creating Word overview reports.
Parent topic: Reporting


Creating Word Overview Reports

  1. Add load test results to the Performance Explorer workspace
  2. In the Reports tab, in the Overview Report group, click one of the following buttons:
    • Click Word or Word Overview Report to show the results in a Word document.
    • Click Word Overview Report from Template, select a .docx file and click Create.
    • Click Custom Word Overview Report, select the information that the Word overview report shall contain, and click Create.
Note: You can enable Use template for all future reports to always create Word overview reports based on a template. To disable this option, click the Performance Explorer application button (on the top left) and click Options. Click the Reporting tab and disable Use template (.docx) when creating a new Word Overview Report.
Parent topic: Word Overview Reports


Creating a Template for Word Overview Reports

Before you can save and use a template, create a Word overview report with all the information you want to have in the report.

  1. On the Reports tab, in the Overview Report group, click Custom Word Overview Report.
  2. Select the information that the template shall contain and click Create. Microsoft Word opens and the specified information displays.
  3. Adapt the content and the appearance of the Word document to your needs. You can add information and comments, rearrange fields, change element styles, change the header, footer, or logo, remove unwanted content, and so on.
  4. Save the Word document as .docx file and close it. Your template is created.
  5. Switch back to Performance Explorer. On the Reports tab, in the Overview Report group, click Word Overview Report from Template.
  6. Browse for the .docx file you have just defined and click Create.
Note: You can enable Use template for all future reports to always create Word overview reports based on a template. To disable this option, click the Performance Explorer application button (on the top left) and click Options. Click the Reporting tab and disable Use template (.docx) when creating a new Word Overview Report.
Parent topic: Word Overview Reports


HTML Overview Reports

When a load test completes, the Load Test Summary page displays in Silk Performer and an overview report is generated automatically. In Silk Performer, you can find the overview report in the Results tree. To open the overview report in Performance Explorer, double-click the report in the tree or click Analyze load test on the Load Test Summary page. You can also open a blank Performance Explorer workspace and click HTML in the Overview Report group on the Reports tab.

  • Creating HTML Overview Reports
    Describes how to create and view an HTML overview report after a load test has completed.
  • Creating a Template for HTML Overview Reports
    Describes how to create a template that you can use when creating HTML Overview Reports.
  • Assigning Overview Report Templates to Projects
    Specify an overview report template for your Silk Performer project. The template will be used for automatic and manual generation of HTML overview reports.
Parent topic: Reporting


Creating HTML Overview Reports

Before you follow the steps below, configure a load test in Silk Performer and execute it. When your load test is completed, the Load Test Summary page displays. Perform one of the following steps:

  • Click Analyze load test in the Next Steps area.
  • Click Results on the bottom of the tree, expand a load test node, and double-click Overview Report.

Performance Explorer opens and the overview report displays.

To open an HTML overview report out of Performance Explorer, perform the following steps:

  1. Add load test results to the Performance Explorer workspace
  2. In the Reports tab, in the Overview Report group, click one of the following buttons:
    • Click HTML or HTML Overview Report to show the results in an HTML overview report.
    • Click HTML Overview Report from Template, select an .ovt file (overview report template) and click Create.
    • Click Custom HTML Overview Report, select the information that the HTML overview report shall contain, and click Create.
Note: You can enable Use template for all future reports to always create HTML overview reports based on a template. To disable this option, click the Performance Explorer application button (on the top left) and click Options. Click the Reporting tab and disable Use template (.ovt) when creating a new HTML Overview Report.
Note: By default, overview reports are generated automatically. To disable the automatic generation, click the Performance Explorer application button (on the top left), click Options, click the Reporting tab and disable Generate Overview Reports automatically.
Parent topic: HTML Overview Reports


Creating a Template for HTML Overview Reports

Templates for HTML Overview Reports are saved as .ovt files.
  1. In Performance Explorer, create or open an HTML Overview Report.
  2. On the Reports tab, in the Overview Report group, click Customize.
  3. Select the information that the template shall contain and click Customize.
  4. On the Reports tab, in the Overview Report group, click Save As Template.
  5. Save the template as .ovt file (overview report template).
Note: You can instruct Performance Explorer to always use this template when an HTML Overview Report is created: Click the Performance Explorer application button (on the top left) and click Options. Click the Reporting tab, enable Use template (.ovt) when creating a new HTML Overview Report and specify the file.
Parent topic: HTML Overview Reports


Comparison Reports

Performance Explorer provides three types of comparison reports:
  • region comparison reports
  • user type comparison reports
  • custom comparison reports

A comparison report allows you to compare the results of up to eight test executions side by side. Its structure resembles the structure of a standard baseline report: Comparison reports contain summaries and statistics regarding transactions, errors, page and action timers, web forms, rankings, and many other measures.

At the bottom of a comparison report, the Baseline Pane displays. This pane includes a column with either the name of a specific region or user type, or a column named Overall if the row contains all test results. The Agents column displays the number of agents that were used for the test in each specified region.

Any test result can be defined as the baseline. All other results will use this baseline as reference and they will be compared to the baseline. In report rankings, the baseline result is always listed first. A b icon or baseline tag identifies the baseline result. All measures that are evaluated against the baseline are identified with heat fields (colored bars in the report). Move your cursor over any heat field to view detailed information. To set a result as the baseline, right-click it and click Set as baseline.

  • Region Comparison Reports
    Region comparison reports allow you to compare the results of cloud-based load tests by displaying the results of cloud regions side by side.
  • User Type Comparison Reports
    User type comparison reports allow you to compare user types side by side.
  • Custom Comparison Reports
    Custom comparison reports allow you to compare the results of up to eight test executions side by side.
  • Creating Region Comparison Reports
    Describes a typical process of creating a region comparison report and setting a baseline.
  • Creating User Type Comparison Reports
    Describes a typical process of creating a user type comparison report and setting a baseline.
  • Creating Custom Comparison Reports
    Describes a typical process of creating a custom comparison report.
Parent topic: Reporting


Region Comparison Reports

Region comparison reports allow you to compare the results of cloud-based load tests. These are load tests that use cloud agents to generate load. You can compare the results from different regions side by side. The report shows one region per column. A maximum of eight regions can be included in a single region comparison report.

Both overall results and region-specific results can be compared. To add measures, drag them from the tree onto the report. To add the overall results, drag the Overall node onto the report.

Parent topic: Comparison Reports


User Type Comparison Reports

User type comparison reports allow you to compare user types side by side. The report shows one user type per column. A maximum of eight user types can be included in a single user type comparison report.

Both overall results and user-type-specific results can be compared. To add measures, drag them from the tree onto the report. To add the overall results of a test, drag the Overall node onto the report. The data set is marked with Overall in the User Type column of the Baseline Pane.

Parent topic: Comparison Reports


Custom Comparison Reports

Custom comparison reports allow you to compare the results of up to eight test executions side by side. Additionally, you can compare load test executions with user types or regions if this makes sense in your scenario.

Parent topic: Comparison Reports


Creating Region Comparison Reports

Before you follow the steps below, configure a cloud-based load test in Silk Performer with cloud agents from different regions and execute the load test.

  1. When your cloud-based load test is completed, the Load Test Summary page displays. Click the Load Test Results chart to open it in Performance Explorer. The results are loaded into Performance Explorer and display in the tree.
  2. Expand the nodes in the tree until you see the Regions node. Results data (time series data) is available for each cloud region that was included in the load test.
    Note: The data is available for the cloud regions, not for the single cloud agents.
  3. Select a region and click Region in the Comparison Report group on the Reports tab. The report displays, showing the selected region. You can now drag further regions from the tree onto the report.
    • To show all regions in the report at once, select the Regions node and click Region.
    • To show all regions and an Overall column in the report, select the Client Measures node and click Region.
    Tip: You can also right-click a node in the tree and use the commands in the context menu.
    Note: Only regions from the same load test can be added to a region comparison report.
  4. To define the results of a certain region as the baseline, right-click the region in the baseline pane at the bottom of the report and click Set as baseline.
Parent topic: Comparison Reports


Creating User Type Comparison Reports

  1. Open Performance Explorer and add results. The results are loaded into Performance Explorer and display in the tree.
  2. Expand the nodes in the tree until you see the User Types node.
  3. Select a user type and click User Type in the Comparison Report group on the Reports tab. The report displays, showing the selected user type. You can now drag further user types from the tree onto the report.
    • To show all user types in the report at once, select the User Types node and click User Type.
    • To show all user types and an Overall column for the workload, select the Client Measures node and click User Type.
    Tip: You can also right-click a node in the tree and use the commands in the context-menu.
    Note: Only user types from the same load test can be added to a user type comparison report.
  4. To define the results of a certain user type as the baseline, right-click the user type in the baseline pane at the bottom of the report and click Set as baseline.
Parent topic: Comparison Reports


Creating Custom Comparison Reports

  1. Open Performance Explorer and add results. The results are loaded into Performance Explorer and display in the tree.
  2. Select a project node in the tree and click Custom in the Comparison Report group on the Reports tab. The report is created with all load tests that are loaded in Performance Explorer. These are the load tests that appear under the project node in the tree.
  3. You can add further load test results and drag them from the tree onto the report. You can even add load tests as well as user type or region results from various projects to one custom comparison report. A maximum of eight data sets can be included in a single custom comparison report.
    Tip: You can also right-click a node in the tree and use the commands in the context menu.
  4. To define the results of a certain load test as the baseline, right-click the load test in the baseline pane at the bottom of the report and click Set as baseline.
Parent topic: Comparison Reports


Real-Time Monitoring

With the Real-Time Monitoring functionality of Performance Explorer, you can monitor a broad range of systems by creating and configuring charts that show the system performance in real-time. It is possible to open multiple charts at the same time, which allows you to watch the performance of two or more systems simultaneously, for example the web server performance and the operating system performance. Adding measures to a chart is easy and intuitive in Performance Explorer: You can drag a single measure or a set of measures from the tree onto the chart.

  • Monitoring Technologies
    Performance Explorer supports a broad range of monitoring technologies, which are described in this section.
  • Monitoring Data Sources
    Describes how to define data sources to collect performance data from servers and applications.
  • Monitoring Load Tests
    Describes adding and removing data sources for client-side measures.
  • Monitor Charts and Monitor Writers
    Describes what monitor charts and monitor writers are.
  • Host Data
    Describes how to change, rename, and duplicate hosts and how to update host credentials.
  • Converting Data from CSV to TSD
    Describes the purpose of converting data from .csv files to the .tsd format.
Parent topic: Performance Explorer 21.0


Monitoring Technologies

Performance Explorer supports a broad range of monitoring technologies, which are described in this section.

  • Monitoring Windows Machines
    Describes the requirements and setup of Windows machines and provides troubleshooting tips.
  • JMX Monitoring
    Describes JMX monitoring and lists the prerequisites.
  • Easy JMX Queries
    Describes the accessibility to the attribute values of MBeans that are hosted on JMX MBeanServers.
  • REXEC and UNIX Data Sources
    Describes how to query Unix-based systems using the Remote Execution protocol.
  • SNMP Support
    Explains that SNMP measures are accessed using a combination of object ID and instance ID.
  • Secure Shell Performance Monitoring
    Provides an overview of retrieving performance metrics by using a secure shell.
  • Generating BDL Monitoring Projects
    Silk Performer projects, or more precisely BDL scripts, can be used to collect performance data for monitored systems.
Parent topic: Real-Time Monitoring


Monitoring Windows Machines

This section describes the requirements and setup of Windows machines and provides troubleshooting tips.

  • Requirements for Monitoring Windows Machines
    Provides the requirements for monitoring Windows machines.
  • Troubleshooting Windows Performance Monitoring
    Describes the error messages that can occur when monitoring Windows-based machines.
Parent topic: Monitoring Technologies


Requirements for Monitoring Windows Machines

Target machines with Windows Vista and newer client operating systems

Make sure that the following preconditions are met to be able to monitor the respective remote systems:

The Remote Registry service must be running on the machine that you want to monitor. This service does not run by default on Windows Vista and Windows 7 machines.

Parent topic: Monitoring Windows Machines


Troubleshooting Windows Performance Monitoring

The following error messages can occur when monitoring Windows-based machines:

Error Message | Possible Cause | Resolution
Computer Name Not Found | You might receive this error message when trying to monitor a remote computer from a non-administrator account. | Enable remote monitoring on a Windows NT computer.

Error=AGENT_ERROR_TCP_SEND_REQUEST_FAILED

This problem can occur if your organization uses proxy auto-configuration files to direct requests to a proxy server, and you specify the automatic configuration script address rather than the registered name of the proxy server.

If your organization uses a non-passive proxy, in most cases you must also specify the port number.

Verify the following proxy settings:
  • Correct entry of the proxy server name, user name, and password
  • Ability to ping the proxy server from the RSM computer
  • Ability of the RSM computer to connect to the portal computer
System 5 - Access denied When monitoring a machine with Windows 2008 or newer using CUSTOM / PERFMON option, logging in with credentials of a user added to the Administrators group generates a System 5 - access denied error. The user with which you run Performance Explorer needs to be added to the Administrators group on the remote computer that you want to monitor. If you specify different user credentials in Performance Explorer’s Data Source Wizard, that user also needs to be added to the Administrators group on the remote computer. To monitor remote machines successfully, you need to launch Performance Explorer (PerfExp.exe) under the same user account that is being used to connect to the remote machine(s).
Tip: To launch PerfExp.exe under a specific user account, press shift + right-click and select Run as different user.
Parent topic: Monitoring Windows Machines


JMX Monitoring

The Silk Performer support for Java Management Extensions (JMX) monitoring enables you to monitor MBean attributes that are exposed by Java application servers. MBean attributes that return numeric data are added to Performance Explorer monitors as data sources.

Prerequisites for JMX Monitoring

The prerequisites for JMX monitoring include the following items:
  • Java Runtime (JVM) 1.5 or later
  • The JVM application that you want to monitor must have an open port for monitoring
  1. Connecting to a JMX Data Source
    Establish a connection to a Java application server to monitor MBean attributes.
  2. Specifying MBeans for Monitoring
    Monitor MBean attributes that are exposed by Java application servers.
  3. Adding Attributes to the Bean-Attribute Pool
    Choose the MBean attributes to monitor.
Parent topic: Monitoring Technologies


Connecting to a JMX Data Source

Establish a connection to a Java application server to monitor MBean attributes.

  1. On the Real-Time Monitoring tab, in the Monitor group, click System.
  2. Click Select from predefined Data Sources and then click Next.
  3. Perform one of the following steps:
    • To explore all available MBean attributes on an application server, expand the Application Server folder and select a JMX recording profile from a vendor-specific folder. Profile names end with the extension .jmx.
    • To explore a selection of MBeans that contain typical attributes for monitoring, expand the Application Server folder and select a JMX recording profile from a vendor-specific folder. Profile names end with the extension .ejmx.
    • To create a generic JMX monitoring data source, expand the Custom Data folder and select JMX Data.
  4. In the Hostname text box, specify the JMX server.
  5. Optional: In the Alias text box, specify the alias name. The alias must be a highly descriptive synonym for the monitored server. It is recommended that you group measures on a particular machine. For example, both WebLogic and IIS might be installed on the same computer. Both servers require monitoring, but the two performance measures must appear in separate menu trees.
  6. Specify the port, username, and password that are appropriate for the username.
  7. If you opted to create a generic JMX monitoring data source, select a supported application configuration from the Application list box.
  8. Click Server Configuration. The JMX Connection Configuration dialog box opens.
  9. Specify the application server installation directory where the application server's communication libraries are located. The relative classpath entries of the application configuration file, together with the specified application server install directory, form the classpath under which the JMX client runs. The resulting classpath is viewed in the Resulting classpath text box.
    Note: It is recommended that you use a UNC path or copy the application library directory of the server to your local machine and specify your local copy as the application server installation directory. To complete this task, click [...] next to the App. server install directory text box.
    Note: JMX monitoring of WebSphere requires that you specify an IBM JDK. If your WebSphere server has disabled administrative security or enabled administrative security and the inbound CSIv2 transport layer is TCP/IP, you can specify a SUN JDK.
  10. In the Java home directory text box, specify the installation directory where the client's communication libraries are located. Alternative: Click [...] to navigate to the appropriate directory.
  11. Specify additional libraries in the Additional classpath text box.
  12. Specify additional virtual machine parameters in the Additional JVM parameters text box. The parameters on the Connection and Visualization pages are preconfigured for each server.
  13. Click OK. The Connection Parameters page opens.
  14. Click Next and then click Finish. Performance Explorer connects to the JMX server.
  15. Examine the exposed beans in the JMX Data Source Browser.
  16. Click Finish.
Parent topic: JMX Monitoring
Next topic: Specifying MBeans for Monitoring


Specifying MBeans for Monitoring

Application configuration profiles are stored as XML files at C:\Program Files\Silk\Silk Performer 21.0\include\jmx-config\. Make any changes to the default configurations in the XML file directory, and create additional profiles in this directory as well. Newly created application configuration profiles are available for use as data sources.

  1. Open the JMX Data Source browser. The Type Tree page shows all the available categories of MBeans in a tree structure. The Type List tab, shows all available categories in a list format. All available MBeans of the selected category are visible in the Beans text box. Each MBean is identified by an object name, which consists of a domain name and one or more pairs of property types and values.
  2. Select an MBean of interest and expand the MBean node to view the available attributes.
  3. Optional: Click Numeric Attributes to filter non-numeric attributes.
    Non-numeric attributes are not supported for JMX monitoring.
  4. Optional: Right-click an attribute and choose Get Value to query the value of any attribute.
  5. Optional: Right-click an attribute that represents an object name and choose Follow Reference to navigate to the referenced MBean.

Add the appropriate attributes to the bean-attribute pool.

Parent topic: JMX Monitoring
Previous topic: Connecting to a JMX Data Source
Next topic: Adding Attributes to the Bean-Attribute Pool


Adding Attributes to the Bean-Attribute Pool

Before you begin this procedure, perform one of the following steps:
  • Specify the appropriate MBeans for monitoring.
  • Run an Easy JMX or custom query to identify MBeans of interest.
  1. Open the JMX Data Source Browser.
  2. Choose the attributes to monitor in the Beans text box.
    Note: Select multiple beans by pressing Shift or Ctrl.
    Note: Certain MBeans like those based on JSR-77 might contain complex attributes that consist of several submeasures or statistics. To a certain depth of recursiveness, you can select submeasures to be monitored.
  3. Right-click the selected attributes and choose Add As. A submenu opens.
  4. Choose one of the following options for monitoring the attribute values:
    • Average – Useful for count values. By default, this option is selected.
    • Sum – Same as Average, but shows a different label in the monitor GUI.
    • Incremental – Useful for rising values. Instead of the attribute value, the change of the value within a monitor interval is calculated.
  5. Click Close. The Select displayed measures page opens.
  6. Optional: Select an MBean and click Add.
    Performance Explorer adds all visible attributes of an MBean as a data source.
  7. Check the check boxes for those measures that you want to include in the initial monitor view and then click Finish.
A connection to the specified host is established, and an initial view that contains the measures you selected is displayed.
Parent topic: JMX Monitoring
Previous topic: Specifying MBeans for Monitoring


Easy JMX Queries

Easy JMX queries enable access to the most important attribute values of MBeans that are hosted on JMX MBeanServers. Easy JMX queries are preconfigured, advanced queries that are executed automatically when a connection to an application server's MBeanServer is established. All MBeans that match Easy JMX query criteria are automatically displayed in the Beans text box of the JMX Data Source browser. Easy JMX profiles are identifiable in the System menu tree on the System Selection dialog box by the EJMX tags that follow them.

  • Filtering Beans Using JMX Query Language
    Display only the MBeans that match specific filter criteria to narrow the JMX query.
  • Running Advanced JMX Queries
    Create a sophisticated combination of simple queries to monitor data for your environment.
  • Running Saved Queries
    Execute an existing JMX query to access the most important attribute values of MBeans that are hosted on JMX MBeanServers.
Parent topic: Monitoring Technologies


Filtering Beans Using JMX Query Language

Display only the MBeans that match specific filter criteria to narrow the JMX query.

  1. Open the JMX Data Source Browser. All available MBeans on the selected JMX MBeanServer are visible in the Beans text box.
  2. Click the Simple Query tab.
  3. Select a domain from the Domain list box. Leave this field set to <All> to search all domains.
  4. Optional: Select a property from the Property field list box.
    This list displays all the properties that are included in the loaded beans.
  5. Optional: Select a value for the selected property from the rightmost Property field list box.
    The Query text box shows the resulting object name that is used for JMX queries, which are based on the JMX 1.2 (JSR-003) standard.
  6. Optional: Type an attribute name in the Attribute filter text box to filter the list based on a specific attribute.
    Only MBeans containing the specified attributes are displayed.
  7. Click Run to execute the query. The Beans text box displays only those MBeans that match the filter criteria.
Parent topic: Easy JMX Queries


Running Advanced JMX Queries

Create a sophisticated combination of simple queries to monitor data for your environment.

  1. Open the JMX Data Source Browser.
  2. Click the Advanced Query tab. Available query types are listed in the upper window. For example, you might see Object Name Query.
  3. Select one of the available operators for the query from the list box of the query. For example, you might select the OR operator.
  4. Select a value for the operator from the subsequent list box. For example, you might select True. [...] appears, enabling you to open the JMX Object Name Query dialog box and browse through a domain list.
  5. Click [...] and select the appropriate domain name from the domain list. For example, you might select jboss.cache.
  6. Continue adding elements until your query is complete. For example, you might add *:J2EEServer =local.
  7. Click OK.
  8. Click the root element of the Query menu tree.
  9. Type a description of the query in the lower pane of the Advanced Query page.
  10. Click Run. All MBeans that meet the query's criteria are displayed.
  11. Click Save. This step allows you to specify a target destination and name for the query. The file extension for JMX Data Queries is .jdq.
    Note: Queries that are saved to the C:\Program Files\Silk\Silk Performer 21.0\include\jmx-config directory are also listed on the Easy JMX page and can be run directly from there.
Parent topic: Easy JMX Queries


Running Saved Queries

Execute an existing JMX query to access the most important attribute values of MBeans that are hosted on JMX MBeanServers.

  1. Open the JMX Data Source Browser.
  2. Click the Advanced Query tab.
  3. Choose Load > Load From File > Load.
  4. Browse through the list of pre-installed queries and any custom queries that you might have saved. Pre-installed query types are available for a number of server types. These types are the same query types that are available with the Easy JMX profiles.
  5. Click Run.
    Note: Queries that are saved to C:\Program Files\Silk\Silk Performer 21.0\include\jmx-config are also listed on the Easy JMX page and can be run directly from there.
    Performance Explorer executes the query.
Parent topic: Easy JMX Queries


REXEC and UNIX Data Sources

Describes how to query Unix-based systems using the Remote Execution protocol.

  • REXEC and UNIX Data Sources Overview
    Describes how to query Unix-based systems using the Remote Execution protocol.
  • Using REXEC to Query UNIX
    Establish a connection to a UNIX-based system that uses the Remote Execution Protocol and add the measures that you want to monitor.
  • Memory Free Custom Example
    Provides an example of custom values for MemFree.
Parent topic: Monitoring Technologies


REXEC and UNIX Data Sources Overview

Data sources on UNIX-based systems can often be queried by using the Remote Execution protocol. Identified data sources appear in the predefined data sources list. For example, you might want to monitor Context switches/sec on a Solaris system. By selecting this entry in the predefined list, you do not need to specify remote execution details. When data sources are not found in the list, create a custom data source.

Remote Execution

Remote execution means that you execute commands on the remote host by using the command-line interface. You can also execute shell scripts. To verify shell scripts, use a telnet client, connect to your UNIX system, and run some commands or scripts.

Single Execution

With single execution, the primary domain controller emulator (PDCE) connects to the remote machine and executes the command each time a new data point is requested. With short intervals this setting might place some load on the remote machine. However, the PDCE does not start a new command on the remote machine until the command of the last interval has finished.

Without single execution, the PDCE connects to the remote machine at the beginning of the monitoring session, starts the command, and forwards the output of the command to the parser. The parser is activated at the given monitoring interval and parses available data. The command is executed only once, and the connection to the remote machine remains active during the entire monitoring session. If the connection is lost because, for instance, the command on the remote machine exits, the PDCE attempts to reconnect after a fixed interval.

Single Execution Example

ps -ef | egrep -c ".*"

The preceding command counts the number of processes running on a UNIX system. Enter this command during the telnet session. The command prints a value (the number of processes running) and then closes. Such behavior is called single execution.

You can wrap a ‘while’ loop around such commands.

Multiple Execution Example

while [ true ]; do	// Mind the spaces
   ps -ef | egrep -c ".*";
   sleep 5;
done

The preceding example continuously prints the number of processes at five-second intervals. Such behavior is defined as multiple executions.

Parent topic: REXEC and UNIX Data Sources


Using REXEC to Query UNIX

Establish a connection to a UNIX-based system that uses the Remote Execution Protocol and add the measures that you want to monitor.

  1. On the Real-Time Monitoring tab, in the Monitor group, click System.
  2. Click Select from predefined Data Sources and then click Next.
  3. Expand the Custom Data folder, click Rexec Data, and then click Next.
  4. In the Hostname text box, specify the machine to be monitored.
  5. Optional: In the Alias text box, specify the alias name. The alias must be a highly descriptive synonym for the monitored server. It is recommended that you group measures on a particular machine. For example, both WebLogic and IIS might be installed on the same computer. Both servers require monitoring, but the two performance measures must appear in separate menu trees.
  6. Specify the port, username, and password that are appropriate for the username.
  7. Click Next. The Add Rexec Measures page opens.
  8. Specify the appropriate values to create the measure that you want to monitor.
    Option | Description
    Measure type | For the specified command, enter a type name. All measurements with the same type name are assembled into one group.
    Measure name | Enter the measurement name for the specified rexec command. This name is displayed in the Performance Explorer chart.
    Is an average measure | Check this check box for the rexec command to be considered an average measurement. This setting affects only the generation of TSD files.
    Explanation | Type additional information for the specified rexec command. This information is displayed in Performance Explorer.
    Command | Specify the rexec command to execute on the remote machine for data collection, such as ps -ef | egrep -c “.*”
    Single execution Check this check box if you want the PDCE to connect to the remote machine and execute the command every time a new data point is requested. With short intervals, this setting might place some load on the remote machine. However, the PDCE does not start a new command on the remote machine if the command of the last interval has not finished.

    By unchecking the Single execution check box, multiple execution is enabled.

    Regular expr Every line of data that is returned by the remote machine is filtered by using the given regular expression. If the regular expression does not match a certain line, the line is discarded. Only the remaining lines are used for further steps. By default, ^.*$ are entered.
    For example, a command's response might appear as follows for each interval:
    XXXXXXXX XXXXXXXX XXXXXXXXX
         123400   103093   121092
    Only the lines with numbers are of interest. The following regular expression allows only lines with numbers and spaces.
    [1234567890 ].*
    Any other lines are ignored.
    Field index The line used for data generation is separated into fields. The separation is accomplished by using either white-space characters or custom separator characters.

    Use this text box to specify the field index that must be converted into a numerical value and used as the next measurement value.

    This index is a one-based index.

    Separators Use this text box to specify the custom separator characters to use to separate the lines for data generation into fields.

    By default, the Whitespaces are separators check box is checked.

    Whitespaces are separators | Check this check box to insert a separator for each empty space.
    Lines to skip | Use this text box to specify the number of lines the PDCE ignores after the start of the command on the remote machine. This option might be useful to filter out garbage data that the command returns at the beginning. Only lines that match the provided regular expression use this setting. If more than one valid line is provided for an interval, the last line is used for data calculation.
  9. Click Add.
  10. Repeat the previous steps until you have entered all the commands that you require for measure collection, then click Close. The Select displayed measures page opens.
  11. Check the check boxes for those measures that you want to include in the initial monitor view and then click Finish.
A connection to the specified host is established, and an initial view that contains the measures you selected is displayed.

Example

Enter the command, in slightly modified form, that was used when defining multiple executions as follows:
while [true]; do
  ps -ef | egrep -c “.*”;
  sleep {%Interval};
done
Note: The command sleep {%Interval} is a placeholder for a number provided by Performance Explorer. This number is the collection interval. For example, Performance Explorer might collect new data every five seconds.
A command's response might appear as follows for each interval:
XXXXXXXX XXXXXXXX XXXXXXXXX
         123400   103093   121092

The Field index value specifies the column that is relevant for your defined measure. If Field index 1 is specified, the value 123400 is returned from the table. If Field index 2 is specified, the value 103093 is returned.

Columns in the preceding example are separated by white spaces. However, other characters, such as colons, can be used. Such values are specified in the Separators text box. White spaces are the default separators.

Parent topic: REXEC and UNIX Data Sources


Memory Free Custom Example

Consider this command for Linux machines:

cat/proc/meminfo

It returns the following table.

 | total: | used: | free: | shared: | buffers: | cached:
Mem: | 131084288 | 54214656 | 76869632 | 26947584 | 7938048 | 28471296
Swap: | 70148096 | 3387392 | 66760704 |  |  |
MemTotal: | 128012 kB |  |  |  |  |
MemFree: | 75068 kB |  |  |  |  |
MemShared: | 26316 kB |  |  |  |  |
Buffers: | 7752 kB |  |  |  |  |
Cached: | 27804 kB |  |  |  |  |
SwapTotal: | 68504 kB |  |  |  |  |
SwapFree: | 65196 kB |  |  |  |  |

The following table identifies the field values to use to obtain the value for MemFree from the preceding table:

Command | cat /proc/meminfo
Single execution | Checked
Regular expr | ^MemFree:.*$
Field index | 2
Separators | Check Whitespaces are separators
Lines to skip | 0
Parent topic: REXEC and UNIX Data Sources


SNMP Support

Standard SNMP support includes a generic interface for all SNMP data sources in which MIBs are present. Specific measures are accessed using a combination of object ID (OID) and instance ID (when objects have more than one instance). The challenge with this approach is that you must know exactly which counter instance is to be applied. Instances are only distinguished by instance ID, not by instance name. Compounding this challenge is the fact that when servers reboot, certain instance numbers can change due to dynamic monitoring-object creation. Therefore monitoring scripts must be able to cope with dynamic monitoring targets.

The value of Silk Performer's enhanced SNMP support is that it allows you to access values not by OID and instance ID, but by OID and instance name.

The following example illustrates the enhanced SNMP support that is available with Silk Performer. This example shows how predefined ESNMP measures are defined, how they are used, and how additional measures can be added to the list of pre-defined measures.

Identifying instance IDs and OIDs

The first step in working with a predefined ESNMP measure is to identify the OID, instance ID, and instance name of a WebLogic counter. The JDBC Connection Pool Runtime Active Connections Current Count for a certain instance is accessible with the OID:

1.3.6.1.4.1.140.625.190.1.25 + <Instance ID>

Without enhanced SNMP support, you have to provide the OID of the table containing the values and the correct instance ID.

JDBC Connection Pool Runtime Object Name and JDBC Connection Pool Runtime Name contain the human readable names of the instances and are accessible with the OIDs:

1.3.6.1.4.1.140.625.190.1.5 + <Instance ID> for “Object Names”

and...

1.3.6.1.4.1.140.625.190.1.15 + <Instance ID> for “Names”

ESNMP support provides you with the option of specifying an instance name, retrieving an instance ID using the (object-) name table, and then getting the value for the correct counter. With ESNMP support, the following must be provided:

  • OID of the table containing the values
  • Instance name
  • OID of the table containing the instance names
  • Monitoring Server Performance Through SNMP
    Collect server performance data through an SNMP protocol and view the results in Performance Explorer.
  • Compiling a New MIB
    To use the contents of an MIB with Silk Performer, the MIB must be compiled first. A number of common MIBs are delivered in a precompiled format. You can compile a new MIB if necessary.
  • Defining an SNMP Data Source
    Explains how to set up a data source header and definition.
Parent topic: Monitoring Technologies


Monitoring Server Performance Through SNMP

Performance Explorer offers you the possibility of selecting the object identifiers (OIDs) of management information bases (MIBs) from several sources for use as data sources for server monitoring. For example, database systems like Oracle offer extensive performance data for collection through an SNMP protocol.

  1. Click Monitor Server on the Performance Explorer workflow bar. The Data Source Wizard opens in the Select Data Sources dialog box.
  2. Click the Select from predefined Data Sources option button and click Next. The System Selection dialog box opens.
  3. In the System menu tree, expand the Custom Data folder.
  4. Select SNMP Data, then click Next. The Connection Parameters dialog box opens.
  5. In the Connection parameters area, specify connection parameters such as the host name or IP address of the appropriate server system, the port number, and other data required to connect to the data source. You must possess access rights to the specified server, and the SNMP service must be configured properly on the server system.
  6. Click Next. The Add SNMP Measures dialog box opens
  7. Select one of the precompiled MIBs delivered with Performance Explorer or click Compile New MIB to use an MIB that was shipped with the server system. To use the contents of an MIB with Silk Performer, the MIB must be compiled first. A number of common MIBs are delivered in a precompiled format. You can compile a new MIB if necessary. After you select a compiled MIB, its contents are displayed in a menu tree.
  8. Click the OID in w hich you are interested and click Get Value(s). Connection to the server is established, and the actual data item is shown.
  9. Click the corresponding data item and then click Add.
  10. Repeat the previous two steps until you select all the OIDs you want.
  11. Click Close. The Select Displayed Measures dialog box opens
  12. Select the factors to be monitored and click Finish. A Monitor graph displays the specified elements in a real-time, color-coded, display of server performance.
Parent topic: SNMP Support


Compiling a New MIB

Vendors of hardware and software systems provide information about the nature of their systems by way or management information bases (MIBs). This information can be retrieved with the help of the SNMP protocol by specifying the appropriate object identifier (OID). MIB browsers assist you in selecting the appropriate OID stored in an MIB.

  1. In the Add SNMP Measure dialog box, click Compile New MIB for an MIB that has been shipped with the server system. The Compile New MIB dialog box opens.
  2. Browse for the MIB file you want to compile and click Open.
  3. Click Compile. If the compilation succeeds, a new name is added to the list of compiled MIBs.
  4. If the message Could not IMPORT from <name>-MIB appears, compile the MIB to which error message refers.
  5. Click Close. The new MIB can now be used to monitor server performance through SNMP.
Parent topic: SNMP Support


Defining an SNMP Data Source

To define a new data source, do not edit the REALTIME.INI file. If you do, you will lose your changes when you next upgrade Silk Performer. To avoid this, create a new file in the sub-folder <installation path>\Silk\Silk Performer 15.0\Include\DataSrcWzd, for example myESNMP_realtime.ini. This file must contain the S= and the M= lines of your data source definition.

By searching for “WebLogic” and “ESNMP” in the REALTIME.INI file, you will find the following entries:
S= Application Server\BEA WebLogic preconfigured\SNMP, ESNMP:BEA-WEBLOGIC-MIB,
M= ESNMP:1.3.6.1.4.1.140.625.340.1.25, BEA WebLogic\JVM Runtime\HeapFreeCurrent, eAvgOnlyCounter, 0, kbytes, 0, 1, 2, 3, 4, 5, Current Heap Free, measureMatchName=Runtime Object Name;measureMatchOID=1.3.6.1.4.1.140.625.340.1.5;
M= ESNMP:1.3.6.1.4.1.140.625.340.1.30, BEA WebLogic\JVM Runtime\HeapSizeCurrent, eAvgOnlyCounter, 0, kbytes, 0, 1, 2, 3, 4, 5, Current Heap Size, measureMatchName=Runtime Object Name;measureMatchOID=1.3.6.1.4.1.140.625.340.1.5;
M= ESNMP:1.3.6.1.4.1.140.625.180.1.25, BEA WebLogic\Queue Runtime\ExecuteThreadCurrentIdleCount, eAvgOnlyCounter, 0, , 0, 1, 2, 3, 4, 5, Thread Idle Count, measureMatchName=Queue Runtime Object Name;measureMatchOID=1.3.6.1.4.1.140.625.180.1.5;
M= ESNMP:1.3.6.1.4.1.140.625.180.1.35, BEA WebLogic\Queue Runtime\PendingRequestCurrentCount, eAvgOnlyCounter, 0, , 0, 1, 2, 3, 4, 5, Current Requests, measureMatchName=Queue Runtime Object Name;measureMatchOID=1.3.6.1.4.1.140.625.180.1.5;
M= ESNMP:1.3.6.1.4.1.140.625.180.1.40, BEA WebLogic\Queue Runtime\ServicedRequestTotalCount, eAvgOnlyCounter, 0, , 0, 1, 2, 3, 4, 5, Total Requests, measureMatchName=Queue Runtime Object Name;measureMatchOID=1.3.6.1.4.1.140.625.180.1.5;
M= ESNMP:1.3.6.1.4.1.140.625.430.1.50, BEA WebLogic\WebApp Component Runtime\OpenSessionsCurrentCount, eAvgOnlyCounter, 0, , 0, 1, 2, 3, 4, 5, Open sessions, measureMatchName=Runtime Object Name;measureMatchOID=1.3.6.1.4.1.140.625.430.1.25;
M= ESNMP:1.3.6.1.4.1.140.625.430.1.55, BEA WebLogic\WebApp Component Runtime\OpenSessionsHighCount, eAvgOnlyCounter, 0, , 0, 1, 2, 3, 4, 5, Session High Count, measureMatchName=Runtime Object Name;measureMatchOID=1.3.6.1.4.1.140.625.430.1.25;
M= ESNMP:1.3.6.1.4.1.140.625.550.1.25, BEA WebLogic\Execute Queue\ThreadCount, eAvgOnlyCounter, 0, , 0, 1, 2, 3, 4, 5, Thread Count, measureMatchName=Queue Object Name;measureMatchOID=1.3.6.1.4.1.140.625.550.1.5;

The first line, which begins with S=, is the data source definition header. You only need one definition header per data source. So if you want to enhance the existing WebLogic ESNMP data source, you can leave the data source definition header as is.

Subsequent lines are for the individual measures:

  • Following M= is the OID that is to be queried, without the instance ID (for example, 1.3.6.1.4.1.140.625.190.1.25).
  • Following that is the name of the measure as it will appear in the GUI. Note that back slashes are used to create the hierarchy (for example, BEA\JDBC Connection Pool\Active Connections).
  • Following that are standard entries: measure class, scale, unit, scale factor, and five unused fields (for example, eAvgOnlyCounter, 0, , 0, 1, 2, 3, 4, 5).
  • The next field is a description for tool-tip help in Performance Explorer. You might write, Current count of active connections in the JDBC connection pool runtime. The measure name itself can be shorter.
  • The last entry is divided into two parts:
    • omeasureMatchName= This is used in the data source wizard to describe the instances (for example, JDBC Connection Pool Runtime Object Name).
    • omeasureMatchOID= This is the OID of the table that contains the instance names (for example, 1.3.6.1.4.1.140.625.190.1.15).
Note: The final measure name consists of the measure name given here (BEA WebLogic\JDBC Connection Pool\Active Connections) and the instance name in parenthesis.
So the key for the measure should appear as follows:
M= ESNMP:1.3.6.1.4.1.140.625.190.1.25, BEA WebLogic\JDBC Connection Pool\Active Connections, eAvgOnlyCounter, 0, , 0, 1, 2, 3, 4, 5, Current count of active connection in the JDBC connection pool runtime, measureMatchName=JDBC Connection Pool Runtime Object Name;measureMatchOID=1.3.6.1.4.1.140.625.190.1.15;
Parent topic: SNMP Support


Secure Shell Performance Monitoring

Use Performance Explorer to retrieve performance metrics by using a secure shell. For example, retrieve CPU-utilization or memory-utilization statistics from a SunOs system. Performance Explorer is shipped with a highly configurable performance-monitoring project that allows for the scripting of any monitors by using the secure shell. This process is done by driving a Silk Performer project inside Performance Explorer. This capability also allows you to keep track of system performance in real time.

The Silk Performer project is located in a SilkEssential package named Ssh.sep, which is located at C:\Program Files\Silk\Silk Performer 21.0\Monitors.

  • Monitoring Performance by Using a Secure Shell
    Enable Performance Explorer to monitor performance by using a secure shell.
Parent topic: Monitoring Technologies


Monitoring Performance by Using a Secure Shell

The system that you want to monitor by using a secure shell must be running a secure shell daemon. Make sure the monitored user has permission to log on multiple times.

  1. On the Real-Time Monitoring tab, in the Monitor group, click System. The Data Source wizard opens.
  2. Click the Select from predefined Data Sources option button.
  3. Click Next. The System selection page opens.
  4. Expand the Miscellaneous folder and click Secure Shell.
  5. Click Next.

    The Connection parameters page opens.

  6. In the Hostname text box, specify the host that you want to monitor.
  7. Click Next. The Attributes Configuration page opens.
  8. Define the following monitoring specific attributes:
    • Username – The user to be used when logging on to a remote system by using a secure shell.
    • Password – The user's password.
    • Command(x) – The preconfigured package allows for retrieving up to five performance measures by using secure shell as the following table shows:
      Attribute | Type | Value
      Command1 | string | ps -ef | egrep -c \”.*\”
      Command1.Active | boolean | true
      Command1.Column | number | 1
      Command2 | string | mpstat | head -n 2 | tail -1
      Command2.Active | boolean | true
      Command2.Column | number | 13
  9. Click OK. The Select displayed measures page opens.
  10. Check the check boxes for those measures that you want to include in the initial monitor view and then click Finish.
A connection to the specified host is established, and an initial view that contains the measures you selected is displayed.

Example Command2

This example works for a SunOs system. The following command is sent to the server.
mpstat | head -n 2 | tail -1
This command returns a one-line response in the following format.
0 0 0 0 228 25 106 1 0 0 0 219 0 0 0 99

The attribute Command2.Column specifies which column to pass on to Performance Explorer for keeping track of the performance counter. In this case, it is column 13, which is the percentage of user time on a SunOs system.

Command2.Active specifies only whether this measure must be collected.

Example Command1

The following command is sent to the server.
ps -ef | egrep -c \".*\"
This command counts the number of processes running on a SunOs system and could return a one-line response in the following format.
87

Therefore, one line is returned with exactly one column.

The attribute Command1.Column specifies the column to forward to Performance Explorer. In this case, it is column 1.

Command1.Active specifies only whether this measure must be collected.

Parent topic: Secure Shell Performance Monitoring


Generating BDL Monitoring Projects

Silk Performer projects, or more precisely BDL scripts, can be used to collect performance data for monitored systems. This section outlines the steps that are required to assemble BDL monitoring projects for use with Performance Explorer and thereby enable real-time display of collected data.

  • Silk Performer BDL Monitoring Projects
    The Performance Data Collection Engine (PDCE) processes performance data collected by BDL scripts. Performance data collected with such scripts can be displayed in Performance Explorer in real-time.
  • Creating a BDL Monitoring Project
    Introduces the workflow required to generate a BDL monitoring project for Performance Explorer using Silk Performer.
  • Creating a Silk Performance Manager Infrastructure Monitor
    Introduces the workflow required to generate a Silk Performance Manager infrastructure monitor.
  • Performance Data Collection Engine (PDCE)
    Describes the engine that is used for online monitoring.
  • Tutorial
    This tutorial consists of two use cases: (1) a simple use case to get you started and (2) an advanced use case.
  • Best Practices
    This section outlines suggestions for working with real-time monitoring projects as relates to the writing of monitoring scripts.
Parent topic: Monitoring Technologies


Silk Performer BDL Monitoring Projects

The Performance Data Collection Engine (PDCE) processes performance data collected by BDL scripts. Performance data collected with such scripts can be displayed in Performance Explorer in real-time. Entities collected by the PDCE are called measures, which may be specified in BDL using the following functions:

  • MeasureInc
  • MeasureIncFloat
  • MeasureStart & MeasureStop
  • MeasureSetTimer
  • MeasureSet

These functions are called within transactions. One-to-many measures are allowed within each transaction. Furthermore, monitoring projects can use exactly one script defining exactly one usergroup. This usergroup may define one init transaction, one end transaction and one main transaction.

Wrapper functions, defined in bdlMonitor.bdh, are used to deliver additional functionality that is necessary for BDL realtime monitoring. See the Supplemental tutorials for information on using these functions:

  • MonitorInc
  • MonitorIncFloat
  • MonitorStart and MonitorStop
  • MonitorSet
  • MonitorSetFloat
  • MonitorSetTimer
Parent topic: Generating BDL Monitoring Projects


Creating a BDL Monitoring Project

  1. Start Silk Performer and create a BDL monitoring project.
    1. Click the Outline Project button on the Workflow bar. The Workflow - Outline Project dialog box opens.
    2. Enter a name for the project in the Name text box and an optional description in the Description text box.
    3. From the Application Type list, select Monitoring > Bdl Monitor for Performance Explorer.
    4. Click Next.
  2. On the Model Script dialog box, select the Open existing script option button.
  3. Select the script BdlMonitorSample.bdf and click OK. This brings up a pre-configured monitoring script that can be used as a template.
  4. Select Project > Project Attributes to define the project attributes. Each measure exported to Performance Explorer requires a fixed set of project attributes.

    To be viewed with Performance Explorer, each measure requires at least these three project attributes:

    • Name: Name to be shown in Performance Explorer
    • Type: An average value or a cumulative value.
    • Enabled: Reserved. Always set to true.
  5. Review the sample monitor script

    As specified in the project attributes, the project exports two measures that can be viewed in Performance Explorer in real-time.

    Look for MonitorInc and MonitorIncFloat in the TMon transaction. This is where the last snapshot is handed over to Performance Explorer.

    use "bdlMonitor.bdh"

const
  nMeasure1 := 1;
  nMeasure2 := 2;

dclrand
  rRand   : RndExpN  (1..10000: 100.000000);
  rRandf  : RndExpF  (5.500000);

var
  fScale : float;

dcluser
  user
    VMon
  transactions
    TInit           : begin;
    TMon            : 1;
    TEnd            : end;

dcltrans
  transaction TInit
  begin
    fScale := AttributeGetDouble("scale");
  end TInit;

  transaction TMon
  var
    n : number;
    f : float;
  begin
    n := rRand;
    MonitorInc(1, n);

    f := rRandf;
    f := f * fScale;
    MonitorIncFloat(2, f);
  end TMon;
  6. Edit the .conf file. The sample .conf file is available in the Project tree under the Data Files node. Double-click the .conf file to open it and change the value of the Type entry. This indicates where in the Performance Explorer hierarchy the project is to be located. For example, use <Type>Monitoring\Sample Project</Type> to locate the monitoring project in Performance Explorer under Monitor > Add DataSource > Predefined data sources at the location Monitoring\Sample Project.
  7. Export the project to a single ZIP archive. Choose File > Export Project. Check the Zip to single archive file check box. For the Export location, set C:\Program Files\Silk\Silk Performer <version>\Monitors\BdlMonitorSample.sep.
    Note: Save the file with an .sep extension.
  8. Start a Realtime BDL Monitoring Project
    1. Start Performance Explorer. On the Monitoring tab, in the Monitor group, click System. Select the Select from predefined Data Sources option button and click Next.
    2. Select the newly created monitoring project (for example, Monitoring > Sample Project) and click Next.
    3. Enter the name of the host that is to be monitored (select localhost or the host recommended by Performance Explorer and click Next). This brings up a dialog on which project attributes can be modified (only one attribute can be modified in this instance).
    4. Enter a value greater than 0. This value will be used in the monitoring project. See the sample script for details.
    5. Click OK. This brings up a choice of measures specified in the BDL monitoring project.
    6. Select both measures and click Finish. This launches the monitoring project. The values can now be seen in real-time using a monitoring graph.
Parent topic: Generating BDL Monitoring Projects


Performance Data Collection Engine (PDCE)

The Performance Data Collection Engine (PDCE) is a module inside the Performance Explorer engine that is used for querying monitoring data in real-time. Its functionality can alternately be accessed through the Benchmark Description Language (BDL). The BDL interface for the PDCE is described in the pdce.bdh include file.

Each of the measurements that Performance Explorer monitors can alternately be monitored via Silk Performer using BDL scripts. After registering measurements of interest, a monitoring data set can be retrieved from the PDCE via the provided polling functions (PDCE API). These functions provide data, status information, and descriptions of the measurements (if available).

Parent topic: Generating BDL Monitoring Projects
Related reference
PDCE Functions Overview


Tutorial

This tutorial consists of two use cases: (1) a simple use case to get you started and (2) an advanced use case. The first use case involves a monitor project that consists of one user group with a single transaction and a single measure.

The second use case illustrates how to have several user groups, transactions, and measures in a single project.

  • Basic Use Case
    In this use case you will create a project that keeps track of the number of processes running on a SunOs.
  • Advanced Use Case
    This use case includes a project with two user groups, the user group from the previous use case and a new user group that measures HTTP requests. The two URLs and host are configurable through project attributes.
Parent topic: Generating BDL Monitoring Projects


Basic Use Case

In this use case you will create a project that keeps track of the number of processes running on a SunOs. SunOs can usually be accessed through remote execution. Compare with the Win2000 command line tool rexec. To count the number of processes running on a SunOs, execute 'ps -ef | egrep -c ".*"' within an X-Terminal, Telnet session, rexec, or other preferred tool. For example, at a DOS prompt type: c:\>rexec yourSunHost -l username "ps -ef | egrep -c \".*\""

This returns the number of processes running on your SunHost. The goal here is to continuously track and display this value in a Performance Explorer real-time chart.

  • Creating a New Project
    Create a new project of application type Monitoring/Bdl Monitor for Performance Explorer as explained earlier in this section.
  • Planning Project Attributes
  • Creating a BDL Monitoring Script
    Explains that three functions are required to remotely execute certain command line tools in BDL.
  • Packaging the BDL Monitoring Script
  • Using the Monitoring Project inside Performance Explorer
    Explains how to open the project and specify the host and measures to be monitored.
Parent topic: Tutorial


Creating a New Project

Create a new project of application type Monitoring/Bdl Monitor for Performance Explorer as explained earlier in this section. Enter a simple project description that reflects the overall purpose of the monitoring project to be displayed in Performance Explorer - for example, "A powerful project used to collect the number of running processes on SunOs systems."

Parent topic: Basic Use Case


Planning Project Attributes

Begin by entering a name for the measure in the project attributes, for example CountNrOfProcesses. This name will also be used in the Performance Explorer hierarchy. A hierarchy is introduced with '\'.

For example, to create this hierarchy:

OS
  Processes
     CountNrOfProcesses
     Another Counter

Specify the name of the measure as SunOs\Processes\CountNrOfProcesses.

This will be an AvgCounter (for average) counter and it should be collected by default.

These values must be transferred into the project's attributes. Open the attribute editor by choosing Project > Project Attributes.

The values in the project attributes identify a single measure. Several attributes (lines in the dialog) may be required to create a measure however. For example, all entries beginning with #BDLMonitor1 in the above example. This is how settings are defined for a measure.

The measure is now defined with a name, a type, and the setting Enabled. A second measure will begin with #BDLMonitor2 (covered in the Advanced Use Case).

Parent topic: Basic Use Case


Creating a BDL Monitoring Script

To remotely execute certain command line tools in BDL, for example "ps" on a SunOs, three functions are required:

  • Connect to a remote machine's "exec" server.
  • Send the command, to be executed on the remote machine.
  • Close the connection
// hCon will be assigned the connection handle
function Connect(/*inout*/hCon : number; sHost : string)
begin
  WebTcpipConnect(hCon, sHost, 512);
end Connect;

// Send a request to the remote execution server
// remote execution protocol:
// What does a request look like in binary:
// 00username00password00shellCommandToExecute00
// What does the response look like
// 00responseData
// sample request:
//   00root00labpass00ps -ef | egrep -c ".*"00
function Request(hCon: number; sUser: string; sPwd: string;
               sCmd: string):number
var
  sSend : string;
  sBuf  : string;
  nSize : number;
  nRec  : number;
begin
  sSend := "\h00";
  SetString(sSend, 2, sUser);
  SetString(sSend, Strlen(sUser) + 3, sPwd);
  SetString(sSend, Strlen(sUser) + Strlen(sPwd) + 4, sCmd);

  nSize := 3 + Strlen(sUser) + Strlen(sPwd)
             + Strlen(sCmd) + 1;

  WebTcpipSendBin(hCon, sSend, nSize);
  WebTcpipRecvExact(hCon, NULL, 1);
  WebTcpipRecv(hCon, sBuf, sizeof(sBuf), nRec);
  Request := number(sBuf);
end Request;

// Closes the connection to the remote exec server
function Close(hCon : number)
begin
  WebTcpipShutdown(hCon);
end Close;

A function wrapper is needed around the Silk Performer MeasureInc functions. This function can be used in all monitoring projects. A function named MonitorInc is created to access project attributes. This function accesses the attributes you specified earlier.

The MonitorInc function can also be imported from an existing bdh, bdlMonitor.bdh.

function MonitorInc(nMon : number; nVal : number)
var
  sMeasure : string;
begin
  // This will check whether the attribute
  // "#BDLMonitor1.Enabled" was set to true
  if AttributeGetBoolean("#BDLMonitor" + string(nMon)
                         + ".Enabled") then
      // If yes then let's read the name of the measure.
      // To do this we read the the project attribute
      // "#BDLMonitor1.Name" and store it
      // to a local variable named sMeasure.
      // sMeasure will have the value:
      // "SunOs\Processes\CountNrOfProcesses"
      AttributeGetString("#BDLMonitor" + string(nMon)
              + ".Name", sMeasure, sizeof(sMeasure));

      //   Set a new value for
      // "SunOs\Processes\CountNrOfProcesses"
      MeasureInc(sMeasure, nVal, MEASURE_KIND_AVERAGE);
    end;
end MonitorInc;

Now the transaction that will take the snapshot using all the functions that have been defined can be coded. This transaction also accesses the project file attributes. The goal is to later have these attributes set in Performance Explorer. For now however, to ensure that the script works, four attributes need to be added to the project attributes.

Note: Attribute names are case sensitive.
  • host: Assign it a sample value, for example sunserver
  • command: Assign it a sample value, for example ps -ef | egrep -c ".*"
  • user: Assign a sample value, for example root
  • password: Assign a sample value for testing purposes

Open the project attributes editor by choosing Project > Project Attributes and add these additional attributes. All are of type string except for the attribute password which is type password. Assign values to the attributes for testing purposes. Choose a description for each attribute that conveys the purpose of the attribute.

const
  nMeasure := 1;

dcluser
  user
    VMonitor
  transactions
    TSnap : 1;

dclfunc
.... // your functions here

dcltrans
  transaction TSnap
  var
    hCon  : number init 0;
    sHost : string;
    sCmd  : string;
    sUser : string;
    sPwd  : string;
    nVal  : number;
  begin
    AttributeGetString("host", sHost, sizeof(sHost));
    AttributeGetString("command", sCmd, sizeof(sCmd));
    AttributeGetString("user", sUser, sizeof(sUser));
    AttributeGetString("password", sPwd, sizeof(sPwd));

    Connect(hCon, sHost);
    nVal := Request(hCon, sUser, sPwd, sCmd);
    MonitorInc(nMeasure, nVal);
    Close(hCon);
  end TSnap;

The project now consists of the newly created script. Save the project and verify that it works by initiating a TryScript run. Have nVal printed or written to a log file to verify that the script works. If the script works, save and close the project.

Parent topic: Basic Use Case
Parent topic: Advanced Use Case


Packaging the BDL Monitoring Script

To export the project as a single ZIP file, go to File > Export Project. Check the zip to single archive check box and export the file to C:\Program Files\Silk\Silk Performer 10.0\Monitors\CountProcess.sep. (Note the .sep extension).

Before the .sep file can be used with Performance Explorer the .conf file for the .sep must be modified. The .conf file looks like this:

<?xml version='1.0' encoding='UTF-8'?>
<Project>
  <Type>Sample\Remote</Type>
  <Copyright>Borland</Copyright>
  <Author>Borland</Author>
  <Version>5.1</Version>
</Project>

For the type setting, specify a hierarchy separated by "\". This hierarchy will be reflected in Performance Explorer.

Parent topic: Basic Use Case


Using the Monitoring Project inside Performance Explorer

  1. Launch Performance Explorer. On the Real-Time Monitoring tab, in the Monitor group, click System. Select the Select from predefined Data Sources option button and click Next.
  2. Select the newly created monitoring project and click Next.
  3. Specify the host that is to be monitored, preferably a machine running SunOs. Click Next to bring up a dialog for setting project attributes. This dialog displays the attributes that you set (except for the host which was specified previously).

    Therefore, the dialog displays the following attributes:

    • user
    • password
    • command
  4. Select the measures (in this case only a single measure) and click OK. The measures are then immediately handed over to the data collection mechanism.
Parent topic: Basic Use Case


Advanced Use Case

This use case includes a project with two user groups, the user group from the previous use case and a new user group that measures HTTP requests. The two URLs and host are configurable through project attributes.

  • Creating a Silk Performer Project
    Enter a simple project description that is to be displayed in Performance Explorer.
  • Planning Project Attributes
  • Creating a BDL Monitoring Script
    Explains that three functions are required to remotely execute certain command line tools in BDL.
  • Packaging the Project
    Explains how to export the project as a ZIP archive and modify the CONF file.
  • Using the Monitoring Project in Performance Explorer
    Explains how to define the required Performance Explorer project attributes.
Parent topic: Tutorial


Creating a Silk Performer Project

Enter a simple project description that is to be displayed in Performance Explorer. The description should describe the overall purpose of the monitoring project. For example, a powerful project used for collecting the number of running processes on SunOs systems and measuring two configurable HTTP requests.

Parent topic: Advanced Use Case


Planning Project Attributes

For this tutorial you will plan three measures. Pick measure names that indicate the hierarchy and purpose of the measures. In this example, a measure counts the number of processes on a SunOs system and includes two measures that measure HTTP requests (Performed using WebUrl):

  • SunOs\Processes\CountNrOfProcesses
  • SunOs\Http Server\URI1
  • SunOs\Http Server\URI2

The intended hierarchy will then look like the following:

  SunOs
    Processes
      CountNrOfProcesses
    Http Server
      URI1
      URI2

A BDL script with two user groups and two transactions is written. See the table below to see how measures are assigned to transactions and how transactions relate to user groups.

User Group | Transaction | Measure
VMonitor | TSnap | CountNrOfProcesses
VWebMon | TWebSnap | URI1
VWebMon | TWebSnap | URI2

With projects that include numerous transactions and/or user groups, measures must be specified with the corresponding user group and assigned measure. This differs from the basic use case outlined previously, which involved only one transaction and one user group.

Open the project attributes editor at Projects > Project Attribute and enter the following data:

Name | Type | Value
#BDLMonitor1.Name | string | SunOs\Processes\CountNrOfProcesses
#BDLMonitor1.Type | string | AvgCounter
#BDLMonitor1.Enabled | boolean | True
#BDLMonitor1.Script | string | remote.bdf
#BDLMonitor1.Usergroup | string | VMonitor
#BDLMonitor1.Transaction | string | TSnap
#BDLMonitor2.Name | string | SunOs\Http Server\URI1
#BDLMonitor2.Type | string | AvgCounter
#BDLMonitor2.Enabled | boolean | true
#BDLMonitor2.Script | string | remote.bdf
#BDLMonitor2.Usergroup | string | VWebMon
#BDLMonitor2.Transaction | string | TWebSnap
#BDLMonitor3.Name | string | SunOs\Http Server\URI2
#BDLMonitor3.Type | string | AvgCounter
#BDLMonitor3.Enabled | boolean | True
#BDLMonitor3.Script | string | remote.bdf
#BDLMonitor3.Usergroup | string | VWebMon
#BDLMonitor3.Transaction | string | TWebSnap
host | sunserver | sunserver
command | string | ps -ef | egrep -c ".*"
user | string | root
password | password | ***********
URI1 | string | /
URI2 | string | /manual/ibm/index.html
Parent topic: Advanced Use Case


Packaging the Project

Export the project to a single ZIP file. Go to File > Export Project. Check Zip to single archive and export the file to C:\Program Files\Silk\Silk Performer\Monitors\Advanced.sep (note the SEP file extension).

Before the SEP file can be used with Performance Explorer, the CONF file for the SEP must be modified. The CONF file appears as:

<?xml version='1.0' encoding='UTF-8'?>
<Project>
  <Type>Sample\Advanced\HttpHit</Type>
  <Copyright>Borland</Copyright>
  <Author>Borland</Author>
  <Version>5.1</Version>
</Project>

For the type setting, specify a hierarchy that is to be reflected in Performance Explorer, separated by backward slashes ("\").

Parent topic: Advanced Use Case


Using the Monitoring Project in Performance Explorer

  1. Start Performance Explorer. On the Real-Time Monitoring tab, in the Monitor group, click System. Choose Select from predefined Data Sources.
  2. Select the newly created monitoring project and click Next.
  3. Enter the name of the server that is to be monitored. For example, enter sunserver and click Next. A dialog box appears. Define the following attributes:
    • command: As with the basic test case you set up earlier in this tutorial, a command that counts the number of processes.
    • user: A valid user account for accessing the remote machine.
    • password: The password.
    • URI1: The URI where response time is to be measured.
    • URI2: A second URI where response time is to be measured.
  4. Select the measures (in this case there is only one) and click OK. The measures are immediately handed over to the data collection mechanism. The choice corresponds to the hierarchy defined in the project attributes.
Parent topic: Advanced Use Case


Best Practices

This section outlines suggestions for working with real-time monitoring projects as relates to the writing of monitoring scripts.

  • Loops
    Explains that Performance Explorer assumes that transactions will be executed within a single interval. Otherwise Performance Explorer returns a warning message.
  • ThinkTimes and Wait
    Explains that monitoring transactions must be executed within a given interval.
  • Initialization
    Explains that you should not place function calls in TInit transactions that may stop runtime.
  • Other Best Practices
    Explains other best practices related to name length, Try Script runs, and special project attributes.
Parent topic: Generating BDL Monitoring Projects


Loops

Performance Explorer executes transactions that run snapshots at regular intervals. For example, a snapshot transaction might be executed every 10 seconds. In such a case, Performance Explorer assumes that the entire transaction is executed within this one interval. Otherwise Performance Explorer returns a warning stating that it can not collect the interval's snapshot.

Do not use endless loops such as the following:

// Forbidden
transaction TSnap
begin
  while true do
    Snap();
  end;
end TSnap;
Parent topic: Best Practices


ThinkTimes and Wait

Be careful with wait statements. Think-times are ignored. A monitoring transaction must be executed within a given interval. Wait statements block execution and transactions may not return on time.

Example

// Forbidden
transaction TSnap
begin
  wait 500000.0;
end TSnap;
Parent topic: Best Practices


Initialization

Do not place function calls in TInit transactions that may stop runtime. For example, OraLogon may generate a ProcessExit on a failed logon. Performance Explorer will not catch this message and will assume that the project is still running. Of course, Performance Explorer will report that it cannot gather data, but it will not be able to report why this is happening.

Parent topic: Best Practices


Other Best Practices

Name Length

Attribute value lengths must not exceed 79 characters.

Performing a Try Script run for the Project

Execute a Try Script run to verify that the project is working before you create an SEP file.

Special Project Attributes

The monitoring-project attribute host can be accessed within BDL scripts using the following function call: AttributeGetString("host", sHost, sizeof(sHost));

Instead of host, an attribute called #MonitorHost may also be queried. Those two attributes are treated equally.

In Performance Explorer the value for this attribute is set using the following dialog:

Parent topic: Best Practices


Monitoring Data Sources

Before you can start monitoring a system with Performance Explorer, you need to specify the system and the measures. There are two ways to do so:
  • You can select a predefined data source.

    Performance Explorer provides predefined data sources for the most popular web servers, application servers, database servers, and operating systems. You are not restricted to using only these data sources. These data sources are included to speed the selection process for measures that are to be monitored.

  • You can use the data source scanner to detect data sources.

    The Data Source Scanner checks your system for a variety of data sources that are commonly found on a range of platforms and returns a list of available data sources.

To specify a system, click System in the Monitor group on the Real-Time Monitoring tab and follow the wizard.

  • Predefined Data Sources
    Performance Explorer provides a wizard that guides you through the setup process for each server type that Performance Explorer can monitor.
  • Custom Data Sources
    Lists the custom monitoring interfaces that are available for Performance Explorer.
  • Automatic Detection of Data Sources
    Describes how Performance Explorer automatically detects data sources that can be monitored.
Parent topic: Real-Time Monitoring


Predefined Data Sources

Performance Explorer provides a wizard that guides you through the setup process for each server type that Performance Explorer can monitor.

  • Enabling Monitoring for Apache Servers
    Monitor detailed information and enable status reports from a specific domain for Apache servers.
  • Enabling SNMP Support for Silverstream Servers
    Monitor the Silverstream application server on Windows NT using SNMP.
  • Monitoring Silk Central Performance
    Establish a connection to a data source to monitor a Silk Central application server and front-end server and to create an initial view that contains the measures you want to monitor.
  • IBM DB2 Performance Monitoring
    Provides an overview of retrieving performance metrics from IBM DB2 database systems.
  • IBM WebSphere Application Server Monitoring
    Lists the IBM WebSphere application servers that can be monitored.
  • Internet Information Server (IIS) Performance Monitoring
    Provides an overview of retrieving performance metrics from Internet Information Server.
  • Microsoft SQL Server Performance Monitoring
    Provides an overview of retrieving performance metrics from Microsoft SQL Server.
  • Oracle Forms Performance Monitoring
    Provides an overview of retrieving performance metrics from Oracle Forms database systems.
  • Oracle Performance Monitoring
    Provides an overview of retrieving performance metrics from Oracle database systems.
  • SAP Performance Monitoring
    Establish a connection to a data source to monitor SAP systems and to create an initial view that contains the measures you want to monitor.
  • WebLogic (SNMP) Monitoring
    Provides an overview of monitoring support for BEA WebLogic by using SNMP and explains important WebLogic performance measures.
  • WebLogic (JMX) Monitoring
    This section explains prerequisites for monitoring WebLogic (JMX) Server, including configuring IIOP and JMX Management Server.
Parent topic: Monitoring Data Sources


Enabling Monitoring for Apache Servers

With Apache Web servers, you have the option of using the built-in status report functionality. This functionality requires that a mod_status module be built in, which is done by default.

  1. Click the ExtendedStatus On option button to view more detailed information.
  2. Add code to the configuration file access.conf to enable status reports only for browsers from the foo.com domain. The Apache configuration is maintained in a set of files typically located in /usr/local/apache/etc or /usr/local/apache/conf (Solaris) or /etc/httpd/conf (Linux).
  3. Add the following code to the main Apache configuration file, httpd.conf.
    <Location /server-status> SetHandler server-status
order deny, allow deny from all allow from .foo.com
</Location>
    If this code already exists but is commented out, un-comment it.
    Note: For monitoring to function appropriately, all allow statements must be correct.
  4. Restart your server.
  5. To verify the server's performance module, type the URL http://<hostname>/server-status?auto into your browser. Monitoring is enabled if you receive a response like the following message:
    Total Accesses: 210
Total kBytes: 94
CPULoad: .000278279
Uptime: 366539
ReqPerSec: .000572927
BytesPerSec: .262608
BytesPerReq: 458.362
BusyServers: 1
IdleServers: 6
Scoreboard: ______W.................................................................................
    Note: The default Apache monitor works only if Telnet is enabled. To monitor an Apache server with Telnet disabled, use the WGet command instead of the default Rexec commands, as the following example shows.
    wget -q -O - http://<hostname>/server-status | grep
"requests/sec" | cut -c5- | cut -d\ -f1
Parent topic: Predefined Data Sources


Enabling SNMP Support for Silverstream Servers

  1. Run SilverStream designer.
  2. Choose SilverMaster3 database > Objects .
  3. Open AgSNMPGetStats in design mode.
  4. Double-click the trigger icon. The Properties page opens.
  5. Set the Enabled option to true.
  6. Save the changes and close the file.
Parent topic: Predefined Data Sources


Monitoring Silk Central Performance

Use Performance Explorer to monitor performance and reliability metrics of a Silk Central application server and front-end server.

  1. On the Real-Time Monitoring tab, in the Monitor group, click System. The Data Source wizard opens.
  2. Click the Select from predefined Data Sources option button.
  3. Click Next. The System selection page opens.
  4. Expand the Silk folder and the Silk Central folder with the version that you want to monitor, then select application server or front-end server.
  5. Click Next.

    The Connection parameters page opens.

  6. Specify the following settings:
    • In the Hostname text box, specify the host name or IP address on which Silk Central is running.
    • Optional: In the Alias text box, specify an alias for the server which is monitored.
    • If Silk Central does not listen on the default port, specify the JMX port number in the Port text box.
    • If JMX authentication is enabled, enter the Username and Password. Per default JMX authentication is disabled and Username and Password should be empty.
    Note: Make sure that your local firewall is turned off or that ports 19140 and 19142 are allowed to communicate through the firewall.
  7. Click Next. The JMX Data Source Browser opens.
  8. Select the measures that you want to include in the initial monitor view and click Add. When you are done adding the measures, click Close.
    Tip: Select the Simple Query tab and filter the measures by borland.com to quickly access the relevant Silk Central measures.
    The Select displayed measures page opens.
  9. Check the check boxes for those measures that you want to include in the initial monitor view and then click Finish.
A connection to the specified host is established, and an initial view that contains the measures you selected is displayed.
Parent topic: Predefined Data Sources


IBM DB2 Performance Monitoring

Use Performance Explorer to retrieve performance metrics from IBM DB2 database systems no matter the database platform. For example, the database can run on a SunOs, Linux, or a Windows system.

With Performance Explorer, you can monitor DB2 database systems in a platform-independent way. To accomplish this task, execute a DB2-specific command for retrieving a database's performance and utilization measures and drive a Silk Performer project inside Performance Explorer. This approach also allows Performance Explorer to keep track of the database system's performance in real time.

The Silk Performer project is located in a Essential package named DB2Monitor.sep, which is located at C:\Program Files\Silk\Silk Performer 21.0\Monitors.

  • Prerequisites for DB2 Monitoring
    Lists the prerequisites for DB2 monitoring.
  • Testing DB2 Snapshot Monitoring
    Test DB2 snapshot monitoring using DB2 Commandline processor or DB2 Command Center.
  • Retrieving IBM DB2 Performance Metrics
    Establish a connection to a data source to monitor IBM DB2 DBMS systems and to create an initial view that contains the measures you want to monitor.
Parent topic: Predefined Data Sources


Prerequisites for DB2 Monitoring

To monitor DB2, ensure that your environment meets the following requirements:
  • IBM DB2 client software (DB2 Connect) must be installed on the machine on which you intend to run Performance Explorer.
  • The DB2 command line processor, db2cmd.exe, must be installed as part of the client installation. This prerequisite is met by default.
  • The appropriate DB2 database user must possess one of the following authorizations:
    • sysadm
    • sysctrl
    • sysmaint
  • DB2 snapshot monitoring must be set up correctly.
Parent topic: IBM DB2 Performance Monitoring


Testing DB2 Snapshot Monitoring

  1. Connect to a DB2 database. db2 command:

    => connect to sample user <dbusername> using <password>

  2. Attach to a DB2 instance. db2 command:

    => attach to <db2instancename> user <dbusername> using <dbusername>

  3. Check if monitor switches are on. db2 command:

    => get monitor switches

    Monitor Recording Switches

    Switch list for node 0

    Buffer Pool Activity Information (BUFFERPOOL) = ON 02-06-2002
18:27:48.722132
Lock Information (LOCK) = ON 02-06-2002
18:28:00.095212
Sorting Information (SORT) = ON 02-06-2002
18:28:12.263183
SQL Statement Information (STATEMENT) = ON 02-06-2002
18:28:24.323446
Table Activity Information (TABLE) = OFF
Unit of Work Information (UOW) = OFF
  4. Turn on switches. db2 commands:

    => update monitor switches using bufferpool on

    => update monitor switches using lock on

    => update monitor switches using sort on

  5. Retrieve data from the DB2 UDB system monitor snapshot. db2 command:

    => get snapshot for all databases

    Database Snapshot:

    Database name = SAMPLE
Database path = /home/db2inst1/db2inst1/
NODE0000/SQL00001/
Input database alias =
Database status = Active
Catalog node number = 0
Catalog network node name =
Operating system running at database server= LINUX
Location of the database = Remote
First database connect timestamp = 02-06-2002 18:01:31.198883
Last reset timestamp =
Last backup timestamp =
Snapshot timestamp = 02-06-2002 18:37:39.254985
High water mark for connections = 1
Application connects = 1
Secondary connects total = 0
Applications connected currently = 1
Appls. executing in db manager currently = 0
Agents associated with applications = 1
Maximum agents associated with applications= 1
Maximum coordinating agents = 1
Locks held currently = 0
Lock waits = 0
Time database waited on locks (ms) = 0
Lock list memory in use (Bytes) = 792
Deadlocks detected = 0
Lock escalations = 0
Exclusive lock escalations = 0
Agents currently waiting on locks = 0
Lock Timeouts = 0
Total sort heap allocated = 0
Total sorts = 0
Total sort time (ms) = 0
Sort overflows = 0
Active sorts = 0
Buffer pool data logical reads = 0
Buffer pool data physical reads = 0
Asynchronous pool data page reads = 0
Buffer pool data writes = 0
Asynchronous pool data page writes = 0
Buffer pool index logical reads = 0
Buffer pool index physical reads = 0
Asynchronous pool index page reads = 0
Buffer pool index writes = 0
Asynchronous pool index page writes = 0
Total buffer pool read time (ms) = 0
Total buffer pool write time (ms) = 0
Total elapsed asynchronous read time = 0
Total elapsed asynchronous write time = 0
Asynchronous read requests = 0
LSN Gap cleaner triggers = 0
Dirty page steal cleaner triggers = 0
Dirty page threshold cleaner triggers = 0
Time waited for prefetch (ms) = 0
Direct reads = 0
Direct writes = 0
Direct read requests = 0
Direct write requests = 0
Direct reads elapsed time (ms) = 0
Direct write elapsed time (ms) = 0
Database files closed = 0
Data pages copied to extended storage = 0
Index pages copied to extended storage = 0
Data pages copied from extended storage = 0
Index pages copied from extended storage = 0
Host execution elapsed time = 0.000000
Commit statements attempted = 1
Rollback statements attempted = 0
Dynamic statements attempted = 0
Static statements attempted = 1
Failed statement operations = 0
Select SQL statements executed = 0
Update/Insert/Delete statements executed = 0
DDL statements executed = 0
Internal automatic rebinds = 0
Internal rows deleted = 0
Internal rows inserted = 0
Internal rows updated = 0
Internal commits = 1
Internal rollbacks = 0
Internal rollbacks due to deadlock = 0
Rows deleted = 0
Rows inserted = 0
Rows updated = 0
Rows selected = 0
Rows read = 9
Binds/precompiles attempted = 0
Log space available to the database (Bytes)= 20400000
Log space used by the database (Bytes) = 0
Maximum secondary log space used (Bytes) = 0
Maximum total log space used (Bytes) = 0
Secondary logs allocated currently = 0
Log pages read = 0
Log pages written = 0
Appl id holding the oldest transaction = 0
Package cache lookups = 0
Package cache inserts = 0
Package cache overflows = 0
Package cache high water mark (Bytes) = 51824
Application section lookups = 0
Application section inserts = 0
Catalog cache lookups = 0
Catalog cache inserts = 0
Catalog cache overflows = 0
Catalog cache heap full = 0
Number of hash joins = 0
Number of hash loops = 0
Number of hash join overflows = 0
Number of small hash join overflows = 0
Parent topic: IBM DB2 Performance Monitoring


Retrieving IBM DB2 Performance Metrics

Establish a connection to a data source to monitor IBM DB2 DBMS systems and to create an initial view that contains the measures you want to monitor.

  1. On the Real-Time Monitoring tab, in the Monitor group, click System. The Data Source wizard opens.
  2. Click the Select from predefined Data Sources option button.
  3. Click Next. The System selection page opens.
  4. Expand the Database System folder and select IBM Universal Database DB2 (snapshot dll).
  5. Click Next.

    The Connection parameters page opens.

  6. In the Hostname text box, specify the host on which the DB2 database is running.
  7. Click Next. The Attributes Configuration page opens.
  8. Define the following monitoring-specific attributes:
    • Alias – The database alias is used by the monitoring project in the following DB2-specific command: "connect to 'alias' user 'user' using 'password'".
    • Instance – The instance name is used by the monitoring project for executing the following DB2-specific command: "attach to 'Instance' user 'user' using 'password'".
    • User – Specify a user with the following DB2 authorizations:
      • sysadm
      • sysctrl
      • sysmaint
    • Password – The password for the user.
  9. Click OK. The Select displayed measures page opens.
  10. Check the check boxes for those measures that you want to include in the initial monitor view and then click Finish.
A connection to the specified host is established, and an initial view that contains the measures you selected is displayed.
Parent topic: IBM DB2 Performance Monitoring


IBM WebSphere Application Server Monitoring

With Performance Explorer, you can monitor the following IBM WebSphere application servers:
  • IBM WebSphere Application Server 6.1 via JMX
  • IBM WebSphere Application Server 7.0 via JMX
  • IBM WebSphere Application Server 8.0 via JMX
  • IBM WebSphere Application Server 8.5 via JMX
  • Typical Performance Measures on WebSphere Application Server 6.1
    Displays typical performance measures and definitions for WebSphere application servers.
  • Monitoring IBM WebSphere Application Server
    Explains how to specify the Java Home directory setting and define additional JVM parameters.
Parent topic: Predefined Data Sources


Typical Performance Measures on WebSphere Application Server 6.1

The following table displays typical performance measures and definitions for WebSphere application server.

Performance Measure | Description
BeanModule | Specific data about deployed EJBs, such as how many beans were created.
ConnectionPoolModule | Contains performance counters about JDBC connections, like how many JDBC connections are currently in the pool.
JvmRuntimeModule | Java Virtual Machine specific performance counters.
ServletSessionModule | Contains performance counters about servlet sessions, such as how many sessions are active or the average session live time.
TransactionModule | Contains performance counters providing information about how many transactions are in progress or the average time required to execute one transaction.
WebApplicationModule | Provides information about deployed servlets and JSPs, such as the average time required for the servlet to process requests.
Parent topic: IBM WebSphere Application Server Monitoring


Monitoring IBM WebSphere Application Server

  1. On the Real-Time Monitoring tab, in the Monitor group, click System. The Data Source wizard opens.
  2. Click the Select from predefinded Data Sources option button.
  3. Click Next. The System selection page opens.
  4. Expand the Application Server folder and the IBM WebSphere Application Server folder.
  5. Click the IBM WebSphere <version> (JMX MBean Server) node and then click Next. The Connection parameters page opens.
  6. In the Hostname field, specify the host on which WebSphere is running.
  7. In the User and Password fields, specify a user with administrator permissions for the above specified host.
  8. Optional: In the Alias field, specify an alias for the monitored server.
  9. Click Server Configuration... The JMX Connection Configuration window opens.
  10. Specify the Java Home directory and the Application Server install directory. Use a UNC path (for example, \\<server name>\c$\IBM\WebSphere\AppServer\java).
    Note: If you cannot specify a UNC path, copy the application server installation directory to your local machine and specify a local path.
  11. Specify additional JVM parameters based on WebSphere security settings.
    JVM vendor

    Security settings

            IBM SUN
    Disabled administrative security Without additional JVM parameters Without additional JVM parameters
    Enabled administrative security

    Inbound CSIv2 Transport Layer = TCP/IP

            Additional JVM parameter: -Dcom.ibm.CORBA.ConfigURL

    (already predefined)

            Additional JVM parameter: -Dcom.ibm.CORBA.ConfigURL

    (predefined)

    Enabled administrative security

    Inbound CSIv2 Transport Layer = SSL-supported

            Additional JVM parameters: -Dcom.ibm.CORBA.ConfigURL (predefined) -Dcom.ibm.SSL.ConfigURL Does not work
    Enabled administrative security

    Inbound CSIv2Transport Layer = SSL-required

            Additional JVM parameters: -Dcom.ibm.CORBA.ConfigURL (already predefined)

    -Dcom.ibm.SSL.ConfigURL

            Does not work
    Note: If your WebSphere server has enabled administrative security and the inbound CSIv2 transport layer is SSL-supported (or SSL-required), copy the application server installation directory to your local machine. Specify Additional JVM parameters according to the table above. The Additional JVM parameters field holds the predefined parameter -Dcom.ibm.CORBA.ConfigURL.

    The value for the -Dcom.ibm.CORBA.ConfigURL parameter must be the URL path to the file sas.client.props. The default sas.client.props file is located in the folder %INSTALL_DIR%/Include/jmx-config/WebSphere%MAJOR_VERSION%. For example: For WebSphere 7, the URL path is C:\Program%20Files%20(x86)\Silk\Silk%20Performer%2010.0\Include\jmx-config\WebSphere7. If your server has specific settings, you can use the sas.client.props file from the properties folder of the WebSphere profile. For Example: file:/C:\Program%20Files%20(x86)\IBM\WebSphere\AppServer1\profiles\AppSrv01\properties\sas.client.props

    Pay attention to the following two variables and their values in your sas.client.props file: com.ibm.CSI.performTransportAssocSSLTLSRequired=false and com.ibm.CSI.performTransportAssocSSLTLSSupported=true

    The value for the -Dcom.ibm.SSL.ConfigURL parameter must be the URL path to the file ssl.client.props, which is found in the properties folder of the WebSphere profile. For example: file:/C:\Program%20Files%20 (x86)\IBM\WebSphere\AppServer1\profiles\AppSrv01\properties\ssl.client.props.

    Pay attention to the variable user.root in the file ssl.client.props. It must contain the valid path to the profile folder with the etc directory that contains the key- and trust-files. Blanks in the URL path to the files sas.client.props and ssl.client.props must be replaced with %20.

  12. Click OK.
  13. Click Next. The JMX Data Source Browser opens.
  14. Choose MBeans for those measures that you want to include in the initial monitor view. Select the type of measures (Average, Sum, or Incremental) and click Add.
  15. Click Close. The Select displayed measures page opens.
  16. Check the checkboxes for those measures that you want to include in the initial monitor view.
  17. Click Finish.
Parent topic: IBM WebSphere Application Server Monitoring


Internet Information Server (IIS) Performance Monitoring

  • Monitoring Internet Information Services (IIS)
    To set up monitoring for IIS you need to select the System Statistics (PERFMON) data source, enter host login credentials, and select the measures to be monitored.
  • Available IIS Performance Measures
    Lists the Web Service and Web Service cache performance measures that are available for IIS.
  • Troubleshooting IIS Monitoring
    Explains how to find solutions for issues with x64/x86 counters and W3SVC_W3WP.
Parent topic: Predefined Data Sources


Monitoring Internet Information Services (IIS)

  1. On the Real-Time Monitoring tab, in the Monitor group, click System. The Data Source wizard opens.
  2. Click the Select from predefined Data Sources option button.
  3. Click Next. The System selection page opens.
  4. Expand the Web Server folder and the IIS <version> folder.
  5. Click the System Statistics (PERFMON) node and then click Next. The Connection parameters page opens.
  6. In the Hostname text box, specify the host on which IIS is running.
  7. In the User and Password text boxes, specify a user with administrator permissions on the above-specified host.
  8. Optional: In the Alias text box, specify an alias for the monitored server.
  9. Click Next. The Select displayed measures page opens.
  10. Check the check boxes for those measures that you want to include in the initial monitor view.
  11. Click Finish.
Parent topic: Internet Information Server (IIS) Performance Monitoring


Available IIS Performance Measures

Performance Measures on IIS 6.0

Measures can be divided into several groups according to perfmon objects.

Web Service Measures
  • Web Service(_Total)\Bytes Received/sec

    Rate of total bytes transferred by service (received)

  • Web Service(_Total)\Bytes Sent/sec

    Rate of total bytes transferred by service (sent)

  • Web Service(_Total)\Bytes Total/sec

    Rate of total bytes transferred by service (sum of bytes sent and received)

  • Web Service(_Total)\Current Connections

    Current number of connections to the service

  • Web Service(_Total)\Get Requests/sec

    Total number of HTTP GET requests received by WWW service

  • Web Service(_Total)\Post Requests/sec

    Number of HTTP requests using POST method

Web Service Cache Measures
  • Web Service Cache(_Total)\Current Files Cached

    Current number of files whose content is in the user-mode cache

  • Web Service Cache(_Total)\Current Metadata Cached

    Current number of metadata information blocks currently in the user-mode cache.

  • Web Service Cache(_Total)\Current URIs Cached

    URI information blocks currently in the user-mode cache

  • Web Service Cache(_Total)\File Cache Hits %

    The ratio of user-mode file cache hits to total cache requests (since service startup). Note: This value might be low if the Kernel URI cache hits percentage is high.

  • Web Service Cache(_Total)\Metadata Cache Hits

    The ratio of user-mode metadata cache hits to total cache requests (since service startup)

  • Web Service Cache(_Total)\URI Cache Hits %

    The ratio of user-mode URI Cache Hits to total cache requests (since service startup)

  • Web Service Cache(_Total)\Kernel:URI Cache Hits %

    Applies to static unauthenticated content and dynamic content that is marked as cacheable

Performance Measures on IIS 7.0, 7.5

All IIS 6.0 measures are available for IIS 7.0/7.5, but in IIS7 there are additional performance counters that give you insight into worker processes level at runtime.

Web Service Measures - Same as IIS 6.0.

Web Service Cache Measures - Same as IIS 6.0.

W3SVC_W3WP Cache Measures
  • W3SVC_W3WP(_Total)\Requests / Sec

    HTTP requests/sec being processed by the worker process

  • W3SVC_W3WP(_Total)\Active Requests

    Current number of requests being processed by the worker process

  • W3SVC_W3WP(_Total)\Active Threads Count

    Number of threads actively processing requests in the worker process

  • W3SVC_W3WP(_Total)\Current File Cache Memory Usage

    Current number of bytes used by user-mode file cache

  • W3SVC_W3WP(_Total)\Current Files Cached

    Current number of files whose contents are present in user-mode cache

  • W3SVC_W3WP(_Total)\Current URIs Cached

    URI information blocks currently in the user-mode cache

  • W3SVC_W3WP(_Total)\Current Metadata Cached

    Number of metadata information blocks currently present in user-mode cache

  • W3SVC_W3WP(_Total)\Metadata Cache Hits

    Total number of successful lookups in the user-mode metadata cache (since service startup)

  • W3SVC_W3WP(_Total)\Metadata Cache Misses

    Total number of unsuccessful lookups in the user-mode metadata cache (since service startup)

  • W3SVC_W3WP(_Total)\Metadata Cache Flushes

    Total number of user-mode metadata cache flushes (since service startup)

  • W3SVC_W3WP(_Total)\File Cache Hits / sec

    Rate of successful lookups in file cache during last sample interval

  • W3SVC_W3WP(_Total)\File Cache Misses / sec

    Rate of unsuccessful lookups in file cache during last sample interval

  • W3SVC_W3WP(_Total)\Metadata Cache Hits / sec

    Rate of successful lookups in metadata cache during last sample interval

  • W3SVC_W3WP(_Total)\Metadata Cache Misses / sec

    Rate of unsuccessful lookups in metadata cache during last sample interval

  • W3SVC_W3WP(_Total)\Uri Cache Hits / sec

    Rate of successful lookups in URI cache during last sample interval

  • W3SVC_W3WP(_Total)\Uri Cache Misses / sec

    Rate of unsuccessful lookups in URI cache during last sample interval

Parent topic: Internet Information Server (IIS) Performance Monitoring


Troubleshooting IIS Monitoring

Issues With x64/x86 Counters

For support, please refer to http://support.microsoft.com/kb/891238.

Issues With W3SVC_W3WP

Note that this group of counters monitors worker processes at runtime. So when no workers are running, this group of counters returns NULL values.

Parent topic: Internet Information Server (IIS) Performance Monitoring


Microsoft SQL Server Performance Monitoring

  • Monitoring Microsoft SQL Server
  • Available Microsoft SQL Server Performance Measures
    Microsoft SQL Server
Parent topic: Predefined Data Sources


Monitoring Microsoft SQL Server

  1. On the Real-Time Monitoring tab, in the Monitor group, click System. The Data Source wizard opens.
  2. Click the Select from predefined Data Sources option button.
  3. Click Next. The System selection page opens.
  4. Expand the Database System folder and the SQL Server <version> folder.
  5. Click the System Statistics (PERFMON) node and then click Next. The Connection parameters page opens.
  6. In the Hostname text box, specify the host on which SQL Server is running.
  7. In the User and Password text boxes, specify a user with administrator permissions on the above-specified host.
  8. Optional: In the Alias text box, specify an alias for the monitored server.
  9. Click Next. The Select displayed measures page opens.
  10. Check the check boxes for those measures that you want to include in the initial monitor view.
  11. Click Finish.
Parent topic: Microsoft SQL Server Performance Monitoring


Available Microsoft SQL Server Performance Measures

Performance Measures on Microsoft SQL Server 2005

The following metrics can be monitored on Microsoft SQL Server 2005 systems:

  • Process(sqlservr)\% Processor Time

    % Processor Time is the percentage of elapsed time that all of the threads of this process used the processor to execute instructions.

  • SQLServer:Access Methods\Full Scans/sec

    Number of unrestricted full scans. These can either be base table or full index scans.

  • SQLServer:Access Methods\Index Searches/sec

    Number of index searches. Index searches are used to start range scans, single index record fetches, and to reposition within an index.

  • SQLServer:Access Methods\Table Lock Escalations/sec

    The number of times locks on a table were escalated.

  • SQLServer:Buffer Manager\Buffer cache hit ratio

    Percentage of pages found in the buffer cache without having to read from disk.

  • SQLServer:Buffer Manager\Checkpoint pages/sec

    Number of pages flushed by checkpoint or other operations that require all dirty pages to be flushed.

  • SQLServer:Buffer Manager\Lazy writes/sec

    Number of buffers written by buffer manager's lazy writer.

  • SQLServer:Buffer Manager\Page lookups/sec

    Number of requests to find a page in the buffer pool.

  • SQLServer:Buffer Manager\Page reads/sec

    Number of physical database page reads issued.

  • SQLServer:Buffer Manager\Page writes/sec

    Number of physical database page writes issued.

  • SQLServer:Buffer Manager\Readahead pages/sec

    Number of pages read in anticipation of use.

  • SQLServer:Cursor Manager by Type\Active cursors

    Number of active cursors.

  • SQLServer:Cursor Manager by Type\Cursor memory usage

    Amount of memory consumed by cursors in kilobytes (KB).

  • SQL Server:Databases\ Active Transactions

    Number of active update transactions for the database.

  • SQL Server:Databases\ Shrink Data Movement Bytes/sec

    The rate data is being moved by Autoshrink, DBCC SHRINKDATABASE or SHRINKFILE.

  • SQL Server:Databases\ Transactions/sec

    Number of transactions started for the database.

  • SQLServer:General Statistics\User Connections

    Number of users connected to the system.

  • SQLServer:Locks(_Total)\Average Wait Time (ms)

    The average amount of wait time (milliseconds) for each lock request that resulted in a wait.

  • SQLServer:Locks(_Total)\Lock Waits/sec

    Number of lock requests that could not be satisfied immediately and required the caller to wait before being granted the lock.

  • SQLServer:Locks(_Total)\Number of Deadlocks/sec

    Number of lock requests that resulted in a deadlock.

  • SQLServer:Memory Manager\Target Server Memory (KB)

    Total amount of dynamic memory the server is willing to consume.

  • SQLServer:Memory Manager\Total Server Memory (KB)

    Total amount of dynamic memory the server is currently consuming.

  • SQLServer:SQL Statistics\Batch Requests/sec

    Number of SQL batch requests received by server.

  • SQLServer:SQL Statistics\SQL Compilations/sec

    The number of SQL compilations per second.

  • SQLServer:SQL Statistics\SQL Re-Compilations/sec

    The number of SQL re-compiles per second.

  • SQLServer:Transactions\Free Space in tempdb (KB)

    The amount of space (in kilobytes) available in tempdb. There must be enough free space to hold both the snapshot isolation level version store and all new temporary objects created in this instance of the database engine.

  • SQLServer:Transactions\Transactions

    The number of currently active transactions of all types.

Performance Measures on Microsoft SQL Server 2008, 2008 R2

All Microsoft SQL Server 2005 counters are still available in Microsoft SQL Server 2008 and 2008 R2 systems. Additional metrics are also available:

  • SQL Server:Databases\Tracked transactions/sec

    Number of committed transactions recorded in the commit table for the database.

  • SQL Server: Databases\Write Transactions/sec

    Number of transactions which wrote to the database in the last second.

  • SQL Server: General Statistics\Connection reset/sec

    Total number of connection resets per second.

  • SQL Server: General Statistics\Tempdb rowset id

    Number of duplicate tempdb rowset id generated

  • SQL Server: SQL Statistics\Misguided plan executions/sec

    Number of plan executions per second in which a plan guide could not be honored during plan generation

  • SQL Server: SQL Statistics\Guided plan executions/sec

    Number of plan executions per second in which the query plan has been generated by using a plan guide.

Parent topic: Microsoft SQL Server Performance Monitoring


Oracle Forms Performance Monitoring

Use Performance Explorer to retrieve performance metrics from Oracle Forms Dynamic Monitoring System (DMS). Performance Explorer can monitor the DMS performance Web page that is provided through the Oracle Forms HTTP server when the DMS module is installed.

Web page requests and the parsing of performance metrics are achieved by driving a Silk Performer project through Performance Explorer. This approach allows you to keep track of application server performance in real time.

The Silk Performer project is located in a SilkEssential package named OraFormsDMS.sep, which is located at C:\Program Files\Silk\Silk Performer 21.0\Monitors.

The Oracle Forms application architecture includes three tiers:
  • Oracle database
  • Oracle application server
  • Client applet

Performance Explorer should be used to gather server-side measures from the database and application servers.

To monitor the database server a set of predefined Oracle database measures is available.

  • Prerequisites for Oracle Forms Monitoring
    Lists the prerequisites for Oracle Forms monitoring.
  • Monitoring Oracle Forms
    Establish a connection to a data source to monitor an Oracle Forms DMS and to create an initial view that contains the measures you want to monitor.
  • Oracle Forms Client-Side Measures
    Explains that client-side measures are automatically generated by load test agents during Oracle Forms load tests.
Parent topic: Predefined Data Sources
Related concepts
Oracle Forms / Oracle Applications Support
Oracle Forms Performance Monitoring


Prerequisites for Oracle Forms Monitoring

To monitor Oracle Forms, ensure that your environment meets the following requirements:
  • Oracle Forms Dynamic Monitoring System must be installed on the Oracle Forms application server.
  • The performance page must be accessible from the monitoring machine.
Parent topic: Oracle Forms Performance Monitoring


Monitoring Oracle Forms

Note: In addition to default measures for the application server, Performance Explorer offers a BDL monitor that allows querying of performance data from the Oracle Forms Dynamic Monitoring System (DMS). Please review Oracle Technology Network instructions (http://otn.oracle.com) for setting up DMS on your Oracle Application Server.
  1. On the Real-Time Monitoring tab, in the Monitor group, click System. The Data Source wizard opens.
  2. Click the Select from predefined Data Sources option button.
  3. Click Next. The System selection page opens.

    Optional: To monitor the application server you can use measures that are provided by the platform upon which the application server runs. Choose from predefined sets or use PERFMON, SNMP or REXEC and manually define the measures that are of interest to you.

  4. Expand the Application Server folder and the Oracle folder.
  5. Select Oracle Forms AS and click Next. The Connection parameters page opens.
  6. In the Hostname text box, specify the host on which the Oracle application server is running. You may optionally add an Alias name for the application server.
  7. Click Next. The Attributes Configuration page opens.
  8. Specify the following settings:
    • URL of the DMS-Site. The standard format is http://server:port/dms0
    • Proxy (if you need to connect using an HTTP proxy)
    • Proxy-Port of the HTTP proxy
    • Username (if you need to authenticate against the Web server to access the DMS site)
    • Password for accessing the DMS site
    This monitor provides interesting measures that are provided by the DMS including:
    • Common Apache measures
    • Module information for HTTP, OC4J, and PLSQL
    • Database connection statistics
  9. Click OK. The Select displayed measures page opens.
  10. Check the check boxes for those measures that you want to include in the initial monitor view and then click Finish.
A connection to the specified host is established, and an initial view that contains the measures you selected is displayed.
Parent topic: Oracle Forms Performance Monitoring


Oracle Forms Client-Side Measures

Client-side measures are automatically generated by load test agents during Oracle Forms load tests. They are aggregated into a single result file by the load test controller.

Agents create measures for the following:
  • Time taken by an action on a control (for example, button press or control edit)
  • Number of bytes received for an action
  • Number of bytes sent for an action
  • Number of messages received for an action
  • Number of messages sent for an action
  • Number of round-trips for an action
Parent topic: Oracle Forms Performance Monitoring


Oracle Performance Monitoring

Use Performance Explorer to retrieve performance metrics from Oracle database systems no matter the database platform. For example, the database can run on a SunOs, Linux, or a Windows system.

  • Monitoring Oracle Database via Perfmon
    Explains how to monitor Oracle Database performance, including prerequisites. Includes descriptions of available performance counters.
  • Monitoring Oracle Database via V$SYSSTAT
    Explains how to monitor Oracle Database performance, including prerequisites.
Parent topic: Predefined Data Sources


Monitoring Oracle Database via Perfmon

  • Oracle Database Monitoring Prerequisites
    Explains how to install Oracle Client and Oracle Counters for Windows. Also explains how to add Oracle Counters to Windows Performance Monitor.
  • Monitoring Oracle Performance (Perfmon)
  • Performance Counters
    Lists the available counters for Oracle Database monitoring
  • Known Issues
    Explains that Silk Performer can monitor both 32bit and 64bit Oracle Database performance, but only the 32bit Oracle client version (Oracle Counters for Windows Performance Monitor) is supported.
Parent topic: Oracle Performance Monitoring


Oracle Database Monitoring Prerequisites

  • Installing Oracle Client and Oracle Counters for Windows
    Explains the installation requirements for monitoring Oracle Database with Perfmon.
  • Adding Oracle Counters to Windows Performance Monitor
    Before adding Oracle counters you must configure which database is to be monitored and add a connection string.
Parent topic: Monitoring Oracle Database via Perfmon


Installing Oracle Client and Oracle Counters for Windows

Before you monitor Oracle Database, ensure that the following requirements have been met:

  • SQL*NET client software must be installed on the machine on which you run Performance Explorer.
  • SQL*Plus must be available on the machine on which you run Performance Explorer.
  • Oracle Counters for Windows Performance Monitor must be available.
  • The Oracle client must have DB administrator permissions and be able to recognize the targeted database server.
    Note: Oracle Counters for Windows Performance Monitor is not installed with default installation options (for example, Instant Client and Administrator installations). It is only available via custom installation options.
Parent topic: Oracle Database Monitoring Prerequisites


Adding Oracle Counters to Windows Performance Monitor

  1. Open file <Oracle Home>\network\admin\tnsnames.ora and add the connection string to the database you want to monitor.
  2. Start the command line and test the connection with the command sqlplus <user>/<password>@<database>
  3. Configure which database is to be monitored using the operfcfg command: <Oracle Home>\bin\operfcfg [-U username] [-P password] [-D TNS_Alias_for_database]

    If successful, you will receive the message operfcfg: New registry values have been successfully set.

  4. Start Windows Performance Monitor Start > Run > Perfmon.
  5. Oracle Counters for Windows Performance Monitor can now be added via the Add Counters dialog box.
Parent topic: Oracle Database Monitoring Prerequisites


Monitoring Oracle Performance (Perfmon)

  1. Choose Monitor > Add Data Source. The Data Source wizard opens.
  2. Click the Select from predefined Data Sources option button.
  3. Click Next. The System selection page opens.
  4. Expand the Database System folder and the Oracle 9/10/11 (perfmon) folder.
  5. Click the System Statistics ( PERFMON ) node and then click Next. The Connection Parameters page opens.
  6. In the Hostname text box, specify the host on which the Oracle Client and Counters for Windows Performance Monitor are running.
  7. In the User and Password text box, specify the user with administrator permissions on the above specified host.
  8. Optional: In the Alias text box, specify an alias for the host where the Oracle database is running.
  9. Click Next.
  10. The Select displayed measures page opens.
  11. Check the check boxes for those measures that you want to include in the initial monitor view and then click Finish.
Parent topic: Monitoring Oracle Database via Perfmon


Performance Counters

Oracle Database Buffer Cache

The counter is phyrds/gets %. The percentage of phyrds/gets is calculated as a miss ratio. The lower the Miss counter, the better. To improve performance, increase the number of buffers in the buffer cache, if memory is available on the computer. This value is not time-derived.

Oracle Database Redo Log Buffer

The counter is redo log space requests. The value of this counter must be near zero. If this value increments consistently, then processes have had to wait for space in the redo log buffer. In this case, it may be necessary to increase the size of the redo log buffer.

Oracle Database Data Dictionary Cache

The counter is getmisses/gets %. The value of this counter must be less than 10-15% for frequently accessed data dictionary caches. If the ratio continues to increase over this threshold while your application is running, then increase the amount of memory available to the data dictionary cache.

To increase the memory available to the cache, increase the value of initialization parameter SHARED_POOL_SIZE. This value is not time-derived.

Oracle Database Library Cache

The counter is reloads/pins %. This is the percentage of SQL statements, PL/SQL blocks, and object definitions that required reparsing. Total Reloads must be near zero. If the ratio of Reloads to Pins is greater than 1%, then reduce the library cache misses. This value is not time-derived.

Oracle Database DBWR stats1

The two counters available, buffers scanned/sec and LRU scans/sec, are helpful in tuning Buffer Cache. Buffers scanned/sec is the number of buffers DBWR scanned in each second. The buffers scanned are on the LRU (Least Recently Used) list. LRU scans/sec is the number of times DBWR scanned the (Least Recently Used) buffer list in each second.

Oracle Database DBWR stats2

The two counters available, timeouts/sec and checkpoints/sec, are helpful in determining how much work DBWR has been requested to perform. Timeouts/sec is the number of times DBWR timed-out in each second. DBWR is on a three second timeout interval. If DBWR has not been posted within a three second interval, then it times out.

Checkpoints/sec is the number of checkpoint messages processed by the database writer each second. Whenever a checkpoint occurs, DBWR must be messaged (posted) to "write dirty buffers to disk."

Oracle Database Dynamic Space Management

The counter is recursive calls/sec. Dynamic extension causes Oracle Database to execute SQL statements in addition to those SQL statements issued by user processes. These SQL statements are called recursive calls.

Oracle Database Free List

The counter is free list waits/requests %. Contention for free lists is reflected by contention for free data blocks in buffer cache. You can determine if contention for free lists is reducing performance by querying V$WAITSTAT.

If the number of free list waits for free blocks is greater than 1% of the total number of requests, then consider adding more free lists to reduce contention.

Oracle Database Sorts

The available counters are sorts in memory/sec and sorts on disk/sec. The default sort area size is adequate to hold all data for most sorts. However, if your application often performs large sorts on data that do not fit into the sort area, then you may increase sort area size.

Parent topic: Monitoring Oracle Database via Perfmon


Known Issues

Silk Performer can monitor both 32bit and 64bit Oracle Database performance, but only the 32bit Oracle client version (Oracle Counters for Windows Performance Monitor) is supported.

Note: The 32bit Oracle client works fine on a 64bit OS and it is not an issue to monitor a 64bit database from a client machine running a 64bit OS.
Parent topic: Monitoring Oracle Database via Perfmon


Monitoring Oracle Database via V$SYSSTAT

You can monitor DB2 database systems in a platform-independent way by fetching performance information from an Oracle database's V$SYSSTAT table.

  • Prerequisites for Oracle Monitoring
    Lists the prerequisites for Oracle monitoring.
  • Monitoring Oracle Performance
    Establish a connection to a data source to monitor an Oracle DBMS and to create an initial view that contains the measures you want to monitor.
Parent topic: Oracle Performance Monitoring


Prerequisites for Oracle Monitoring

Before you monitor Oracle, ensure that the following requirements have been met:
  • Oracle Net (part of Oracle Net Services) client software is installed on the machine on which you run Performance Explorer.
  • The Oracle client must be a 32-bit version, must have DB administrator permissions and be able to recognize the targeted database server.
  • The relevant project attributes have been changed accordingly for your Oracle installation (choose Menu Project > Project Attributes ).
  • SQL*Plus is available on the machine on which you want to run Performance Explorer.
  • Log on using the specified user name, password, and server information and perform the query SELECT * FROM V$SYSSTAT.

    If the logon attempt is successful, the environment is most likely set up correctly.

    If the logon attempt fails, you can judge from the error messages generated by SQL*Plus what caused the problem.

Parent topic: Monitoring Oracle Database via V$SYSSTAT


Monitoring Oracle Performance

Drive a Silk Performer project from inside Performance Explorer to keep track of the database system's performance in real time. The Silk Performer project is located a Essential package named OracleMonitoring.sep, which is located at C:\Program Files\Silk\Silk Performer 21.0\Monitors.

  1. On the Real-Time Monitoring tab, in the Monitor group, click System. The Data Source wizard opens.
  2. Click the Select from predefined Data Sources option button.
  3. Click Next. The System selection page opens.
  4. Expand the Database System folder and the Oracle (v$sysstat) folder.
  5. Click the System Statistics (v$sysstat) node and then click Next. The Connection parameters page opens.
  6. In the Hostname text box, specify the host on which the Oracle database is running.
  7. Optional: In the Alias text box, specify an alias for the host where the Oracle database is running.
  8. Click Next. The Attributes Configuration page opens.
  9. If necessary, change the attribute values. Typically, the Oracle TNS name, UserId, and Password are included in these settings.
  10. Click OK. The Select displayed measures page opens.
  11. Check the check boxes for those measures that you want to include in the initial monitor view and then click Finish.
A connection to the specified host is established, and an initial view that contains the measures you selected is displayed.
Parent topic: Monitoring Oracle Database via V$SYSSTAT


WebLogic (SNMP) Monitoring

This section explains how to monitor BEA WebLogic using Performance Explorer. It also explains important WebLogic performance measures.

By default, the WebLogic SNMP agent is not running. You can enable SNMP support by using the WebLogic Administration Console. Open the console by typing the URL http://weblogichost:port/console into your browser. In the menu tree on the left, select the SNMP node. This selection opens the SNMP configuration page. Within this page, verify that the SNMP agent is enabled. You must restart WebLogic to enable SNMP support.

  • Monitoring BEA WebLogic (SNMP)
    Establish a connection to a data source to query BEA WebLogic through SNMP and to create an initial view that contains the measures you want to monitor.
Parent topic: Predefined Data Sources


Monitoring BEA WebLogic (SNMP)

Establish a connection to a data source to query BEA WebLogic through SNMP and to create an initial view that contains the measures you want to monitor.

  1. On the Real-Time Monitoring tab, in the Monitor group, click System. The Data Source wizard opens.
  2. Click the Select from predefined Data Sources option button.
  3. Click Next. The System selection page opens.
  4. Expand the Application Server folder and the BEA WebLogic (SNMP) folder.
  5. Select the SNMP node and then click Next. The Connection parameters page opens.
  6. In the Hostname text box, specify the host on which WebLogic is running.
  7. Click Next. The Add SNMP Measures page opens. BEA-WEBLOGIC-MIB is selected in the list box of available MIBs.
    The following entries for monitoring the performance of your WebLogic Server are available:
    • bea.wls.jdbcConnectionPoolRuntimeTable
    • bea.wls.servletRuntimeTable
    • bea.wls.ejbEntityHomeRuntimeTable
    • bea.wls.ejbStatelessHomeRuntimeTable
    • bea.wls.executeQueueRuntimeTable
  8. Select jdbcConnectionPoolRuntimeEntry and click Get value(s) to retrieve all available JDBC connection pools. For example, when monitoring the Pet Store sample application, a connection pool named ServerRuntime:petstoreServer is returned. Interesting performance counters exposed by connection pools include the following counters:
    • JdbcConnectionPoolRuntimeActiveConnectionsCurrentCount – Returns the number of connections that are currently being used.
    • JdbcConnectionPoolRuntimeWaitingForConnectionCurrentCount – Returns the number of waiters for connections. This number is greater than zero when all connections are in use and additional requests for connections are being sent to the connection pool.
    • JdbcConnectionPoolRuntimeWaitSecondsHighCount – Returns the maximum number of seconds a client waits to check out a connection from the connection pool.
  9. To monitor the number of active connections, search for the jdbcConnectionPoolRuntimeActiveConnectionsCurrentCount column in the table that was previously returned and select the cell.
    Note: Connection pools provide a large number of performance counters. You might need to resize some columns to view the columns in which you are interested.
  10. Click Add.
  11. Repeat the previous steps until you have entered all commands you require for measure collection, then click Close. The Select displayed measures page opens.
  12. Check the check boxes for those measures that you want to include in the initial monitor view and then click Finish.
A connection to the specified host is established, and an initial view that contains the measures you selected is displayed.
Parent topic: WebLogic (SNMP) Monitoring


WebLogic (JMX) Monitoring

This section explains prerequisites for monitoring WebLogic (JMX) Server, including configuring IIOP and JMX Management Server.

  • Enabling JMX Management Server
    You must enable JMX Management Server in the Oracle WebLogic console before you can monitor WebLogic (JMX).
  • Enabling and Configuring IIOP
    You must enable and configure the IIOP protocol in Oracle WebLogic 11g R1 before you can monitor WebLogic (JMX).
  • Monitoring WebLogic (JMX)
Parent topic: Predefined Data Sources


Enabling JMX Management Server

Enable the JMX Management Server in the Oracle WebLogic console at Configuration > General > Advanced Settings. Set both Compatibility Mbean Server Enabled and Management EJB Enabled. This enables both the legacy and the new JMX interface.

You must restart your system for these changes to go into effect.

Parent topic: WebLogic (JMX) Monitoring


Enabling and Configuring IIOP

You must enable and configure the IIOP protocol in Oracle WebLogic 11g R1 before you can monitor WebLogic (JMX).

  1. In the Change Center of the Oracle WebLogic administration console, click Lock & Edit.
  2. In the left pane of the console, expand Environment and select Servers.
  3. Select the Protocols tab, then select IIOP.
  4. Check the Enable IIOP check box to enable the IIOP protocol.
  5. To modify the default configuration, click Advanced.
  6. To specify a default IIOP user name and password:
    1. In the Default IIOP User field, enter a user name.
    2. In Default IIOP Password field, enter a password.
  7. To activate these changes, in the Change Center of the administration console, click Activate Changes.

You must restart your system for these changes to take effect.

Parent topic: WebLogic (JMX) Monitoring


Monitoring WebLogic (JMX)

  1. On the Real-Time Monitoring tab, in the Monitor group, click System. The Data Source wizard opens.
  2. Click the Select from predefined Data Sources option button.
  3. Click Next. The System selection page opens.
  4. Expand Application Server and select the WebLogic server version to be monitored. Select either EJXM or JMX.
  5. Click Next. The Connection parameters page opens.
  6. In the Hostname text box, specify the host on which WebLogic is running.
  7. Specify the WebLogic Port (Default is 7001).
  8. Do not specify a user or password.
  9. Click Server Configuration.
  10. Specify the Java Home directory and the Application Server install directory. Use a UNC path, including the folder lib. Example: \\<server name>\Oracle\Middleware\wlserver_10.3\server\lib.
    Note: If you can not specify a UNC path, copy wljmxclient.jar from the folder <WL_HOME>\server\lib to your local machine and add it to the classpath.
  11. Click OK.
  12. Click Next. The JMX Data Source Browser opens.
  13. Select measures that you want to include in the initial monitor view.
  14. Click Finish.
Parent topic: WebLogic (JMX) Monitoring


Custom Data Sources

In addition to predefined data sources, Performance Explorer offers the following monitoring interfaces:
  • PerfMon – Provides access to all Windows Performance Monitoring data sources.
  • REXEC – Provides access to data sources on UNIX-based systems through the Remote Execution Protocol.
  • SNMP – Provides access to monitoring data that is exposed by Simple Network Management Protocol services.
  • Monitoring PerfMon Data Sources
    Establish a connection to a PerfMon data source and create an initial view that contains the measures you want to monitor.
  • Querying Through SNMP
    Establish a connection to a data source to query through SNMP and create an initial view that contains the measures you want to monitor.
  • Adding MIB Files to Browse SNMP Agents
    To browse SNMP agents for available performance counters, your MIB files must contain textual descriptions of performance counters.
Parent topic: Monitoring Data Sources


Monitoring PerfMon Data Sources

PerfMon is a Microsoft-specific monitoring interface that queries performance counters. Establish a connection to a PerfMon data source and create an initial view that contains the measures you want to monitor.

  1. On the Real-Time Monitoring tab, in the Monitor group, click System.
  2. Click Select from predefined Data Sources and then click Next.
  3. Expand the Custom Data folder, click NT Performance Monitor Data, and click Next.
  4. In the Hostname text box, specify the machine to be monitored.
    The host to be monitored might be located on a different NT Domain.
  5. Optional: In the Alias text box, specify the alias name. The alias must be a highly descriptive synonym for the monitored server. It is recommended that you group measures on a particular machine. For example, both WebLogic and IIS might be installed on the same computer. Both servers require monitoring, but the two performance measures must appear in separate menu trees.
  6. In the Username text box, specify a user who has administrative security rights.
  7. In the Password text box, specify the appropriate password for the username.
  8. Click Next.
  9. Examine your system for available performance counters and add them to the monitoring template. To select multiple counters from the list, press Ctrl or Shift.
    1. Select a counter.
    2. Select the amount of instances.
    3. Click Add. The Counter Usage page opens.
    4. Ensure that Is an average measure is enabled.
    5. Click Next.
    6. Add more counters as described above.
    7. When you are done, click Close.
  10. Check the check boxes for those measures that you want to include in the initial monitor view and then click Finish.
A connection to the specified host is established, and an initial view that contains the measures you selected is displayed.
Parent topic: Custom Data Sources


Querying Through SNMP

Performance Explorer provides a set of predefined data sources that are queried through SNMP. However, you can add an entry for ORADB-MIB in an SNMP datasource.

Establish a connection to a data source to query through SNMP and create an initial view that contains the measures you want to monitor.

SNMP involves an SNMP agent, which is typically provided by the application vendor. For example, Oracle databases expose data sources using their SNMP agents. The client-side counterpart is Performance Explorer, which collects performance data.

  1. On the Real-Time Monitoring tab, in the Monitor group, click System.
  2. Click Select from predefined Data Sources and then click Next.
  3. Expand the Custom Data folder, click Snmp Data, and then click Next.
  4. In the Hostname field, specify the host running the SNMP agent.
  5. Optional: In the Alias text box, specify the alias name. The alias must be a highly descriptive synonym for the monitored server. It is recommended that you group measures on a particular machine. For example, both WebLogic and IIS might be installed on the same computer. Both servers require monitoring, but the two performance measures must appear in separate menu trees.
  6. Specify the port, community, and version that are appropriate and click Next. If you select version 3, the community field disappears.
  7. If you have selected version 3, specify the authentication details for SNMPv3 and click Next.
  8. Specify the appropriate values to create the measure that you want to monitor as follows:
    1. Select an MIB from the Select a MIB, and object, and get the object's value(s) list box. After you select an MIB, the objects and the object values display in a hierarchical tree below the list box.
    2. Select the object that you want to measure. The object's properties are displayed in the text boxes adjacent to the list box.
    3. Click Get value(s) to check the object's availability.
    If the performance counter is queried successfully, the object's value is displayed in the grid below the list box.
  9. Click Add to add the SNMP measure.
  10. Repeat the previous steps until you have entered all the commands that you require for measure collection, then click Close. The Select displayed measures page opens.
  11. Check the check boxes for those measures that you want to include in the initial monitor view and then click Finish.
A connection to the specified host is established, and an initial view that contains the measures you selected is displayed.
Parent topic: Custom Data Sources


Adding MIB Files to Browse SNMP Agents

To browse SNMP agents for available performance counters, your MIB files must contain textual descriptions of performance counters.

  1. On the Real-Time Monitoring tab, in the Monitor group, click System.
  2. Click Select from predefined Data Sources and then click Next.
  3. Expand the Custom Data folder, click Snmp Data, and then click Next.
  4. In the Hostname field, specify the host running the SNMP agent.
  5. Optional: In the Alias text box, specify the alias name. The alias must be a highly descriptive synonym for the monitored server. It is recommended that you group measures on a particular machine. For example, both WebLogic and IIS might be installed on the same computer. Both servers require monitoring, but the two performance measures must appear in separate menu trees.
  6. Specify the port, community, and version that are appropriate and click Next.
  7. Select Import new Mib... from the Select a MIB, and object, and get the object's value(s) list.
  8. Type the MIB file name that you want to compile in the MIB source file field. Alternative: Click [...] to navigate to and select the file.

    Commonly used MIB files are located in the <public user documents>\Silk Performer 21.0\Data\Mibs\VendorMibs directory.

  9. Click Import. The MIB file is added to the Compiled MIBs list.
Parent topic: Custom Data Sources


Automatic Detection of Data Sources

The data source scanner queries your machine for data sources that can be monitored. This eliminates the need for you to do the search manually. The automatic detection might not find every possible data source, since it is based on a configuration that closely mimics the predefined data sources. It goes through the list of the predefined data sources and checks for their availability.

For example: The data source scanner queries your machine for the number of processors, the number of network interfaces, the number of database instances, and how these components can be monitored.

Details such as the platform on which your system runs (NT, AIX, or Linux) do not matter because the monitored components, such as CPU or hard disk utilization, are platform-independent.

  • Using the Data Source Scanner
    Describes how to use the data source scanner.
Parent topic: Monitoring Data Sources


Using the Data Source Scanner

The data source scanner queries your machine for data sources that can be monitored.

  1. On the Real-Time Monitoring tab, in the Monitor group, click System.
  2. Click Have Data Sources detected and then click Next.
  3. In the Hostname field, specify the machine that is to be scanned.
  4. Optional: In the Alias text box, specify the alias name. The alias must be a highly descriptive synonym for the monitored server. It is recommended that you group measures on a particular machine. For example, both WebLogic and IIS might be installed on the same computer. Both servers require monitoring, but the two performance measures must appear in separate menu trees.
  5. Click Next. The data source scanner now queries your system for the following data sources on various platforms:
    • .NET
    • Active Server Pages
    • Apache
    • Coldfusion
    • IBM Universal Database DB2
    • Internet Information Servers
    • iPlanet Directory Servers
    • Microsoft Proxy Servers
    • Microsoft SQL Servers
    • Netscape Directory Servers
    • Netscape Enterprise 3.0
    • Netscape/iPlanet Directory Server
    • Operating System Data, such as hard disk, CPUs, and network interfaces
    • Oracle Databases
    • Rstat which often can be queried on UNIX-based systems and provides large amounts of operating system-related data.
    • SilkPerformer Agent
    • SilkPerformer Controller
    • Silverstream

    While your system is scanned, the data source scanner might display dialog boxes that request credentials for specific data sources (for a remote execution daemon, for example).

    The scanner also checks whether your system resides within a remote NT domain. In such instances, you must provide the domain name of the specified host.

    Note: The specified user must possess administration security rights, which are necessary for monitoring NT based systems.
  6. When the Progress section indicates Done, click Next.
  7. Check the check boxes for those measures that you want to include in the initial monitor view and then click Finish.
A connection to the specified host is established, and an initial view that contains the measures you selected is displayed.
Parent topic: Automatic Detection of Data Sources


Monitoring Load Tests

With Performance Explorer, you can collect data for client-side monitoring in addition to server data.

  • Configuring Load Test Monitoring
    To use real-time client-side measures, such as in built-in charts and monitor writers, add a connection entry for the client-side data source.
  • Removing Client-Side Measures
    To remove real-time client-side measures, such as in built-in charts and monitor writers, remove the connection entry for the client-side data source.
Parent topic: Real-Time Monitoring


Configuring Load Test Monitoring

To use real-time client-side measures, such as in built-in charts and monitor reports, add a connection entry for the client-side data source.

  1. On the Real-Time Monitoring tab, in the Monitor group, click Load Test.
  2. In the Hostname field, specify the host name of the load test controller.
  3. In the Alias field, specify the alias for the controller that provides the client-side measures. The alias will display in the Client-Side Measures tree.
  4. Click Finish.
The host appears in the tree. The client-side measures that are available on this data source are listed in folders in the tree.
Note: Check the Enable real-time measures check box in the Workload Configuration dialog, which instructs the runtime system to supply host measures. A green icon on in the Client-Side Measures tree indicates a successful connection to the data source. A red icon indicates that the data source is not connected.
Parent topic: Monitoring Load Tests


Removing Client-Side Measures

You can remove a client-side measure node from the tree. However, Silk Performer replaces the measure node if it receives updated information for the measure.
  1. Click the Client-Side Measures tab in the tree area.
  2. Right-click the measure node that you want to delete and click Remove Client-Side Data Source.
  3. Click Yes.
Parent topic: Monitoring Load Tests


Monitor Charts and Monitor Writers

Performance Explorer provides monitor charts and monitor reports to display and store measured values.
  • A monitor chart displays the measured values of a data source in real-time. You can adjust the polling interval of a monitor chart.
  • A monitor writer records the measured values of a data source and stores them in a .tsd file. Monitor writers are also useful to compare server-side and client-side measures when a load test is completed.
Note: A short polling interval can reduce the performance of your computer which, consequently, can influence test results. For large load tests, define intervals greater than 60 seconds.
Note: The values that display in a monitor chart cannot be written to a .tsd file afterwards.
  • Creating Monitor Charts
    Create a monitor chart to analyze measured values in a chart.
  • Creating Monitor Writers
    Create a monitor writer to write measured values to a .tsd file.
Parent topic: Real-Time Monitoring


Creating Monitor Charts

Monitor charts are useful for providing a graphical overview of the state of a system.

  1. On the Real-Time Monitoring tab, in the New group, click Monitor Chart.
  2. Drag measures from the Monitor tree onto the chart.
  3. Right-click a measure in the measure list and click Properties.
  4. On the General tab, you can adapt the caption and description.
  5. On the Monitor tab, you can adapt monitor and view options: The Interval defines the refresh rate for retrieving new values. The Page size defines how many intervals display on each page. The History size defines how many intervals are stored in the chart history.
  6. Click OK.
Tip: You can also create a Transaction Rate Monitor. Performance Explorer will automatically populate this chart with transaction measures. Make sure to Enable real-time measures on the Workload Configuration dialog before you start monitoring.
Parent topic: Monitor Charts and Monitor Writers


Creating Monitor Writers

A monitor writer can be defined to capture measures during load tests. Monitor writes write a time series data (.tsd) file that you can include in an overview report or use as the basis for a chart.
  1. On the Real-Time Monitoring tab, in the New group, click Monitor Writer.
  2. Drag measures from the Monitor tree onto the writer.
  3. On the Real-Time Monitoring tab, in the Control group, click Recording.
  4. Specify a directory for the .tsd file and click Save. Performance Explorer will write all captured values into this .tsd file.
    Note: If you are running a load test and the workspace you have assigned to your profiles contains a monitor writer, all monitor writers begin writing automatically when the test starts and stop when the test finishes.
All monitor writers are stored in the result directory of the load test.
Note: For SAPGUI data sources, it is recommended that you change the monitor interval to 20 seconds or higher. To change the interval, click Properties in the Report group, on the Report tab. Then click the TSD-Writer tab and change the interval.
Parent topic: Monitor Charts and Monitor Writers


Host Data

You can change, rename, and duplicate hosts and update the credentials that allow you to access a host.

  • Changing Hosts
    Describes how to change a host that was specified for real-time monitoring or the host alias.
  • Duplicating Hosts
    Describes how to duplicate a host that was specified for real-time monitoring.
  • Editing Host Credentials
    Describes how to edit the credentials of a host that was specified for real-time monitoring.
Parent topic: Real-Time Monitoring


Changing Hosts

You can change a host that has already been specified or you can change just the alias of the host. In both cases, the specified measures, which display in the tree, will not be lost.

  1. Select a host (a top-level node) in the Monitor tree.
  2. On the Real-Time Monitoring tab, in the Host group, click Change.
  3. To change the host, enter the Hostname of the new host, enter an Alias, and click Next.
  4. To change the alias of the host (the name that displays in the Monitor tree), enter the Hostname of the current host, enter a new Alias, and click Next.
  5. Enter the Username and Password and click Finish.
Parent topic: Host Data


Duplicating Hosts

When you duplicate a host, Performance Explorer creates a new host node in the Monitor tree and adds all measures that are specified for the selected host.

  1. Select a host (a top-level node) in the Monitor tree. This host will be duplicated.
  2. On the Real-Time Monitoring tab, in the Host group, click Duplicate.
  3. Specify the Hostname of the new host and an Alias and click Next. The alias will display as name of the new host in the Monitor tree. Depending on the specified data source, fields with various connection parameters appear. These fields are automatically populated with the original values.

    If there are configurable attributes for the specified data source, a Change Attributes button appears.

  4. Enter the credentials of the host and click Finish. The measures are checked to confirm validity. If invalid measures are discovered, you have the option of changing the connection parameters or ignoring the measures.
    Note: It is not possible to duplicate or rename invalid measures.
Note: Measures are grouped into measure groups when they use the same data source and connection parameters. For example: If you have PerfMon measures with different credentials, you have different measure groups.
Parent topic: Host Data


Editing Host Credentials

The security policies of many companies require that user passwords expire at regular intervals. Such policies can create in automatic access of tools like Performance Explorer. For such environments, Performance Explorer enables you to change user names and passwords for existing hosts.

  1. Select a host (a top-level node) in the Monitor tree.
  2. On the Real-Time Monitoring tab, in the Host group, click Edit Credentials.
  3. The Hostname and the Alias of the selected host are already prefilled. Click Next.
  4. If necessary, click Change Attributes.
  5. Change the Username and Password as required and click Finish.
Parent topic: Host Data


Converting Data from CSV to TSD

Silk Performer offers a command-line tool (csv2tsd.exe) that enables you to convert .csv files (comma-separated values) into .tsd files (time series data).

Converting data to the .tsd format is useful when you monitor external Windows data that, for security reasons, cannot be monitored by Silk Performer. By converting .csv data into the .tsd format, external data can be analyzed alongside internal Silk Performer monitoring data within Performance Explorer.

For example, if a performance counter measures the behavior of a remote server and the results of that monitor are saved in .csv files, those results can be imported into Performance Explorer for analysis alongside the results of a Silk Performer load test involving the same server. Using Silk Performer, you then have the opportunity to look for correlations between the two data sets.

  • Generating a CSV File on a Remote Server for Windows 7/2008 R2
    Any performance-counter log (CSV) file you specify with the command-line conversion tool must follow the format generated by the Windows Performance Monitor tool.
  • Capturing Performance Counter Log Data
    Use your performance counter to capture remote-server log data that can be analyzed with Silk Performance Explorer.
  • Converting a Properly Formatted CSV File to TSD Format
    Use csv2tsd.exe to convert a CSV log file to Time Series Data format, which can be analyzed using Silk Performance Explorer.
Parent topic: Real-Time Monitoring


Generating a CSV File on a Remote Server for Windows 7/2008 R2

Any performance counter log (CSV) file you specify in the command line tool must follow the format generated by the Windows Performance Monitor tool ( Administrative Tools > Performance ). So, before using csv2tsd.exe you must create a performance counter with settings that will allow you to import its data.

  1. Open the Windows Performance Monitor tool ( Administrative Tools > Performance ).
  2. Expand the tree Performance > Data Collector Sets > User Defined.
  3. Right-click and select New > Data Collector Set from the context menu.
  4. Enter a name and select Create manually (Advanced) and click Next.
  5. Create data logs and select Performance counter. Click Next.
  6. Specify the location of the CSV file and click Next.
  7. Optional: Specify a different user in Run as. Click Save and close the dialog box.
  8. Right-click on the defined Data Collector Set and select New > Data Collector from the context menu.
  9. Enter a name and select Performance counter data collector. Click Next.
  10. Click Add to add the performance counters.
  11. Specify the computer (can be both local and remote) and performance counter instances for which you want to track results.
  12. Select Open properties for this data collector and click Next.
  13. On the Performance Counters tab specify the log format to be Comma Separated.
  14. Select the File tab and specify a file name.
  15. Click OK to close the dialog.
  16. Close the Performance Monitor.
Once you have configured a performance counter so that its log results can be converted to TSD format using csv2tsd.exe, you can start capturing behavioral data using the performance counter.
Parent topic: Converting Data from CSV to TSD


Capturing Performance Counter Log Data

Once you have configured a performance counter so that its log results can be converted to TSD format using csv2tsd.exe, you can start capturing remote-server log data using the performance counter.

  1. Open the Windows Performance Monitor tool ( Administrative Tools > Performance ).
  2. Expand the Performance Logs and Alerts tree node.
  3. Click the Counter Logs node.
  4. Right-click a counter log in the right-hand window and select Start from the context menu. Active counters are shown in green. Inactive counters are shown in red. Generated CSV counter log files have the following format:
    "(PDH-CSV 4.0) (W. Europe Standard Time)(-60)","\\JONES\Processor(_Total)\% Interrupt Time","\\JONES\Processor(_Total)\% Privileged Time","\\JONES\Processor(_Total)\% Processor Time"
"02/25/2008 23:24:23.826"," "," "," "
"02/25/2008 23:24:38.841","0","0.10406093659265107","0.10150087105497141"
"02/25/2008 23:24:53.841","0.052084666700800877","1.8229633345280307","2.4454192693999621"
"02/25/2008 23:25:08.840","0.052084666700800877","3.0729953353472514","5.4663299380464103"
"02/25/2008 23:25:23.840","0.052084666700800877","0.57293133370880955","1.0391332684783428"
Parent topic: Converting Data from CSV to TSD


Converting a Properly Formatted CSV File to TSD Format

  1. Launch csv2tsd.exe ( Start > All Programs > Silk > Silk Performer 21.0 > Analysis Tools > CSV to TSD Converter ).
  2. Enter file-import and export settings using the following format: Csv2Tsd <csvFile> <tsdfile> [[+/-]<time offset>]. <csvFile> is the full path of the CSV file to be imported. <tsdFile> is the full path of the TSD file that is to be generated. <time offset> is the time difference in seconds (the default is 0).
  3. Hit Enter to execute the conversion.

    Example:

    Csv2Tsd C:\perflogs\Test1.csv C:\perflogs\Test1.tsd

Parent topic: Converting Data from CSV to TSD


Summary Measures

The group Summary Measures contains summarized measurements on a global level. It contains measures that aggregate individual measures from other measure groups as well as measure types that represent information on a global level that are not included in other measure groups.

This group contains only counters, it does not contain timers. It represents a fixed set of global measures that are collected only during the measurement period, thus excluding the warm-up and shutdown period of the load test. The Summary Measures group contains measure types that are available as real-time data and time-series data (.tsd).

  • General Measures
    Displays the measures that are shown at the beginning of the overview report.
  • Agent Health Control Measures
    Describes the measures that are used for analyzing an agent's health.
  • Internet-Related Measures
    Describes the measures that are related to the internet connection.
  • Web-Specific Measures
    Describes the measures that are specific for the Web.
  • IIOP-Related Measures
    Describes the scripted measures which relate to IIOP operations.
  • Database-Specific Measures
    Describes the measures that are specific to the database.
Parent topic: Built-In Measures


General Measures

Displays the measures that are shown at the beginning of the overview report.
Measure | Description
Active users

The number of active virtual users. A virtual user is regarded as active if it has been started and is currently in one of the following states:

  • executing
  • warm up
  • wait database
  • loading documents
  • wait resource
  • rendezvous
  • thinktime
  • shutdown

A virtual user is regarded as inactive if it currently is in one of the following states:

  • starting
  • wait queue
  • wait user
  • wait stop
  • pacing time
  • suspended
Transactions The number of Silk Performer transactions that have completed, regardless of whether or not they were successful.
The overview report shows the following information:
  • A graph indicating how many transactions ended in a given second.
  • Average number of ended transactions per second.
  • Total number of ended transactions.
Errors | The number of API errors, including Internet, database, and middleware APIs. An API error is counted if the severity is error or higher (transaction exit or process exit). An error is ignored if the severity is informational or warning.
Running users The number of running virtual users. A virtual user is regarded as running if it has been started and not been stopped. In contrast to the measure Active users, it also includes virtual users that are in one of the following states:
  • wait queue
  • wait user
  • wait stop
  • pacing time
Parent topic: Summary Measures


Agent Health Control Measures

Describes the measures that are used for analyzing an agent's health.
Measure | Description
CPU utilization | The percentage of time that a processor is busy executing tasks. If the processor utilization is equal to or near 100%, the computer has run out of available processing capacity.
Memory The percentage amount of memory allocated (committed) by the driver machine in relation to the total amount of physical RAM. High memory utilization indicates that the driver machine is low on available memory, and this situation can cause disk swapping, which degrades the overall performance of the computer.
Note: Task Manager may show different memory statistics depending on your operating system.
Responsiveness

For most Silk Performer project types the responsiveness measure is determined directly by the internal measure System Health.

For Silk Performer projects of type SAP GUI, Citrix, or browser driven load testing (BDLT), the responsiveness measure also takes into account the health of the application under test (SAP GUI or perfBrowserHost.exe). This health is indicated by the internal App Health value. The overall Responsiveness measure corresponds to the worse of these two health values.

Parent topic: Summary Measures


Internet-Related Measures

Describes the measures that are related to the internet connection.
Measure | Description
Concurrent connections | The number of currently open TCP/IP connections.
Requests sent | The number of HTTP requests sent by low-level web functions, the number of data packets sent by TCP/IP-level functions, or the number of commands sent by POP3, SMTP, FTP, or LDAP function calls. Silk Performer also includes LDAP traffic in this measure; it reports the number of LDAP requests sent. IIOP uses other counters.
Requests failed | The number of the requests listed above that are not sent or executed successfully. IIOP uses other counters.
Request data sent | The amount of data (in KB) sent to the server, including header and body content information as well as all TCP/IP-related traffic (HTTP, native TCP/IP, IIOP, POP3, SMTP, FTP, and LDAP), and secure traffic over SSL/TLS. It does not include data overhead caused by encryption using SSL/TLS or other API-related traffic like TUXEDO ATMI, ODBC, and Oracle OCI.
Responses received | The number of HTTP responses received by low-level web functions, the number of data packets received by TCP/IP-level functions, and the number of responses received by POP3, SMTP, FTP, and LDAP functions. IIOP uses other counters.
Responses failed | The number of the expected responses that are not received successfully. IIOP uses other counters.
Response data received | The amount of data (in KB) received from the server, including header and body content information as well as TCP/IP-related traffic (HTTP, native TCP/IP, IIOP, POP3, SMTP, FTP, and LDAP), and secure traffic over SSL/TLS. It does not include API-related traffic like TUXEDO ATMI, ODBC, and Oracle OCI.
Connects successful | The number of successful TCP/IP connects to the remote hosts established by low-level, TCP/IP-level, IIOP, SMTP, POP3, FTP, or LDAP functions.
Connects failed | The number of TCP/IP connection failures caused by invalid host names, invalid IP addresses, invalid ports, unavailable remote hosts, network-related problems, or authentication failures. This counter is used by low-level, TCP/IP-level, IIOP, SMTP, POP3, FTP, and LDAP functions. By default, low-level web functions perform up to three connect attempts (up to two retries). Only if all attempts fail, a failure is recorded.
Connects retries | The number of attempts to connect to the server if the initial connection fails.
Page data | The amount of data (in KB) for all requests and responses related to the request and retrieval of an entire Web page, including all embedded objects.
Embedded objects data | The amount of data (in KB) for all requests and responses related to the request and retrieval of objects embedded in a Web page.
Parent topic: Summary Measures


Web-Specific Measures

Describes the measures that are specific for the Web.
Measure | Description
HTTP request retries | The number of times a client is forced to retry a request. This may happen when the server closes a persistent connection (available with Keep-Alive or HTTP/1.1) because of a timeout occurring while the client tries to send a request. This counter is used only by low-level web functions.
HTTP redirections | The number of HTTP redirections performed due to a Web server response with status code 3xx. This measure is incremented only by Web functions.
HTTP re-authentications | The number of re-authentications necessary because of a status code 401 or 407 returned by the Web server. This counter is used only by Web functions that perform basic authentication.
HTTP hits | The number of HTTP requests that arrive at the Web server. This measure is incremented only by Web functions.
Hits failed | The number of failed HTTP requests. This measure is incremented only by Web functions.
HTTP 1xx responses | The number of HTTP responses containing status codes indicating that their content has the status informational. This measure is incremented by Web functions.
HTTP 2xx responses | The number of HTTP responses containing status codes indicating successful requests. This measure is incremented by Web functions.
HTTP 3xx responses | The number of HTTP responses containing status codes indicating redirected requests. This measure is incremented by Web functions.
HTTP 4xx responses | The number of HTTP responses containing status codes indicating client errors. This measure is incremented by Web functions.
HTTP 5xx responses | The number of HTTP responses containing status codes indicating server errors. This measure is incremented by Web functions.
HTTP cache conditional reloads | The number of requests sent to the server to download an item if its content has changed since it was last placed in the cache.
HTTP cache hits | The number of times requests that are fulfilled from the cache.
HTTP cookies sent | The number of cookies sent by low-level web functions. If the header line of an HTTP cookie request contains multiple cookies, each cookie in the header is counted.
HTTP cookies received | The number of cookies received by low-level web functions. If the HTTP response includes multiple cookie header lines, each cookie of these header lines is counted.
HTTP pages | The number of HTML pages requested by the page-level Web API.
Parent topic: Summary Measures


IIOP-Related Measures

The following table describes the scripted measures which relate to IIOP operations.
Measure | Description
IIOP messages | The number of IIOP messages sent by Silk Performer.
IIOP requests | The number of IIOP request messages sent by Silk Performer.
IIOP loc requests | The number of IIOP locate request messages sent by Silk Performer.
IIOP fragments sent | The number of fragmented IIOP messages sent by Silk Performer.
IIOP replies OK | The number of IIOP reply messages with status OK received by Silk Performer.
IIOP replies exception | The number of IIOP reply messages with the status exception raised received by Silk Performer. This count includes system exceptions as well as user exceptions.
IIOP replies obj moved | The number of IIOP reply messages with the status object has moved. This status message causes Silk Performer to reissue the request to the new location.
IIOP request timed out | The number of times the time limit for receiving data (specified in the load-testing script) was exceeded while waiting for a pending reply. Whenever the time limit is exceeded, no reply is received and Silk Performer sends an IIOP Cancel Request message to inform the server about the aborted operation.
IIOP loc replies obj here | The number of IIOP Locate Reply messages with status object here received by Silk Performer.
IIOP loc replies obj unknown | The number of IIOP Locate Reply messages with status object unknown received by Silk Performer.
IIOP loc replies obj moved | The number of IIOP Locate Reply messages with status object moved received by Silk Performer.
IIOP message errors | The number of IIOP error messages received by Silk Performer.
IIOP fragments received | The number of fragmented IIOP messages received by Silk Performer.
IIOP loc request timed out | The number of times that the time limit for receiving data (specified in the load-testing script) was exceeded while waiting for a pending locate reply. Whenever the time limit is exceeded, no locate reply is received and Silk Performer sends an IIOP Cancel Request message to inform the server about the aborted operation.
Parent topic: Summary Measures


Database-Specific Measures

The following table describes the measures that are specific to the database.
Measure | Description
SQL commands | The number of SQL commands sent to the DBMS for execution.
Open database logins | Counts the currently open database sessions. This counter is relevant for the OCI, ODBC, and ODBC high-level interfaces (This measure is not available in report files).
Open database cursors | Counts the currently opened database cursors (handles). This counter is relevant for the OCI, ODBC, and ODBC high-level interfaces. For ODBC, only OdbcClose calls with the SQL_DROP option decrease this measure value. (This measure is not available in report files.)
Parent topic: Summary Measures


Transaction Measures

The Transaction measure group contains response-time data on the transaction level. For each transaction defined in your load-test script, a measure of this group type is automatically created, using the name of the transaction as the key for the measures. Only measures that contain a counted value are displayed. This fact means that Trans.failed is not displayed if none of the transactions fail.

Note: The transactions TInit and TEnd do not count towards the load-test measures because beginning and ending transactions should not contain measures that relate to the application under test.

The following table describes the corresponding measure types.

Measure | Description
Trans. ok | The response time for successful transactions, in seconds. A transaction time is reported in this measure type if no API function call performed within the transaction returns an error message.
Trans.(busy) ok | The busy time for successful transactions, in seconds. A transaction busy time is the transaction response time without any think time, wait time, and time necessary for function transformations. A transaction time is reported in this measure type if no API function call performed within the transaction returns an error message.
Trans. failed | The response time for failed transactions, in seconds. A transaction time is reported in this measure type if at least one error of severity error or higher occurs within the transaction.
Trans.(busy) failed | The busy time for failed transactions, in seconds. A transaction busy time is the transaction response time without any think time, wait time, and time necessary for function transformations. A transaction time is reported in this measure type if at least one error of severity error or higher occurs within the transaction.
Trans. canceled | The response time for canceled transactions, in seconds. A transaction time is reported in this measure type if a return statement in the script is issued with a return value of 1.
Parent topic: Built-In Measures


Web Form Measures

The Web Form measure group contains the measure types related to forms declared in the dclform section of a load-test script. The Web Form measure group provides response time and throughput rates for form submissions with the POST, GET, and HEAD command sent by scripting function calls. For each form declared in the dclform section, a measure group is created automatically with the name of the form as the key. The following table describes the corresponding measure types:

Measure | Description
Server busy time | Measure, in seconds, that starts after the user has sent the complete request and ends when the user receives the first part of the response.
Round trip time | The time, in seconds, that it takes to send a request and receive the appropriate response. It also includes the connect and shutdown time when the connection is not persistent (the connection can persist if the Keep-Alive option is enabled or HTTP/1.1 is used).
Hits | The number of successful form submissions.
Request data sent | The amount of data (in KB) sent to the Web server during submission of a form. This measure also includes HTTP header and body content information. The count specifies the number of Web server requests sent.
Response data received | The amount of data (in KB) received from the Web server in response to the submission of a form. This measure also includes HTTP response header and body content information. The count specifies the number of Web server responses received.
Parent topic: Built-In Measures


Web Page Measures

The Web Page measure group contains the measure types related to Web pages. For each Web page that is downloaded during a load test, a measure group is created automatically with the name of the Web page as the key. The following table describes the corresponding measure types:

Measure | Description
Page time | The time, in seconds, that it takes to retrieve an entire Web page from the server, that is, for retrieving all HTML documents and all embedded documents, such as images, videos, and audio files.
Document download time | The time, in seconds, that it takes to retrieve all HTML documents of a Web page.
Server busy time | The time, in seconds, that the server takes to process a Web page request. This measure starts after a virtual user has sent the last byte of the request and ends when the user retrieves the first byte of the response.
Page data | The amount of data (in KB) for all requests and responses related to the request and retrieval of an entire Web page including all embedded objects.
Embedded objects data | The amount of data (in KB) for all requests and responses related to the request and retrieval of objects embedded on a Web page.
Parent topic: Built-In Measures


Browser-Driven Measures

The following table describes the corresponding measure types:
Measure | Description
Dom interactive | Reflects the time span from the request until the browser has completed parsing all HTML elements and constructing the DOM.
Dom complete | Reflects the time span from the request until the browser has completed downloading and processing all resources (images, stylesheets, scripts, and so on).
Load End | Reflects the time span from the request until the browser has completed executing the onLoad function. As a final step in every page load process the browser sends an onLoad event, which triggers the onLoad function. Once the onLoad functions are executed, additional application logic might be executed.
First paint | Reflects the time span from the request until the page begins to display. This measure is available for Internet Explorer only.
Time to interact | Reflects the time span from the request until all TTI-relevant elements are available on the page. At this point in time, the user can interact with the web page.
Action time | Reflects the time span from the request until the browser has completed downloading and processing all resources. The end of this time span varies, depending on the defined synchronization mode: If the synchronization mode HTML is defined, the action time ends when the onLoad function is completed. If the synchronization mode AJAX is defined, the action time ends during the Asynchronous Application Logic phase.
Important: When the TTI feature is being used, the other measures listed here might not be available or might show incorrect values.
Parent topic: Built-In Measures
Related concepts
Time to Interact
Related tasks
Including Elements in the TTI


CORBA-Specific Measures

The IIOP measure group contains the measure types related to IIOP operations that are called within a load-testing script. It provides response time and throughput ratings for the IIOP operation calls issued by the API function IiopRequest. With the IiopObjectSetMeasures function you can specify a prefix to the name of the measure groups associated with the operations of a certain CORBA object. If you decide not to do so, the name of the operation is used as the name of the corresponding measure group. The following table describes the corresponding measure types:

Measure | Description
Round trip time | The time measured, in seconds, from when the processing of the IiopRequest function call begins to when the processing of the reply of the CORBA object ends.
Server busy time | Measure, in seconds, that starts after a user has sent the last byte of the CORBA operation call and ends when the user retrieves the first byte of the response. Note: Depending on the content of the application and the request, server busy time might begin before the last byte is sent and continue after the user has received the first byte. Therefore, server busy time is, in many cases, only an approximation.

For non-blocking IIOP requests, these measures are performed in the same way. This approach can lead to a situation where the sum of all your measured times exceeds the total time of your load test.

If a CORBA object decides to redirect a request, the IiopRequest function has to reissue this request to a different location. The result is two request-reply message pairs, where both are measured separately. As in the case of the measure times for the IiopRequest function, the sum of both (separately measured) request-reply pairs is supplied.

Parent topic: Built-In Measures


SQL Database-Specific Measures

The following table describes the corresponding measure types:

Measure | Description
Parse | The time, in seconds, that it takes to prepare (Oracle terminology: parse) a SQL command. Preparing a SQL command usually includes a server round-trip during which the SQL command is sent to the server. The SQL command is then parsed and transformed into an internal format that can be reused on subsequent calls of that SQL command. Note: If you use the OraParse function with the ORA_DEFERRED option, the parsing of the SQL command is deferred to the execute step, and the server round-trip time is produced for the parse step. In this case, this measure type is meaningless.
Exec | The time, in seconds, in which a SQL command is executed. Executing a SQL command includes at least one server round-trip for sending the command and returning the result to enable the SQL command to be executed. Because of the considerable amount of data processing required on the server for a SQL command, executing SQL commands usually generates a major part of the load on the database server. A separate measure type in the SQL measure group is used for fetching data. Fetching data can either be included as part of the execute step or in a separate step. In the latter case, results are not included in the SQL measure group.
ExecDirect | The time, in seconds, in which a SQL command is prepared and executed.
Parent topic: Built-In Measures


Middleware-Specific Measures

The TUXEDO measure group contains the measure types related to TUXEDO service calls performed in a load-testing script. It provides response time and throughput ratings for the TUXEDO service calls issued by the functions Tux_tpcall, Tux_tpacall, Tux_tpsend, Tux_tprecv, Tux_tpgetrply, Tux_tpenqueue, and Tux_tpdequeue. For each TUXEDO service used in these TUXEDO functions, a measure group is created automatically with the name of the service as the key. The following table describes the corresponding measure types:

Measure | Description
Response time | The response time, in seconds, for a TUXEDO service call. For synchronous service calls, the response time includes the time the server needs to process the call. For asynchronous service calls, Silk Performer reports the time that elapses between sending the request and receiving the reply, plus the time spent waiting for the request. Asynchronous service calls do not measure the time a server needs to execute the service. For send and request calls, Silk Performer measures the time for sending data across an open connection as well as the time for receiving data from an open connection. For queuing communication, both the time required for sending the service call to the queue and the time for retrieving the results of a service call are measured.
Request data sent | The amount of data (in KB) sent to the TUXEDO server for submission of a given service. Silk Performer measures the application data buffer size used by the service calls rather than the transferred bytes on the network.
Response data received | The amount of data (in KB) received from the TUXEDO server by a given service. Silk Performer measures the application data buffer size used by the service calls rather than the transferred bytes on the network.
Parent topic: Built-In Measures


Citrix-Specific Measures

The Citrix Synchronization Points measure group states how many synchronization functions already have been executed. The main purpose of this measure is to visualize the progress of a transaction.

Measure | Description
Citrix Synchronization points | The number of executed Citrix synchronization functions (CitrixWaitForXXX).
Parent topic: Built-In Measures


Custom Timer Measures

The Custom Timer measure group contains the timers that are defined in the load test script with the MeasureStart and the MeasureStop functions, as the following table shows.

Measure | Description
Response time | The time, in seconds, measured between MeasureStart and MeasureStop function calls.
Busy time | The busy time, in seconds, measured between MeasureStart and MeasureStop function calls. A busy time is the response time without any think time, wait time, and time necessary for function transformations.
Note: You can pause and resume timers with the MeasurePause and the MeasureResume function.
Parent topic: Built-In Measures


Custom Counter Measures

The Custom Counter measure group contains the counters that are defined in the load-testing script with the MeasureInc function, as the following table shows.

Measure | Description
Custom counter | Counts values that are set with the MeasureInc function.
Parent topic: Built-In Measures


Streaming Measures

The following table describes the corresponding measure types:

Measure | Description
Actual video duration | The play time of all downloaded media segments (the complete stream) in seconds.
Overall download time | The download time of all media segments in seconds.
Segments | The number of all downloaded media segments.
Segments critical D/P ratio | The number of media segments with a D/P ratio (download time/play time ratio) of more than 0.9.
Stream D/P ratio | The ratio of the download time to the play time (D/P ratio). A value over 0.9 indicates potential lagging/stuttering/buffering.
Stream size | The size of all downloaded media segments (the complete stream) in kilobytes.
Time to first segment | The time elapsed from loading the page to the complete download of the first media segment.
Parent topic: Built-In Measures


Command Line Parameters

Performance Explorer offers a number of parameters that you can execute from a command line interface.

  • Available Commands
    Lists the Performance Explorer commands that you can use in a command line interface and provides examples.
  • Command File
    Describes the syntax for submitting a command file in XML format.
Parent topic: Performance Explorer 21.0


Available Commands

The following table lists the Performance Explorer commands that you can use in a command line interface.

Command | Description
/TSD:<file> | Opens the specified .tsd file.
/ADDLOADTEST:<file | Opens the load test results that contain the specified .tsd file.
/OVT:<template> | Sets the specified template as preselection of the overview report template when manually generating an overview report.
/MONITORDIR:<dir> | Sets the output directory for monitor writer files.
/MONCREATE:<dir> | Starts in Monitoring mode (BDL Script Generation).
/ACTION:STDGRAPH | Opens a predefined chart of type General. Uses the specified .tsd file (/TSD:<file>).
/ACTION:SELGRAPH | Opens a wizard that allows you to select a template for the chart. Uses the specified .tsd file (/TSD:<file>).
/ACTION:MONSERVER | Starts the server monitoring wizard.
/ACTION:STARTALLMONITORS | Starts all monitor charts.
/ACTION:STOPALLMONITORS | Stops all monitor charts.
/ACTION:OVERVIEWREPORT [:<template>] | Generates an overview report for the specified .tsd file (/TSD:<file>). Can apply a template file. Make sure to specify a merged .tsd file (m@).
/ACTION:WORDOVERVIEWREPORT | Generates a Word overview report for the specified .tsd file (/TSD:<file>). Make sure to specify a merged .tsd file (m@). The parameters /WORDTEMPLATE and /WORDTARGET can be set optionally. Performance Explorer will be executed in GUI-less mode.
/WORDTARGET:<file> | The absolute path of the Word document (.docx) that will be generated. This parameter must be added before the parameter /ACTION:WORDOVERVIEWREPORT (see example below).
/WORDTEMPLATE:<file> | The absolute path of the Word document (.docx) that will be used as a template for the generated Word overview report. This parameter must be added before the parameter /ACTION:WORDOVERVIEWREPORT (see example below).
/EXPORTOVR:<file> | Exports a recently generated overview report view to <file>. Use file.htm for HTML or file.mht for WebArchive export.
/NOGUI | Specifies whether Performance Explorer is executed visibly or invisibly (GUI-less mode). /NOGUI functions appropriately only when /NOEXIT is used in a DOS-based command line.
/SINGLEINSTANCE[:NOSTARTUP] | Searches for an existing instance. When used with NOSTARTUP, no new instances are created.
/PEW:<workspace file> | Opens or creates the specified workspace. When used with /SINGLEINSTANCE, an existing instance is selected only when it uses the given workspace file. Otherwise, a new instance is created.
/COMMANDFILE:<xml file> | Load commands from the specified XML file.
/EXIT | Saves the .tsd file, then closes Performance Explorer without saving changes to the workspace.
/NOEXIT | Performance Explorer stays open after the command line execution.
/? | Displays Performance Explorer with allowed command line parameters.

Examples

The following snippets illustrate how some of the above listed commands can be used.

If you add the parameter /TSD to the command PerfExp.exe, as shown in the first snippet, Performance Explorer opens and shows the specified .tsd file. Additionally, the parameters /ACTION:STDGRAPH and /ACTION:STARTALLMONITORS ensure that a predefined chart (of type General) is opened and all monitors are started automatically.

PerfExp.exe /TSD:"c:\test.tsd" /ACTION:STDGRAPH /ACTION:STARTALLMONITORS

This second snippet starts Performance Explorer and opens the specified .pew file (/PEW). Then the monitor directory is set (/MONITORDIR) and all monitors contained in the .pew file are started automatically (/ACTION:STARTALLMONITORS). All these actions are performed without showing a user interface (/NOGUI). Finally, the parameter /SINGLEINSTANCE causes Performance Explorer to search for an existing instance and the parameter /NOEXIT ensures that Performance Explorer stays open when the command line is fully executed.

PerfExp.exe /PEW:"c:\test.pew" /MONITORDIR:"c:\temp\perf" /ACTION:STARTALLMONITORS /NOGUI /SINGLEINSTANCE /NOEXIT

The third snippet causes the following behavior: Performance Explorer starts and the specified .pew file is opened (/PEW). While starting-up, Performance Explorer searches for an existing instance. If an instance is found, no new instance is started /SINGLEINSTANCE). The monitor directory is set (/MONITORDIR) and all monitors are stopped (/ACTION:STOPALLMONITORS). No user interface displays (/NOGUI). Finally, the .tsd file is saved and Performance Explorer closes without saving any changes to the workspace (/EXIT).

PerfExp.exe /PEW:"c:\test.pew" /MONITORDIR:"c:\temp\perf" /ACTION:STOPALLMONITORS /NOGUI /SINGLEINSTANCE:NOSTARTUP /EXIT

The fourth snippet generates a Word overview report: First, Performance Explorer starts without displaying any user interface (caused by the parameter /ACTION:WORDOVERVIEWREPORT) and opens the specified .tsd file (/TSD). Make sure to specify a merged .tsd file (m@). Then, the path and name of the Word document that will be generated are specified (/WORDTARGET) as well as the path and name of the Word template that is to be applied (/WORDTEMPLATE). Finally, the parameter /ACTION:WORDOVERVIEWREPORT causes the report to be generated.

PerfExp.exe /TSD:"c:\test.tsd" /WORDTARGET:"c:\report.docx" /WORDTEMPLATE:"c:\template.docx" /ACTION:WORDOVERVIEWREPORT
Parent topic: Command Line Parameters


Command File

Besides submitting commands directly within the command line, you can also submit a command file in XML format. Specify the commands by using the following syntax.
Perfexp.exe /COMMANDFILE:<CmdFile>

The command file is designated for batch operation.

The structure of the XML file to use as a command file consists of a root node called PerfExpCommandFile and two optional sub-nodes called OverviewReport and Command.

PerfExpCommandFile

Possible specifications in the root node PerfExpCommandFile include the following examples:
  • NoGui="True" / NoGui="False"

    Specifies whether Performance Explorer launches visibly or invisibly.

  • LogFile="<filename>"

    Specifies the name and location of the log file.

Different Command and OverviewReport nodes can reside below the root node.

OverviewReport

The OverviewReport node specifies which .tsd file Performance Explorer uses. The following attributes are available:
  • File

    Specifies which .tsd file to use. If omitted, the last file loaded by Performance Explorer is used.

  • Export
    Specifies the output file to which the overview report is saved. Available formats include the following options:
    • HTML (.htm)
    • WebArchive (.mht)
  • Template

    Specifies an optional template OVT file to use for the overview report.

Command

The text of a Command node is interpreted as a command line parameter. Nodes are executed sequentially.

The following code shows an XML command file:

<?xml version="1.0" encoding="UTF-8" ?>
<PerfExpCommandFile NoGui="True"
      LogFile="c:\TEMP\Results\PerfExp.log">
 <OverviewReport
      File="c:\TEMP\Results\m@host@Simple.tsd"
      Export="c:\TEMP\Results\Simple.mht"
  />
   <Command>PEW:"c:\test.pew"</Command>
   <Command>SINGLEINSTANCE</Command>
   <Command>ACTION:STARTALLMONITORS</Command>
   <Command>EXIT</Command>
</PerfExpCommandFile>

Help command

Use the help command /? with the following syntax.
Perfexp.exe /?

Performance Explorer opens and displays the command line help.

Parent topic: Command Line Parameters


Customizing Visualization

Performance Explorer offers numerous possibilities to customize the appearance of charts, graphs, and reports. You can set default values for a variety of visualization settings and you can set specific options for individual charts, graphs, and reports.

  • Default Options
    Lists the default options that you can set for charts, graphs, and reports.
  • Customizing Chart Display
    Describes how to customize the appearance of a chart.
  • Customizing Graph Display
    Describes how to customize the appearance of a graph.
  • Displaying Measure Bounds
    Describes how to display the configured measure bounds in a chart as colored areas.
  • Displaying Performance Level Conditions
    Describes how to display performance level conditions in a chart as colored boundaries.
Parent topic: Performance Explorer 21.0


Default Options

You can change the default options for how charts, graphs, and reports are visualized.

  • Setting Default Chart Options
    Set default viewing and scaling options for charts.
  • Setting Default Time Series Data Options
    Set the time series data options such as displaying null values, line width, chart markers, and the number of decimal digits.
  • Setting Default Chart Exporting Options
    Set the default resolution and file type for exporting charts.
  • Setting Default Candle Graph Options
    Set the default candle and marker style.
  • Setting Default Monitoring Options
    Set the default background, text, and grid colors as well as the data interval options.
  • Setting Default TSD Writer Options
    Set options for the time interval value and time unit for which time series data will be written.
  • Setting Default Reporting Options
    Set options to generate overview reports automatically, display null values in charts, and use a default report template for the overview report.
Parent topic: Customizing Visualization


Setting Default Chart Options

  1. Click the Performance Explorer Application Button (on the top left) and click Options.
  2. Check the Highlight Selected Series check box to display the currently selected series with an emphasized, thicker line.
    Note: While this option might be useful as long as you are working with charts, uncheck the check box before you export or print charts.
  3. Check the Overlay series check box to assume that all time series that are displayed in a chart start at the same time. Use this option when you are viewing a chart that contains time series from tests with different starting times.
  4. From the Background colors lists, select the colors that you want to use to enhance your charts. To use a custom color, click [...] to the right of the list box. Performance Explorer displays a vertical color transition from the first to the second color as the background image.
  5. From the Text and grid color list box, select the color that you want to use for the axis information and the grid in your charts. To use a custom color, click [...] to the right of the list box.
  6. In the Scaling area, you can enable the following features:
    • Enable Scale values between 0 and 100 to display scaled values rather than real time series data values.
    • Enable Use same scale factor for similar series to set the same scale factor for series of the same type.
  7. Click OK.
Parent topic: Default Options


Setting Default Time Series Data Options

  1. Click the Performance Explorer Application Button (on the top left) and click Options.
  2. Click the Series tab.
  3. If you want to display null values by default, check the Display NULL values check box. On the Series tab, in the Display group, you can click Null Values to enable or disable null values separately for single measures. The check box in the Options dialog enables or disables null values for all measures.
  4. From the Show summary and counter values per list box, select the time unit for which you want time series data to be displayed.
    • Select Interval if you want to display data for the computation interval contained in the .tsd file.
    • Select Second to scale displayed data to one-second intervals.
    To change the default computation interval, use the Time Series tab of the Profile Settings – Results dialog.
  5. From the Default line width list, select a line width to use whenever you add a new measure to a chart.
  6. To display a chart marker for each measure value of each series, indicating the exact measure value, check the Show chart markers check box.
  7. In the Decimal digits field, type the number of digits to display in the chart markers. Use chart markers to display exact measure values for each measure within a chart.
  8. Click OK.
Parent topic: Default Options


Setting Default Chart Exporting Options

  1. Click the Performance Explorer Application Button (on the top left) and click Options.
  2. Click the HTML View tab.
  3. In the Chart picture resolution area, select an option to determine the resolution of the image that is generated when you export a chart as an HTML document. The size of an image file is directly proportional to its resolution. As a result, images with higher resolutions take longer to transfer over the web than images with lower resolutions.
  4. Use the Picture type area to select the picture format of your chart in an HTML document.
    • Click JPEG to include the chart in an HTML document as a JPEG file.
    • Click BMP (only with Internet Explorer) to include the chart in an HTML document as a BMP file.
  5. Click OK.
Parent topic: Default Options


Setting Default Candle Graph Options

  1. Click the Performance Explorer Application Button (on the top left) and click Options.
  2. Click the Candles tab.
  3. From the Border color list box, select the color you want to use for the candle borders in your current graph. To use a custom color, click [...] to the right of the list box.
  4. In the Candle width spin box, enter the width for the candles in your current graph.
  5. From the Marker color list box, select the color you want to use for the markers. To use a custom color, click [...] to the right of the list box.
  6. In the Marker height spin box, specify the height for the markers.
  7. Click OK.
Parent topic: Default Options


Setting Default Monitoring Options

  1. Click the Performance Explorer Application Button (on the top left) and click Options.
  2. Click the Monitor tab.
  3. In the Interval field, set the length of the intervals at which the chart is updated.
    Note: When modifying the monitor interval to a value lower than the default minimum interval during a run, the interval will be reset to the minimum monitor interval upon reopening the saved workspace.
  4. In the Page size field, set the number of measured values currently displayed per graph on the horizontal axis.
  5. In the History size field, set the number of measured values stored for the entire graph on the horizontal axis.
  6. From the Background colors lists, select the colors that you want to use to enhance your charts. To use a custom color, click [...] to the right of the list box. Performance Explorer displays a vertical color transition from the first to the second color as the background image.
  7. From the Text and grid color list box, select the color that you want to use for the axis information and the grid in your charts. To use a custom color, click [...] to the right of the list box.
  8. Click OK.
Parent topic: Default Options


Setting Default TSD Writer Options

  1. Click the Performance Explorer Application Button (on the top left) and click Options.
  2. Click the TSD-Writer tab.
  3. In the Interval field, select a time interval and a time unit for the time series data that is written.
  4. Click OK.
Parent topic: Default Options


Setting Default Reporting Options

  1. Click the Performance Explorer Application Button (on the top left) and click Options.
  2. Click the Reporting tab.
  3. To automatically display an overview report when you start exploring the results of a test, check the Generate overview reports automatically check box. An overview report contains the most important results of a test, such as the number of virtual users that were active, the number of transactions that were executed, and the number of errors that occurred.
  4. To display null values in charts, check the Show NULL values in charts check box. If you uncheck this check box, Performance Explorer replaces each null value with a direct line from the preceding to the following value.
  5. To use a previously stored template for the creation of overview reports, check the Use template when creating a new overview report check box, click [...], and select the template. The selected template is used to create a new overview report for all projects.
  6. Click OK.
Parent topic: Default Options


Customizing Chart Display

Performance Explorer displays charts in a standard format but offers numerous possibilities for customization. You can enable scaling, overlay graphs, highlight graphs, export charts, and more. These display options can be found on the Chart tab, which is a contextual tab. It displays when you create or select a chart.

  1. Create a chart and drag measures from the tree onto the chart.
  2. On the Chart tab, in the Chart group, you have the following options:
    • Scaling: The scaling feature allows you to visually equalize graphs in a chart. This means that measures with big values and measures with small values can be displayed appropriately and a meaningful chart can be drawn. Without scaling, measures with small values would display as flat lines, while measures with big values would display as steep lines. To set a specific scaling factor for individual graphs, select a factor from the Scaling list, in the Series group on the Series tab.
    • Overlay Graphs: When you overlay graphs, all graphs are shifted to a common start time, regardless of the actual start time. Use this option when you are viewing a chart that contains measures from tests with different starting times.
    • Logarithmic Y-Axis: Changes the linear y-axis into a logarithmic y-axis.
    • Highlight: Emphasizes the selected graph with a thicker line.
      Tip: Highlighting graphs is useful while you work with and view charts in Performance Explorer. However, make sure to uncheck this option before you export or print a chart.
    • Scale Similar Series: Performance Explorer applies the same scaling factor to similar series. Similar series are series with the same type (see the Type column in the measure list). To use this feature, progress as follows: Drag a measure with a certain type onto an empty chart. Right-click the measure and select a custom scaling factor (not Auto). Enable Scale Similar Series, on the Chart tab. Drag further measures with the same type onto the chart. Performance Explorer automatically applies the scaling factor that you have manually specified for the first measure.
    • Properties: In the properties, you can type a Caption and a Description for the chart. These will display above the chart when you export or print it.
    • Export: Exports the active chart as a .csv file or as an Excel document. When you click Export As CSV File you can choose from a range of file types, like .csv, .htm, .mht, or .png.
  3. In the Display group, you have the following options:
    • Series Points: Displays the series points of all graphs.
    • Zoom Out: Resets the zoom level.
    • Zoom & Scale: Zoom & Scale is enabled by default. It allows you to zoom into the chart, which means that both the x- and y-axis are adjusted. When you disable Zoom & Scale, only the x-axis will be adjusted.
    • Measure List: Shows or hides the measure list. The measure list can also be regarded as the legend of the chart. However, it provides lots of additional information for each measure.
  4. In the Generate group, you have the following options:
    • Monitor Writer: Creates a new monitor writer with the real-time measures from a monitor graph.
    • VUser-based Chart: Creates a new virtual user-based chart using the same measures as the active time-based chart. A time-based chart displays the measured values on the y-axis and the time on the x-axis. A VUser-based chart displays the number of virtual users on the x-axis.
  5. In the Data group, you have the following options:
    • Clear Monitor Chart: Clears all graphs from the active monitor chart.
    • View in Browser: Shows the active chart as HTML document in a browser.
Parent topic: Customizing Visualization


Customizing Graph Display

Performance Explorer displays graphs in a standard format but offers numerous possibilities for customization. You can change colors, line width, and line styles. You can change scaling options, insert markers, and more. These display options can be found on the Series tab, which is a contextual tab. It displays when you create or select a chart.

  1. Create a chart, drag measures from the tree onto the chart, and select a graph or a measure from the measure list.
  2. On the Series tab, in the Line Style group, you have the following options:
    • Style: Select from various line styles.
    • Color: Select a color.
    • Width: Select a width.
  3. In the Series group, you have the following options:
    • Scaling: The scaling factor allows you to visually equalize graphs in a chart. This means that measures with big values and measures with small values can be displayed appropriately and a meaningful chart can be drawn. Without scaling, measures with small values would display as flat lines, while measures with big values would display as steep lines. To enable auto scaling for all graphs in the chart, click Scaling in the Chart group on the Chart tab.
    • Display as: Select a display type for the selected graph. This can be Line, Candle, Candle with sticks, and Area.
    • Source Type: Select one of the following source types: Average, Count, Sum, Maximum, Minimum, StdDev.
  4. In the Display group, you have the following options:
    • Markers: Markers show the measured values in the chart.
    • Null Values: Displays the null values for the selected graph.
    • Measure Bounds: Displays the bounds for the selected graph. You can configure these bounds in the Automatic Threshold Generation dialog before you start a load test.
    • Performance Level Conditions: Displays the performance levels for the selected graph. You can define and assign performance levels on the Reports tab.
    • Normalized Values: Displays normalized values for the selected graph. Normalized values are values per second.
    • Standard Deviation Area: Displays the standard deviation for the selected graph.
    • Visible: Click this check box to show or hide the selected graph. You can also use the check boxes in the measure list to show or hide graphs.
Parent topic: Customizing Visualization


Displaying Measure Bounds

Before you start a load test, you must define a lower and upper bound within the Automatic Threshold Generation dialog or directly within the script. The values of the bounds display in the Overview Report.

To display measure bounds in a chart:
  1. Create or open a chart.
  2. Drag measures that have defined bounds onto the chart.
  3. Click a measure in the measure list to active it.
  4. On the Series tab, in the Display group, enable Measure Bounds.
The chart shows a red and a yellow colored area. The red colored area is the area above the upper bound. The yellow colored area is the area between the upper bound and the lower bound.
Note: The colored areas only display if the measure exceeds the configured thresholds. Performance Explorer only shows graphical measure bounds for one measure at a time. When you display measure bounds, the scale of the chart may adjust automatically.
Performance Explorer shows graphical bounds for the Average, Maximum, and Minimum values of the following measures:
  • Page and Action Timer - Action Time
  • Page and Action Timer - Page Time
  • Timer - Response Time[s]
  • Transaction - Trans. (busy) Ok
Parent topic: Customizing Visualization


Displaying Performance Level Conditions

Before you can display performance levels in charts, you have to define and assign them. You can do so before a load test execution (proactive approach) or after an execution (reactive approach).

To display performance level conditions in a chart:

  1. Create or open a chart.
  2. Drag measures that have performance levels assigned onto the chart.
  3. Click a measure in the measure list to activate it.
  4. On the Series tab, in the Display group, enable Performance Level Conditions.
The chart shows colored boundaries for the conditions of the assigned performance level and a small legend describing them. For example: If the current performance level contains a condition like P90 < 0.2, the condition is fulfilled if 90 % of the graph lie below the shown boundary.
Note: Performance Explorer only shows performance level conditions for one measure at a time.
Parent topic: Customizing Visualization


Contacting Micro Focus

Micro Focus is committed to providing world-class technical support and consulting services. Micro Focus provides worldwide support, delivering timely, reliable service to ensure every customer's business success.

All customers who are under a maintenance and support contract, as well as prospective customers who are evaluating products, are eligible for customer support. Our highly trained staff respond to your requests as quickly and professionally as possible.

Visit http://supportline.microfocus.com/assistedservices.asp to communicate directly with Micro Focus SupportLine to resolve your issues, or email supportline@microfocus.com.

Visit Micro Focus SupportLine at http://supportline.microfocus.com for up-to-date support news and access to other support information. First time users may be required to register to the site.

  • Information Needed by Micro Focus SupportLine
    Lists information needed by Micro Focus SupportLine to help address customer issues.


Information Needed by Micro Focus SupportLine

When contacting Micro Focus SupportLine, please include the following information if possible. The more information you can give, the better Micro Focus SupportLine can help you.

  • The name and version number of all products that you think might be causing an issue.
  • Your computer make and model.
  • System information such as operating system name and version, processors, and memory details.
  • Any detailed description of the issue, including steps to reproduce the issue.
  • Exact wording of any error messages involved.
  • Your serial number.

To find out these numbers, look in the subject line and body of your Electronic Product Delivery Notice email that you received from Micro Focus.

Parent topic: Contacting Micro Focus


Launching the Cloud Agent Manager

Before you begin, contact your sales representative for your Enterprise Cloud Services user name and password.

  1. Choose Tools > Cloud Agent Manager.
  2. Type your Enterprise Cloud Services User name and Password.
  3. Click OK.


Recording a Test Script Over a Secure Connection

  1. Click Model Script on the workflow bar. The Workflow - Model Script dialog box appears.
  2. From the Recording Profile list, select the profile for the client application that you plan to test. If a profile has not yet been set up for the application you want to use, click Settings to the right of the list to set one up.
  3. Depending on the project type, enter either the application's URL in the URL field or the location of the application in the Command line field.
  4. Click Record over a secure connection. The Configure secure recording dialog box appears.
  5. On the Configure secure recording dialog box, select if you want to use the Micro Focus CA (certificate authority) certificate or if you want to use the certificate of your system under test. If you are unsure which approach to use, refer to Secure Connections and Certificates.
    If you selected Configure Micro Focus certificate:
    1. Click Install Micro Focus CA certificate.
    2. Follow the Certificate Import Wizard instructions.
    3. After you have completed the certificate import, click Start recording.
    If you selected Configure server certificate:
    1. In the Server certificate field, locate the server certificate you want to use.
    2. In the Pass phrase field, enter the pass phrase that is to be used, if the server certificate you want the Recorder to use is protected with a pass phrase.
    3. Optional: Check the Send root CA during SSL handshake check box to have the Recorder send the root CA certificate during the SSL handshake. The root CA certificate may be requested by a client to authenticate the certificate authority that signed the Recorder server certificate.
    4. Optional: In the Root CA certificate field, locate the root CA certificate that you want to use.
    5. After you have completed configuring the server certificate, click Start recording.
    The Silk Performer Recorder dialog opens in minimized form, and the client application starts.
  6. To see a report of the actions that happen during recording, maximize the Recorder dialog by clicking the Change GUI size button. The maximized Recorder opens at the Actions page.
  7. Using the client application, conduct the kind of interaction with the target server that you want to simulate in your test. The interaction is captured and recorded by the Recorder. A report of your actions and of the data downloaded appears on the Actions page.
  8. Insert transactions and timers into the test script during the recording phase. You can create as many transactions and timers as you want. To insert a transaction, click the New Transaction button. A transaction represents a piece of work that can be assigned to a virtual user.
  9. In the ensuing dialog, enter a name for the transaction and click OK. The new transaction appears in the Actions log.
  10. To insert a timer, click the New Timer Session button. A timer is a user-defined measurement period in a test. You should create timers for each component of a transaction for which you want to analyze performance. In the ensuing dialog, enter a name for the timer and click OK.
  11. To end recording, click the Stop Recording button.
  12. Enter a name for the .bdf file and save it. The Capture File page displays. Click Generate Script to generate a script out of the capture file.
Related concepts
Secure Connections and Certificates


Viewing Overview Reports

  1. Click the Explore Results button on the workflow bar. The Workflow - Explore Results dialog appears.
  2. Click the Silk Performance Explorer button or link. If you have selected the Generate overview report automatically option in the Settings/Options/Reporting dialog, Performance Explorer opens and displays an overview summary report for the most recent load test. Additionally, you can choose to use a previously stored template for the generation of an overview report in this dialog. This setting is a global setting and will be used with Performance Explorer, regardless of the workload project you are using.
  3. If the overview report does not appear automatically, click the Overview Report button on the workflow bar.
    1. Navigate to the directory of the load test you are working with and select the corresponding .tsd file and then click Open.
    2. Click Next.
    3. Optionally, in the Template field, click [...] to navigate to the template file that you want to use.
    4. Click Finish.
    5. Depending on the load test that you selected, you may be prompted to confirm that you want to load all relevant files into your project.
    The overview report opens.